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 pnpm lint:registries 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.

The same rule applies inside a change. Use the platform feature that removes code before adding code, such as a CSS grid row from 0fr to 1fr for an auto height in place of a measured one. When a review asks to test machinery that need not exist, remove the machinery. Kevin, 2026-10-06, on a caption card that measured its own height: "Beautiful but don't complicate. Always simplify."

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.

On a page that already exists, "enhance" keeps the page and adds to it: the copy, the sections and the pieces Kevin likes stay. Kevin, 2026-10-08, after a rebuild of the careers page dropped its hero and its copy: "keep the original write up".

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. pnpm lint:public scans every file for key shapes, machine paths and the terms on a private denylist, and the pre-push hook in .githooks/ runs it.

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; always-simplify (2026-10-06) and careers-team-photo (2026-10-08), read 2026-10-10 for the additions to rules 12 and 15.

The overall bar

• GT's own finished work is the reference. The brand deck governs product surfaces, and the shipped site, generaltranslation.com, governs landing and marketing pages (gt-aesthetic, section 1). The deck is built from deck/ and served at /deck, and the site is built from apps/landing on gt-cloud origin/main. From 2026-08-06 the Dossier (/d/singularity-dossier) governed the site (Kevin, 2026-08-06: "dossier is indeed our completed version and treat it as such"). On 2026-10-07 Kevin ruled "fix the dossier references", and the Dossier stays in the gallery as the direction the site grew from. Before the deck and the Dossier 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/check/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), 2026-10-07 (the shipped site as the site's reference).

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

Plan facts come only from the public pricing page, https://generaltranslation.com/pricing, quoted as it read on 2026-10-10. Plan rules the page does not state, such as what a new account receives, are internal and stay in gt-cloud's gt-dashboard skill.

• The lead: "Start for free with usage-based billing. Unlimited projects and users on every plan."
• Starter: "$0", "For individuals and small teams". It lists unlimited projects, users and languages, the Translation Editor, the GitHub Integration, the Locadex AI Agent and usage-based pricing, with a Get Started button.
• Enterprise: marked Recommended, "For large teams with complex localization needs". It lists unlimited projects, users and languages; "Dedicated FDE hours to build any workflow for your use case."; "Custom integrations, webhooks, and tailored automation."; and "SSO, RBAC with custom permissions, SOC 2 and ISO 27001 certificates", with a Contact Us button.
• The comparison table: a Platform Fee of $0 on Starter and Custom on Enterprise, and Usage Rates that link to https://generaltranslation.com/pricing/usage on Starter and read Custom on Enterprise. Its rows name the core products (Locadex AI Agent, Custom Workflows, Translation CLI, Context Platform, Translation CDN, Version Branching), the platform (languages, projects and users unlimited on both plans, Context Groups, Keyword Glossary, Custom Prompts, Translation Editor, Custom Roles, Webhooks, SOC 2 Type II and ISO 27001 certification, SSO over SAML and OIDC) and support (GitHub, email, Discord, Slack and phone). The table marks which plan has each row with icons, so copy that says which plan includes a row reads the live page first.

The comparison table follows the cards directly (Kevin, 2026-08-15), and the page's diagram sits below the plans. The money format on pricing pages is gt-landing-pages' whole-dollar rule.

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.

Public surfaces

Every address below answered HTTP 200 on 2026-10-10. BRAND.md section 8 says how the identity applies to each kind of surface.

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-10: /pricing (section 5) and the addresses in section 10, each fetched with curl. 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).
• The list of brand surfaces sent to the brand agency on 2026-09-04, from which section 10 is rebuilt and checked against the live addresses.

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): 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.

Using the log

• The later ruling holds. Guidance with an earlier date in a memory note, a transcript or a skill gives way to a later row here, and the change that finds the conflict corrects the stale text. When a skill changed after a row and the two disagree, the skill holds and this log needs a fix.
• Design verdicts are recorded in full in verdicts.md in gt-aesthetic, with Kevin's words and what was wrong. Their rows here are one line and link there.
• The skills named in the last column hold the procedures. A row states the ruling and where it is enforced.
• Each path names its repository: gt-cloud, Prototemplate, or content: for generaltranslation/content, which holds the docs and blog source.
• A row quoting a transcript carries the day the transcript stamped on Kevin's message, which is UTC. A design verdict row carries its date in verdicts.md, and a row with no message behind it carries the date its skill or memory note gives. Those two use Kevin's local date in California, so they can sit one day before the UTC stamp of the same evening.
• Agents do not change a standard on their own. Bring Kevin the current row with a recommendation. When he rules, add a dated row that names what it replaced, and update the lint, gate or skill that holds it in the same change.

July and August 2026

September 2026

October 2026

Superseded July practices

Notes, commits and transcripts from July 2026 still describe these practices, and no row above names them. The Replaced column of the tables above covers the other July practices: Lenis, headings with periods, Switzer and the July bar.

Recorded elsewhere

• Version pins, ports, open PR states and other temporary technical states describe the code on a date and change without a ruling. They live in gt-website section 8 and the Sources lines of the skills. The landing's Next.js pin is one of them.
• The full wording of each design verdict, with what was wrong and what Kevin approved, is in verdicts.md. The table in gt-aesthetic section 2 summarizes it.
• The Sources lines of gt-voice, gt-website, gt-ship and gt-lints list the directives each skill was written from. This log puts every ruling in one dated list with the practice it replaced.

Sources

• Kevin's messages to Claude Code and Codex from 2026-07-20 to 2026-10-05, about 5,800 in all; his rulings on the page heads, the corners and the brand's reference on 2026-10-05 and 2026-10-06, and on the Dossier references, the titles, the addresses and the films on 2026-10-07; and the session transcripts behind them for context. Quotes keep his spelling. Three quotes come from messages the corpus cut short or queued with an image, and were read in the transcripts: the 2026-08-11 eyebrow line, the 2026-09-25 screenshot line and the 2026-09-30 hero line.
• Prototemplate, read 2026-10-05: skills/gt-aesthetic/references/verdicts.md and SKILL.md sections 1 and 2; skills/gt-ship sections 1 to 8, references/pr-body.md and scripts/pr-size.mjs; skills/gt-lints and references/gt-ui-rules.md; skills/gt-website sections 3 to 8 and references/docs.md and references/pages.md; skills/gt-voice, Headings and casing; skills/gt-brand sections 1 to 5 and 7; skills/gt-components; skills/gt-motion sections 1 and 6; skills/gt-dither sections 5 and 7; skills/gt-landing-pages; skills/gt-reporting section 5; skills/prototemplate sections 1 and 8 to 10; BRAND.md; DESIGN.md section 3; ARCHITECTURE.md, The mirror; LICENSE; README.md; docs/ARTIFACT-PICTURES.md; package.json; .oxlintrc.json; scripts/lint/practices.mjs; scripts/lint/type.mjs in the working tree; commits 502dc0a and 08b33c6 (2026-07-31 Pacific), 229d413 and c064945 (2026-09-08).
• gt-cloud at origin/main e17fce499 (2026-10-05): .oxlintrc.json and tooling/oxlint-plugins/gt-ui.ts, apps/landing/src/app/robots.ts, apps/landing/vercel.json, apps/landing/gt.config.json, apps/landing/staging.gt.config.json, scripts/deploy-landing.sh, packages/node/src/database/featureFlags/isFeatureEnabled.ts, apps/admin/src/components/featureFlags/ and packages/ui/src/components/pricing/dollar-format.ts; merged PRs #4213, #4359, #4773, #4785, #4795, #4828, #4887, #4909, #5007 and #5049; open PRs #4977 and #5133.
• generaltranslation/content at main, read 2026-10-05: DOCS-SKILL.md ("When something gets its own top-level section" and the rule for descriptions); PR #501.
• Kevin's wiki: the humanizer skill.
• Claude Code memory notes for gt-cloud, which are private to Kevin's machine: redesign-v0-verdict, brand-questionnaire-directives, variants-program-state, lighthouse-round-conventions, gt-commit-identity, lost-work-audit-2026-09, agent-readable-docs, pricing-money-format, explorations-stay-local, landing-inter-only, landing-icon-rule, agent-prompt-test, pr-screenshots-and-gallery, landing-hero-agent-button, speed-marks-set, onboarding-parity-rule, pr-stacks-2026-10, artifact-picture-standard, world-language-map and prototemplate-hub-skills. Added on 2026-10-10 from an allowlist of standing rulings, each row written fresh: landing-cta-conventions, writing-for-strangers, pr-size-discipline, always-simplify and careers-team-photo.
• The review of the system v2 plan on 2026-10-10: Kevin's answers and the recommended defaults he accepted, for the 2026-10-10 rows.
• Kevin's request of 2026-10-14 for the SEO system and the docs site, and his answers to the plan's open questions that day, for the 2026-10-14 row.

Read in this order

1. This file.
2. Operating principles, before the first task.
3. The skill for the task, from the routing table below. Its Review checklist is the bar for the work.
4. Quality bar, before showing Kevin anything or shipping it.
5. Decisions log, before changing a standard or when two sources disagree.

The principles in brief

The operating principles hold all eighteen with their sources.

1. Finish everything that was asked. "Continue" resumes every open item and every open lane.
2. Do every step an agent can do, and collect what only Kevin can do (a login, a payment, an approval) into one numbered list.
3. Change only what was asked, keep what he approved, and after a rejection restore the exact earlier state.
4. Fix the whole class of a defect, and add the lint or test that keeps it from coming back.
5. Measure the rendered result at the spot Kevin flagged. A page that loads is a proxy check and proves nothing about the look.
6. Show the result before he asks: before and after crops, a running URL, a gallery of takes.
7. Use real content and real assets, sourced and credited. Invent no quotes, numbers or logos.
8. Ship nothing unnecessary, and prefer the free and cheap design.
9. Keep secrets in protected files, and keep private facts off this public repository.
10. Codify what worked as a skill, a document or a lint that any agent can load.

