Handbook

The documents

How the handbook relates to the skills

• A skill holds the procedure. The handbook states the rule and names the skill. When the two disagree, the skill is right, and the change that finds the difference corrects the handbook.
• AGENTS.md at the repository root is the entry point for an agent. It summarizes the principles, routes each kind of task to its skill, and points here for depth.
• The skills name handbook files by their paths (docs/handbook/quality-bar.md). A project that installs the skills copies this folder and AGENTS.md beside them, as README.md's "Import this into another project" section describes.

Changing the handbook

• A new ruling from Kevin goes into the decisions log as a dated row that names what it replaced, and the skill, lint or gate that holds it changes in the same commit.
• A document keeps the writing rules of gt-voice: plain declarative sentences, no em dashes, no metaphors, and no contrast pairs.
• The repository is public. No document carries keys, account ids, email addresses, personal details, customer names beyond BRAND.md section 9, unannounced plans or business figures (operating principle 18).
• On the site, a new document needs its entry in src/app/handbook/registry.ts and its headings in HANDBOOK_HEADINGS (src/lib/search-index.ts). The prototemplate skill (section 6) lists every step, and node skills/prototemplate/scripts/check-registries.mjs reports what a change missed.

Sources

• The six documents were written on 2026-10-05 from Kevin's messages to Claude Code and Codex between 2026-07-20 and 2026-10-05, about 5,800 in all, and from the curated skills. Each document's Sources section lists its own evidence.
• Kevin, 2026-10-05: "this prototemplate is supposed to be my hub for general translation work, but also i should be able to use it anywhere and build on top of it so it also acts as a wiki / repository of how i do work at GT".

Keep going until everything is done

Run every wave of a plan to completion without stopping between waves to ask for permission. "Continue", "continue all" and "keep going" resume every open lane and every unfinished item. When an agent dies on a usage limit, an outage or a closed app, check the working tree, then resume the agent with its brief intact (gt-orchestration section 6). Do the hard items as well and report each one. Spend the time on the fixes, and write tests to prove them.

Kevin, 2026-09-09: "can we just do all of our updates? why are you holding back". He said the same on 2026-07-24 and 2026-09-12.

Do the work yourself and ask once for what only Kevin can do

Do every step an agent can do, including console setup through a CLI (vercel, gh, gcloud) or the browser page Kevin already has open. Collect what only he can do (a login, a payment, a credential consent, an approval, a Linear issue id) into one numbered list with the exact file, line or URL for each item. A blanket approval covers the plan it answers. The safety lines still hold. Before a step that cannot be undone, such as a merge over recent work, check that nothing is lost. Wait for his word on a force push, a production deploy to GT's Vercel team, new spend, or landing an exploration round on Prototemplate main (gt-ship section 8).

Kevin, 2026-10-05: "anything approved is approved from me." Also 2026-07-20 and 2026-10-02.

Change only what was asked

Make the smallest literal change that answers the request. "Move it down" means translate it and keep its angle and easing. When a request could mean a small or a large change, make the small one or ask. When a fix spreads into neighbouring behaviour, assets or metadata, revert the extra changes exactly and apply the narrow change. An image Kevin pastes is the whole spec.

Kevin, 2026-08-06: "why did so much change, i just wanted to alter the connectors and line coming up". On 2026-08-07 a landing update had also redone the OG image, the favicon and the metadata, and he said there was no need.

Keep approved work

Before changing a surface, list what Kevin praised on it and carry every item forward, because a rewrite that drops an approved element is a regression. When he rejects a direction, restore the files to exactly their state before the rejected change and rebuild from there, since the rejected version is never the base of the next attempt. Commit early in each round on a local branch so git holds the restore point, and archive each published version before overwriting it. The dated verdicts are in gt-aesthetic section 2, and the restore and archive steps are in gt-explorations section 6 (After a rejection) and section 7 (Archive before overwriting).

Kevin, 2026-08-07: "lets redo this to before i started asking for this change and rebuild". Also 2026-07-30 and 2026-10-03.

Fix the whole class

When Kevin flags one instance (an icon, a footer, a flag chip, a double border), enumerate the class programmatically with grep, a registry, a lint or a measurable check, fix every member, verify each one and report the count. The sweep repeats the requested change on each instance of the same defect, and rule 3 still holds for everything around them. When he likes a treatment in one place, apply it to the sibling components. The cross-app sweep is in gt-components (Standardization), and the fixes by failure class are in gt-lints section 6.

Kevin, 2026-09-28: "look for ANYWHERE ELSE icons nneed to be synced". Also 2026-08-03.

Find the root cause and guard it

Diagnose before editing: read the computed values of the element Kevin selected, read the full log, and reproduce with the deployed environment. Fix the cause, then add the regression test or lint that keeps the class from returning (gt-lints section 4). Error handling keeps the underlying error in its message and never substitutes a guessed cause.

Kevin, 2026-08-18: "right but why is the fetch failing". Also 2026-08-05.

Measure the rendered result

A fix is reported only with visual or measured proof of the rendered result at the place Kevin flagged: computed styles on the live element, 2x crops of corners and junctions, and every animation state. A code change does not prove the render, and neither does a green proxy check (the page loads, the sizes match) or a settings panel that shows the right value. When a tool reads badly, switch to another one, such as a Playwright capture, and finish the verification yourself. The methods are in gt-verify, and the quality bar (Done) states when work counts as finished.

Kevin, 2026-07-30: "no, the borders are still sstraight black, still padding, and borders wrong color". The fix before it had been reported as verified from a screenshot.

Show the result

