# The Handover

> How to work with AI: the structures and documents that make an agent useful
> across time rather than only inside one conversation — with a free, vetted
> library of the documents themselves. No account required.

The argument this site makes, in one paragraph: every session starts cold, so this
is a handover problem rather than a memory problem. Nothing was forgotten, because
nothing was there. Four layers of written context follow from that — rootnotes,
a documentation set, a working agreement, and a retrieval corpus. The full case is
at https://the-handover.org/docs/working-with-ai-the-system.

Two standards, and the difference is stated rather than implied. Most documents are
VETTED — read adversarially before publication. Some are POSITION — this site's own
view, not independently reviewed. Position documents say so in their own header, so
the distinction survives the file being copied somewhere this site cannot reach.

Every document carries its authors and states when it was last confirmed to work.
Append `.md` to any document URL for the source markdown with no markup.

Documents past 90 days without re-confirmation are marked
unconfirmed below. They remain published: unconfirmed means "may be out of date",
not "withdrawn".

Structured index: https://the-handover.org/index.json

## General Chat

- [A pointer rootnote — addresses, not knowledge](https://the-handover.org/docs/a-pointer-rootnote.md): The one rootnote that contains no instructions and no content, only addresses — and why each entry should name the decision at which it becomes relevant rather than the activity it describes. (rootnotes, confirmed 2026-09-19 against Claude Code 2026-09) [templated]
- [Affiliate links on a content site](https://the-handover.org/docs/affiliate-links-on-a-content-site.md): What you link to decides your tooling, and the consent rules decide whether a cookieless story survives. (guides, confirmed 2026-07-31 against UK CAP Code, PECR and UK GDPR as at 2026-07)
- [Auditing a context file you already have](https://the-handover.org/docs/auditing-a-context-file.md): A pass over an existing AGENTS.md or CLAUDE.md that decides, passage by passage, what is worth its tokens — and the three questions that decide it. (processes, confirmed 2026-09-16 against claude-opus-5)
- [Business context for an agent working on commercial software](https://the-handover.org/docs/business-context.md): The commercial facts an agent cannot read from a repository, and the decisions that go wrong without them. (rootnotes, confirmed 2026-08-14 against Claude Code 2026-08) [templated]
- [Contributing](https://the-handover.org/docs/contributing.md): How to submit a document, what happens to it during review, and what rights you keep. (guides, confirmed 2026-08-07) [normative]
- [Data handling and privacy for an agent working with real data](https://the-handover.org/docs/data-handling-and-privacy.md): What counts as personal data, where it must never end up, and the changes that quietly widen what you hold. (rootnotes, confirmed 2026-08-21 against Claude Code 2026-08) [templated]
- [Drafting email an agent does not send](https://the-handover.org/docs/drafting-email-an-agent-does-not-send.md): The draft-and-hand-over boundary for outbound email, and the ways email rendering differs from the web. (guides, confirmed 2026-08-08 against major email clients as at 2026-08)
- [The canon](https://the-handover.org/docs/canon.md): Seven invariants every document in this library must satisfy, and what happens to one that does not. (guides, confirmed 2026-08-06) [Hard-Won, normative]
- [What earns its place in a context file](https://the-handover.org/docs/what-earns-its-place.md): Two tests decide whether a passage is worth its tokens, and applying them to twelve rootnotes found that padding accumulates in documents that explain and almost never in documents that constrain. (guides, confirmed 2026-09-16 against Claude Code 2026-09) [Hard-Won]
- [Working with AI is a handover problem](https://the-handover.org/docs/working-with-ai-the-system.md): Why every session starts cold, what follows from that, and the four layers that turn context into something an agent can be handed. (guides, confirmed 2026-08-28 against Claude Code 2026-08)

## Coding

- [Documentation standard for agent-maintained projects](https://the-handover.org/docs/documentation-standard.md): A linked set of documents with defined sections and relationships, rather than one long file that narrates the code. (rootnotes, confirmed 2026-08-25 against Claude Code 2026-08) [templated]
- [Faking an external service you do not own](https://the-handover.org/docs/faking-external-services-for-tests.md): A stateful fake plus a control API, so a real app runs a full journey with no live calls — and the isolation you must build before the first run. (guides, confirmed 2026-08-21 against Rust with an embedded HTTP router 2026-08, Playwright 1.x) [Hard-Won]
- [Four ratios, four different failures](https://the-handover.org/docs/four-ratios-four-different-failures.md): Four ratios used to score code quality, and four different reasons each one measured something other than what it claimed. (guides, confirmed 2026-08-28 against Rust 1.96.0, Claude Code 2026-08) [Hard-Won]
- [Getting a new domain past security filters](https://the-handover.org/docs/new-domain-reputation.md): Two independent causes of a false-positive block, only one of which you can do anything about. (guides, confirmed 2026-07-22 against Cloudflare Radar and the major URL-reputation databases as at 2026-07) [Hard-Won]
- [Handling live secrets in AI coding sessions](https://the-handover.org/docs/live-secrets-in-ai-sessions.md): Getting a credential from its store into its destination without it ever appearing as text the assistant emits. (guides, confirmed 2026-08-07 against security (macOS Keychain CLI) macOS 14+) [Hard-Won]
- [Killing processes safely on a shared machine](https://the-handover.org/docs/killing-processes-shared-machine.md): Why process-selection commands over-select silently, and the inspect-then-kill pattern that catches it. (guides, confirmed 2026-08-07 against lsof 4.x, pkill / pgrep procps-style) [Hard-Won]
- [Nothing was wrong, or nothing was examined](https://the-handover.org/docs/nothing-was-wrong-or-nothing-was-examined.md): Four checks that passed because they had no subjects — three in a scoring tool, and one set that caught this document's own author an hour after he went looking for them. (guides, confirmed 2026-09-18 against Rust 1.96.0, Claude Code 2026-09) [Hard-Won]
- [Operating something that is live, and what an agent may do during an incident](https://the-handover.org/docs/operational-runbook.md): Stop the bleeding before diagnosing, record while acting, and the autonomy rules that matter most when they are under pressure. (rootnotes, confirmed 2026-08-26 against Claude Code 2026-08) [templated]
- [Running a local neural TTS model, and the artifact that changed the runtime](https://the-handover.org/docs/local-neural-tts-on-candle.md): Why a model correct op-by-op can still sound wrong, and the CPU hot paths a naive port leaves on the table. (guides, confirmed 2026-08-11 against Candle 0.10, misaki-rs 0.3, Kokoro-82M v1.0) [Hard-Won]
- [Ship edge deployments on a custom domain, never the platform subdomain](https://the-handover.org/docs/custom-domains-for-edge-deployments.md): Free platform subdomains are blocked as a category by security filters, so a subset of real users silently fails. (guides, confirmed 2026-08-08 against wrangler 4.x, Cloudflare Workers / Pages 2026-07) [Hard-Won]
- [Signed self-updates for a desktop app, hosted on object storage](https://the-handover.org/docs/desktop-app-signed-self-updates.md): Wiring an updater keypair, a version manifest and a public bucket, and the flags that make uploads silently do nothing. (guides, confirmed 2026-08-08 against Tauri 2.x, wrangler 4.x) [Hard-Won]
- [Signing and notarising a macOS app for direct distribution](https://the-handover.org/docs/macos-signing-and-notarisation.md): The certificate types, the notarisation flow, and the build setting that silently ships an unnotarised DMG. (guides, confirmed 2026-08-08 against notarytool Xcode 26, Tauri 2.x) [Hard-Won]
- [Supply-chain security baseline for AI-assisted development](https://the-handover.org/docs/supply-chain-baseline-ai-development.md): What an agent should check before installing a dependency, and which files it must never modify without a shown diff. (guides, confirmed 2026-08-07 against npm 10+, cargo 1.x)
- [Test output against the tools people actually have](https://the-handover.org/docs/test-against-the-tools-people-have.md): A file format verified only by the reader you wrote is verified against your own assumptions. (guides, confirmed 2026-08-08 against Info-ZIP unzip 6.00, Node 24) [Hard-Won]
- [Testing a desktop app on a disposable Windows VM](https://the-handover.org/docs/windows-vm-testing-for-desktop-apps.md): Driving an interactive Windows session over SSH, and why testing as an admin proves nothing about permissions. (guides, confirmed 2026-08-11 against Azure CLI 2.x, OpenSSH for Windows 8.x) [Hard-Won]
- [The strongest evidence against this library, read carefully](https://the-handover.org/docs/agents-md-does-not-help.md): A controlled study finds context files do not improve task success and cost 20% more — and its detailed findings are closer to this library's own rule than its headline suggests. (readings, confirmed 2026-09-14 against Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev)
- [UI testing an agent can write and run itself](https://the-handover.org/docs/ui-testing-agents-can-run.md): Drive interfaces by stable identity rather than pixels, in tiers, so tests are headless, deterministic and fan out. (guides, confirmed 2026-08-21 against Playwright 1.x, Vitest + Testing Library 3.x, Tauri 2.x) [Hard-Won]
- [Verification that cannot fail](https://the-handover.org/docs/verification-that-cannot-fail.md): Three ways a passing check reports success without ever being able to report anything else. (guides, confirmed 2026-08-11 against zsh 5.9, bash 3.2+, GitHub Actions 2026-08) [Hard-Won]
- [We could not get ground truth, and it took three attempts to accept it](https://the-handover.org/docs/we-could-not-get-ground-truth.md): Three attempts to validate a scoring tool against human judgement, and why all three failing was evidence for the tool's premise rather than against it. (guides, confirmed 2026-08-28 against Rust 1.96.0, Claude Code 2026-08) [Hard-Won]
- [When the tool disagrees with you, neither of you gets to win](https://the-handover.org/docs/when-the-tool-disagrees-with-you.md): What to do when a tool built to outrank your judgement is wrong, given that overruling it destroys the only property it had. (guides, confirmed 2026-08-28 against Rust 1.96.0, Claude Code 2026-08) [Hard-Won]
- [Wiring Polar billing and webhooks without cutting off paying customers](https://the-handover.org/docs/polar-billing-webhooks.md): An eligibility gate the sandbox does not enforce, a signature scheme that deviates from the spec it cites, and the webhook orderings that zero a live subscription. (guides, confirmed 2026-08-18 against Polar API as at 2026-08, WebCrypto (workerd) 2026-07) [Hard-Won]
- [Working agreement for an agent in this repository](https://the-handover.org/docs/working-agreement.md): What may be run without asking, what must stop first, and how to report what actually happened. (rootnotes, confirmed 2026-08-26 against Claude Code 2026-08) [templated]
- [Writing about a thing is not doing it](https://the-handover.org/docs/writing-about-a-thing-is-not-doing-it.md): Six ways a code scanner mistook writing about a practice for following it, and a seventh found inside the check built to prevent the other six. (guides, confirmed 2026-08-28 against Rust 1.96.0, Claude Code 2026-08) [Hard-Won]
- [You cannot find it by re-reading the thing that is wrong](https://the-handover.org/docs/you-cannot-find-it-by-re-reading.md): Four cases where a description and the thing it described drifted apart, none of which was discoverable by reading the description again. (guides, confirmed 2026-08-29 against Claude Code 2026-08, Node 24) [Hard-Won]
- [Your pattern matches the shape you pictured](https://the-handover.org/docs/patterns-narrower-than-reality.md): Two ways text scanning silently misses what it exists to find — soft line wraps, and identifiers in an unexpected form. (guides, confirmed 2026-08-11 against Node 24, JavaScript RegExp ES2024) [Hard-Won]

## Research

- [A research working agreement: gather, and do not conclude](https://the-handover.org/docs/research-working-agreement.md): What an agent may do unattended in a research project, where it must stop, and why uncertainty has to survive contact with it. (rootnotes, confirmed 2026-08-30 against Claude Code 2026-08) [templated]
- [Research context — what has been established, and what has been ruled out](https://the-handover.org/docs/research-context.md): The rootnote a research project needs an agent to read before it starts, and the dead-ends record that is the most expensive thing in any project to rediscover. (rootnotes, confirmed 2026-09-18 against Claude Code 2026-09) [templated]

## Writing

- [A writing working agreement: draft, and do not publish](https://the-handover.org/docs/writing-working-agreement.md): What an agent may write unattended, where it must stop, and the two failures that are specific to prose — inventing detail to finish a sentence, and not knowing what you have already said. (rootnotes, confirmed 2026-08-30 against Claude Code 2026-08) [templated]
- [Language and editorial guide for agent-written copy](https://the-handover.org/docs/language-editorial-guide.md): Voice, mechanics and error-message rules, and why inconsistent terminology costs more than any single bad sentence. (rootnotes, confirmed 2026-08-15 against Claude Code 2026-08) [templated]
- [Multi-language support for an agent writing interface code](https://the-handover.org/docs/multi-language-support.md): Why concatenating a sentence breaks translation, and the assumptions in code that only hold for one language. (rootnotes, confirmed 2026-08-21 against Claude Code 2026-08) [templated]

## Design

- [A design working agreement: propose, and do not ship](https://the-handover.org/docs/design-working-agreement.md): What an agent may change in a design system unattended, where it must stop, and how to tell a problem of taste from a problem of structure before spending a day on the wrong one. (rootnotes, confirmed 2026-08-30 against Claude Code 2026-08) [templated]
- [Accessibility for an agent building and testing interfaces](https://the-handover.org/docs/accessibility-commitment.md): The conformance level, what gets verified and how, and the failures an agent introduces without noticing. (rootnotes, confirmed 2026-08-21 against Claude Code 2026-08) [templated]
- [Design system context for an agent building interfaces](https://the-handover.org/docs/design-system-context.md): Why an agent drifts a visual language one plausible value at a time, and the rules that stop it. (rootnotes, confirmed 2026-08-15 against Claude Code 2026-08) [templated]

## Packs

Curated sets, downloadable as one archive with a manifest.

- [Measuring your own work](https://the-handover.org/packs/measuring-your-own-work): Five failures from building a tool that scores code quality: what the proxies actually measured, what the checks never examined, why validation had no oracle, and what an authoritative interface costs when it is wrong.
- [Project root starter](https://the-handover.org/packs/project-root-starter): Every rootnote in the library: the commercial, privacy, documentation, design and editorial context an agent cannot read from the code.
- [Design context](https://the-handover.org/packs/design-context): What a design project needs an agent to read before it touches anything: the system, the accessibility floor it is held to, and where the work stops.
- [Security baseline](https://the-handover.org/packs/security-baseline): The floor for any project an agent works in: process hygiene, credential handling, and dependency discipline.
- [Shipping a desktop app](https://the-handover.org/packs/desktop-app-distribution): Signing, notarisation and signed self-updates for a desktop application distributed outside an app store.
- [Testing without the live service](https://the-handover.org/packs/testing-without-the-live-service): Drive the interface by stable identity and fake the network, so a full journey runs headlessly with no live external calls.
- [New edge project](https://the-handover.org/packs/new-edge-project): Standing up a site or API on edge infrastructure without the reputation and credential mistakes.

## Optional

- [The canon](https://the-handover.org/docs/canon.md): the seven invariants every document here satisfies.
- [Contributing](https://the-handover.org/docs/contributing.md): how submission and review work.
- [Build a pack](https://the-handover.org/build): select any documents and download them together.