Which skill to load

The skills live in skills/<slug>/SKILL.md. In this repository they are already linked into .claude/skills and .agents/skills, so Claude Code, Codex and other Agent Skills loaders find them by name. skills/README.md lists them by area. The Tools column names the pnpm commands for the task, run from this checkout; docs/TOOLS.md, served at /handbook/tools, lists every command and the scripts the skills bundle.

The handbook

docs/handbook/, also served at /handbook:

• Operating principles: the standing rules and where each procedure lives.
• Quality bar: the bar for each kind of artifact and for done.
• Multi-session playbook: lanes, forks, shared checkouts, collisions, Claude and Codex on one main.
• GT product and architecture map: what GT sells, the copy that must be exact, the repositories.
• Glossary: the working vocabulary and where each term lives.
• Decisions log: Kevin's dated rulings and what each replaced.

On the site the canon follows these six in the same book: this guide, BRAND.md, DESIGN.md, ARCHITECTURE.md, the ship loop, the tools, the libraries with the build log, the graphics pipeline and the artifact pictures. The docs site at /docs explains in ten pages how the hub works.

House rules

• Writing. Plain technical English: complete declarative sentences, no em dashes, no metaphors, no "X, not Y" pairs, no signposts and no eyebrows. Headings are plain nouns in sentence case with no trailing period (gt-voice).
• Type. Inter is the only typeface, the self-hosted rsms InterVariable, at weight 500 or less, read through the type tokens. pnpm lint:type holds it (gt-brand).
• Lines. Every line is drawn once by one owner, in one of three roles (DESIGN.md section 2). pnpm lint:lines:shell holds it.
• Corners. Rounded controls, square shells: controls and cards at 6px, chips at 4px, and only the shells square (DESIGN.md section 2, Corners). pnpm lint:radius holds it.
• Pages. Every page with a book head follows one structure (DESIGN.md section 4, The book page). pnpm lint:heads holds it.
• Explorations stay local. New directions and redesign rounds stay uncommitted or on a branch until Kevin reviews them on localhost and says to land them (gt-explorations, gt-ship section 8).
• One session per lane. Several sessions share this checkout. Work that belongs to another lane goes to that session by name, motion/ belongs to the Videos session and stays untracked, and nobody runs git add -A or git add . (docs/handbook/multi-session-playbook.md, prototemplate section 8).
• Commits. Stage explicit paths and commit with a pathspec. Prototemplate commits author as Kevin with his GitHub noreply address and keep the session's Co-Authored-By: trailer (docs/SHIP-LOOP.md section 6). gt-cloud commits carry the repository's configured General Translation work identity, which its Vercel deploys require; never set that identity globally (gt-ship section 2).
• Landing. Kevin merges, or says to merge. In this repository nothing reaches main until he has reviewed it on localhost.
• Privacy. The repository and the site are public. No keys, tokens, account ids, email addresses, personal details, unannounced plans or business figures go into a file, a capture or a commit (operating principle 18).

Working in this repository

pnpm install
pnpm run doctor               # what this machine is missing to run the tools
pnpm dev                      # http://localhost:3005
pnpm exec tsc --noEmit        # 3 to 5 minutes
pnpm lint:static              # every lint and test that needs no server (the lane and CI gate)
pnpm lint:all                 # lint:static, then the live audits against PT_BASE (default 3005)
pnpm check:pages --preset quick --pages <id> # eight devices in dark and 1440x900 in light on the touched pages

• Reuse the dev server on 3005 when it is running, and never build in the shared .next. The build gate runs in a scratch worktree with && (gt-ship section 8).
• The browser lints launch the Chrome for Testing build playwright-core installs (pnpm exec playwright-core install chromium); CHROME_PATH overrides it.
• Generated files change only through their scripts: pnpm build:skills (src/lib/skills.ts, skills/README.md), pnpm build:updated (src/lib/updated.ts), pnpm build:deck, pnpm build:marks, pnpm build:tools (docs/TOOLS.md); pnpm gen:all runs every one of them. pnpm build:motion runs only when the Videos session hands a film over (gt-films section 11).
• README.md maps the routes, ARCHITECTURE.md the code, DESIGN.md the visual laws and BRAND.md the identity.

Using the hub in another project

README.md's "Import this into another project" section gives the commands. In short:

1. Copy skills/ and scripts/skills/install.mjs to the project's root, then run node scripts/skills/install.mjs --project . --dry-run there and again without --dry-run. The skills land as relative links in .claude/skills and .agents/skills, the layout this repository uses.
2. Copy AGENTS.md, BRAND.md, DESIGN.md and docs/handbook/ beside them, so every link between the skills, the canon and the handbook keeps working, and add a CLAUDE.md that imports AGENTS.md.
3. Edit the copied AGENTS.md: the project's name and purpose, its own commands and ports, its lanes, and its own gates. Keep the principles, the routing table and the house rules that still apply.
4. Read the current canon by its address on the site (www.prototemplate.com/handbook/design, /handbook, /skills/<slug>), and copy the folders again to take later changes. The docs site's last page, www.prototemplate.com/docs/template, explains how to lift the docs site itself into the project.

Ending a turn

A turn that changed something ends the way gt-reporting section 4 sets out: the answer to what Kevin asked in the first line, what shipped with its exact state, something he can see, a numbered list of what only he can do, and the risks, numbered so he can answer by number.

The name

General Translation was chosen deliberately, in this order:

1. Ambition. Like General Motors or General Electric, the name says we intend to be the trustworthy, technologically innovative number one in the category, an enterprise in the old sense.
2. Generality. A reference to "artificial general intelligence": general AI models outperform specific translation models because they understand context and can be directed.
3. Distinction. Every other localization company seemed to begin with an "L".

The naming system

The idea

Every product in every language. Native-level speed and quality, from day one. That's the whole thesis, executed insanely hard.

The positioning: the Vercel of localization. Two halves designed together: open-source developer tools (the Next.js of the analogy: the gt libraries) and closed-source infrastructure (the Vercel: context-aware translation APIs, versioning, editing, integrations, agents) that is the best-in-class way to use those tools. Because we build the entire stack, we can promise what point solutions can't: consistent, high-quality translation across a whole business, integrated in an afternoon.

Two registers, one family: the open source should feel community-owned; the platform should feel enterprise-grade.

The values, which the visual identity must carry:

• Engineering-first. Built by people with deep technical roots, for the world's best engineering teams.
• Craft. We care about the difference between drawn-once and drawn-twice lines. That is literal: see the line law in DESIGN.md.
• Infrastructure-grade. Reliable, fast, secure. The brand should feel like something an enterprise stands on, not an app it tries.
• Cosmopolitan. Urbane, sophisticated, connecting the world and its languages. Language is our material, not just our market.
• Hand-crafted. The brand reads as made by people who care, not assembled from a template.

The character

The brand carries itself like a "fullstack director": it writes the script and it pushes the camera. Creative and technically innovative, never one without the other. On time, under budget, over-delivering, always working with the best people, with a keen sense of the market and for making things people love.

Personality (working readings, from the completed system)

Aesthetic (working readings)

These are read from the shipped system for basement to confirm or push.

Voice

Measured, declarative, precise, quietly confident. Every sentence is complete and makes one claim. A caption states the mechanism: "A framed cell has a 1px padding reveal that shows the ground underneath, so the cell draws no border." Copy uses no exclamation marks, no hedging and no marketing adjectives where a fact would do. Wit is allowed when it is precise. Technical terms are used precisely and sparingly, then explained plainly. The register sits closer to a well-written spec or a good engineering blog than to marketing copy, and the copy is about the product.

• Say: "Translations are generated at build time and deploy with the app."
• Not: "Supercharge your global growth with cutting-edge AI!"

The mark

The GT monogram (/brand/gt-logo-light.svg, gt-logo-dark.svg + transparent PNG variants): every stroke of the mark is two parallel lines, the doubled-line grammar at brand scale. Locadex carries its own mark (/brand/locadex-mark.svg).

Rules:

• One ink. The mark renders in ink on paper or paper on ink. Never a third color, never a gradient, never a shadow.
• The dark surface inverts the drawn mark's ink, either as an alpha mask taking the surface's ink or as a clean invert. The mark is a drawing, not a picture.
• In illustration systems (the iso family), marks render as alpha masks so the shape takes the surface's ink; the sanctioned flourish is the Bayer-dithered specular shimmer (DitheredMark), never a GIF, never a filter glow.
• At text size, the wordmark sits inline with prose at the cap height of the line it lives in, as in the generaltranslation.com hero's "GT builds full-stack localization for apps, docs, and websites".
• The identity must survive compression: a favicon, a CLI banner, a README, a syntax-highlighted code block. Developers meet the brand in a terminal as often as on a website.

Color