Results reach Kevin as something he can see or hear: before and after crops at the same viewport, the localhost URL with its server running, a page open in his browser, or a small HTML page for a set of images or audio takes. Send them before he asks. The formats are in gt-reporting section 1, the review servers and the steps for letting him try a build are in gt-local-dev sections 1 and 5, and the crop and PR rules are in gt-aesthetic (Showing the work) and gt-ship section 4.

Kevin, 2026-10-05: "i cant listen to the voices, make it in html so i can go through and listen to em".

Real content and real assets

Copy and numbers come from production, the benchmark and data files, or GT's published pages. Never invent testimonials, quotes, metrics, prices or feature promises, and mark placeholder content as placeholder. Marks, logos, flags and scans are the real files, sourced and credited: third-party logos from thesvg.org (gt-brand section 5), pictures with their source, license and credit (gt-dither section 5), and the search for an asset continues until the real one is found (gt-brand section 8, Third-party material).

Kevin, 2026-08-05: "like these arent real quotes", about a testimonial block an agent had written.

Ask only real decisions, with a recommendation

Ask Kevin only what is his to decide: spend, naming, licensing, scope, or an instruction that reads two ways. Ask each as a multiple-choice question with the recommended option first, and batch several into one numbered list with short ids so he can answer inline (gt-reporting section 6). When a new state resembles an existing one, reuse the existing behaviour and say so instead of asking. A gate that blocks a requested change is a question for him, and bypassing it silently is a defect.

Kevin, 2026-09-25: "no need to ask me anythiing just do this all for me please".

Correct from the first frame

Treat a gap at startup, a flash on reload and lag on the first interaction as defects, even when the page settles a moment later. Check the first frame and the first interaction after a cold load and after a reload, and reserve space so nothing shifts (gt-verify, gt-performance).

Kevin, 2026-08-08: "if i reload i briefly see 3 layers stacked on top of each other". Also 2026-08-04, on an animation that had to start "without a startup lag".

Nothing unnecessary ships

A release carries no development code. Keep galleries, stand-ins, test-only hooks, dev routes, temporary tests, recorded fixtures and harnesses off the release branch (gt-ship section 3). Add no dependency that existing code can replace, keep comments to one or two lines, and keep an unready dashboard feature behind a feature flag.

Kevin, 2026-10-01: "we cant ship anythign unnnecessary". On 2026-08-28 he questioned three packages added for one feature, and since 2026-09-03 a dashboard page that is not ready ships behind a feature flag.

Prefer free and cheap

Challenge any design that adds paid infrastructure, and lay out the free alternative with numbers first. Use the cheapest model that performs well enough, put spend caps on paid model runs (gt-orchestration section 7), and turn off git-triggered preview deploys where they only cost money: the landing builds main and staging only (gt-website section 8). Check which account a cost lands on before acting.

Kevin, 2026-09-15: "make a new pr to not allow preview deployments from git in landing, this is running up a lot of costs".

Secrets stay in protected files

Keys and tokens live in a protected config file or a gitignored env file. They never appear in chat, URLs, prompts, commits, docs or PR bodies, and briefs and docs name them by variable name only. When Kevin pastes a key into chat, move it into the env or config file, never echo it or commit it, and tell him it now sits in a transcript so he can rotate it. Never ask him to paste a key into chat.

Kevin's brief, 2026-08-03: "never print a key value".

"Fully" means complete

When Kevin asks to build out, enhance or update something fully, cover every section and capability with real diagrams, visuals and code, and state why the design works. A placeholder or a partial pass does not count.

Kevin, 2026-08-05: "show actual diagrams and visuialzations and code in these. enhance fully". Also 2026-08-04.

Codify what worked

After something works once, turn it into a skill, a doc, a lint or saved parameters: the prompts that worked and how they were structured, a lint for each standard, and generation parameters saved next to each asset. Every tool and skill belongs to a workflow with a routing doc. A new skill follows the contract in prototemplate section 10, and a new lint follows gt-lints section 4.

Kevin, 2026-10-05: "create docs and skills for audio creation and generation, what prompts worked and how u structured it". Also 2026-07-24 and 2026-08-06.

Vendor-agnostic agent tooling

Agent tools, skills and scripts work with Codex, Claude Code and local models alike. Skills use the Agent Skills frontmatter fields only, so every loader accepts them (prototemplate section 10), and no script hard-wires one provider.

Kevin, 2026-09-10: "be vendor agnostic, dont just ennforce claude code".

Privacy on public surfaces

Prototemplate is public at www.prototemplate.com and github.com/Kevin-Liu-01/Prototemplate. Nothing in it carries keys, account ids, email addresses, personal details, customer names beyond BRAND.md section 9, unannounced plans, or business numbers such as funding, revenue and headcount (gt-brand section 8, gt-voice "Facts and public surfaces"). Colleagues appear by role.

The rule dates from the brand questionnaire round (2026-08-06 and 2026-08-11) and from 2026-10-05, when Kevin made Prototemplate his public hub for GT work.

Where the procedures live

Kevin's wiki skill agent-iteration-loop holds the general loop of implementing, verifying, reviewing and shipping, and these rules apply inside it.

Sources

• Kevin's messages to Claude Code and Codex from 2026-07-20 to 2026-10-05, about 5,800 in all. Quotes keep his spelling. Rules 1, 4, 5 and 8 recur most: about 90 messages ask to continue or resume, 137 to revert or restore an earlier state, 177 for a change "everywhere" or "for all", and 86 to be shown the result. The counts include copies in forked sessions.
• Prototemplate: BRAND.md section 9; skills/gt-aesthetic sections 2 and 5; skills/gt-ship sections 3, 4 and 8; skills/gt-lints sections 1, 4 and 6; skills/gt-components (Standardization); skills/gt-brand sections 5 and 8; skills/gt-dither section 5; skills/gt-voice (Hard rules, Facts and public surfaces); skills/gt-website section 8; skills/gt-local-dev sections 1 and 5; skills/prototemplate sections 8 and 10; docs/handbook/quality-bar.md and docs/handbook/glossary.md.
• Kevin's gt-cloud memory notes redesign-v0-verdict, pr-size-discipline, explorations-stay-local, plain-technical-english and sentence-order-rules, which hold earlier statements of rules 2, 3, 4 and 12 and the writing rules this page follows.

The overall bar

• GT's own finished work is the reference. The brand deck governs product surfaces, and the Dossier governs the site (gt-aesthetic, section 1). The deck is built from deck/ and served at /deck, and the Dossier is served at /d/singularity-dossier. Kevin, 2026-08-06: "dossier is indeed our completed version and treat it as such". Before those existed, the July rounds measured against generaltranslation.com and resend.com (Kevin, 2026-07-30).
• Clearing every row on this page is the minimum. The work must also hold up beside its reference at the same geometry, and the convergence loop below checks that.
• When tweaks will not reach the bar, restart from the reference. A version Kevin rejected is never the base of the next attempt (gt-aesthetic, section 2). On 2026-08-11 he had the diagrams of the new site pages restarted outright.
• Every page gets a second pass against its reference before it is shown (gt-aesthetic, verdict of 2026-08-17).
• A bar is met on the rendered result. A gate is a typecheck or a lint. A structural check confirms that a page loads with the right hierarchy and dimensions, and reports also call it a proxy check. A measured check reads computed values or pixels on the render, and a visual check is a person or a fresh critic comparing a crop with its reference. An item that passed only gates and structural checks is reported as unverified (gt-verify, The definition of done). Every report says which kind of check passed (gt-orchestration, section 4; gt-reporting, section 1).

Reading the tables

Owner is the skill or document that holds the bar, with the section to read. Read is the day the owner was read for this page. Where the owner is this page, Read gives the day Kevin set the bar. Paths are relative to the Prototemplate root, and the glossary defines terms such as plate, rail and the Dossier.

Pages

The rows apply to product surfaces, the site, Prototemplate's own pages and docs pages.

A landing or marketing page also clears the gt-landing-pages checklist (one rail, hatch spacers, heads, the shared Cta), checked at 390, 768, 1024, 1440 and 1920 in both themes.

Motion

Graphics and diagrams

Copy

Pull requests

Convergence loops

A convergence loop iterates on quality until a bar holds: a page against its reference, a set of graphics against its best accepted item, a film cut against its brief. Kevin, 2026-07-30: "remember the bar is generaltranslation.com and resend.com. literally rereview and continuously score yourself until it look sright".

Performance

Films

Charts

Kevin set these bars for benchmark charts on 2026-07-30 and 2026-09-30. The wiki's dataviz skill holds the general method for form, color and marks.

Repositories

Kevin set these bars for a repository's own documents between 2026-08-02 and 2026-09-30.

Done

Work is ready to show when its artifact's table holds on localhost or in a file Kevin can open, and the report carries before and after crops of each changed region in both themes (gt-aesthetic, Showing the work). It is ready to ship when the pull request table holds as well. It is done when the rows below hold.

Sources

