# 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] - [A rootnote per tool — the vendor's half and the community's half](https://the-handover.org/docs/a-rootnote-per-tool.md): Each tool a project depends on deserves its own short rootnote in two layers — the vendor's map of its documentation, and a record of where it catches agents out, which vendors rarely publish. (guides, confirmed 2026-10-23 against Claude Code 2026-10) - [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) - [Asking an AI to check its own work is not a second opinion](https://the-handover.org/docs/asking-ai-to-check-its-own-work.md): Research finds that asking a model to review its answer, or whether it is sure, can turn right answers wrong — and that correction works when something external can be checked. (readings, confirmed 2026-10-20 against Jie Huang, Xinyun Chen, Swaroop Mishra, Huaixiu Steven Zheng, Adams Wei Yu, Xinying Song, Denny Zhou, Mrinank Sharma, Meg Tong, Tomasz Korbak, David Duvenaud, Amanda Askell, Samuel R. Bowman, Newton Cheng, Esin Durmus, Zac Hatfield-Dodds, Scott R. Johnston and others, Ryo Kamoi, Yusen Zhang, Nan Zhang, Jiawei Han, Rui Zhang) - [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) - [Open source and licence policy for an agent adding code](https://the-handover.org/docs/open-source-and-licence-policy.md): Which licences may enter the project, what even permissive licences oblige you to ship, and where code copied from anywhere — including generated code — has to come from. (rootnotes, confirmed 2026-10-19 against Claude Code 2026-10) [templated] - [Telling an AI it is an expert does not make it more accurate](https://the-handover.org/docs/telling-ai-it-is-an-expert.md): A study of 162 personas found none made models reliably more accurate on factual questions. A role shapes tone and focus; accuracy comes from what you hand over, not what you call the model. (readings, confirmed 2026-10-20 against Mingqian Zheng, Jiaxin Pei, Lajanugen Logeswaran, Moontae Lee, David Jurgens, Anthropic) - [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] - [Where something sits in a long prompt changes whether it gets used](https://the-handover.org/docs/where-it-sits-in-a-long-prompt.md): Models used information at the start and end of long inputs far better than in the middle — at worst, below having no documents. Put material first, the question last, and cut what is not needed. (readings, confirmed 2026-10-20 against Nelson F. Liu, Kevin Lin, John Hewitt, Ashwin Paranjape, Michele Bevilacqua, Fabio Petroni, Percy Liang, Anthropic) - [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, unconfirmed] - [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] - [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) - [Supportability for an agent working on software people use](https://the-handover.org/docs/supportability.md): Where people get help, which versions are supported, and what an error message, a log line and a diagnostic bundle must and must never contain. (rootnotes, confirmed 2026-10-19 against Claude Code 2026-10) [templated] - [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] - [Brand and claims for an agent writing about the product](https://the-handover.org/docs/brand-and-claims.md): The exact name, the claims the product never makes, and how other companies' names and marks may be used — brand decisions an agent cannot infer from the code. (rootnotes, confirmed 2026-10-19 against Claude Code 2026-10) [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] ## Withdrawn Still reachable, with no successor. The reason is the replacement. - [Running a local neural TTS model, and the artifact that changed the runtime](https://the-handover.org/docs/local-neural-tts-on-candle.md) — Too narrow to maintain: one model on one runtime, where the specifics went stale faster than anyone revisited them. The durable finding — that a port correct operation-by-operation can still be wrong in its output, because op-level equivalence is not output equivalence — is the subject of "Verification that cannot fail" in The System: https://the-handover.org/system ## Services What to tell an agent about a specific tool. Plain text. - [Polar](https://the-handover.org/services/polar.md) - [Stripe](https://the-handover.org/services/stripe.md) - [Paddle](https://the-handover.org/services/paddle.md) - [Lemon Squeezy](https://the-handover.org/services/lemon-squeezy.md) - [Keygen](https://the-handover.org/services/keygen.md) - [Cloudflare Pages and Workers](https://the-handover.org/services/cloudflare-pages.md) - [Vercel](https://the-handover.org/services/vercel.md) - [Netlify](https://the-handover.org/services/netlify.md) - [Tauri](https://the-handover.org/services/tauri.md) - [Electron](https://the-handover.org/services/electron.md) - [Apple code signing and notarisation](https://the-handover.org/services/apple-code-signing.md) - [Windows code signing](https://the-handover.org/services/windows-code-signing.md) - [Plausible](https://the-handover.org/services/plausible.md) - [PostHog](https://the-handover.org/services/posthog.md) - [Google Analytics](https://the-handover.org/services/google-analytics.md) - [Clerk](https://the-handover.org/services/clerk.md) - [Auth.js](https://the-handover.org/services/auth-js.md) - [Supabase](https://the-handover.org/services/supabase.md) - [Cloudflare Access](https://the-handover.org/services/cloudflare-access.md) - [Postgres](https://the-handover.org/services/postgres.md) - [SQLite](https://the-handover.org/services/sqlite.md) - [Cloudflare D1](https://the-handover.org/services/cloudflare-d1.md) - [Turso](https://the-handover.org/services/turso.md) - [Mailgun](https://the-handover.org/services/mailgun.md) - [Postmark](https://the-handover.org/services/postmark.md) - [Resend](https://the-handover.org/services/resend.md) - [Amazon SES](https://the-handover.org/services/amazon-ses.md) ## The System The library read in order, as one course. Thirteen chapters, three parts. - [The System](https://the-handover.org/system.md): the whole course as plain text, in order, with attribution per chapter. ## 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. - [Rootnote builder](https://the-handover.org/build): answer what your project uses and get a rootnote assembled for it. - [Guides](https://the-handover.org/guides): how to work with AI from published evidence, with retrieval dates and the dated findings separated from the durable ones.