Four absolute colors (ink #070707, raised ink #101010, titanium #8a8f98, paper #ffffff) plus exactly one spectral accent per page (the working accent: #2f5ce0; its dark-band lift #86a8ff). Structural color everywhere derives from the four as alpha steps; dark mode is a pure token remap. Full law: DESIGN.md §1. The accent is a controlled edge, never a wash; one bright white; depth from lines and material, not shadows.

Type

• Inter is the one typeface: display, interface and text. Headlines, interface chrome, captions, long-form reading and documentation prose are all set in it. The build is the real rsms.me Inter (v4.1 variable, roman + italic, opsz axis), self-hosted rather than loaded from Google Fonts.
• Headings use weight 500 at most. Display text never goes bolder than 500; long-form text is set at weight 400.
• Multilingual-first. Headlines, UI, and marks must hold up in CJK, RTL, and Indic scripts as well as Latin. A wordmark or layout that only works in English contradicts the company. Inter covers Latin, Greek and Cyrillic; other scripts fall back to the system face for that script, and every layout is checked in them. Licensed type needs credible CJK and RTL coverage, or well-matched companion faces.
• Inter is the working typeface for the identity project. It is not a final decision. Alternatives remain open if they satisfy the script-coverage constraint.
• Monospace is an instrument voice, not a brand voice. It appears where code artifacts appear (tokens, terminals, file paths, small labels in technical diagrams and product UI) and nowhere else, and even those labels are avoided where possible. The direction explicitly avoids monospace as the brand voice in headlines, body, and marketing.
• The prototemplate chrome (this site's own serif/grotesk pairing) is the lab's stationery, not the product brand.

Language as material

The signature device: glyphs, characters that make up greater wholes. Writing systems are the raw material the brand keeps returning to:

• The sentence reassembler (EverySentence): a headline dissolves into glyph dust and reassembles in the next language. Matter is conserved; the same swarm becomes the next sentence.
• The glyph field: rain from eight writing systems condensing into the word "language," script after script.
• Locale pills (LocaleTag): flag print + code, the one way a locale is named anywhere. The prints are SVG, never emoji; a flag is a functional data chip, never decoration.
• The 1-bit Bayer language: density as ordered dither, never alpha veils. This is the texture of the brand.
• The doubled line: every connector one path stroked twice; the mark's own grammar running through every diagram.

All of them run live in the build log on /handbook/libraries, with their APIs.

Where it ships

The identity is applied on four kinds of surface today.

• The site. Marketing pages ship on generaltranslation.com, built in gt-cloud's apps/landing. The production landing page (gt-cloud #4213) has been canonical for the site since 2026-08-11.
• Product surfaces. The dashboard, onboarding, the sign-in plate and the Prototemplate shell have followed the brand deck (/deck) since 2026-09-25.
• Motion. The films on /motion apply the identity to film: the blog trailers, the product films and the translation-history series.
• The marks. The speed marks chosen on 2026-09-29 (/marks) sit beside the doubled-line monogram, which stays the current mark (section 4). The title badges in the /brand and /marks heads cycle through a selection of the marks on /marks.

When in doubt about how the brand behaves, read the shipped surface the work belongs to.

The site grew from the direction of the Dossier (/d/singularity-dossier). It stays in the gallery with the other directions as the working record of how we got there. From 2026-08-06 to 2026-10-07 this section named it the completed reference for the brand.

Context for partners

• Industry: AI developer tools; the full stack for localization, meaning i18n libraries, context-aware translation APIs, and the infrastructure for versioning, editing, and integrations.
• Audience: technical and product executives at growth-stage startups; their engineering and growth teams are the users.
• Public names: a customer or partner is named only where generaltranslation.com shows it. On 2026-10-10 the home page showed Cursor, Ramp, Mintlify, Profound, Partiful and ClickHouse, and a quote from Theo, CEO of T3 Chat. /enterprise showed Ramp with 11+ locales across its dashboard, landing page and iOS, Cursor with 14+ across web and docs, Profound with 47+ across platform and docs, Partiful with 2+ across web, iOS and Android, and Sierra with 7+ across web and GTM, with a quote from Lee Robinson, VP of Developer Experience at Cursor. /enterprise/contact had partner pages for YC, Mercury, Slash, speedrun, a16z and The Residency. Every other name stays off public surfaces, this repository included. Read the live site again before a new surface names anyone.
• Against: legacy TMS (seat-based, partial-stack). GT is usage-based and owns the whole stack, so it can own the whole experience.
• Admired: Vercel, Resend, Stripe, for reliable, developer-first infrastructure with engineering excellence and customer experience.
• Direction: International Style discipline with Art Deco's future-embracing stance. Swiss grids, blueprints, boxes, no rounded corners. Water and ocean as the recurring theme, connecting the globe. Bespoke material textures (reference: materialarchiv.ch).
• References: Josef Müller-Brockmann and the Swiss poster tradition; Otl Aicher's Munich 1972 pictograms; Vignelli's subway map; split-flap departure boards; undersea cable maps and nautical charts; the Rosetta Stone; the Chrysler Building; Powers of Ten; vintage National Geographic; Borges' Library of Babel; the Whole Earth Catalog; transit signage; NYRB Classics; Dieter Rams; vintage Olympics stamps.
• Avoid (final): - monospace as the brand voice in headlines, body, or marketing; small mono labels inside technical diagrams and product UI remain instruments, avoided where possible. - smooth scrolling, scroll-hijacking, and inertia libraries; native scroll everywhere. - robot and sparkle iconography for AI. - the flag-soup cliche; flags are functional data chips only, printed as SVG, never emoji. - iridescent AI gradients and glassmorphism. - eyebrow text that has not earned its place; three stacked lines saying the same thing is noise, functional tags and labels are fine. - em dashes in rendered prose.

The four-color system

Four absolute colors, declared once in src/app/globals.css:

• Structural color everywhere derives from these plus alpha: every text step is ink or white at some alpha, every hairline is titanium at some alpha, every hatch is a thin ink or white veil.
• Each page adds exactly one spectral accent (toolchain: #2f5ce0; its dark-band lift: #86a8ff). One bright white. An accent is a controlled edge, never a wash.
• Pages never touch the raw values. Each root class (.pt-root, .toolchain-root, fork roots) publishes a semantic layer — surfaces, ink steps (-2/-3/-4), hairlines (--*-hair, --*-hair-2), hatch — and everything downstream reads those.
• Dark mode is a token remap, nothing else: under [data-theme='dark'] <root> the paper family collapses onto ink, ink flips to white, and hairline alphas rise so a 1px seam survives between two ink surfaces. One surface family in the dark, the way light mode is one white.
• The second surface: light diagrams sit on exactly one sanctioned second surface (--tc-plate), mirroring the ink / raised-ink pair dark mode runs on. --tc-panel (#101010) is the one dark artifact surface for code, config, and diffs.

The line law

Structure comes from hairlines, and every line is drawn exactly once. The auditor (scripts/lint/lines.mjs) enforces it mechanically — see docs/SHIP-LOOP.md. Four defect classes:

1. Doubled lines — two parallel strokes from different owners within 4px, including coincident strokes that composite darker than either.
2. Missing seams — section and row junctions no rule closes.
3. Self-stacks — a translucent border over the element's own translucent background. Fix: background-clip: padding-box, everywhere.
4. Invisible seams — rules that exist geometrically but sit within a few RGB steps of the surface they cross.

Ownership

• Exactly one thing draws the page rails for any section — a rails wrapper, or the section's own full-bleed pair. Never both. The pair is the column's inner pair only: one hairline at each column edge, nothing outside it.
• The row owns every structural line; cells never draw borders that parallel a row seam. A framed cell has a 1px padding reveal that shows the ground underneath, so the cell draws no border.
• Flush at the rail: where a row meets a line that already exists, the cell sits flush and that side's reveal is dropped. A reveal never runs beside a rail; a border never runs beside a seam.

The named antipattern

The overlap: two owners each drawing a real line along the same edge, compositing into a band darker and thicker than any line the system allows. The auditor cannot see SVG strokes — reconstructed lines come from computed CSS — so figures must be checked by eye at 2× pixel crops of the junctions.

Sanctioned devices

• The diagonal-hatch band marks the boundary between a book's front matter and its first section, once per book: 42px of repeating-linear-gradient(-45deg, transparent 0 6px, var(--pt-hatch) 6px 7px) between two hairlines it draws itself, border-block: 1px solid var(--pt-hair) (.pt-book-band, BookView.css). Its rules and its hatch run across the whole stage, as every rule of a book does (see The reading column), and nothing else draws a line within 4px of either rule; the first section's divider draws no rule of its own. The gallery's article (.pt-hatch, prototemplate.css) is the one place a band draws only its bottom rule, because every section there draws its own bottom rule and owns the band's top seam.
• Border crosses: where two hairlines must legitimately cross, a small plus seated exactly on the intersection (ink, 1px, non-scaling) declares the crossing deliberate — the one ornament a junction is allowed.
• The doubled line is the one sanctioned double — one owner, one path, stroked twice (see §5). The auditor's allow list holds deliberate devices by name; everything else stays strict.
• The fixed sheet's ring is the one sanctioned doubled line in chrome. It is the edge of a fixed-size artifact: a slide, the gallery's live 1440x900 exhibit, the compare rig's panes, and the live page on /directions/<slug> (.dr-sheet). The shell draws it as a 1px --pt-hair border on .sheet, a 1px paper gap from the padding of .sheet-mat, and a 1px --pt-hair-soft outline on the mat, with no shadow, on the --pt-plate letterbox of the fixed stage, as the deck's slide view draws it. A reading page has no ring and no plate. The active thumbnail frame and the active book page frame carry the same border plus offset outline. The auditor allows them under sheet, thumb-frame and page-frame.

The reading column

A reading page sits straight on the stage's paper. That covers the book mode of /brand, /handbook, /motion, /graphics, /skills and /marks, their record pages, /directions/<slug> and /archive/<slug>: every route that renders Sheet variant='flow'. Its column is the deck's book column (deck/parts/head.html .book-in): 1280px at most and centered in the stage, with --pt-col-pad-x (56px, 16px under 900px) on each side, --pt-title-clear over the title and 120px (80px under 900px) under the last block. The column draws no border, no ground and no mat. The toolbar's bottom rule is the only line above the title, and the sidebar's right edge is the only line beside the page. A fixed-size artifact inside a reading page keeps a frame, because the frame is its edge: the live page on a direction page keeps the fixed sheet's ring, and a capture takes the frame role with the card corner. Kevin asked for this on 2026-10-06, after the grey mat had made every page a framed picture of a page.

Every shell rule written for 900px and under also matches a phone on its side, (pointer: coarse) and (max-height: 500px), and ViewerShell.tsx isNarrow() reads the same query: a 932x430 phone gets the phone's composition and touch sizes (the list as the overlay, 44px book links) instead of the desktop list column of 28px rows. A tablet is taller and keeps the desktop composition.

Every structural horizontal rule of a book runs across the whole stage, from the sidebar's edge to the stage's right edge: the mast's rule, the contents rows, the band and the dividers, the full-width list rows of /skills, /graphics, /motion, /marks and a direction page, an archive record's rows, and the rule over a blog post's footer. The element keeps its 1px border for layout and paints it as a border image outset past both ends (--pt-bleed-top, --pt-bleed-bottom and --pt-bleed-block in tokens.css); the outset never scrolls, and the scroll region clips it at the stage's edges. A rule that drops its border also writes border-image-source: none, because the image ignores border-width and the build empties the shorthand border-image: none (lint:practices holds this). Under forced colors the hairs take CanvasText. A contents row is one line: the first link of each row draws it and the others draw none. Rules inside the content keep their measure: the head panel's rows, tables, prose lists, the --- rule, ledgers and file lists. Kevin asked for full-width rules on 2026-10-07.

Line law for chrome

Chrome is everything the viewer shell draws around content: the toolbar, the sidebar, the index panel, the search, the fixed sheet's ring, the grid, the book frame, the help card, the direction corner, and the standalone deck viewer's own chrome. Every rule in chrome is 1px, drawn once, in one of three roles, and this is part of the identity: a page reads as Prototemplate because its lines are single and their weights mean something.

The three roles, and only three:

The weights carry meaning. A frame at 0.62 alpha is the darkest line in chrome because it holds a picture in place: the eye must find the edge of a capture against the paper around it. A large surface (a fixed sheet, a card, a panel, a head) is not a picture; it is the paper itself, so its edge is the structural hairline, and its outer ring (where it has one) steps down again to the row weight. A fixed sheet drawn in the frame weight reads as a boxed image, which is the bug Kevin named in round six ("make the borders around these areas the proper border colors"). The help card is the one card that keeps the frame weight: it floats over a scrim, where the hairline would vanish.

Nothing in chrome sets a border color from any other token or literal. --pt-ink appears on a border only as a state: a pressed button (.is-on), the active thumbnail or page frame (.is-active), the count while it is being edited, the solid call to action, the sidebar's current thumb on its rail, and a field while it holds focus. Book heads, table headings and the deck surface index's group headers draw --pt-hair, never ink; the sidebar's group headers draw no rule at all. Outlines are rings: the three roles, ink for focus and active rings, paper for a ring on an ink plate.

Where two bordered components touch, exactly one draws the line:

The auditor enforces this from computed CSS. pnpm lint:lines:shell walks /, /brand, /compare, /archive/<first slug>, /directions/<first slug>, /skills, /skills/<first slug>, /handbook, /motion, /motion/<first package>, /graphics, /marks, /d/production and /deck (the deck's own document) at 1440, 1280 and 390 in both themes against the dev server on port 3005, with the list toggled, the index panel open, the search open, and the grid and book modes on / and /deck. It fails on any doubled line (two owners within 4px), any junction (two owners coincident on one seam), and any border color in chrome outside the three roles. The sidebar's rail is a masked box the walk cannot see, so the auditor reads its vertical runs from its path (data-rail-path), holds its ink to the row role, and fails a state audited with the list open in outline density when the rail layer is not live. pnpm lint:all runs it. The allow list in scripts/lint/lines.mjs names every sanctioned multi-stroke device with its reason inline; for chrome those are the fixed sheet's ring (sheet: a hair border, a paper gap, a hair-soft outline, on /compare, in slide mode and around a direction's live page), the active frames (thumb-frame, page-frame, the sidebar's site tiles as pt-tile) and the hover preview's mat (pt-preview).

Scroll regions belong to the same law: one thin scrollbar everywhere in chrome, a 4px gutter with no track rule and a 2px thumb in --pt-thumb that widens to 4px on hover, owned by .pt-scroll in src/components/viewer/tokens.css and mirrored by the deck's .scroll rule. No scroll region draws a rule beside its thumb.

Corners: rounded controls, square shells

Kevin's toolbar is the reference (2026-10-05): the search pill and the segmented control round at 6px, the key chip at 4px. Everything a reader presses, types into, picks up or looks at as an object is rounded; the surfaces that hold the interface are square. src/components/viewer/tokens.css holds the corners as six tokens, and nothing in the shell or the pages writes a radius any other way.

• A part n px inside a rounded box (n from 1 to 3) takes calc(var(--pt-radius-<role>) - npx).
• A picture in a rounded frame is clipped by the frame or takes the concentric radius.
• Named exceptions: Present keeps 8px (section 15); the marks page's app tile keeps the platform's 22% and its browser tab mock stays square, because they are specimens. The /d/ directions, the deck, the presenter, the craft article and the dashboard plate keep their own grammar.
• scripts/lint/radius.mjs holds the law: statically in pnpm lint:radius and the build, and on the rendered pages in pnpm lint:radius:live.

The corner notches on hero cards are not drawn — they are the ground showing through, so a corner can never disagree with the seam that meets it.

The rails

The page's spine is a ruled column with ONE rail on each side.

• The column wrapper draws the pair once, with its own border-inline.
• A band mounted inside the wrapper draws no side rails of its own: the wrapper already owns them.
• A full-bleed band that sits outside the wrapper draws its own inner pair once, at the column edges, from its own -in column, in the band's rule ink. It never draws a pair beside the column.
• Retired everywhere: the outer pair at ±10px that earlier directions drew from a wrapper pseudo (the "doubled rail"). A second stroke beside a rail is defect class 1 above, and a coincident second stroke stacks alphas and reads as a different color.

The doubled LINE of section 5 is a different device: one path stroked twice, a connector, never a page rail.

The sidebar's rail (section 16) is a different device: a row-weight line inside the list that marks the place, never a page rail.

Typography and voices

• Three voices: the serif face for brand moments, the grotesk for labels (11px, letter-spacing: 0.06em), the mono for numbers and tokens only.
• Hairline-boxed code blocks; figcaptions under figures; one type scale per page. Labels never shout; the active element is the only color.

Book type

The shell's type is one family, the rsms InterVariable (v4.1), cut into unicode-range subsets by scripts/build/subset-inter.py (pnpm build:inter): Google Fonts' latin, latin-ext, vietnamese, greek, greek-ext, cyrillic and cyrillic-ext, plus Latin Extended-A, the private use area and the remaining symbols, each with every feature and both axes. The roman's latin subset comes through next/font, bound as ptInter in src/lib/fonts.ts so its family name matches no installed Inter, and every route preloads it. The other subsets and the italic are plain @font-face rules in the same ptInter family in src/app/inter-subsets.css, each fetched only where the page draws a code point in its range. Any other localFont call sets preload: false (pnpm lint:type, T3). Every stylesheet reads the type tokens of src/components/viewer/tokens.css and declares no family, feature list or display size of its own. The /d/ directions keep their own type.

• Stacks. --pt-text is var(--font-inter), system-ui, sans-serif; --pt-display reads it. --pt-mono is for code, numbers and tokens only. The per-language stacks (--pt-text-hant, -hans, -ja, -he) name system faces after Inter. The nameplate's faces are --pt-face-serif and --pt-face-grot.
• Features. h1 and h2 (and a display sentence such as the brand plate's .ptc-every) take --pt-ff-display: the single-storey a (cv11) and the open digits (ss01). Everything else takes --pt-ff-text. Both name 'liga' 1, 'calt' 1, because Chrome turns contextual forms off under any letter-spacing. The base rules on the shell's roots set them; a rule never writes a feature list.
• Weight. 400 for text, 500 for labels, headings and strong. Nothing above 500.
• The display ladder. Optical size follows the size, so 32px and up is the Display design.

| step | role | size / line | tracking | 900px and under | | --- | --- | --- | --- | --- | | d1 | page title (the book head's h1) | 44 / 1.04 | -0.025em | 32 | | d2 | section title (a divider's h2, a brand chapter) | 32 / 1.05 | -0.025em | 26 / 1.15 | | d3 | h2 in prose, a record's title | 24 / 1.25 | -0.02em | 21 |

• The text ladder. Title 18/1.35 at 500 and -0.01em (h3, a row's title); lead 17/1.55 in ink; body 16/1.6 in ink-2; small 14/1.55 (table cells, contents links, ledgers); meta 13/1.5 in titanium (meta tables, gutter notes, captions, th); group labels 12.5 at 500 and -0.005em. Weight 400 text is never tracked, and nothing on Inter is tracked positive.
• Measure. Body text at --pt-measure (32em, about 66 characters); a head's lead at --pt-measure-lead (30em). Tables, figures, code and ledgers keep the full column.
• The book page. Every page with a book head has one structure, rendered by BookHead (BookView.tsx), and differs from another only in its words and its facts: 1. nothing is drawn in the --pt-title-clear space between the toolbar's bottom rule and the title (the reading column's top padding), and no line crosses a title; 2. the title, the page's plain name from src/lib/page-names.ts (Brand, Documentation, Motion) or a record's own title, at d1 across the mast; after the name, a badge on the title's line (BookHead's badge: a 1px --pt-hair box at the card corner, its content at most the cap height tall and set on the baseline, hidden from the accessible name) cuts every 1.4s through what the page holds (src/components/viewer/BadgeCycle.tsx, steps(n) on one strip, so the count lives in the frames; under reduced motion the first frame stands): /brand the GT monogram and the register's monograms, /marks the register's marks, /handbook its files, /skills the skill ids, a skill its files, /graphics the numbered visuals' file stems, /motion the film slugs, a translation film its vocabulary in its own script, /blog the post slugs, a direction its pages; 3. the lead (one to three lines at --pt-measure-lead, at most 200 characters, plain declarative sentences) and the panel on one row under the title, both starting on the lead's first line; 4. the panel: Updated first (the day of the last commit that touched the page's own sources, from src/lib/updated.ts, linked to its commit, with a relative hint after hydration), then three facts, or one fact and the install field; each row a Heroicons 20 solid glyph in titanium, a label in ink-2 and a value in ink at 500, one lead line tall with its text centered between 2px of air above and below, and a --pt-hair-soft rule between rows, none over the first row or under the last; beside the lead the panel starts 2px under the lead's top, so each row's baseline lands on a lead baseline; 5. one --pt-hair rule --pt-head-rule-pad under the taller of lead and panel, across the stage; 6. the note at the body step, then the contents; 7. one hatch band ruled on both edges and running across the stage, --pt-sec-over under the block above it; 8. the sections, each a section.pt-book-part opened by a divider: a --pt-hair rule (the first section's rule is the band's), --pt-sec-pad, a gutter note of two lines in titanium (Section n, then one fact) on the h2's last baseline, the h2 at d2.

Under 880px of head width the panel stacks under the lead, ruled the same way, and the mast's rule sits --pt-head-rule-pad under it. The gallery (/) is the site's front page, the nameplate hero and the redesign post in the article's own grammar, and has no book head; /compare is a tool and has none. scripts/lint/heads.mjs holds the structure, statically and on the rendered pages.

• The gutter. Sections and rows keep the deck's 128px gutter and 28px gap. A gutter number takes the size, line height and baseline of the title beside it, in titanium (ink while active); under 900px it sits above the title at the meta step.
• The lint. scripts/lint/type.mjs holds all of this: statically in pnpm lint:type and the build, and on the rendered pages with pnpm lint:type:live. Its allowlist names every exception with its reason: the nameplate, the gallery's grotesk labels, the mono numbers and tokens, the specimens, and other sessions' code. scripts/lint/heads.mjs holds the book page (pnpm lint:heads, pnpm lint:heads:live).

The doubled line (thread grammar)

The brand's connector: one SVG path stroked twice — a full-gauge ink stroke under a narrower surface-colored core (stroke-width: gap), carving two parallel hairline threads at a constant gap along any curve. Tokens: --thread-gauge: 1.5px, --thread-gap: 3px.

• All three roles carry vector-effect: non-scaling-stroke.
• The core's stroke must match the actual surface behind the diagram, or the carve reads as a painted stripe.
• Layer order is load-bearing: threads first, pulses next, cores last. Draw a later sandwich over an earlier one and the junction re-carves into one clean pair — merges cost zero parallel-curve math.
• The live pulse is a third copy of the same path in accent at full sandwich gauge, between threads and cores — carved into two accent hairlines, never a filled band. The traveling window is real geometry (a sub-polyline rewritten per tick), never stroke-dasharray — dash distances drift under anisotropic stretch.
• Two-tone (one white thread, one gray): clip the white copy to a half-plane closed along the same center path — the split seam lies inside the carve. Componentized as src/components/shared/diagrams/DoubledLine.tsx. Offset clones collapse on curves; concentric restrokes only make symmetric rings.

The isometric family

One 30° axonometric map for every iso drawing (src/app/d/toolchain/diagrams/iso.ts): project(x, y, z) = [(x−y)·cos30, (x+y)·sin30 − z], camera at (+,+,+).

• Light from the upper left, always: exactly three faces visible, shaded top 4% / left 9% / right 15% (currentColor mixes; accent faces keep the same order). Reordering is forbidden.
• The extrusion recipe: opaque hull from roundedPolygon(silhouette(...)) (the occluder), then right/left/top face fills, then hairlines — rim, top contour, and the interior front edge(s) the silhouette doesn't draw.
• IsoPrism extrudes any convex plan polygon under the same visibility and tone law; plane(z, ox, oy) seats whole flat drawings into a surface with one matrix; markPath() lays rounded bars in a face; brand marks render as alpha masks so the shape takes the surface's ink.
• One corner radius family-wide (ISO_RADIUS = 2.4); plate thickness ≈4% of footprint, air between stacked plates ≈40%; depth cues live in per-plate stroke alphas, never group opacity; each drawing spends its accent on exactly one element.
• The mark shimmer is DitheredMark (§7's 1-bit language as a specular band): nested Bayer coverage tiers windowed by pre-rotated 60° clip paths, swept by pure horizontal translate — rotate() windows are GSAP-origin fragile.

The 1-bit language (Bayer dither)

Density ramps render as ordered dither, never alpha veils.

• The 4×4 matrix ([0,8,2,10 / 12,4,14,6 / 3,11,1,9 / 15,7,13,5]) and the 8×8 (an exact permutation of 0..63 — 65 tonally linear levels) are the house screens.
• Coverage tiers nest by construction — every tier's lit cells are a subset of the next — so non-overlapping regions filled with different tiers compose exact ramps, and opaque glint ink means doubled cells never brighten.
• Cells are square screen pixels: transforms that would foreshorten them (a plane seat) go inside the alpha mask; crispEdges keeps cells 1-bit at any zoom; CSS upscales with image-rendering: pixelated.
• Engines: src/lib/dither.ts (CPU, any scalar field, 1 device px per cell) and src/lib/studio-field.ts (GPU, the authentic BAYER_PRESETS roster of ten variants, one shared GL context, switch by remount).
• Artifact pictures (the dithered photographs and scans on the plate's field, the deck's mood slides and the transition demo on /handbook/libraries) follow the Blue Marble standard in docs/ARTIFACT-PICTURES.md, held by scripts/lint/pictures.mjs.

The moving type law

• The morphing unit is one shaped text node — never per-character spans, which break Arabic joining and Devanagari matras. lang + dir on the node; unicode-bidi: isolate on the container.
• Width is measured from a hidden probe carrying the word's own lang/dir — never a sum of per-character boxes — cached, device-pixel snapped, and the container's width is the only layout-affecting property that animates, one continuous tween per cycle. Re-measure on resize and fonts.ready.
• One clock per page: the component never runs a timer; the host drives it (the dossier's locale belt, a craft plate's interval). Engine: src/components/shared/EverySentence.tsx.
• Locale pills render through one component (LocaleTag): flag first (fixed 15×11 SVG print), code in the host's mono on the baseline; the host supplies the box.

Motion discipline

• Every loop is created paused; ScrollTrigger (or an IntersectionObserver) plays/pauses it while the section is on screen; multi-phase choreography lives on ONE timeline so phases can never drift.
• prefers-reduced-motion short-circuits setup entirely; the markup pose IS the still (static accent pair, parked seam cut, single dither frame).
• Dash gotchas: normalize pathLength to 1000 (GSAP integer-rounds offsets); dashes clip at a subpath's end rather than wrapping closed loops; Chromium computes dash patterns in screen space under non-scaling-stroke and ignores pathLength there — rings that dash use raw user units with neither.
• Cache a path's source d (el.dataset.traceD) before an animation blanks it per tick — a re-run would otherwise trace an emptied path.
• Leader joints overshoot into opaque hulls so joints are gapless; leaning shapes (scan beams) are re-projected per phase (beamAt(t)), never a translated constant.
• The sidebar's thumbs and pills move on transform only, by WAAPI, at --pt-dur-sb (a pick) and --pt-dur-toast (the pointer), eased by --pt-ease. Their geometry is read once per layout change (a ResizeObserver per group, a MutationObserver for rows and marks), never per frame and never on hover. Before the shell settles they are placed, not moved. Reduced motion places them at once.

The seam (slide-to-reveal)

Both layers full-width and pinned; the handle writes one CSS var (--seam-cut) and the top layer clips to it — content never travels with the handle. State lives in the var: drags cause zero re-renders, GSAP tweens drive the same dial, the keyboard path re-reads the live computed value. The handle is the dossier refit: a 64px transparent hitbox, solid two-tone threads with the payload's ink filling the run, and a 16×40 rectangular grip tab — the light surface wears the dark chip, the dark surface the light chip. Component: src/app/d/toolchain/sections/RevealSeam.tsx (host CSS supplies the skin).

Engine lifecycle

Every canvas/GL engine follows one contract: mount lazily (an IntersectionObserver arms the plate), pause offscreen and on hidden tabs by its own observer, render exactly one still under reduced motion, and destroy() releases everything the instance owns (shared GL contexts persist for the session by design). Ink re-resolves on data-theme flips. Where an engine has quality tiers, quality follows measured frame cost, not just the window: glyph-field's frame-time governor ratchets a slow device down the phone cut's own ladder (lean device-pixel cap, then the lean pool), down only, with pool cuts applied at idle.

The mobile type ladder

Under 720px, type and spacing are one token ladder, not per-rule values — --tcm-* slots declared on .toolchain-root in the engine's LATE 720px block (src/app/d/toolchain/styles.css), consumed by every floor below:

• The px-fallback consumption law: every consumer reads var(--tcm-X, <px fallback>) with the slot's canonical value as the fallback — a rule the ladder doesn't reach (a 721–900px cut, a fork that hasn't declared it) degrades to the same number, never to unstyled. New mobile rules never hardcode a size the ladder has a slot for.
• Unlayered engine beats utilities: the engine's plain CSS is unlayered and Tailwind utilities live in a @layer, so engine floors outrank utility metrics (the box-gap rule beats a head's max-lg:mb-6). Heading and paragraph metrics therefore live in engine CSS, never in page utilities.
• The late block: the ladder and its floors sit in the engine's LAST 720px block because several base rules they override appear after the earlier 720px block — same-specificity declarations only win by following them. New mobile floors go there, not in the early block.
• The sg cut outranks the engine: v0-pages.css's mobile cut (.toolchain-root:is(.sgdh-root, …)) carries higher specificity than any engine floor, so it must consume the same tokens — an engine-only raise silently fails to render on the singularity homes. Change one, change both.

The box-air standard

Boxed cells — framed cards, bento plates, stacked dark-band cells — breathe alike on mobile: block padding --tcm-box-pt/--tcm-box-pb (36/38), and --tcm-box-gap (28px) between a box's head and its artifact. The gap is card-scoped (.tc-card > .shell-cell-head) on purpose: cells are flex columns, margins never collapse, so an unscoped head margin would stack onto the copy cells' own body margins. The seam floor rides alongside: copy never sits within 20px of a hairline (--tc-card-pad: 20px; the trust lead's 20px bottom pad).

The svh/dvh law

A mobile stage measures the viewport twice, and the two units never trade jobs:

• Reach is dvh. Whatever must touch the true screen bottom — the stage's rails, the text zone — sizes from 100dvh, the real viewport with browser chrome collapse included.
• Layout is svh. Any height that participates in layout rides 100svh, the stable viewport: a dvh layout height grows the document on every chrome toggle and jitters the scroll under it.
• The difference is a token — the stack stage's --v0sm-bar-gap (dvh − svh, 0 while the URL bar shows) — and only overhangs (the rails' lower reach) spend it. Anything SIZED from the stage derives from the stable var, or it breathes with the URL bar.

The two read lines

The stack story runs on two ladders of scroll anchors, measured per beat and re-anchored on every ScrollTrigger refresh (src/app/d/_v0/sections/FullStack.tsx):

• The read line (55%) is structural. A beat LOCKS IN when its COPY BLOCK's center takes the 55% line — the same line the sticky figure's seat centers the tower on, and, for the finale, its pin-engage. The tower's build clock and the capstone scrub both key on it. Anchors are measured on the copy itself, from FLOW geometry (the sticky finale's own rect would read the stuck pose on a mid-dwell refresh) — never on the beat window's top, which runs nearly half a viewport ahead of the copy and fires every arrival early.
• The highlight line (80%) is the spotlight's alone. A beat's copy lights as its center rises through the 80% line — just after entering the screen, while the arriving layer is still mid-build beside it.

One scrubbed dial spans the whole read; a piecewise map (measured lock-ins in, story time out) HOLDS the clock while a row is being read and spends each gap hold → build → lock, so a layer stands locked before its own copy takes the line.

Chrome exceptions Kevin asked for

The shell's chrome is Inter only, weight 500 or less, corners as section 2 sets them (square shells, 6px controls and cards, 4px chips), one hairline per rule, colors from src/components/viewer/tokens.css and borders in the three roles of section 2. Kevin's round six directives override those rules for exactly five elements. Each exception is listed here with its owner file so nothing else reaches for it, and so the next sweep does not "fix" it back.

Everything else in chrome keeps the rules above: every other toolbar button takes the control corner, the palette and the help card take the card corner, the index panel is a shell column and stays square, and no other element carries a chroma or a face outside Inter.

The sidebar's rows

Three rules govern the list in column one (src/components/viewer/Sidebar.tsx), on every route that shows the site map.

Every row is a link to a page. A site map row navigates to its route through the router; a row that leaves the site opens a new tab. A route's own item navigates too when its href names a page other than the one the reader is on: a direction row on / opens /directions/<slug>, an archive row /archive/<slug>, a skill row /skills/<slug>. The shell selects in place only an item with no address of its own (a slide, a brand section), an item that asks for it (ShellItem.inPlace, the documents on /handbook, whose book scrolls and writes the address itself), or the item of the page the reader is already on. No row scrolls the gallery. The grid's tiles and the filter's Enter follow the same rule.

A page's sections open under its row. On the page's own routes, its sections open as a run under the page's row, in the row's group (ShellSection.under: brand, docs, handbook, marks, graphics, motion, skills). A run is flush under the row. Each row of the run draws the route's own number in the icon's slot, in the deck's number style, and a name that wraps (a run row to two lines at most, a deep heading to three) and is never cut; a title that is a sentence takes a short name (ShellItem.short). When two or more of the page's sections hold more than one row, each gets a label with a chevron and a count inside the run; a section of one row is that row. The headings of the item being read hang under it as a deep run, at 12.5px titanium, ink while read. A chevron button at the right end of the page row folds the run for the visit; the run opens again on the page's next visit. A labelled group opens when the run has 40 rows or fewer, and past 40 only the group holding the active item opens; those folds persist under gt-shell-groups. A route section that stands for a site map group (Shipped, Sites, Explorations, Archive) keeps replacing that group. The sidebar is 208px, the deck's column.

The rail marks the place. In outline density each top-level group carries one rail: a 1px --pt-hair-soft line drawn by .pt-sb-rail (src/components/viewer/SidebarRails.ts) and masked to an SVG path down the group's rows. The rail runs in a column 16px before each level's first glyph: x 18, under the group header's chevron, for the tree rows; x 34 for a run's rows and labels, a site's enterprise page and the live site's rows, whose icons and numbers start at 50; x 50 for the deep headings, which start at 66. Where the level changes, the path bends at 45 degrees across one 16px step. The marked row carries a 2px ink thumb on the rail and a --pt-sb-pill-current ground with the control corner. The row under the pointer, or under keyboard focus, carries a --pt-thumb thumb and a --pt-plate ground. The marked row is the deep heading being read when the deep run is shown, else the active item when its row is shown, else the current page's row, else the page row the reader is inside. A plain click moves both marks to the clicked row over --pt-dur-sb and turns it ink before the page arrives. When the click opens another route, the new page's list keeps the clicked row where it was and the marks travel from it to that page's mark once the shell settles. Thumbnail density has no rail: its rows lead with their captures, each run keeps its guide and the active row its 2px bar.

The current page is always marked. The row whose path is the longest one covering the pathname is current, site map row or route item alike: on /skills/<slug> the skill's row, on /directions/<slug> the direction's, on /d/production/enterprise the Enterprise row and not Home. While no item is marked (a direction page, the gallery at its top) that row carries the rail's thumb and ink text; while an item is, it draws ink text (.is-current, aria-current="page"), as does the page row the reader is inside (Skills on /skills/<slug>). Exactly one row is aria-current="page": the current row whose own path is the pathname; a page row the reader is inside is "true".

The list is cheap to change. Rows are memoized on data built once per route, so a fold renders only the rows it adds or removes, a pick renders the rows whose state changed, and a hover renders nothing in React. Rows are opaque in their first frame; nothing fades in on mount. A row that opens another route prefetches it after the pointer rests on it for 80ms or on keyboard focus, never on pointer down: the click's own navigation follows within milliseconds, and a prefetch there fetches the route twice and renders the arriving page twice. The index panel builds its rows on first open.

Ground rules

• The dev server runs at http://localhost:3005 in the shared checkout. A worktree runs its own server on another port, and PT_BASE points the live lints, the page check and the captures at it.
• A concurrent session may be editing the same worktree. Check git status before staging; commit only your own files. Expect the other session to absorb your changes into its commits. When that happens, verify by content, not by diff, and push the backup branch from HEAD.
• pnpm lint:all may be red on files you don't own; ship anyway when your own diff is clean under the checks below.

The line audit

node scripts/lint/lines.mjs http://localhost:3005/<page> --theme light
node scripts/lint/lines.mjs http://localhost:3005/<page> --theme dark

• Audits at 1440 and 1280; expects zero findings in all four classes (doubles, missing, selfStacks, invisibles) in both themes.
• The standing battery: /, /handbook, the three singularity homes (dossier, orbit, signal) and every page the round touched.
• Deliberate devices live on the ALLOW list inside the script; add an owner there only for a sanctioned device, never to silence a real double.
• The auditor reconstructs lines from computed CSS and cannot see SVG strokes. Figures get verified by eye with 2× pixel crops of junctions.

The page check

pnpm check:pages --preset quick --pages <id>,<id>   # the round's touched pages
pnpm check:pages                                    # every page on every device, before a release

scripts/check/pagecheck/ (its README explains the tool) loads every named page on the dev server on the device table in scripts/lib/site-pages.mjs: phones from 320x568 to 430x932 and on their sides, tablets from 768x1024 to 1366x1024 in both orientations, desktops from 1280x720 to the 3440x1440 ultrawide, Kevin's 1527x814 laptop and 1440x900 at 200% zoom. A phone or a tablet is read as a touch device whatever its width. The quick preset reads eight devices in dark and 1440x900 in light; the full preset every device in dark and three in light. Each cell is read once the page's own ready signal has fired and its layout holds still: horizontal overflow, boxes past the viewport edge, text clipped mid-word, console errors and failed resources, the theme applied, the tap targets' hit areas on touch devices, the layout shift score, and the site invariants hooks.mjs names (the 52px toolbar row, the stage rows, the sidebar column, the deck's sheet, the docs contents grid, the gallery's tiles). The declared interactions run in the same queue: the theme flip, the index panel and the preview, the search, the deck's arrow key, every deck slide in its sheet and the deck's grid and book, a docs contents link, the presenter's dock, and the presenter walked slide by slide on every device (each title visible, the "So I built 12" close beat and the grid at 16 prototypes). It writes .pagecheck/REPORT.md with a page by device grid and the run's timing.

• Thresholds: a tap target under 40px on a phone is a defect, 40 to 43 a note (44 is the target), a tablet's under 40 a note until Kevin decides on tablet touch sizing; a layout shift score over 0.1 is a defect and over 0.05 a note; an ellipsis truncation is a note, a clip without one a defect.
• Each defect row names the file and line to change (the rule declaring the element's class, the line rendering its text, or the line naming a missing file) and a fix written from the element's kind; a folder stands in when no line matched.
• Expects zero defects and every interaction passing; the run exits 1 otherwise. Notes are read, not fixed on sight.
• A round's touched pages run the quick preset before shipping; the whole site runs the full preset before a release.
• Captures of the first screen live under .pagecheck/shots/ (ignored by git), with the full page for a failing cell; --sheets adds a contact sheet per device for a quick look at every page.

The practices ratchet

scripts/lint/practices.mjs counts button types, bare effects, any-types, raw hex in TS/TSX ('#xxxxxx'-quoted; unquoted hex inside template CSS snippets doesn't count), and !important. It refuses anything that adds to lint/practices.baseline.json. When files are deleted, prune their baseline entries in the same commit.

scripts/lint/type.mjs holds the type to DESIGN.md section 4 ("Book type"): statically on every pnpm build and pnpm lint:type (family, stack, next/font binding, features, weight, heading and tracking rules, plus a per-file ratchet of literal sizes in lint/type.baseline.json), and against the dev server with pnpm lint:type:live (the face Chrome rendered, the computed features, tracking, optical size and weight). pnpm test:type runs its tests; --update-baseline records a burn-down.

scripts/lint/radius.mjs holds the corners to DESIGN.md section 2 ("Corners: rounded controls, square shells"): statically on every pnpm build and pnpm lint:radius (every radius reads one of the six --pt-radius-<role> tokens, shells and rows stay square, controls are never square, chips read the chip corner, the token values are pinned), and against the dev server with pnpm lint:radius:live (the computed corners at 1440 and 390, the overlays on /brand and the toolbar's hover boxes: square shells, round controls, a picture clipped by its frame). A named exception carries /* lint-radius: allow <reason> */. pnpm test:radius runs its tests.

scripts/lint/heads.mjs holds every book page to DESIGN.md section 4 ("The book page"): statically (pnpm lint:heads, in the build: BookHead's props, page titles from src/lib/page-names.ts, no route restyling the shared head, band or dividers, no second hatch, no guide over a title, the spaces on their tokens), and against the dev server with pnpm lint:heads:live (each head route at 1440 and 390 in both themes: the structure, the title's clearance, the lead, the panel and its Updated day, the mast rule, the band's two rules and the dividers, measured). pnpm test:heads runs its tests.

Types

pnpm exec tsc -p tsconfig.json --noEmit

Film it

Screenshot every changed visual with the external harness (the in-app browser pane pauses rAF, so shader canvases come out blank):

• Driver: the repository's playwright-core, launched against Chrome for Testing: CHROME_PATH, else the build playwright-core installs (pnpm exec playwright-core install chromium). pnpm capture:pages and pnpm check:pages launch it the same way.
• Dark shots: seed localStorage['gt-theme'] = 'dark' in an init script.
• Zoom junctions at deviceScaleFactor: 2+ and crop, because full-page shots hide 1px defects.
• Scroll through the page first so IntersectionObserver-armed plates mount; wait out arm delays before shooting animated engines.

Commit and back up

• Commit only your files, by explicit path. Commits author as Kevin with his GitHub noreply address (66856750+Kevin-Liu-01@users.noreply.github.com) and end with the session's Co-Authored-By: trailer (decisions log, 2026-10-10).
• Run pnpm build:updated --staged after staging the change, and stage src/lib/updated.ts with it. pnpm lint:updated (in the build and pnpm lint:all) fails when a commit touched a book page and the file was not regenerated with it.
• Push the round to a branch of this repository from HEAD (git push origin HEAD:<branch>), so the work survives a wiped scratch folder or a reset checkout. Main takes only work Kevin approved (section 7).

Push to main

Prototemplate main is the only copy of this code. The public site, www.prototemplate.com, deploys from it through the General Translation team's Vercel project. gt-cloud's apps/redesign stopped being a copy on 2026-09-08, so nothing is copied in from another tree, and no rsync --delete runs toward this repository: it would erase the routes that exist only here.

Kevin decides what lands. Exploration and redesign rounds stay on a branch or on the local dev server until he says to land them (decisions log, 2026-09-14). Approved work lands in this order:

git fetch origin && git log --oneline HEAD..origin/main   # other sessions push to main too: take their commits first
git grep -n '^<<<<<<< ' -- src docs deck skills scripts     # any hit stops the push
pnpm build > "$TMPDIR/pt-build.log" 2>&1 && git push origin HEAD:main || tail -40 "$TMPDIR/pt-build.log"

• The build gates the push with &&. A pipe such as pnpm build | tail returns tail's exit code and lets a failed build through, which happened on 2026-08-07 and 2026-08-11. A flaky failure with a clean log gets one re-run before diagnosis.
• Commit with explicit paths, never git add -A or git add .: the shared checkout holds other sessions' files, including the untracked motion/ folder.
• Push with git push origin HEAD:main when HEAD is a fast-forward of origin/main. Rewriting shared history needs Kevin.
• After the push, read the commit's deployment statuses on GitHub and the new build on www.prototemplate.com. A failed Preview is redeployed, never pushed again with an empty commit.

Site

Setup

Lints

Tests

Checks and captures

Generators

Skills

Graphics

Skill scripts

Each skill carries the scripts its procedure calls, self-contained so an installed copy runs on its own. Run one from a checkout with node skills/<slug>/scripts/<file>; pnpm test:skill-scripts runs their offline tests.

Environment

Each tool reads its setting from a flag first, then the variable, then the default. No tracked file names a machine path.

What a visual is

One HTML page, 1600 by 900, rendered headlessly at 7680 wide and downsampled to 3840. The page holds real screenshots of the product cut into padded crops, labels and leader lines drawn once, and a glyphfield export as the ground. Nothing in it is invented: every rectangle is a measured region of a captured page, every label names something the reader can find in the product.

The rules the set settled on, each learned from a review:

• No text except labels. No titles, captions or descriptions inside an image; the post carries the prose.
• One idea per slide. A carousel is a set of different points; a slide that restates its neighbour gets new content, not a new style.
• Real crops, not mockups. The one illustrative mock in the set is labelled as a mock.
• Red for what was removed, blue for the page and what replaced it.
• No glass panels, no sparkle icons, no over-rounded boxes: the graphics obey the same hit list the post publishes.

Sizing

The article column is about 700 CSS px wide, so a 1600px stage is shown at 0.44x. Everything is sized for that, not for a full-screen viewer:

Resolution was never the blur. At 1x the dither's one-pixel dots landed on less than a device pixel and aliased into noise; at 2x with smooth scaling they read as a halftone. Small labels were the other half of it.

The floor is measured after zoom-to-fit, not as declared. A composition wider than 90% of the frame is scaled down, and its 28px labels with it, so when the audit reports text under the floor the usual fix is to make the composition narrower (smaller crops, shorter labels, one label column) rather than to enlarge the type. MIN_TEXT in gen-lib.js holds the floor.

The files

Generated folders (graphics/build/visuals/, graphics/out/, graphics/rec/stopmo*/) are ignored by git; everything in them comes back from the scripts.

Procedure

1. Install once: pnpm install at the root (heroicons for the label icons), pip install pillow, and agent-browser and ffmpeg on the PATH.
2. Serve: pnpm graphics:serve keeps graphics/ on port 8765.
3. Capture sources into graphics/shots/hi/ (see "Capturing") and register them in SHOTS with their density.
4. Measure the rectangles you will cut, in CSS px at 1440 by 900, into the page objects in gen-visuals.js.
5. Write each visual as one add(id, area, name, bg, why, () => html). Assign it its own export in ASSIGN.
6. pnpm graphics:gen writes the HTML and the manifest; pnpm graphics:audit [ids] measures every text against the floor and lists overlapping boxes (fix the failures, judge the warnings); pnpm graphics:render [ids] shoots them; python3 graphics/build/sheet.py [ids] tiles them for review.
7. For a clip, record (see "Clips"), then graphics/build/composite-videos.sh.
8. pnpm graphics:export writes the webp set and GIFs into public/static/blogs; --dest points at a landing checkout. Bump the ?v= stamp on every reference in the post.
9. Check the set on /graphics and the post on /blog.
10. Let the page serve each image at the width it is shown. The masters are 3840px wide and the column is about 700 CSS px, so a browser left to shrink them itself blurs them (measured: about an eighth of the edge contrast on a 2x screen, none for a variant at the device width). Every blog image goes through next/image with the column's sizes and the dense images.deviceSizes ladder in next.config.ts, at quality 95; clips are cut at 1400px, the column's 2x width.

Capturing

Sources come from a landing dev server built from main, captured with agent-browser at a device pixel ratio of 4 or 5 at 1440 by 900, the Next.js dev portal hidden, the pointer parked on plain text. Themes come from agent-browser set media light|dark; the docs follow the preference when no theme is stored. Menus open with their real control. The old docs lived on an SSO-protected Vercel preview; those were captured by serializing the DOM from a signed-in Chrome to the local server and screenshotting the saved page. Convert captures to lossless webp; the library reads webp sizes.

Backgrounds

The exports are Kevin's glyphfield project, rendered headlessly through window.glyphfield.studio (graphics/glyph/gfexport.sh). The generator draws one export per visual at exactly 2x the stage and dims it under article visuals; covers keep the full export. Blue duotone variants carry the covers. Every cover has a light-theme twin (light: true on coverExploded and coverWiremap): the same ground and scale, the docs captured in their light theme, the wireframe plate in paper and ink. The post lists the light cover under imagesLight and the blog shows the one for the reader's theme.

Clips

The recorder keeps one or two frames per second at 4x, so interactions are captured as stop-motion: pause the Web Animations, step currentTime between screenshots, assemble with ffmpeg at variable frame durations. Screenshots re-fire trusted pointer events on the last clicked element, so the capture blocks real pointer events in the region and drives hovers synthetically. The composite reads the crop rectangle from the rendered visual, overlays the clip, and writes a 30fps MP4 master and the GIF the post embeds: 1600 wide, 256 colours, sierra dither, rectangle diffing.

Handing off to a post

The post embeds the set with the Carousel and HitList MDX components of the landing blog (children with string attributes; the blog's MDX renderer strips expression props). Covers ship as 3840 webp and the OG image as a 2400 by 1260 PNG; the landing app serves webp covers at quality 95, because dithered artwork smears at the default 75. Posts live in the generaltranslation/content submodule, so a change is two pull requests. When the post needs anything from gt-cloud (a new MDX component, images under public/static/blogs/, redirects or navigation entries), the gt-cloud pull request merges first and the content pull request second; in the other order the post publishes with missing images or a failed build. The content repository's preview app needs a simple version of every component or its build fails. gt-website (references/blog.md, read against gt-cloud main on 2026-10-05) holds both rules. This repository keeps the authoritative copy of the three docs-redesign posts under content/blog and their graphics under public/static/blogs, read by /blog and /graphics.

Where it went wrong, and the fix

• A captured Lucide glyph is a <rect> plus a path (copy, sidebar). The inliner used to strip width/height from every element, so the rect collapsed and only a corner path drew. It now resizes the root tag only.
• With the static server down, render.sh shot Chrome's error page and the export shipped it. The render now skips a page that never centres.

Files

The rules

1. No plain English prose

A picture may not be a page of readable English: dictionary entries, book pages, documents, signs or captions. That text reads as copy and distracts from the form beside it.

Writing is welcome when it is the artistic or design subject of the object: carved inscriptions (the Rosetta Stone), calligraphy, manuscripts in other scripts or old hands (Devanagari, the gloss), signs pressed in clay (the tablet), and the lettering engraved on a historical chart or instrument (the cable chart, the compass rose).

Each recipe declares writing: 'none' | 'artistic'. The cutter's text-line detector counts rows of six or more letter-sized marks and records the count as textLines. A picture with any text lines must declare 'artistic'. The detector cannot read meaning, so a reviewer checks every 'artistic' declaration against this rule. Plain English prose never qualifies.

2. Sources

• Cut from the original scan or photograph. Never cut from a screened, two-tone or resized copy.
• The license is public domain or Creative Commons, taken in this order: public domain and CC0 first (Wikimedia Commons public domain files and the open-access collections of the Met, the Smithsonian, the Cleveland Museum of Art, the Rijksmuseum and the Library of Congress), then CC BY, then CC BY-SA only when nothing else shows the object. A CC BY-SA print is a derived work under the same license, and its credit says so. Non-commercial (NC) and no-derivatives (ND) licenses are refused, so the British Museum's images, which carry a non-commercial license, are refused.
• The subject is the original object. A cast, a replica or a modern reprint is refused when the original can be shown. A picture shows no flag, emblem or coat of arms, no map with borders, no caption that states sovereignty, and no private person. The license order and these subject rules come from the artifact pictures of the language map (gt-cloud branch k/language-map, 2026-10-03).
• The credit is shown with the picture: on the deck slide's plate, in the picture's caption in moodPictures.ts, which the plate port's field shows, and in the credit line under the transition demo on /handbook/libraries (CraftArticle.tsx). The demo's line carries the deck slide's credit for each picture the demo shows, without the label ("Image:", "Photograph:"). The lint checks the deck slides and the demo's line.
• Sources are never committed. Each person keeps a sources directory and passes it to the wrapper. scripts/media/mood-tone/README.md lists each file's name, origin, pixel size and sha256, and the wrapper refuses a source whose sha256 differs from SOURCES in mood-tone.mjs.

3. The tone grid is the Blue Marble's

The Blue Marble on the onboarding field is the reference. Its numbers are in standard.json under tone.

Fixed for every picture:

• no blur;
• gamma 1.2;
• autocontrast that clips 0.5 percent at each tail, over the frame, or over the subject mask for a masked object;
• an 8-bit gray JPEG at quality 82, or 75 when 82 is over the cap.

Chosen per picture, in the recipe:

• the crop;
• the channel: red (the earth's) or gray;
• the polarity: invert so the subject is lit on a black ground;
• the kind: scene or marks.

Solved per picture by the cutter, never set by hand: the black and white points.

• A scene lands on the Blue Marble's mean tone 0.361 and standard deviation 0.342, over the region of the grid that is shown.
• Marks (writing, engraving, lines on a plain ground) put the ground at black with an Otsu threshold and the 90th percentile of the marks at white.

The solver returns levels 80 and 230 for the plate's earth, which is the earth's own recipe.

Sizes: a cover is 1600 by 900, one grid cell per CSS px at a 1440 by 900 view. A disc is 2400 by 1350. The cap is 560 KB (573440 bytes).

4. The screen is the Blue Marble's

standard.json under screen:

• an ordered 8x8 Bayer matrix with threshold (m + 0.5) / 64;
• cells of 1 CSS px, screened live at display size. Never ship a pre-screened bitmap that is then scaled;
• tone floor 10: bytes at or under 10 read as 0;
• the loop runs at gamma 1 and bias 0, because the whole curve is in the grid;
• dark theme: white cells at opacity 0.62 over the #070707 ground. Light theme: #070707 cells at opacity 0.7 over white.

Where each surface states these:

The deck engine sizes each mood canvas's backing store to its box on screen (getBoundingClientRect, because the stage is CSS-scaled), so a cell is 1 CSS px on the sheet, in a thumbnail, in the book view and on the full-stage backdrop. It reads the grid at cover fit, centred, and draws again on slide activation, resize and a theme flip.

5. The windows

The cutter measures each grid over the region shown (the deck's full 1600 by 900 sheet; on the plate, the part right of the ramp at 1440 by 900; only the disc or the masked subject where there is one) and records the stats in the manifest. The lint holds them to standard.json under windows:

The cutter

From the repository root:

pnpm mood-tone <sources dir> [--set deck|plate] [--preview <dir>] [--check]

The wrapper sends the recipes and the standard to mood_tone.py, which writes mood-{name}.jpg for each recipe (the deck set to deck/shots/tone, the plate set to public/brand/mood) and prints one manifest entry per picture. The wrapper writes those entries to manifest.json and prints each picture's levels and stats. With --preview, the cutter also saves the 1 px screen of each grid at the view size as preview-{name}.png.

The cutter is deterministic: a run on the same sources writes the same bytes. A grid's sha256 ties the file to its manifest entry, and the lint checks that. It does not show that the entry came from the recipe: an entry edited by hand next to an untouched grid passes the lint. Only --check, run with the sources, proves that. It cuts into a temporary folder and fails unless every grid and the manifest equal the committed files byte for byte. The lint cannot run it, because the sources are not committed. Never edit a grid or a manifest by hand.

A recipe holds only: name, source, the size and cap from standard.json, crop, channel, invert, kind, writing and placement. It holds no tone numbers. The crop kinds are documented above DECK in mood-tone.mjs.

Adding a picture

1. Choose the object against rule 1. Find the original scan or photograph and confirm its license (rule 2).
2. Put the source file in your sources directory, add its origin and sha256 to SOURCES in mood-tone.mjs, and add its row to the source table in scripts/media/mood-tone/README.md.
3. Add a recipe to DECK or PLATE in mood-tone.mjs. Spread COVER for a cover. Set kind: 'marks' for writing or engraving on a plain ground and kind: 'scene' for anything else. Declare writing. A deck recipe's placement is a cover at focus 0.5, 0.5.
4. Run the wrapper with --preview and look at preview-{name}.png.
5. If the subject is not where it should be, or the stats miss the window, change the crop, the channel, the polarity, the kind or the placement and run it again. If no crop puts a scene in its window, the picture does not meet the standard. Do not add tone settings to make it pass.
6. Show it. - On the deck: add deck/slides/NN-mood-{name}.html from an existing mood slide, with <canvas class="mood-img" data-tone="shots/tone/mood-{name}.jpg" role="img" aria-label="...">, the plate's title, sentence and credit, then update SLIDE_COUNT in scripts/build/deck.mjs, SECTIONS in deck/parts/tail.html, DECK_SLIDES in src/lib/search-index.ts, and the entry in deck/shots/OPENERS.md. Run pnpm build:deck. - On the plate port: add the name to PictureName and an entry to MOOD_PICTURES in moodPictures.ts: src is /brand/mood/mood-{name}.jpg, placement equals the recipe's (a disc also carries the manifest's disc values cx, cy and r), and the caption has a title, a note of at most 90 characters that says what the object is, and the credit. Make the same change in gt-cloud.
7. Run node scripts/lint/pictures.mjs (it also runs before next build and in pnpm lint:all).
8. Commit the grid, manifest.json, the recipe, the README row and the slide or registry entry. If the manifest shows textLines above 0, say so in the commit so the reviewer checks rule 1.

To remove a picture, delete its recipe, its grid and its slide or registry entry, run the wrapper so the manifest drops it, and move its pages to another picture.

The lint

scripts/lint/pictures.mjs runs before next build (pnpm build), in pnpm lint:all, and on its own with pnpm lint:pictures. Its tests are in scripts/lint/pictures.test.mjs. pnpm lint:all runs them after the lint, and pnpm test:pictures runs them alone. It fails when: