{ "name": "The Handover", "description": "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.", "thesis": { "claim": "Every session starts cold. Nothing was forgotten, because nothing was there. This is a handover problem, not a memory problem.", "url": "https://the-handover.org/docs/working-with-ai-the-system" }, "standards": { "vetted": "Read adversarially before publication. The baseline; unmarked.", "position": "The site's own view, not independently reviewed. Marked in the document's own attribution header so the distinction survives the file leaving the site.", "field": "provenance" }, "url": "https://the-handover.org", "licence": { "documents": "Handover-1.0", "url": "https://the-handover.org/licence", "note": "Copyright retained by the authors and Captivated Ltd; this is not an open licence. You may read, download, copy into your own projects — private, public, commercial — modify, and machine-read. Reserved: republishing the corpus as a corpus. Keep the header each file carries." }, "generated": "2026-09-19", "conventions": { "plain_text": "Append .md to any document URL for the source markdown, no markup.", "confirmation_threshold_days": 90, "unconfirmed": "Past the threshold. Published and readable — staleness is a display state, not a withdrawal.", "areas": [ "general", "coding", "research", "writing", "design" ], "categories": [ "processes", "prompts", "rootnotes", "guides", "readings" ] }, "counts": { "documents": 43, "superseded": 0, "packs": 7 }, "documents": [ { "slug": "a-pointer-rootnote", "title": "A pointer rootnote — addresses, not knowledge", "summary": "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.", "area": "general", "category": "rootnotes", "tags": [ "rootnotes", "retrieval", "context", "pointers", "tokens", "agents" ], "headings": [ "The entries", "What is deliberately not available", "Hook the decision, not the activity", "The one rule that keeps it working", "Keeping it honest", "Why this is a good trade" ], "url": "https://the-handover.org/docs/a-pointer-rootnote", "plain_text_url": "https://the-handover.org/docs/a-pointer-rootnote.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-09-18", "last_confirmed": "2026-09-19", "tested_on": [ { "tool": "Claude Code", "version": "2026-09", "date": "2026-09-19" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "library_root", "label": "Where the fetchable material lives", "required": true, "help": "A path, a URL, or the name of a service. Not inside this repository — if it were small enough to keep here it would not need a pointer." }, { "token": "library_access", "label": "How an agent reaches it", "required": true, "help": "Exactly enough to act on. An address an agent cannot resolve is worse than no address, because it spends effort failing before it asks." } ], "sha256": "9e59ecbff96e63db752d3757d1761ff27075f520a12319d19df24f0dec182269" }, { "slug": "accessibility-commitment", "title": "Accessibility for an agent building and testing interfaces", "summary": "The conformance level, what gets verified and how, and the failures an agent introduces without noticing.", "area": "design", "category": "rootnotes", "tags": [ "accessibility", "wcag", "screen-readers", "keyboard", "testing", "inclusive-design" ], "headings": [ "The blind spot that makes this a commitment rather than a checklist", "The commitment", "What is actually required before merge", "Where to stop and ask", "Why this survives pressure" ], "url": "https://the-handover.org/docs/accessibility-commitment", "plain_text_url": "https://the-handover.org/docs/accessibility-commitment.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-21", "last_confirmed": "2026-08-21", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-21" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "accessibility_standard", "label": "Accessibility standard", "required": true, "help": "The conformance level this project holds itself to. Shared with the design system rootnote.", "default": "WCAG 2.2 AA" }, { "token": "assistive_tech_support", "label": "Assistive technology commitment", "required": true, "help": "What is actually tested against, rather than what is theoretically supported." } ], "sha256": "f2bae6c2e5b194878f56920f68f53dc8a29b4046ec04e7e517d3e373e9da24ff" }, { "slug": "affiliate-links-on-a-content-site", "title": "Affiliate links on a content site", "summary": "What you link to decides your tooling, and the consent rules decide whether a cookieless story survives.", "area": "general", "category": "guides", "tags": [ "affiliate", "monetisation", "disclosure", "consent", "gdpr", "editorial-trust" ], "headings": [ "The rule that protects the site", "What you link to decides your tooling", "The tooling landscape", "Compliance, and where the real constraint sits", "A framework, not a decision", "Verify before relying" ], "url": "https://the-handover.org/docs/affiliate-links-on-a-content-site", "plain_text_url": "https://the-handover.org/docs/affiliate-links-on-a-content-site.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-31", "last_confirmed": "2026-07-31", "tested_on": [ { "tool": "UK CAP Code, PECR and UK GDPR", "version": "as at 2026-07", "date": "2026-07-31" } ], "unconfirmed": false, "normative": false, "hard_won": false, "sha256": "d33405d2b53f9319c5c121781e372c3a841a74c953a5dd50c6bfaca2cd38b7f3" }, { "slug": "agents-md-does-not-help", "title": "The strongest evidence against this library, read carefully", "summary": "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.", "area": "coding", "category": "readings", "tags": [ "context-files", "evidence", "agents-md", "measurement", "disagreement" ], "headings": [ "What they did", "The headline, which is the least interesting part", "The finding that matters", "Three places it genuinely challenges us", "Their tasks have discoverable answers. That is the whole disagreement.", "Where evidence is the wrong instrument", "We applied their finding to ourselves, and it found something", "What we would have to run" ], "url": "https://the-handover.org/docs/agents-md-does-not-help", "plain_text_url": "https://the-handover.org/docs/agents-md-does-not-help.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain" ], "date_written": "2026-09-14", "last_confirmed": "2026-09-14", "source": [ { "title": "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?", "author": "Thibaud Gloaguen, Niels Mündler, Mark Müller, Veselin Raychev, Martin Vechev", "url": "https://arxiv.org/abs/2602.11988", "published": "2026-02-12", "retrieved": "2026-09-14" } ], "unconfirmed": false, "normative": false, "hard_won": false, "sha256": "7211a2a80dcbdf37209509e3ed44b2770811a452970913881d469fdd491b1862" }, { "slug": "auditing-a-context-file", "title": "Auditing a context file you already have", "summary": "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.", "area": "general", "category": "processes", "tags": [ "context-files", "rootnotes", "audit", "tokens", "agents" ], "headings": [ "Before starting", "The pass", "The grammatical tell", "What to do with the result", "What this does not do" ], "url": "https://the-handover.org/docs/auditing-a-context-file", "plain_text_url": "https://the-handover.org/docs/auditing-a-context-file.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-09-16", "last_confirmed": "2026-09-16", "confirmed_with": [ { "model": "claude-opus-5", "date": "2026-09-16" } ], "unconfirmed": false, "normative": false, "hard_won": false, "sha256": "1db23c36f5a1c42c6babbd8c05bc7e5825a535ecf89828ae1cfcf34b03c0be3e" }, { "slug": "business-context", "title": "Business context for an agent working on commercial software", "summary": "The commercial facts an agent cannot read from a repository, and the decisions that go wrong without them.", "area": "general", "category": "rootnotes", "tags": [ "business-context", "commercial", "licensing", "jurisdiction", "context-file", "governance" ], "headings": [ "Why this file exists", "The constants", "Licensing obligations run in both directions", "What is not in this file", "Decisions that need a human", "Public commitments are constraints", "For the agent working here" ], "url": "https://the-handover.org/docs/business-context", "plain_text_url": "https://the-handover.org/docs/business-context.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-14", "last_confirmed": "2026-08-14", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-14" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "legal_entity", "label": "Legal entity", "required": true, "help": "The company or person that owns the work. Used for copyright, licensing and contracts." }, { "token": "jurisdiction", "label": "Primary jurisdiction", "required": true, "help": "Where the entity is established. Determines which consumer, data and tax rules apply." }, { "token": "default_visibility", "label": "Default visibility of work", "required": true, "help": "What to assume about anything committed, written in an issue, or published.", "default": "private — assume nothing leaves the repository without a decision" } ], "sha256": "511012933c613bf27be18cde94cabfc0282965bb3c8df7067ade7cfdda822027" }, { "slug": "canon", "title": "The canon", "summary": "Seven invariants every document in this library must satisfy, and what happens to one that does not.", "area": "general", "category": "guides", "tags": [ "canon", "safety", "standards", "vetting" ], "headings": [ "The seven", "What each one is actually protecting", "Mention is not instruction", "The dangerous kind of submission", "Arguing with the canon", "How the canon is enforced" ], "url": "https://the-handover.org/docs/canon", "plain_text_url": "https://the-handover.org/docs/canon.md", "authors": [ { "name": "The Handover", "url": "https://the-handover.org" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-06", "last_confirmed": "2026-08-06", "unconfirmed": false, "normative": true, "hard_won": true, "sha256": "128093fea0aefc07f4515a7ad73533ced4e6caa381a4a5ab7686b9d0384df3a0" }, { "slug": "contributing", "title": "Contributing", "summary": "How to submit a document, what happens to it during review, and what rights you keep.", "area": "general", "category": "guides", "tags": [ "contributing", "review", "licensing", "attribution" ], "headings": [ "What's worth submitting", "Rootnotes", "Overlap is routed, not rejected", "Where to send it", "What the frontmatter must say", "What happens to it", "Identity, and what stays private", "Rights, plainly", "After publication" ], "url": "https://the-handover.org/docs/contributing", "plain_text_url": "https://the-handover.org/docs/contributing.md", "authors": [ { "name": "The Handover", "url": "https://the-handover.org" } ], "licence": "Handover-1.0", "formats": [ "plain" ], "date_written": "2026-08-07", "last_confirmed": "2026-08-07", "unconfirmed": false, "normative": true, "hard_won": false, "sha256": "52be7899fcbc7498c50de5c9feac7338b711e25a4c482f08e805b18d7bb71874" }, { "slug": "custom-domains-for-edge-deployments", "title": "Ship edge deployments on a custom domain, never the platform subdomain", "summary": "Free platform subdomains are blocked as a category by security filters, so a subset of real users silently fails.", "area": "coding", "category": "guides", "tags": [ "cloudflare", "workers", "pages", "dns", "custom-domain", "reputation" ], "headings": [ "The rule", "Why, concretely", "What to do", "How to test for it, given your own network hides it", "The general principle" ], "url": "https://the-handover.org/docs/custom-domains-for-edge-deployments", "plain_text_url": "https://the-handover.org/docs/custom-domains-for-edge-deployments.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-22", "last_confirmed": "2026-08-08", "tested_on": [ { "tool": "wrangler", "version": "4.x" }, { "tool": "Cloudflare Workers / Pages", "version": "2026-07" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "6304426f72897dee8c868baa5efbbe5aa4bcfa297c406bc2cef0d0b4dc301d3b" }, { "slug": "data-handling-and-privacy", "title": "Data handling and privacy for an agent working with real data", "summary": "What counts as personal data, where it must never end up, and the changes that quietly widen what you hold.", "area": "general", "category": "rootnotes", "tags": [ "privacy", "gdpr", "personal-data", "logging", "retention", "data-residency" ], "headings": [ "Why an agent needs this in front of it", "What counts as personal data here", "The regime", "Where personal data must not go", "Never log", "Sending data to model providers", "Retention, and what deletion actually means", "The changes that quietly widen what you hold", "Where to stop and ask" ], "url": "https://the-handover.org/docs/data-handling-and-privacy", "plain_text_url": "https://the-handover.org/docs/data-handling-and-privacy.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-21", "last_confirmed": "2026-08-21", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-21" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "jurisdiction", "label": "Primary jurisdiction", "required": true, "help": "Determines which data protection regime applies. Shared with the business context." }, { "token": "retention_default", "label": "Default retention", "required": true, "help": "How long personal data is kept unless something specific says otherwise." }, { "token": "data_residency", "label": "Data residency requirement", "required": true, "help": "Where personal data must physically stay, if anywhere. Say \"no requirement\" if there is none.", "default": "no requirement" } ], "sha256": "6e6ef926fa1c8c0839798a56b3fb05c6b237567a04eefdc723c5bbde8fcc2fb7" }, { "slug": "design-system-context", "title": "Design system context for an agent building interfaces", "summary": "Why an agent drifts a visual language one plausible value at a time, and the rules that stop it.", "area": "design", "category": "rootnotes", "tags": [ "design-system", "tokens", "accessibility", "ui", "states", "context-file" ], "headings": [ "The failure this prevents", "Tokens are the source of truth", "Every state is part of the component", "Accessibility is a floor", "Before building a new component", "Responsive and density", "The boundary with the editorial guide", "What needs a human" ], "url": "https://the-handover.org/docs/design-system-context", "plain_text_url": "https://the-handover.org/docs/design-system-context.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-15", "last_confirmed": "2026-08-15", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-15" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "tokens_path", "label": "Design tokens source of truth", "required": true, "help": "The single file that defines colour, type, spacing and radius values." }, { "token": "accessibility_standard", "label": "Accessibility standard", "required": true, "help": "The conformance level this project holds itself to. Shared with the accessibility rootnote.", "default": "WCAG 2.2 AA" } ], "sha256": "79506fce319d41163205ff3c5b309e01599e49f22c6c7f460da6087890e945f4" }, { "slug": "design-working-agreement", "title": "A design working agreement: propose, and do not ship", "summary": "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.", "area": "design", "category": "rootnotes", "tags": [ "design", "working-agreement", "design-systems", "accessibility", "agents" ], "headings": [ "The division", "Safe without asking", "Stop and ask first", "Taste or structure? Establish this before touching anything", "What was rejected, and why", "Accessibility is a floor", "Consistency beats local improvement", "Reporting honestly", "Where this lives" ], "url": "https://the-handover.org/docs/design-working-agreement", "plain_text_url": "https://the-handover.org/docs/design-working-agreement.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-30", "last_confirmed": "2026-08-30", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-30" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "tokens_path", "label": "Design tokens source of truth", "required": true, "help": "The single file that defines colour, type, spacing and radius. Shared with the design-system rootnote, so answering once fills both." }, { "token": "accessibility_standard", "label": "Accessibility standard", "required": true, "help": "The conformance level this project holds itself to. Shared with the design-system and accessibility rootnotes — one answer, three documents.", "default": "WCAG 2.2 AA" }, { "token": "ships_via", "label": "How a design change reaches a user, and who decides", "required": true, "help": "Name the gate. Without it \"ship\" is undefined, and an agent will read a merged branch or a saved file as the end of the job." } ], "sha256": "9b0311a53ca5ff5a3e4e772e4eae5938b4c59feda8348c41db13e2e94f46623d" }, { "slug": "desktop-app-signed-self-updates", "title": "Signed self-updates for a desktop app, hosted on object storage", "summary": "Wiring an updater keypair, a version manifest and a public bucket, and the flags that make uploads silently do nothing.", "area": "coding", "category": "guides", "tags": [ "tauri", "updater", "minisign", "r2", "object-storage", "releases", "desktop" ], "headings": [ "The model, in three steps", "Key management", "App-side wiring", "The version manifest", "Hosting", "Cutting a release", "Proving it end to end", "Gotcha quick-reference", "For CI" ], "url": "https://the-handover.org/docs/desktop-app-signed-self-updates", "plain_text_url": "https://the-handover.org/docs/desktop-app-signed-self-updates.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-13", "last_confirmed": "2026-08-08", "tested_on": [ { "tool": "Tauri", "version": "2.x", "os": "macOS" }, { "tool": "wrangler", "version": "4.x" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "c9011b1c199185eadfbd7e22001f3ce5703d351c54d7acaa5887e3f765a0fb36" }, { "slug": "documentation-standard", "title": "Documentation standard for agent-maintained projects", "summary": "A linked set of documents with defined sections and relationships, rather than one long file that narrates the code.", "area": "coding", "category": "rootnotes", "tags": [ "documentation", "context-file", "vault", "decision-log", "conventions" ], "headings": [ "The shape: a linked set, not a pile and not one long file", "File naming", "The set records when it was last confirmed", "The sections", "What to read first", "The links are the structure", "Writing rules", "What is deliberately not here", "User documentation", "Related rootnotes", "For the agent working here" ], "url": "https://the-handover.org/docs/documentation-standard", "plain_text_url": "https://the-handover.org/docs/documentation-standard.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-12", "last_confirmed": "2026-08-25", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-25" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "docs_path", "label": "Documentation directory", "required": true, "help": "Where the documentation set lives, relative to the repository root.", "default": "docs/" }, { "token": "spelling_variant", "label": "Spelling variant", "required": true, "help": "Applies to documentation prose. Must match whatever user-facing copy uses.", "default": "British English (en-GB)" }, { "token": "link_style", "label": "Link style between documents", "required": true, "help": "Wikilinks suit an Obsidian-style vault; relative links render on most code hosts.", "default": "Obsidian-style [[wikilinks]]" } ], "sha256": "5bdb1e39328c3bf5984be900688130a814db3d3bdb2b89ed79581adcb4a80b5a" }, { "slug": "drafting-email-an-agent-does-not-send", "title": "Drafting email an agent does not send", "summary": "The draft-and-hand-over boundary for outbound email, and the ways email rendering differs from the web.", "area": "general", "category": "guides", "tags": [ "email", "newsletter", "outbound", "human-review", "boundaries" ], "headings": [ "The boundary: draft, validate, hand over", "Email is not the web", "Why this belongs in an agent's context" ], "url": "https://the-handover.org/docs/drafting-email-an-agent-does-not-send", "plain_text_url": "https://the-handover.org/docs/drafting-email-an-agent-does-not-send.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-08", "last_confirmed": "2026-08-08", "tested_on": [ { "tool": "major email clients", "version": "as at 2026-08", "date": "2026-08-08" } ], "unconfirmed": false, "normative": false, "hard_won": false, "sha256": "f75e4fa20ad9211118ebc9f48aee6748be71946c78b7907686bbebe8a4c7516e" }, { "slug": "faking-external-services-for-tests", "title": "Faking an external service you do not own", "summary": "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.", "area": "coding", "category": "guides", "tags": [ "testing", "integration", "http", "e2e", "fixtures", "isolation" ], "headings": [ "Why not stub each request", "The two seams", "Anatomy", "Test mode, so the running application can use it", "Fidelity, which is the load-bearing caveat", "Driving a real backend from an ordinary browser", "Isolation is not optional", "Adapting to any stack", "The companion problem" ], "url": "https://the-handover.org/docs/faking-external-services-for-tests", "plain_text_url": "https://the-handover.org/docs/faking-external-services-for-tests.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-17", "last_confirmed": "2026-08-21", "tested_on": [ { "tool": "Rust with an embedded HTTP router", "version": "2026-08" }, { "tool": "Playwright", "version": "1.x" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "a9f186f2ad9a9d05c441cb36932e8d41f2c60799d7eabd94c45a5690f66bdf70" }, { "slug": "four-ratios-four-different-failures", "title": "Four ratios, four different failures", "summary": "Four ratios used to score code quality, and four different reasons each one measured something other than what it claimed.", "area": "coding", "category": "guides", "tags": [ "metrics", "goodhart", "code-quality", "measurement", "thresholds", "tooling" ], "headings": [ "The threshold that ranked nothing", "Failure one: it punished good structure", "Failure two: it punished being a command-line tool", "Failure three: it measured how much code existed", "Failure four: it measured file granularity", "The rule", "What replaced them", "Where a number is still allowed", "One consequence worth expecting" ], "url": "https://the-handover.org/docs/four-ratios-four-different-failures", "plain_text_url": "https://the-handover.org/docs/four-ratios-four-different-failures.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-28", "last_confirmed": "2026-08-28", "tested_on": [ { "tool": "Rust", "version": "1.96.0", "os": "macOS" }, { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-28" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "e8762fc7c07275ba94166e7388c0f1bab304f4346ab5e7abba5f0c1a2be65281" }, { "slug": "killing-processes-shared-machine", "title": "Killing processes safely on a shared machine", "summary": "Why process-selection commands over-select silently, and the inspect-then-kill pattern that catches it.", "area": "coding", "category": "guides", "tags": [ "shell", "processes", "lsof", "pkill", "agents", "shared-machine" ], "headings": [ "Rule 1 — Always inspect before you kill", "Rule 2 — Get the lsof invocation exactly right", "Rule 3 — Never kill by broad substring match", "Rule 4 — Never suppress errors on a kill command", "Rule 5 — Prefer not killing at all", "Rule 6 — Headless browsers don't exit, and they orphan their helpers", "Two related output traps", "The canonical safe form", "The general principle" ], "url": "https://the-handover.org/docs/killing-processes-shared-machine", "plain_text_url": "https://the-handover.org/docs/killing-processes-shared-machine.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-07", "last_confirmed": "2026-08-07", "tested_on": [ { "tool": "lsof", "version": "4.x", "os": "macOS" }, { "tool": "pkill / pgrep", "version": "procps-style", "os": "macOS, Linux" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "44d33208ce1405ffdf1ff9092466bdfd23e0aa4680eced2f3f9306d003f685a3" }, { "slug": "language-editorial-guide", "title": "Language and editorial guide for agent-written copy", "summary": "Voice, mechanics and error-message rules, and why inconsistent terminology costs more than any single bad sentence.", "area": "writing", "category": "rootnotes", "tags": [ "editorial", "voice", "tone", "microcopy", "error-messages", "terminology", "context-file" ], "headings": [ "The failure this prevents", "Voice and tone", "Mechanics", "Terminology is a list, not a preference", "Error messages", "Microcopy", "Words to avoid", "The boundary with the design system", "What needs a human" ], "url": "https://the-handover.org/docs/language-editorial-guide", "plain_text_url": "https://the-handover.org/docs/language-editorial-guide.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-15", "last_confirmed": "2026-08-15", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-15" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "spelling_variant", "label": "Spelling variant", "required": true, "help": "Applies to prose, UI copy and documentation. Code and APIs keep their own spellings.", "default": "British English (en-GB)" }, { "token": "heading_case", "label": "Heading capitalisation", "required": true, "help": "Sentence case is easier to apply consistently; title case has more rules to get wrong.", "default": "sentence case" } ], "sha256": "4d01d8651e74e90fdd62b5bea67cc2ada9fd9544ce7327cd92ee31d60254cd54" }, { "slug": "live-secrets-in-ai-sessions", "title": "Handling live secrets in AI coding sessions", "summary": "Getting a credential from its store into its destination without it ever appearing as text the assistant emits.", "area": "coding", "category": "guides", "tags": [ "secrets", "credentials", "keychain", "transcripts", "agents" ], "headings": [ "The threat model", "The core pattern: a secret store as the courier", "Rules of thumb", "Quick reference", "Why the assistant should refuse" ], "url": "https://the-handover.org/docs/live-secrets-in-ai-sessions", "plain_text_url": "https://the-handover.org/docs/live-secrets-in-ai-sessions.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-07", "last_confirmed": "2026-08-07", "tested_on": [ { "tool": "security (macOS Keychain CLI)", "version": "macOS 14+", "os": "macOS" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "9500dfd8b29cb16839d65a7f04a5ab98860ea4d268e0b73f4b298310af9864ec" }, { "slug": "local-neural-tts-on-candle", "title": "Running a local neural TTS model, and the artifact that changed the runtime", "summary": "Why a model correct op-by-op can still sound wrong, and the CPU hot paths a naive port leaves on the table.", "area": "coding", "category": "guides", "tags": [ "tts", "kokoro", "candle", "rust", "onnx", "local-ai", "numerical-precision" ], "headings": [ "The model, concretely", "Why not ONNX — the metallic artifact", "Running it on Candle", "CPU-only, on purpose", "Phonemes without espeak", "The call path", "Making CPU inference fast", "Checklist" ], "url": "https://the-handover.org/docs/local-neural-tts-on-candle", "plain_text_url": "https://the-handover.org/docs/local-neural-tts-on-candle.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-20", "last_confirmed": "2026-08-11", "tested_on": [ { "tool": "Candle", "version": "0.10", "os": "macOS" }, { "tool": "misaki-rs", "version": "0.3" }, { "tool": "Kokoro-82M", "version": "v1.0" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "b10c1badb2f9a00a42fa2497e90685398aa308c1381c460f9e40b6663e15fef7" }, { "slug": "macos-signing-and-notarisation", "title": "Signing and notarising a macOS app for direct distribution", "summary": "The certificate types, the notarisation flow, and the build setting that silently ships an unnotarised DMG.", "area": "coding", "category": "guides", "tags": [ "macos", "codesign", "notarisation", "gatekeeper", "tauri", "distribution" ], "headings": [ "The certificate types are not interchangeable", "Organisation account specifics", "Getting the identity onto the signing machine", "Notarisation credentials", "Build, then notarise — as separate steps", "The gotcha that ships a broken build", "Verify, notarise, staple, verify again", "Secret hygiene", "Gotcha quick-reference" ], "url": "https://the-handover.org/docs/macos-signing-and-notarisation", "plain_text_url": "https://the-handover.org/docs/macos-signing-and-notarisation.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-16", "last_confirmed": "2026-08-08", "tested_on": [ { "tool": "notarytool", "version": "Xcode 26", "os": "macOS" }, { "tool": "Tauri", "version": "2.x", "os": "macOS" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "e2c19f458a04fdf9e927cbe161702520e03da29629bd3fc6c7c4930413804351" }, { "slug": "multi-language-support", "title": "Multi-language support for an agent writing interface code", "summary": "Why concatenating a sentence breaks translation, and the assumptions in code that only hold for one language.", "area": "writing", "category": "rootnotes", "tags": [ "i18n", "l10n", "localisation", "translation", "rtl", "pluralisation" ], "headings": [ "The one rule that matters most", "Assumptions in code that hold only for one language", "Formats belong to the locale, not to you", "Working with the strings", "Even when there is one language today", "Where to stop and ask" ], "url": "https://the-handover.org/docs/multi-language-support", "plain_text_url": "https://the-handover.org/docs/multi-language-support.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-21", "last_confirmed": "2026-08-21", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-21" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "source_locale", "label": "Source locale", "required": true, "help": "The locale interface copy is authored in, and which everything else translates from.", "default": "en-GB" }, { "token": "supported_locales", "label": "Supported locales", "required": true, "help": "What actually ships. Say \"none yet\" if the product is single-language today.", "default": "none yet — single language, but written to be translatable" } ], "sha256": "56310d4f75a68b6efb77e4bc0defb1842ade1427e9a076ecc896b80f88dd5559" }, { "slug": "new-domain-reputation", "title": "Getting a new domain past security filters", "summary": "Two independent causes of a false-positive block, only one of which you can do anything about.", "area": "coding", "category": "guides", "tags": [ "dns", "domains", "reputation", "filtering", "launch", "cloudflare" ], "headings": [ "There are two independent causes, and only one is fixable", "Launch hygiene, at go-live", "Submit a category", "Diagnosing a live block", "Per-launch checklist", "Why this matters more than it sounds" ], "url": "https://the-handover.org/docs/new-domain-reputation", "plain_text_url": "https://the-handover.org/docs/new-domain-reputation.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-22", "last_confirmed": "2026-07-22", "tested_on": [ { "tool": "Cloudflare Radar and the major URL-reputation databases", "version": "as at 2026-07", "date": "2026-07-22" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "6eb2609db88aae4793fda405a95acc6868a86fe6564d5692fc85514cfd1cbc40" }, { "slug": "nothing-was-wrong-or-nothing-was-examined", "title": "Nothing was wrong, or nothing was examined", "summary": "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.", "area": "coding", "category": "guides", "tags": [ "testing", "verification", "assertions", "false-negatives", "ci", "agents" ], "headings": [ "A criterion that agreed with everything", "A failure count that included things it could not answer", "A test that passed five claims nothing could contradict", "The fix: make the check declare its candidates", "What this looks like elsewhere", "Then it happened to the person who wrote this, four times in an afternoon", "What that says that the three cases above do not", "The single question" ], "url": "https://the-handover.org/docs/nothing-was-wrong-or-nothing-was-examined", "plain_text_url": "https://the-handover.org/docs/nothing-was-wrong-or-nothing-was-examined.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-29", "last_confirmed": "2026-09-18", "tested_on": [ { "tool": "Rust", "version": "1.96.0", "os": "macOS" }, { "tool": "Claude Code", "version": "2026-09", "date": "2026-09-18" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "4e5cc068e606e5f2b7ab5541cd243143d9866ce1a7ee3d12c7cd76d93ce64995" }, { "slug": "operational-runbook", "title": "Operating something that is live, and what an agent may do during an incident", "summary": "Stop the bleeding before diagnosing, record while acting, and the autonomy rules that matter most when they are under pressure.", "area": "coding", "category": "rootnotes", "tags": [ "operations", "incidents", "runbook", "rollback", "oncall", "observability" ], "headings": [ "Why an agent needs explicit rules here", "The order of operations", "What an agent may do", "And you may be the cause", "Related rootnotes", "What a runbook must contain", "Software you ship rather than run", "Afterwards" ], "url": "https://the-handover.org/docs/operational-runbook", "plain_text_url": "https://the-handover.org/docs/operational-runbook.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-21", "last_confirmed": "2026-08-26", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-26" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "escalation_path", "label": "Escalation path", "required": true, "help": "Who is told, and how. If the answer is nobody, say so — that is a real answer and it changes the advice.", "default": "nobody — this is operated by one person, so see the note on operating alone" }, { "token": "failure_signal", "label": "How you find out something is wrong", "required": true, "help": "A dashboard for a service; user reports or crash telemetry for shipped software. Whatever actually reaches you first.", "default": "user reports, since there is no dashboard for software running on other people's machines" } ], "sha256": "66ef47c1cd9f7f3c35a00e99c0ff9b3a6ba3c611a8e51562469dc878dc898fdb" }, { "slug": "patterns-narrower-than-reality", "title": "Your pattern matches the shape you pictured", "summary": "Two ways text scanning silently misses what it exists to find — soft line wraps, and identifiers in an unexpected form.", "area": "coding", "category": "guides", "tags": [ "regex", "scanning", "secrets-detection", "text-processing", "false-negatives" ], "headings": [ "1. Line-by-line matching misses soft-wrapped prose", "2. Identifiers rarely appear in their canonical form", "The asymmetry that makes this dangerous", "What to do" ], "url": "https://the-handover.org/docs/patterns-narrower-than-reality", "plain_text_url": "https://the-handover.org/docs/patterns-narrower-than-reality.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-11", "last_confirmed": "2026-08-11", "tested_on": [ { "tool": "Node", "version": "24", "os": "macOS" }, { "tool": "JavaScript RegExp", "version": "ES2024", "date": "2026-08-11" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "e900d284392cf2f523d276a23e2346b8b3ed59e93757f31a3a34fa65929d6aad" }, { "slug": "polar-billing-webhooks", "title": "Wiring Polar billing and webhooks without cutting off paying customers", "summary": "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.", "area": "coding", "category": "guides", "tags": [ "polar", "billing", "webhooks", "hmac", "subscriptions", "merchant-of-record" ], "headings": [ "Before you build: is your product even allowed?", "The signature scheme deviates from the spec it cites", "Why it is a trap rather than merely a bug", "Verify the raw body, never a re-serialised object", "Sandbox and production are entirely separate", "Product fields that are locked at creation", "Graduated versus volume tiers, and the revenue inversion", "Prefer private products if you attribute through your own IDs", "The seat-assignment privacy trap", "Organisation settings with dangerous defaults", "Webhook semantics that decide whether you cut off paying customers", "A field-name asymmetry that is easy to mis-wire", "The upgrade race, which follows from monthly and annual being separate products", "Endpoint immutability and delivery behaviour", "Verify the product through the API, not the dashboard", "Minting a checkout server-side", "Testing against real signed deliveries", "What a clean integration looks like" ], "url": "https://the-handover.org/docs/polar-billing-webhooks", "plain_text_url": "https://the-handover.org/docs/polar-billing-webhooks.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-17", "last_confirmed": "2026-08-18", "tested_on": [ { "tool": "Polar API", "version": "as at 2026-08", "date": "2026-08-18" }, { "tool": "WebCrypto (workerd)", "version": "2026-07" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "afd96a3c7d1255ac3abab38e17d7648f42928b5fde0760f88a8cee50eaae0218" }, { "slug": "research-context", "title": "Research context — what has been established, and what has been ruled out", "summary": "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.", "area": "research", "category": "rootnotes", "tags": [ "research", "rootnotes", "dead-ends", "evidence", "provenance", "agents" ], "headings": [ "The question behind the question", "What counts as evidence, which is not a general question", "Dead ends — the section this document exists for", "How firmly each thing is held", "Who has already been asked", "Where this lives" ], "url": "https://the-handover.org/docs/research-context", "plain_text_url": "https://the-handover.org/docs/research-context.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-09-18", "last_confirmed": "2026-09-18", "tested_on": [ { "tool": "Claude Code", "version": "2026-09", "date": "2026-09-18" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "question", "label": "The question this project exists to answer", "required": true, "help": "The real one, not the tidy version. Shared with the research working agreement, so answering once fills both." }, { "token": "evidence_bar", "label": "What counts as evidence here", "required": true, "help": "Varies enormously by field and cannot be inferred. Shared with the working agreement." }, { "token": "dead_ends_path", "label": "Where the dead-ends record lives", "required": true, "help": "A file, not a folder, and one an agent can append to without asking. If it is somewhere awkward it will not be written, and an unwritten dead end is the whole problem this document exists for." } ], "sha256": "1997352c3448440a0b651c8a545c2f91c29ca646d210ae62468a562ad978040d" }, { "slug": "research-working-agreement", "title": "A research working agreement: gather, and do not conclude", "summary": "What an agent may do unattended in a research project, where it must stop, and why uncertainty has to survive contact with it.", "area": "research", "category": "rootnotes", "tags": [ "research", "working-agreement", "evidence", "uncertainty", "citations", "agents" ], "headings": [ "The division", "Safe without asking", "Stop and ask first", "Uncertainty is the finding, not a defect in it", "A search result is not evidence", "Absence is a search failure until proven otherwise", "Never produce a citation you did not retrieve", "Dead ends are output", "Reporting honestly", "Where this lives" ], "url": "https://the-handover.org/docs/research-working-agreement", "plain_text_url": "https://the-handover.org/docs/research-working-agreement.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-30", "last_confirmed": "2026-08-30", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-30" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "question", "label": "The question this project exists to answer", "required": true, "help": "The real one, not the tidy version. If the stated question is a proxy for something else, say what the something else is — an agent optimising the proxy is the most expensive failure available here." }, { "token": "evidence_bar", "label": "What counts as evidence here", "required": true, "help": "Varies enormously by field and cannot be inferred. A clinical reviewer and a market analyst both say \"evidence\" and mean incompatible things." }, { "token": "sources", "label": "Where the agent may look", "required": true, "help": "Name the boundary. Silence here reads as the open web, which is rarely what anyone means and occasionally a confidentiality problem." } ], "sha256": "bb2ad45169963d3c6f5289d35bd881d85b1a45ebefb6f564b509d34a19de5d4e" }, { "slug": "supply-chain-baseline-ai-development", "title": "Supply-chain security baseline for AI-assisted development", "summary": "What an agent should check before installing a dependency, and which files it must never modify without a shown diff.", "area": "coding", "category": "guides", "tags": [ "supply-chain", "dependencies", "npm", "lockfiles", "install-scripts", "ci" ], "headings": [ "What the threat actually looks like", "Before adding or updating any dependency", "When auditing existing dependencies", "Never modify without explicit approval and a shown diff", "Stop and alert immediately on", "Ecosystem notes", "CI hardening", "Why this belongs in an agent's context" ], "url": "https://the-handover.org/docs/supply-chain-baseline-ai-development", "plain_text_url": "https://the-handover.org/docs/supply-chain-baseline-ai-development.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-22", "last_confirmed": "2026-08-07", "tested_on": [ { "tool": "npm", "version": "10+" }, { "tool": "cargo", "version": "1.x" } ], "unconfirmed": false, "normative": false, "hard_won": false, "sha256": "c8e859d28eec8b76940b4b4b1c317ef66b9db58779ebf997a30b301ce0643e1b" }, { "slug": "test-against-the-tools-people-have", "title": "Test output against the tools people actually have", "summary": "A file format verified only by the reader you wrote is verified against your own assumptions.", "area": "coding", "category": "guides", "tags": [ "file-formats", "zip", "interoperability", "testing", "unicode" ], "headings": [ "The case", "UTF-8 filenames: valid, flagged correctly, still unreadable", "Empty archives: structurally valid, practically broken", "Why the unit tests could not have found either", "What to do", "The generalisation" ], "url": "https://the-handover.org/docs/test-against-the-tools-people-have", "plain_text_url": "https://the-handover.org/docs/test-against-the-tools-people-have.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-08", "last_confirmed": "2026-08-08", "tested_on": [ { "tool": "Info-ZIP unzip", "version": "6.00", "os": "macOS" }, { "tool": "Node", "version": "24", "date": "2026-08-08" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "2950763cc178684971c5fdce3234a37567a0a67a633bc953d4614cfec5980946" }, { "slug": "ui-testing-agents-can-run", "title": "UI testing an agent can write and run itself", "summary": "Drive interfaces by stable identity rather than pixels, in tiers, so tests are headless, deterministic and fan out.", "area": "coding", "category": "guides", "tags": [ "testing", "ui", "playwright", "accessibility", "e2e", "agents", "ci" ], "headings": [ "Why not just let the agent click the screen", "The anchor convention, which is the whole trick", "The tiers", "Logic, called directly with no UI", "Components in a headless DOM, faked at your own seam", "A real browser, with the platform bridge stubbed", "Full stack, real backend", "Why this multiplies an agent", "Gotchas already paid for", "CI, split by the constraint that actually differs", "Adapting to any stack", "The companion problem" ], "url": "https://the-handover.org/docs/ui-testing-agents-can-run", "plain_text_url": "https://the-handover.org/docs/ui-testing-agents-can-run.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-17", "last_confirmed": "2026-08-21", "tested_on": [ { "tool": "Playwright", "version": "1.x" }, { "tool": "Vitest + Testing Library", "version": "3.x" }, { "tool": "Tauri", "version": "2.x", "os": "macOS, Linux" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "b75792281de210b1a7331ddd9e7c0280679990df800874070b90d037b345f49b" }, { "slug": "verification-that-cannot-fail", "title": "Verification that cannot fail", "summary": "Three ways a passing check reports success without ever being able to report anything else.", "area": "coding", "category": "guides", "tags": [ "verification", "testing", "ci", "shell", "exit-codes", "agents" ], "headings": [ "1. Grepping for words instead of asserting exit codes", "2. Pipes discard the exit code", "3. A guard nobody has watched fail", "What to do instead", "Why this matters more for agents" ], "url": "https://the-handover.org/docs/verification-that-cannot-fail", "plain_text_url": "https://the-handover.org/docs/verification-that-cannot-fail.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-11", "last_confirmed": "2026-08-11", "tested_on": [ { "tool": "zsh", "version": "5.9", "os": "macOS" }, { "tool": "bash", "version": "3.2+" }, { "tool": "GitHub Actions", "version": "2026-08", "date": "2026-08-11" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "8a239ccaaa7007facfaf907b03fc84da92f113d856fcf1426e92040bd4aec033" }, { "slug": "we-could-not-get-ground-truth", "title": "We could not get ground truth, and it took three attempts to accept it", "summary": "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.", "area": "coding", "category": "guides", "tags": [ "validation", "evaluation", "ground-truth", "tooling", "methodology", "testing" ], "headings": [ "Attempt one: rank the projects", "Attempt two: predict each criterion", "Attempt three: ask about the proxies instead", "What the three had in common", "What was done instead, and what it does not cover", "Two limits worth naming", "If you are in the same position" ], "url": "https://the-handover.org/docs/we-could-not-get-ground-truth", "plain_text_url": "https://the-handover.org/docs/we-could-not-get-ground-truth.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-28", "last_confirmed": "2026-08-28", "tested_on": [ { "tool": "Rust", "version": "1.96.0", "os": "macOS" }, { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-28" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "f6392b19b872bc5df4d7fd637f6a605c8c104646b14d8da8f85729ef697b5d5c" }, { "slug": "what-earns-its-place", "title": "What earns its place in a context file", "summary": "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.", "area": "general", "category": "guides", "tags": [ "context-files", "rootnotes", "tokens", "method", "measurement", "agents" ], "headings": [ "Two tests, and both have to fail before something is waste", "One axis is not enough, and the failure is instructive", "What happened when we applied it", "A third kind, which neither axis predicts", "What this says about the evidence against context files", "The measurement that did not work, reported because it did not", "What is not claimed" ], "url": "https://the-handover.org/docs/what-earns-its-place", "plain_text_url": "https://the-handover.org/docs/what-earns-its-place.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-09-16", "last_confirmed": "2026-09-16", "tested_on": [ { "tool": "Claude Code", "version": "2026-09", "date": "2026-09-16" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "0eb84ef830ed40b8c40c6589f0b6d604abc478d3e577904b888b1f97b5453f84" }, { "slug": "when-the-tool-disagrees-with-you", "title": "When the tool disagrees with you, neither of you gets to win", "summary": "What to do when a tool built to outrank your judgement is wrong, given that overruling it destroys the only property it had.", "area": "coding", "category": "guides", "tags": [ "tooling", "automation", "authority", "code-review", "process", "agents" ], "headings": [ "The comment that was wrong about the world", "The disagreement where the tool was right and I was wrong", "The scanner was right and the output was still harmful", "Why this is worse than an ordinary bug", "The procedure that came out of it", "Three things that made the procedure work", "The part that does not resolve" ], "url": "https://the-handover.org/docs/when-the-tool-disagrees-with-you", "plain_text_url": "https://the-handover.org/docs/when-the-tool-disagrees-with-you.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-28", "last_confirmed": "2026-08-28", "tested_on": [ { "tool": "Rust", "version": "1.96.0", "os": "macOS" }, { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-28" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "eec67b8754979aada3a650b6bd77921ad7ed8eca15f15bb42335d5638520391a" }, { "slug": "windows-vm-testing-for-desktop-apps", "title": "Testing a desktop app on a disposable Windows VM", "summary": "Driving an interactive Windows session over SSH, and why testing as an admin proves nothing about permissions.", "area": "coding", "category": "guides", "tags": [ "windows", "azure", "vm", "testing", "desktop", "installers", "permissions" ], "headings": [ "Hygiene, before anything is created", "Provisioning", "Getting an interactive session, which is the whole difficulty", "Screenshots that actually contain your application", "Testing as a genuine standard user", "Verifying an installer's ACL side effects", "The per-user versus per-machine installer trap", "The general lesson" ], "url": "https://the-handover.org/docs/windows-vm-testing-for-desktop-apps", "plain_text_url": "https://the-handover.org/docs/windows-vm-testing-for-desktop-apps.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-07-18", "last_confirmed": "2026-08-11", "tested_on": [ { "tool": "Azure CLI", "version": "2.x", "os": "Windows 11 24H2" }, { "tool": "OpenSSH for Windows", "version": "8.x" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "77648221e270604fbe2f0aba46e75605998d27e5494591d47b0e7ddfc06841f7" }, { "slug": "working-agreement", "title": "Working agreement for an agent in this repository", "summary": "What may be run without asking, what must stop first, and how to report what actually happened.", "area": "coding", "category": "rootnotes", "tags": [ "workflow", "git", "commits", "review", "autonomy", "reporting" ], "headings": [ "The division", "Three modes, and what changes between them", "Safe without asking", "Stop and ask first", "When nobody is there", "Scope discipline", "Commits", "When something fails", "Reporting honestly", "Related rootnotes", "What outlives this repository", "Leaving the repository" ], "url": "https://the-handover.org/docs/working-agreement", "plain_text_url": "https://the-handover.org/docs/working-agreement.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-21", "last_confirmed": "2026-08-26", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-26" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "branch_model", "label": "Branching model", "required": true, "help": "How work reaches the main line. The default describes what this author's projects actually do.", "default": "a named branch for a phase of work, merged with a descriptive merge commit; smaller changes commit directly to the default branch" }, { "token": "review_requirement", "label": "Review requirement", "required": true, "help": "When and how a human sees the work. This changes the tempo of every rule below.", "default": "a human approves each step as it happens, in session, before it is taken" } ], "sha256": "94990cd4aa7455f9268e2b3c4981d74f2ce180270eac8b0f56606b6ac6cf3548" }, { "slug": "working-with-ai-the-system", "title": "Working with AI is a handover problem", "summary": "Why every session starts cold, what follows from that, and the four layers that turn context into something an agent can be handed.", "area": "general", "category": "guides", "tags": [ "method", "context", "handover", "system-design", "memory", "agents" ], "headings": [ "It is not forgetting. It is never having known.", "What follows", "The four layers", "1. Rootnotes — what cannot be discovered", "2. The documentation set — what was decided, and why", "3. The working agreement — how work happens, and where it stops", "4. A retrieval corpus — what is too large to hold", "What it looks like in a project", "This is not about code", "A fifth layer, and why it is separate", "What we can and cannot claim for this", "Where to start" ], "url": "https://the-handover.org/docs/working-with-ai-the-system", "plain_text_url": "https://the-handover.org/docs/working-with-ai-the-system.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-28", "last_confirmed": "2026-08-28", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-28" } ], "unconfirmed": false, "normative": false, "hard_won": false, "sha256": "f17778bc05e0e83ded7d30f17bcf67be914d3d40e7d33b48a1d0053918def9bb" }, { "slug": "writing-about-a-thing-is-not-doing-it", "title": "Writing about a thing is not doing it", "summary": "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.", "area": "coding", "category": "guides", "tags": [ "static-analysis", "false-positives", "detection", "tooling", "evidence", "agents" ], "headings": [ "The first defence: an extension allowlist", "The second: restrict to source paths", "The third: declaring a dependency is not using it", "The fourth: what kind of evidence is this", "The fifth: code matching code", "The sixth: published content is product, not practice", "The seventh: a defence failing in the way it defends against", "What generalises" ], "url": "https://the-handover.org/docs/writing-about-a-thing-is-not-doing-it", "plain_text_url": "https://the-handover.org/docs/writing-about-a-thing-is-not-doing-it.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-28", "last_confirmed": "2026-08-28", "tested_on": [ { "tool": "Rust", "version": "1.96.0", "os": "macOS" }, { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-28" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "73d0c055f0097618458a96adfdab61634bdb12675124b66f90c138682a1f38ae" }, { "slug": "writing-working-agreement", "title": "A writing working agreement: draft, and do not publish", "summary": "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.", "area": "writing", "category": "rootnotes", "tags": [ "writing", "working-agreement", "editorial", "publishing", "agents" ], "headings": [ "The division", "Safe without asking", "Stop and ask first", "Do not invent detail to finish a sentence", "You do not know what has already been said", "Voice is not style", "Do not smooth away the specific", "Reporting honestly", "Where this lives" ], "url": "https://the-handover.org/docs/writing-working-agreement", "plain_text_url": "https://the-handover.org/docs/writing-working-agreement.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-30", "last_confirmed": "2026-08-30", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-30" } ], "unconfirmed": false, "normative": false, "hard_won": false, "fields": [ { "token": "audience", "label": "Who reads this, and what they already know", "required": true, "help": "The second half matters more than the first. An agent that does not know what the audience already knows will explain the wrong things at length." }, { "token": "publishes_via", "label": "How something reaches a reader, and who decides", "required": true, "help": "Name the gate. Without it \"publish\" is undefined and a saved draft in the CMS looks like the end of the job." }, { "token": "never_covered", "label": "What this publication does not write about, and why", "required": true, "help": "The single least inferable thing here, and the most expensive to get wrong. Give the reason as well as the rule — a rule without its reason gets argued around by the next agent." } ], "sha256": "ba5c7ceeee3ac08bd2dddcc33056dd076b9cecdfaae34e7440a7edae02a6e866" }, { "slug": "you-cannot-find-it-by-re-reading", "title": "You cannot find it by re-reading the thing that is wrong", "summary": "Four cases where a description and the thing it described drifted apart, none of which was discoverable by reading the description again.", "area": "coding", "category": "guides", "tags": [ "documentation", "drift", "review", "testing", "process", "agents" ], "headings": [ "The same shape, three more times, in a codebase", "Why re-reading cannot find any of them", "What does find them", "Then automate the part that fits, and be honest about the rest", "The order that matters" ], "url": "https://the-handover.org/docs/you-cannot-find-it-by-re-reading", "plain_text_url": "https://the-handover.org/docs/you-cannot-find-it-by-re-reading.md", "authors": [ { "name": "Leon Mallett", "affiliation": "Founder of Captivated Ltd", "url": "https://captivated.online" } ], "licence": "Handover-1.0", "formats": [ "plain", "CLAUDE.md", "AGENTS.md" ], "date_written": "2026-08-29", "last_confirmed": "2026-08-29", "tested_on": [ { "tool": "Claude Code", "version": "2026-08", "date": "2026-08-29" }, { "tool": "Node", "version": "24", "os": "macOS" } ], "unconfirmed": false, "normative": false, "hard_won": true, "sha256": "28a19a21064180a7479e04d33196fe38c2680e650ae99de87ae4162228c95378" } ], "superseded": [], "packs": [ { "slug": "measuring-your-own-work", "title": "Measuring your own work", "summary": "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.", "assumes": "You are building, or relying on, a tool that scores work its author cannot be trusted to score. Read in order: three kinds of measurement failure, then how to validate any of it, then what happens when it is wrong. The last two are two halves of the same argument about authority.", "url": "https://the-handover.org/packs/measuring-your-own-work", "archive_url": "https://the-handover.org/packs/measuring-your-own-work.zip", "documents": [ "writing-about-a-thing-is-not-doing-it", "four-ratios-four-different-failures", "nothing-was-wrong-or-nothing-was-examined", "we-could-not-get-ground-truth", "when-the-tool-disagrees-with-you" ] }, { "slug": "project-root-starter", "title": "Project root starter", "summary": "Every rootnote in the library: the commercial, privacy, documentation, design and editorial context an agent cannot read from the code.", "assumes": "A project an agent will work in. Nothing about language, platform or size. Several documents share fill-in fields, so answering once applies across the set.", "url": "https://the-handover.org/packs/project-root-starter", "archive_url": "https://the-handover.org/packs/project-root-starter.zip", "documents": [ "business-context", "data-handling-and-privacy", "documentation-standard", "design-system-context", "language-editorial-guide", "accessibility-commitment", "multi-language-support", "working-agreement", "operational-runbook" ] }, { "slug": "design-context", "title": "Design context", "summary": "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.", "assumes": "A design project with a token set, or the intention to have one. No repository required — a folder is enough. Three fields are shared across the set, so you answer each once.", "url": "https://the-handover.org/packs/design-context", "archive_url": "https://the-handover.org/packs/design-context.zip", "documents": [ "design-system-context", "accessibility-commitment", "design-working-agreement" ] }, { "slug": "security-baseline", "title": "Security baseline", "summary": "The floor for any project an agent works in: process hygiene, credential handling, and dependency discipline.", "assumes": "A project with a shell, a package manager and at least one credential. Nothing about the language or platform.", "url": "https://the-handover.org/packs/security-baseline", "archive_url": "https://the-handover.org/packs/security-baseline.zip", "documents": [ "killing-processes-shared-machine", "live-secrets-in-ai-sessions", "supply-chain-baseline-ai-development" ] }, { "slug": "desktop-app-distribution", "title": "Shipping a desktop app", "summary": "Signing, notarisation and signed self-updates for a desktop application distributed outside an app store.", "assumes": "macOS as the signing machine, an Apple Developer account, and object storage for hosting updates. Tauri-flavoured, but the shape applies to any updater verifying a detached signature.", "url": "https://the-handover.org/packs/desktop-app-distribution", "archive_url": "https://the-handover.org/packs/desktop-app-distribution.zip", "documents": [ "macos-signing-and-notarisation", "desktop-app-signed-self-updates", "live-secrets-in-ai-sessions", "supply-chain-baseline-ai-development" ] }, { "slug": "testing-without-the-live-service", "title": "Testing without the live service", "summary": "Drive the interface by stable identity and fake the network, so a full journey runs headlessly with no live external calls.", "assumes": "An application with a user interface and at least one external dependency you do not own. Tool-agnostic: the tiers and the two seams transfer, only the tooling changes.", "url": "https://the-handover.org/packs/testing-without-the-live-service", "archive_url": "https://the-handover.org/packs/testing-without-the-live-service.zip", "documents": [ "ui-testing-agents-can-run", "faking-external-services-for-tests", "verification-that-cannot-fail" ] }, { "slug": "new-edge-project", "title": "New edge project", "summary": "Standing up a site or API on edge infrastructure without the reputation and credential mistakes.", "assumes": "An edge platform with custom-domain support, and a domain you already control. Cloudflare-flavoured; the reputation problem is not platform-specific.", "url": "https://the-handover.org/packs/new-edge-project", "archive_url": "https://the-handover.org/packs/new-edge-project.zip", "documents": [ "custom-domains-for-edge-deployments", "live-secrets-in-ai-sessions", "supply-chain-baseline-ai-development" ] } ] }