Gator can turn its understanding of your codebase into clear, visual documents for the people who decide what happens to it.
What Gator docs are for
Charters make this possible. They give the AI agent a deep, written understanding of the repository and its context, so it can explain the system accurately and at the level the reader needs.
Map systems and flows. Show how the code in the repository is organised, how a feature works from end to end, and where each part lives.
Discuss features before they exist. Show how a proposed feature could work, what it would touch, and what the options are. Share the document with other architects and decide together.
Draw the whole system. Lay out the code and the infrastructure it runs on in one diagram: services, data stores, queues, networks and the boundaries between them.
Support project management. Explain what is happening in the code and the system as a project view: what has shipped, what is in progress, what the risks are, and what decisions are open. Executives can read it without reading code.
Examples
Ask your agent for a Gator doc in plain words. Name the thing you want to understand, and say who will read it.
Create me a Gator doc for …
The agent reads the repository's charters and the code, then writes one standalone HTML document. It is not a chat answer and not a dump of source code. It is an explanation written for a person, with pictures.
Figure 1 — from a one-line request to a document you can read, review and keep.
The examples below show seven situations, the request a person makes, and the kind of document they get. All seven take place at an imaginary online store, so you can see how one team could use Gator docs across its work.
Example 1 · Explain a new feature
Suppose a developer at an online store has built product photo uploads, and the reviewers need to see how the new code and the new infrastructure fit together.
Create me a Gator doc for how product photo uploads work, code and infrastructure, for the review.
Ask to upload. The seller's browser asks the Upload API for permission. The API checks the seller and returns a signed link that is valid for five minutes.
Upload the photo. The browser sends the photo straight to the private photo bucket with that link. The photo never passes through the API servers.
Make thumbnails. Each new photo starts the resize function, which writes three smaller sizes back to the bucket.
Serve through the CDN. The CDN reads the files from the bucket and keeps copies close to shoppers.
Show the photos. The product page links to the CDN files, so photos load quickly everywhere.
The feature changed application code and infrastructure in the same piece of work. A reviewer who reads only the code sees an API endpoint and a function. A reviewer who reads only the Terraform files sees a bucket and a cache rule. The document joins the two halves into one path that a person can follow.
Labelled diagrams, linked to the source. Every box says in words whether it is code or infrastructure, and names the file or folder that defines it. Every arrow has a step number that matches the list. Nothing depends on colour alone, so a reader can check each part of the picture against the code.
Example 2 · Explain code
Suppose an engineer at an online store must explain why a customer's card was charged a few seconds late.
Create me a Gator doc for the payment service's retry logic.
The document answers in one picture: which code decides to retry, how long it waits, how many times it tries, and where a charge goes when every attempt fails. The text names the settings and the tests that pin them.
Reviewed and versioned in Git. The document is committed like any other change. When someone changes the retry limit, the same commit updates the document, and Git shows who changed it, when, and why.
Example 3 · Explain a procedure
Suppose the store's release manager is asked for a visual of the release procedure, for the engineer who will run the next release.
Create me a Gator doc for our release procedure.
Cut the release branch. Create release/2.4 from main. From now on, only fixes go to this branch.
Build a candidate. CI builds 2.4.0-rc1 and stores it. A failed smoke test means a new candidate, never a patched one.
Run the smoke tests on staging. If one fails, fix it on the branch and build the next candidate.
Promote the tested build. Production gets the same files that passed the tests. Nothing is rebuilt.
Tag and announce. Tag v2.4.0 and post the release notes.
Readable prose. Short, direct sentences explain what each step does and why. A person who has never released the product can follow it on the first try.
Example 4 · Record a decision
Suppose someone at the store asks, a year later, why the team chose Postgres for its event store.
Create me a Gator doc for why we chose Postgres for the event store.
Option
Operations
Queries
Decision
Postgres
A database we already run and back up
Full SQL over events
✓ Chosen
DynamoDB
A new service to learn, monitor and pay for
Key lookups only
Rejected
Files in Git
Nothing to run
No queries
Rejected
The document shows the options, the trade-offs and the choice, and gives the reason in words: the team already runs Postgres well, and reporting needs real queries. It also says what would make the team decide again.
The reason lives with the code. A decision made in a meeting or a chat thread is soon lost. A Gator doc is a file in the repository, beside the code it explains, so the next person finds the reason where they look for it.
Example 5 · Discuss a feature before it exists
Suppose an architect at the store wants to propose a bulk-export feature and review it with the platform team.
Create me a Gator doc for how a bulk-export feature could work, for review with the platform team.
Nothing is built yet. The agent knows the parts that exist from the charters, so the proposal reuses the job queue and the object storage, and shows only three new parts. It lists the options it considered, what each one would change, and the questions the team must answer first.
Made for working with other architects. The proposal is a standalone page. Open it in the Dashboard, or send it to the platform team before the meeting. Their comments go back to the agent, which revises the document. When the team agrees, the document becomes the plan.
Example 6 · Draw the network and its security boundaries
Suppose the store's security team must show a PCI DSS auditor how card data moves through the system, and where every security boundary is.
Create me a Gator doc for how card data flows through our network, with every security boundary, for the PCI audit.
The auditor's first question is where card numbers can go. The picture answers it: card details enter the PCI zone directly from the load balancer, the token vault keeps them, and only tokens cross back out to the orders database. The only way out to the internet is the egress firewall, and it allows one destination, the payment provider. The keys and the logs live in a separate security account, so a person with access to production cannot read the keys or delete the evidence.
Solid arrows carry data. Dashed arrows carry keys, secrets, logs and access, which is what auditors and security reviewers check next. The text under the diagram lists each boundary with the rule that enforces it: the route table, the security group, or the account policy.
Drawn from the code, not from memory. The agent builds the diagram from the infrastructure files and the application code that the charters describe. Each boundary in the picture is a real boundary in the code: a subnet, a route table, a security group, or a separate account. When the network changes, the same request brings the diagram up to date.
Example 7 · Report progress
Suppose the store's engineering lead must report this month's progress to the leadership team.
Create me a Gator doc for this month's progress, for the leadership team.
Two of five goals are done. Bulk export is on schedule. The event-store upgrade is at risk, and the second region needs a decision this week.
Failed card charges, % of all charges
After the retry logic shipped, failed charges fell by four fifths.
Work done per goal
Bars show progress only. The table below gives each goal's status in words.
Goal
Status
What it means
Safer card payments
✓ Done
Failed charges fell from 2.1% to 0.4% after the new retry logic.
Faster checkout page
✓ Done
The page loads in 1.2 s, down from 2.8 s.
Bulk export for customers
◐ In progress
Design approved. About 60% built. On schedule for next month.
Event-store upgrade
⚑ At risk
Waiting for a maintenance window from the database team.
Second region
? Decision
Approve the hosting budget so work can start next quarter.
The agent reads the commits, the charters and the open work in the repository, then writes for people who will not read code: goals instead of file names, outcomes instead of changes. The charts show the trend and the progress at a glance; hover a bar to see its value. Each status in the table is a word and a symbol, not only a colour.
Easy to share. A Gator doc is one self-contained HTML file. Attach it in Microsoft Teams, email or chat, and it opens in any browser exactly as it looks in the Dashboard. Nothing is lost on the way.
Keep it up to date
A Gator doc stays beside what it explains, so it is easy to check.
When the code changes, or whenever you are not sure, ask the agent:
Is this document up to date? If not, please update it.
The agent compares the document with the charters and the code, tells you what has changed, and updates the document. The update is a commit like any other, so you can see exactly what changed in the document and why.
Addendum: Cumberland style HTML communication
Every Gator doc uses the Cumberland style, a design template built into Gator. You do not need to ask for it.
The template ships with Gator in .gator/.includes/reference-notes/. The agent starts each Gator doc from it, so every document looks and reads the same way, in every repository, whichever AI model writes it.
Type sized for reading. Body text is large enough to read for a long time, with generous line spacing and clear headings. A Gator doc reads like a document, not like a web page of small print.
Colour coding with a fixed meaning. A small palette of six colours, chosen so that people with colour blindness can tell them apart. Each colour has one job (structure, status, or emphasis), and every colour is paired with a word, a symbol or a border, so no meaning depends on colour alone.
Diagrams drawn into the page. Diagrams and charts are drawn inside the document, with a label on every box and arrow. There are no image files or scripts to load, so the file works offline, opens safely in the Dashboard, and stays complete when you attach it to a message.
Simplified technical English. The prose follows the style of ASD-STE100 Simplified Technical English: short sentences, one idea in each sentence, active voice, and the same word for the same thing every time. Readers whose first language is not English can follow it too.