• Skills read on 2026-10-05: skills/gt-aesthetic/SKILL.md and references/verdicts.md, skills/gt-verify/SKILL.md, skills/gt-orchestration/SKILL.md, skills/gt-performance/SKILL.md, skills/gt-landing-pages/SKILL.md, skills/gt-lints/SKILL.md, skills/gt-motion/SKILL.md, skills/gt-graphics/SKILL.md, skills/gt-diagrams/SKILL.md, skills/gt-voice/SKILL.md, skills/gt-ship/SKILL.md, skills/gt-films/SKILL.md, skills/gt-dither/SKILL.md, skills/gt-reporting/SKILL.md, skills/prototemplate/SKILL.md.
• Canon: DESIGN.md section 2, deck/DECK-GRAMMAR.md, docs/SHIP-LOOP.md section 2, scripts/pagecheck/README.md, LICENSE.
• Kevin's rulings, checked against his messages to Claude Code and Codex: 2026-07-30 (the reference sites, side-by-side scoring, chart margins, method and cost metric), 2026-08-01 and 2026-08-02 (the OpenGraph card's type and lines), 2026-08-02 (AGENTS.md and SKILL.md), 2026-08-04 (two-line heads, repository topics), 2026-08-05 (morph length, numbers in diagrams, Lighthouse with no visual change), 2026-08-06 (the Dossier), 2026-08-11 (the diagram restart), 2026-08-17 (the second pass), 2026-09-13 (Greptile 5/5), 2026-09-17 (the OpenGraph card's own composition), 2026-09-30 (chart metric, README), 2026-10-05 (the page heads, PR bodies that let the crops explain).

Lanes

One session owns one lane. ListAgents prints the live list of sessions, and the table lists the GT lanes as of 2026-10-05.

Kevin's personal projects run in sessions and repositories of their own. They share the machine with the GT lanes (section 10) and nothing else.

• Work that belongs to another lane goes to that session. Find it with ListAgents and send the request with SendMessage, with Kevin's words for the request and the paths involved. Address the session by its name, because the bracketed id after the name changes when the session restarts.
• Codex sessions do not appear in ListAgents. Reach them through a relay note that Kevin pastes (section 7).
• Two lanes edit deck/. The session about to change a shared folder messages the other first (section 8).
• When Kevin narrows a session to one thing, the session drops everything else, including its own open items. While it waits, it starts no PR sweep and no work from another lane.

Kevin, 2026-10-03: "that videos one should be making them, and this one is just for prototemplate work".

• A session that gives up work to another lane sends the work's real state: the files, the commits, what passed and what is open. On 2026-10-03 the Prototemplate session handed two films to Videos with a message that understated how far they had come, and Videos learned the rest from the files. The receiving session reads the files and the git history before it acts on a handover message.

Forked sessions

Kevin forks sessions often. Ten gt-cloud sessions active between August and October descend from one session started on 2026-07-30. Videos was forked from New Onboarding and Dashboard on 2026-10-01, Glyph Map from Videos on 2026-10-02, and the Prototemplate session from New Onboarding and Dashboard on 2026-10-03. A fork starts with its parent's whole message history, and every inherited message reads as if it were addressed to the fork.

• A fork acts on the newest instruction addressed to it and on its own lane. Inherited messages are history. Their asks belong to the parent, which is usually still running and still owns them.
• In a fork, "continue", "continue everything" and "keep going" cover the fork's own lane. Two forks got this wrong. The Glyph Map fork restarted its parent's film build before starting the map, and Kevin stopped it. The Prototemplate fork took "continue everything" as its parent's list and pushed review fixes to the parent's open PRs, one of them from the parent's scratch worktree. Kevin narrowed it twice that day, first to its own request and then to Prototemplate work alone, and the films it had started went to Videos.

Kevin, 2026-10-02: "wait another agent is workign on the motion and videos. just focus on the nnew page".

• Before acting, a fork learns what the parent already did and who holds the parent's lanes now. It reads git status --short, git log --oneline -15 on its branch and on origin/main, git worktree list, the lane's notes (memory notes, HANDOFF.md, the round's spec) and ListAgents.
• A fork takes its own branch, worktree and dev port before it changes any file. Kevin's rule for any conversation, 2026-10-02: "the work in this convo should be on its own worktree branched off from main".
• In a Claude Code transcript (~/.claude/projects/<project>/<session>.jsonl), an inherited message keeps the parent's sessionId. One message of 2026-07-31 sits in eleven gt-cloud transcripts with a single originating sessionId. A count of Kevin's messages across transcripts dedupes on sessionId and timestamp.

One instruction to several sessions

Kevin sometimes sends one instruction to several sessions within seconds. On 2026-08-06 "commit and push everything to prototemplate, our branches, and 4213" reached four gt-cloud sessions within 25 seconds. Two of them went after the same three targets. One of the two had its Prototemplate build collide with a concurrent build. The other later saw a worktree directory vanish between two commands, because a parallel session was porting into it.

• Each session does its own part: its own paths, its own branch, its own PR.
• The session whose lane owns a shared step does it, once. Shared steps include a push of Prototemplate main, a sync of files into another repository, and a commit on a PR branch that two sessions use. The other sessions commit their own paths and check whether the shared step already happened (git fetch, then git log --oneline HEAD..origin/<branch> or gh pr view <n> --json headRefOid). They report the sha they found. When ownership is unclear, they ask the other session by SendMessage before pushing.
• A diverged branch is never force-pushed to make an instruction come true. On 2026-08-06 the branch of PR #4213 carried eight commits of the landing port that a force push would have erased. The session reported the divergence and offered to port the missing work onto that branch as new commits, which Kevin then asked for.
• When Kevin asks which session did something, answer from git and GitHub: the PR, the branch and commit, and the exact source text or file the work used. When Kevin asked "did we work on docs redesign in this convo?" on 2026-09-01, each session listed the PRs and files its conversation had touched, and the sessions that had not done the redesign said so.
• "Try again" after an API error or a spend limit re-runs the step that failed, starting from a fresh read of the state. On 2026-08-06 a session cut off by the spend limit re-read every target after "Try again" and reported each one clean.

Shared checkouts

gt-ship sections 1, 2 and 8 and prototemplate section 8 hold the rules for a shared checkout. They give motion/ to Videos, require explicit paths and a pathspec commit, check the branch before every commit, keep the primary gt-cloud checkout on its old branch, and leave the Prototemplate dev server on 3005 and its .next alone.

• Re-read a shared file immediately before editing it, because another session may have saved it a minute ago.
• Keep scratch output in the session's scratchpad. Every session started in the main gt-cloud checkout reads its .claude folder, and on 2026-10-02 a preview written there had to be moved out.

Collisions

• Report another session's in-flight changes and leave them where they are. A lint or type failure in files the session does not own goes into its report and does not hold back its own clean diff (docs/SHIP-LOOP.md section 0). Kevin, 2026-07-31: "dont worry about the uncommited work. only worry about localhost3006/ page".
• Keep another session's uncommitted file out of your commit, even when your own tweak sits inside that file. Say in the report that the tweak will land with that session's commit.
• Rerun a failure once before diagnosing it when another session may be mid-save. Such failures include a 500 from hot reload, a page the line auditor refuses, and a type error in a file the other session is editing. On 2026-08-05 tsc failed on a parallel edit that used Code2 before importing it. By the time the session looked, the other session had added the import, and the rerun passed.
• When the build stays broken on another session's change, make the smallest change that restores the build and tell the owner. On 2026-07-31 one session pushed a full sync to Prototemplate main while a second session was mid-push. The second session rebuilt on top of that push and landed one fix: pnpm-workspace.yaml held a placeholder line that made pnpm install fail.
• When another session's commit regresses your work, measure the regression and send the owner the exact fix. On 2026-09-29 a second session's commit on PR #5021 stopped a gallery state from playing when the console paged to it. The measurement and the fix went to that session, and it fixed the regression on the same PR.
• Fix another session's regression in the smallest unit that regressed (a token, a rule, a layer), and keep the rest of its file. On 2026-08-05 a parallel session had grayed a belt in v0-pages.css at higher specificity, and the fix changed that one rule to blue. On 2026-09-29 Kevin asked for the earlier glyphs back, and the fix restored only the rain layer from the earlier head and kept the other session's gallery console.
• Ask the owner before building a file another repository or session owns. gt-ship section 1 records the case of the CLI login callback page (2026-09-30).
• When two sessions find they are doing the same work, the one further along messages the other with its PRs, and the other stops. On 2026-09-30 the session that had opened the docs drift PRs told a second session, started from a task chip for the same fix, to stand down.
• When two sessions must change one feature, agree on a split by module and file. On 2026-09-29, in the sign-in gallery work, one session took the console requests in its own worktree, and the other kept the caption card's copy in a module of its own. When the first session shipped caption plates of its own, the second stopped its caption build before it wrote any files.

Claude and Codex together

Kevin, 2026-07-30: "let codex do its own thing, but branch off again".

• Each tool works on its own branch, in its own worktree, on its own dev port. A Codex branch named codex/<topic> is renamed k/<topic> before it becomes a gt-cloud PR (2026-08-27).
• Answer "are you on X's branch?" from git: git -C <worktree> branch --show-current and git -C <worktree> log --oneline -1 for each worktree involved. The answer on 2026-07-30 named both worktrees, both branches, both ports and the commit both branches started from.
• Every landing starts from a fresh origin/main and adds to the other agent's work. Kevin ruled on 2026-09-23 for a main that both agents push. Each agent keeps absorbing the other's pushes by rebase, every push to main has run the core test suite, and the two agents share main without separate deploy windows ("WE MERGE").
• Before publishing to a shared main: 1. Record the starting base commit when the worktree is created. 2. Fetch and compare git diff --stat <base> origin/main with your own change. For every file both agents touched, keep the incoming behaviour and re-apply yours on top. A merge without conflicts can still undo a feature through a whole-file replacement. 3. Read git diff origin/main HEAD in full, removals included, as the change about to be published. 4. Run the gates on the integrated commit. A green run on the branch before the merge says nothing about the merge. 5. Push without force. If the push is rejected, fetch, integrate and run the gates again.

In GT's repositories, gt-cloud main takes only squash merges through PRs with three required checks (gt-ship section 5), and Prototemplate's gates and deploy checks are in gt-ship section 8.

• Before a deploy that follows a stretch of both agents pushing, audit the last week of main for work one agent undid. Kevin, 2026-09-22: "MAKE SURE ALL CHANGES WITHIN LAST WEEK ARE PROPERLY SYNCED". - In a fresh worktree from origin/main, list the week: git log origin/main --since='7 days ago' --format='%h %ad %s', git worktree list and git branch -r. - Check every branch that looks unmerged for patch equivalence with git cherry -v origin/main <branch> and git range-diff. A squash or a rebase changes commit ids and keeps the work. - Read each merge commit's conflict resolutions with git show --remerge-diff <sha>. - For merged PRs, measure how many of their added lines survive on main and trace every removal to a stated follow-up. On 2026-09-08 Kevin thought the routing PR #4359 had been reverted. The gt-cloud audit found it open and unmerged with every commit intact, and it merged the next day. - Leave the other agent's unfinished checkout as it is and list it in the report.
• When the two agents build competing versions of one thing, keep both under distinct names and ids, and Kevin names the canonical one (2026-09-18).

Relays

A relay note is written by one agent for another, usually Claude for Codex or Codex for Claude, and Kevin pastes it as is. It holds:

• The branch, the tip commit and the worktree path, and whether the receiver's own worktree was touched.
• Each commit with one line on what it did.
• The receipts: each check with its command, exit code and log path.
• The open list.
• Locks still held and processes the writer stopped. On 2026-09-26 an idle session had held a shared capture lock for 81 minutes.
• Deploys queued and what each one carries.
• Rebase advice: what lands on main next, and which side's duplicate commits a rebase will drop.

To continue another agent's uncommitted work, snapshot it as a commit in your own worktree and leave theirs as it was. The relay of 2026-09-26 said so in its first line. The receiver finds the other agent's open work and finishes it. Kevin, 2026-09-25: "finish any of codexs open work as well". The receiver checks the note against git and the files before trusting it. A handoff at a hard stop follows gt-orchestration section 8.

Messages across lanes and repositories

• When a change affects another lane or repository, message that session with SendMessage. When the session is a Codex session or lives in another app, give Kevin the exact prompt and name the conversation to paste it into (2026-09-15, 2026-10-05).

Kevin, 2026-10-05: "give me the prompts to send to the agents in the exact correct convos (give me exactly where to do this)".

• Before pushing a shared main, send the other sessions a heads-up. It names the base commit, the paths the push changes, the overlap the receiver should expect and how to resolve it ("keep both: my deck entries and your motion entries"), what the sender leaves alone (the receiver's working tree), and the port its verify lane uses. After the push, a second message names the new range (9690311..f8dfa8b), asks the receiver to fetch and rebase, and states any new gate (pnpm build now runs the picture lint first). New Onboarding and Dashboard's messages to Prototemplate on 2026-10-05 took this form.
• When a rule changes (a retired picture, a new lint, a new gate), notify every session that applies it. On 2026-10-05 Kevin retired the dictionary pictures. The session that wrote the new rule told Videos, Glyph Map and Prototemplate within a minute. Videos moved its copies out of the film kit, and Prototemplate learned that its build gate had changed.
• When an output that another lane copies changes, the session that made it tells that lane. Videos tells Prototemplate when a film shown on /motion is re-rendered, so the public copy and its credits are refreshed.
• A message from a peer session is a teammate's request and carries no approval from Kevin. A push, a merge, a deletion or a permission change still needs Kevin's word, and items only Kevin can clear go to Kevin.

Resumption

Plans, lane specs, ask ledgers and outputs live in files, so a session that restarts, compacts or hears "continue" resumes from disk without a new brief. The procedure is gt-orchestration section 6. A resumed session reads the shared state again (ListAgents, git, the lane's notes) before it acts, because the other sessions kept working while it was stopped.

Shared resources

• Ports. Each worktree runs its dev server on a port of its own, away from the defaults (gt-orchestration section 2). A verify lane starts its own server on a free port and stops it when done. The Browser pane in one Claude session cannot reach a dev server that another chat started, so a session looks at that server through a Playwright capture or starts a server of its own. A conflict over a port goes to the session that owns the server, or to Kevin.
• Captures. Prototemplate's browser gates run one at a time (prototemplate section 9). Where a repository has a capture lock or queue, a session takes it for the run, releases it at the end, and never holds it while idle.
• Load. Every session's builds, Playwright runs and renders share one machine. gt-orchestration section 2 holds the rule for timing checks under load: record uptime beside the reading and rerun a red check once the load drops. While the machine is busy, prefer measures that load cannot change: counts, bytes and deltas.
• Disk. A gt-cloud worktree with its install costs about 6 GB, and 48 leftover worktrees filled the disk on 2026-10-05. Remove a scratch worktree as soon as its work is pushed. gt-ship section 1 gives the checks to run first and the command for removing many at once.
• Cleanup. Cleanup of another session's files goes to that session. Message it, or give Kevin the prompt for its conversation, as he asked for the Codex and gt-cloud logs on 2026-10-05.

Checklist

• [ ] ListAgents, git status, recent commits on the branch and on origin/main, and the lane's notes were read before acting.
• [ ] In a fork, only the newest instruction for this lane was acted on, and the parent's open items stayed with the parent or the lane that owns them.
• [ ] The session works on its own branch, worktree and port.
• [ ] Explicit paths were staged and committed with a pathspec, and the branch was checked before the commit (gt-ship section 2).
• [ ] A shared push was done once, by its owner, and the other sessions reported the sha they found.
• [ ] Other sessions' in-flight files stayed out of the commit and were named in the report.
• [ ] A heads-up went out before pushing a shared main, and the session fetched and rebased after another session's push.
• [ ] A changed rule reached every session that applies it.
• [ ] A relay note carries the branch, tip, worktree, commits, receipts with exit codes, open list, locks, queued deploys and rebase advice.
• [ ] Servers this session started are stopped, locks are released, uptime sits beside timings, and scratch worktrees are removed.

Sources

• Prototemplate: skills/gt-ship/SKILL.md sections 1, 2, 5 and 8; skills/prototemplate/SKILL.md sections 8 and 9; skills/gt-orchestration/SKILL.md sections 2, 6 and 8; docs/SHIP-LOOP.md section 0; docs/handbook/glossary.md (working terms).
• Kevin's gt-cloud memory notes session-lanes-prototemplate, ship-loop-hard-gates, scratch-worktree-disk, lost-work-audit-2026-09, gt-motion-films, world-language-map, blog-lottie-figure, signin-field-transition and landing-hero-agent-button.
• The Claude Code transcripts of the gt-cloud project under ~/.claude/projects/: the fork lineage read from each transcript's inherited sessionId and title records; the 2026-08-06 instruction and the four sessions' responses; the 2026-10-03 handover to Videos; the 2026-09-29 and 2026-09-30 messages between the sign-in sessions; the 2026-10-05 messages from New Onboarding and Dashboard and Videos; and the desktop app's notice that another chat's dev server is out of the Browser pane's reach (2026-09-29). The Codex sessions under ~/.codex/sessions/2026/09/ hold the shared-main audit of 2026-09-22 and the relay of 2026-09-26.
• Kevin's messages to Claude Code and Codex from 2026-07-30 to 2026-10-05, for the rulings quoted above. Quotes keep his spelling.
• Dates are in UTC, as the transcripts record them.

Positioning

The home page hero says GT "builds full-stack localization for apps, docs, and websites" (read 2026-10-05). GT builds every layer of that stack itself:

1. open-source i18n libraries and SDKs for every major framework;
2. context-aware translation APIs;
3. the platform for versioning, editing, review and delivery;
4. Locadex, the agent that internationalizes a codebase and keeps it localized.

Kevin, 2026-07-30: "the whole point is that were a full stack localization, end to end".

• The positioning is the Vercel model applied to localization. GT pairs open-source developer tools with the hosted infrastructure that runs them best (BRAND.md section 2). This is the one comparison GT copy makes (gt-voice, hard rule 2).
• The thesis is "Every product in every language" (BRAND.md section 2). Copy quotes it as written.
• Pricing is usage-based. Legacy translation management systems (TMS) charge per seat and cover part of the stack. Because GT owns the whole stack, it can own the whole customer experience (BRAND.md section 9).
• The careers mission Kevin set on 2026-08-14 said that context and developer-first infrastructure now limit translation quality more than model quality does. The careers page read on 2026-10-05 carries a later mission text without that sentence, so copy states the claim only from a current source.

Audience and the sale

• The audience has two ends, which Kevin calls a barbell (2026-07-30). Developers and small teams start self-serve at one end. Enterprises buy through sales at the other. A page carries enterprise presence and developer comfort together.
• BRAND.md section 9 names the buyer: technical and product executives at growth-stage startups, whose engineering and growth teams use the product. The open source carries a community register and the platform an enterprise register (BRAND.md section 2).
• GT runs a challenger sale (Kevin, 2026-07-30). Many buyers cannot yet tell localization, translation and internationalization (i18n) apart. Pages show what localization does: translated copy, changed code, converted currency, reformatted dates and numbers, and layout rearranged for a script. The terms themselves stay on the page for evaluators who check for them. The docs define them on Key concepts.
• Heroes and demos show the product working. Kevin, 2026-08-11, on the enterprise page: "far less telling, more showing, so same content but less text and more better diagrams".

Products

The React libraries share one API. <T> wraps a block of static JSX, and <Var>, <Num>, <Currency> and <DateTime> mark its dynamic parts. gt() translates a string, msg() marks strings in a data array, and <Tx> and tx() translate content at runtime in server code. The usage rules, including const gt = useGT(); and await getGT() in async server code, are in gt-components and gt-cloud's AGENTS.md.

Context

Context reaches a translation through three layers: the Organization, then the Project, then the Component (Kevin's outline of 2026-07-30; the dashboard guide Defining context for translations, read 2026-10-05). Each layer is inherited by the one below it.

• The Glossary holds terminology: product names, brand names, feature names, technical terms and phrases that stay untranslated. Its standing example is that Locadex is never translated in any locale.
• Custom Prompts hold style: tone, audience, formality, conventions and formatting. A prompt applies to every locale or to one. Kevin's July outline called this half Directives, and the importer still accepts exports that use that label. The dashboard, the API and the pricing page call it Custom Prompts (2026-10-05), and copy uses that name.
• Kevin's component example, from the 2026-07-30 outline: <T context="notification popup, not bread">Click the toast to dismiss</T>.
• An edit to a Context Group applies to new translations. The Apply button on a project's Context page updates existing translations with chosen Glossary terms.
• The Context Management API (org:context:read and org:context:write) and its MCP tools automate groups, terms and prompts.

Enterprise and plans

The pricing page has two plan cards (read 2026-10-05):

• Starter is self-serve with usage-based pricing and a Get Started button.
• Enterprise is marked Recommended and has a Contact Us button.

Both cards list unlimited projects, unlimited users and unlimited languages, and the comparison table follows the cards directly (Kevin, 2026-08-15). The page's diagram sits below the plans. The money format on pricing pages is gt-landing-pages' whole-dollar rule. Onboarding and billing copy about cards and credits follows the plan states the dashboard shows at the time of writing.

Kevin set the four enterprise pillars on 2026-08-15, and the enterprise page carries them (read 2026-10-05). His list named the third pillar Forward-deployed engineers, and the live page heads it Forward-Deployed Support, the name copy uses.

• The enterprise page's section order is governance and SSO, translation review, shared context across teams, forward-deployed support, then the contact form (Kevin, 2026-08-16). A change to the page's sections follows that order.
• Features grouped under one heading share one purpose (Kevin, 2026-08-15).
• The enterprise hero has one button. Kevin cut its second button, Talk to an Engineer, on 2026-08-15.

Copy that must be exact

CLI and agent entry points

The CLI facts below come from the start prompt served at /agent-prompt.md (read 2026-10-05) and from the CLI source on generaltranslation/gt origin/main. A coding agent ran the prompt end to end on a fresh Next.js app on 2026-09-25 with gt 2.22.3 and again on 2026-09-30 with gt 2.23.1. The published CLI was 2.25.1 on 2026-10-05.

• gt login signs the CLI in with the person's GT account. It opens GT's sign-in page in the browser and shows a confirmation page when sign-in completes. gt login --no-browser prints a sign-in URL and a code to use on any device, and an SSH session takes that path by default. gt whoami reports the signed-in account.
• Public writing explains how to sign in and use the product. It leaves out how the CLI obtains, stores or refreshes its tokens, which is the public authentication boundary in the AGENTS.md of generaltranslation/content.
• gt translate --dry-run shows the scope, and gt translate translates it. With translations stored in the repository, the run writes public/_gt/<locale>.json, gt-lock.json and a _versionId in gt.config.json.
• gt init and gt configure ask any unanswered question through an interactive prompt and wait with no timeout. An agent passes --no-interactive (or --json, which implies it) and a flag for every question. A missing answer then exits 1, lists the flags still needed and changes no file. Kevin asked on 2026-10-01 that agents always run the CLI this way.
• The CLI has no --version flag. npm view gt version gives the published version, and the translate banner prints the installed one. gt auth is not a command in current releases.
• A development key belongs in .env.development.local, which next dev loads and next build does not. A production next build refuses to run with a development key present.

The docs serve agents directly (gt-cloud #4499, merged 2026-09-10). gt-website's references/docs.md holds the routes behind them.

• /llms.txt is the curated entry point, /llms-index.txt lists every page, and /openapi.yaml is the API specification. /llms-full.txt, scoped /docs/<scope>/llms.txt files, /AGENTS.md and /sitemap.md sit beside them.
• Appending .mdx or .md to a docs page URL returns the page's raw Markdown twin.
• Every docs page's Copy page menu carries the llms.txt entries (Kevin, 2026-09-11).
• The hero's second button is Setup for Agents (gt-cloud #5049, merged 2026-10-01). It copies the start prompt, whose one source is docs/en-US/overview/for-coding-agents.mdx in the content repository. The same text is served raw at /agent-prompt.md. After any change to the prompt, the CLI or the quickstarts, the prompt is run end to end by a coding agent on a fresh app. Kevin, 2026-09-30: "Agent experience (AX) is a huge deal for us".

The start prompt sets these onboarding rules for an agent (read 2026-10-05):

1. Inspect the repository before asking anything: framework, router, app directory, existing i18n library, GT configuration, source language and build scripts.
2. In a monorepo, choose the app or content directory and run setup there. Setup never runs at the workspace root.
3. Ask for missing decisions one at a time: the source language, the target languages, then the first page or workflow. When the project itself is unclear, ask one question ("What would you like to translate?") with concrete choices.
4. Preserve existing locale choices and reuse an existing i18n setup. The source language is never assumed to be English.
5. Sign in with gt login. The agent never asks for a pasted API key, a password or OAuth tokens, and it writes new keys to ignored files without printing them.
6. Carry the work through setup, translation and verification, then hand off what changed, the project and locales, what was verified and what the person still has to do. Auto-merge and paid plan changes wait for the person's direction.

Repositories

File-level maps stay with their owners: gt-cloud's AGENTS.md and .agents/skills (gt-landing, gt-dashboard, gt-api, gt-admin), gt-website for the landing and gt-brand for the identity files.

Site behaviour

gt-website owns the site's routing. Its references/docs.md holds the unsupported-locale redirects, the docs near-miss ladder and suggestion page (gt-cloud #4359), the markdown twins and the step order in src/proxy.ts. The rules below are not in that reference. Each was read on gt-cloud's origin/main and checked on production on 2026-10-05.

• Staging builds translate one locale. apps/landing/staging.gt.config.json lists es only, and gt.config.json keeps the production roster (es, fr, zh, ja, it, ru and en-GB beside en-US). Kevin, 2026-08-08: "only es for staging".
• Missing localized content falls back to en-US. A legal page renders the en-US copy in place, an untranslated docs page serves the default language, and a blog slug absent in a locale redirects to the en-US post. Kevin, 2026-08-17: "fix pages that are breaking from like en-GB".
• The docs suggestion page answers HTTP 200 with noindex, nofollow by design (gt-cloud #4359). A real 404 needs the not-found boundary, and under the force-static root layout that boundary never sees the requested slug. The blog checks frontmatter aliases and close matches before it renders its own suggestion page.

Sources

• Prototemplate: BRAND.md sections 1, 2 and 9; gt-brand sections 1, 2 and 8; gt-website with references/docs.md and references/pages.md; gt-voice; gt-landing-pages; gt-components.
• gt-cloud at origin/main e17fce499 (2026-10-05): AGENTS.md, .gitmodules, apps/landing/gt.config.json, apps/landing/staging.gt.config.json, apps/landing/src/app/[locale]/docs/[variant]/[...slug]/page.tsx, apps/landing/src/app/[locale]/blog/[slug]/page.tsx, apps/landing/src/lib/legal.ts, apps/landing/src/components/landing/sections/global/Global.tsx, apps/landing/src/components/pages/enterprise/services-landing/GovernedExplorer.tsx, scripts/deploy-landing.sh, .agents/skills/gt-landing/SKILL.md; pull requests #4359, #4499 and #5049.
• generaltranslation/gt at origin/main a16ae03c6 (2026-10-05): packages/, packages/cli/src/cli/base.ts, packages/cli/src/auth/__tests__/oauth.test.ts, packages/cli/src/cli/__tests__/initOnboarding.test.ts, packages/core/src/runtime.ts, packages/next/src/server.ts, packages/next/src/index.types.ts.
• generaltranslation/content at origin/main (2026-10-05): AGENTS.md, Public authentication boundary.
• generaltranslation.com, read 2026-10-05: the home page, /en-US/pricing, /en-US/enterprise, /en-US/careers, /ja, /llms.txt, /llms-index.txt, /agent-prompt.md, /openapi.yaml and the docs guide Defining context for translations.
• npm and PyPI package pages, and the public repository list of the generaltranslation GitHub organization, read 2026-10-05.
• Kevin's rulings: the full stack, the barbell and the challenger sale, and the context layers (2026-07-30); layout, review surfaces, formatting and region names (2026-08-06); locale heroes and staging (2026-08-08); showing over telling (2026-08-11); the mission text (2026-08-14); the enterprise pillars and CDN copy (2026-08-15); the enterprise order and the pricing cards (2026-08-15 and 2026-08-16); en-GB routing (2026-08-17); the copy page menu (2026-09-11); the agent button and AX (2026-09-30); the interactive CLI (2026-10-01); geography by language (2026-10-03).

Company and products

Repositories and places

Design vocabulary

Material and motion

Gates and tools

Working terms

Kevin's shorthand

Retired terms

These terms still appear in older messages, commits and skills. The ruling that retired each one, its date and its reason are recorded in decisions.md.

Sources

• Prototemplate: BRAND.md sections 1, 2, 5, 7 and 8; DESIGN.md sections 1 to 5, 7, 8 and 10 to 14; ARCHITECTURE.md; docs/ARTIFACT-PICTURES.md; package.json; .oxlintrc.json; src/lib/directions.ts, src/lib/surfaces.ts and src/components/viewer/tokens.css; scripts/lint-practices.mjs; motion/kit/gemsmoke.js (header); all read 2026-10-05.
• Skills: prototemplate, gt-aesthetic, gt-ship, gt-lints, gt-dither, gt-landing-pages, gt-website, gt-components, gt-brand, gt-deck, gt-films, gt-motion, gt-diagrams, gt-orchestration, gt-reporting, gt-local-dev and gt-explorations. The handbook pages gt-product-map.md, operating-principles.md, multi-session-playbook.md and decisions.md hold the procedures behind the working terms and the rulings behind the retired ones.
• gt-cloud at origin/main e17fce499 (2026-10-05): package.json (dev-env), apps/landing/package.json (dev), apps/dashboard (components/frame/PlateFrame.tsx, components/brand/, the context routes), packages/node/src/database/featureFlags/, packages/db/prisma/schema/flags.prisma, apps/admin/src/components/featureFlags/, apps/landing/src/lib/ (studio-field.ts, horizon-field.ts, report-card/) and apps/landing/src/components/blog/; the branch k/dashboard-dev-gallery at ebb900124.
• The gt repository: packages/*/package.json for the package names.
• Kevin's messages to Claude Code and Codex from 2026-07-20 to 2026-10-05 and the session transcripts behind them, for the shorthand and the working terms.