agents-handoff 0.0.0-stage → 2.0.3

package/docs/UPGRADE.md

@@ -0,0 +1,177 @@
+---
+title: Upgrade
+---
+
+# Upgrade
+
+An upgrade replaces skill files. It does not touch the handoff folders, the configuration, or
+anything you added next to them.
+
+## Before upgrading
+
+Confirm what is installed:
+
+```bash
+npx agents-handoff --list
+```
+
+`--list` prints each installed location with its version and the number of manifest files
+present. The version also appears as `version:` in the `SKILL.md` front matter of the
+installation.
+
+Back up handoff data before any manual change. The upgrade path keeps it, but a copy costs
+nothing:
+
+```bash
+cp -r handoffs/ handoffs-backup/
+```
+
+Note any local edits to `handoff.config.json`, since a reinstall overwrites skill files but
+leaves that file alone.
+
+## Upgrade with the installer
+
+```bash
+npx agents-handoff --update
+```
+
+With no target flag, `--update` updates **every installation found on this machine**. That is
+the whole answer to "keep my install current": a machine can hold the same skill in
+`~/.claude/skills` and in `~/.agents/skills`, and updating only one of them is how the other
+keeps running an old engine. Each installation is updated and reported on its own, and the run
+ends with a summary naming the version it moved from and to:
+
+```
+Update summary
+  ✓ updated <dir>/agents-handoff — 2.0.2 → v2.0.3
+  ✓ updated <dir>/agents-handoff — 2.0.2 → v2.0.3
+✓ 2 of 2 installation(s) updated
+```
+
+When nothing is installed anywhere the installer can see, it says so and exits non-zero:
+`Nothing to update: no agents-handoff installation found.`
+
+The update then reinstalls: the skill files are copied over the existing installation and
+overwrite the files of the same name. Files that are not part of the installation manifest —
+`handoffs/`, `projects/`, `links/`, `.agent-handoff/`, `handoff.config.json`, `.env.example`, and
+anything you added — are left in place. Nothing outside the manifest is read or rewritten.
+
+Scope the update to one harness, or several, with the same flags install uses:
+
+```bash
+npx agents-handoff --update --claude     # just Claude Code
+npx agents-handoff --update --codex      # just Codex CLI
+npx agents-handoff --update --all        # every harness found on this machine
+npx agents-handoff --update --location project
+npx agents-handoff --update --version 2.0.0
+```
+
+`--all` covers the harnesses whose configuration directory exists here; a named harness is
+updated whether or not that directory exists.
+
+`--version` asks for a version, and the installer resolves it honestly: the tree beside the
+installer is used when it **is** that version (or when nothing was requested), and when it is a
+different version the requested tag's archive is fetched instead, with its sha256 recorded in
+the install record's `source`. To switch versions, ask npm for the one you want
+(`npx agents-handoff@<version>`), pass `--version <x>`, or install manually from that version's
+tag archive. Confirm what is actually installed with `--verify`, which prints the version read
+back from the installed `SKILL.md`, rather than trusting the request.
+
+An update rewrites the install record as well, so `--verify --provenance` describes the new
+state afterwards and reports the archive (with its sha256) when the files came from a download
+rather than from a tree. The record's `package` block names the npm package and version the
+installation should match; `npx agents-handoff --verify-package --record` fills in that
+package's tarball hashes.
+
+## Manual upgrade
+
+Replace the skill files and keep the data:
+
+1. Extract the release archive (`agents-handoff-v<version>.zip` from the
+   [releases page](https://github.com/Alot1z/agent-handoff/releases); the newest release carries
+   its own version in the file name) into a temporary directory.
+2. Copy the skill files over the installation: `SKILL.md`, `skill.json`, the manifest JSON
+   files, `tools/`, `tools/lib/`, `schemas/`, `refs/`, `templates/`, `docs/`, `tests/`.
+3. Do not delete `handoffs/`, `projects/`, `links/`, or `handoff.config.json`.
+
+```bash
+unzip agents-handoff-v<version>.zip -d /tmp/agents-handoff-new
+cp -r /tmp/agents-handoff-new/tools/ /tmp/agents-handoff-new/refs/ \
+      /tmp/agents-handoff-new/templates/ /tmp/agents-handoff-new/schemas/ \
+      /tmp/agents-handoff-new/docs/ "<install-path>/"
+cp /tmp/agents-handoff-new/SKILL.md /tmp/agents-handoff-new/skill.json "<install-path>/"
+```
+
+## What an upgrade changes
+
+| Changed | Unchanged |
+|---|---|
+| `tools/` — the engine and the dynamic runtime | `handoffs/` — your session data |
+| `refs/`, `templates/`, `schemas/`, `docs/` | `projects/`, `links/` |
+| `SKILL.md`, `skill.json`, manifest JSON files | `handoff.config.json` and your edits |
+| `install/` — the installer itself | `HANDOFFS_ROOT`, if you use it |
+| `.agents-handoff-install.json` — the install record, rewritten for the new version, including its `package` block | — |
+| `.agent-handoff/` and any other store directory, whatever it is called | — |
+
+Handoff folders are read from the handoff root in place, so an upgrade does not move or rewrite
+them.
+
+## After upgrading
+
+```bash
+npx agents-handoff --verify                  # every installation found
+npx agents-handoff --verify --provenance
+npx agents-handoff --verify-package --record  # and prove it matches the published tarball
+npx agents-handoff doctor
+node "<install-path>/tools/handoff.mjs" config
+node "<install-path>/tools/handoff.mjs" list
+```
+
+`config` proves the engine starts and prints the handoff root it resolved. `list` proves the
+engine still finds the handoff folders that were already there. `--verify --provenance` prints
+the install record the verification was checked against — version, source, harness and the
+file-set hash — which is the shortest way to prove an upgrade landed and left nothing behind.
+
+The shipped test suite is a stronger check and does not touch existing handoffs when you point
+it at a scratch root:
+
+```bash
+HANDOFFS_ROOT=/tmp/handoff-check node "<install-path>/tools/handoff.test.mjs"
+```
+
+Read an existing handoff to confirm the data survived:
+
+```bash
+node "<install-path>/tools/handoff.mjs" show <id-prefix>
+node "<install-path>/tools/handoff.mjs" verify <id-prefix>
+```
+
+`verify <id-prefix>` recomputes the stored handoff's manifest hash, so it fails loudly if an
+upgrade damaged the folder.
+
+## Rollback
+
+1. Restore the previous version's skill files: extract that version's release archive and copy
+   the skill files over the installation, as in the manual upgrade above.
+2. Or reinstall the files that ship with the installer: `npx agents-handoff --force`.
+3. Restore handoffs from your backup if you made one, and confirm with `--verify` and
+   `handoff.mjs list`.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| `Not installed at <dir>` | `--path`, `--location` or a harness flag named a directory that holds no installation. Drop the flag to update every installation found, or check `--list`. |
+| `Nothing to update: no agents-handoff installation found.` | Nothing to update anywhere the installer looks. Run `npx agents-handoff --all`, or name the directory with `--path`. |
+| Reported version did not change | The installer uses the tree beside it when that tree **is** the requested version (or nothing was requested), so running it from a checkout installs that checkout. Use the published package, pass `--version <x>` to fetch that tag's archive, or check `--verify --provenance` to see which source the record names. |
+| `verify-package` fails with `does NOT match … as published` | A file changed after the update. The check names it; reinstall with `--force`. |
+| Verification fails after an upgrade | A file is missing or the engine cannot start. Reinstall with `--force` and read the failing check. |
+| Handoffs no longer listed | The engine is reading a different root. Run `config` and compare it with where your handoffs live; set `HANDOFFS_ROOT` if needed. |
+| `no provenance record` after upgrading | The record is written by installs from 2.0.3 on. Reinstall with `--force` to write one for this target. |
+| Configuration was overwritten | `handoff.config.json` is preserved, but a manual copy step can still overwrite it. Restore your backup. |
+
+## See also
+
+- [INSTALL.md](INSTALL.md)
+- [UNINSTALL.md](UNINSTALL.md)
+- [../README.md](https://github.com/Alot1z/agent-handoff/blob/main/README.md)

package/docs/_config.yml

@@ -0,0 +1,18 @@
+title: agents-handoff
+description: Cross-harness capture and verified continuation for AI working sessions.
+url: https://alot1z.github.io
+# The site is served from the repository's Pages path, which follows the REPOSITORY name
+# (agent-handoff), not the product name (agents-handoff).
+baseurl: /agent-handoff
+plugins:
+  - jekyll-relative-links
+relative_links:
+  enabled: true
+  collections: false
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default
+exclude:
+  - README.md

package/docs/_data/nav.yml

@@ -0,0 +1,36 @@
+- title: Overview
+  path: /index.html
+- title: Install
+  path: /INSTALL.html
+- title: Upgrade
+  path: /UPGRADE.html
+- title: Uninstall
+  path: /UNINSTALL.html
+- title: Architecture
+  path: /ARCHITECTURE.html
+- title: Command reference
+  path: /CLI.html
+- title: Handoff format
+  path: /FORMAT.html
+- title: Session index
+  path: /SESSIONS.html
+- title: Integration
+  path: /INTEGRATION.html
+- title: Runtime layer
+  path: /LEVEL4.html
+- title: Dispatch
+  path: /LEVEL5.html
+- title: Permissions
+  path: /PERMISSIONS.html
+- title: Security
+  path: /SECURITY.html
+- title: Compatibility
+  path: /COMPATIBILITY.html
+- title: Provenance
+  path: /PROVENANCE.html
+- title: Troubleshooting
+  path: /TROUBLESHOOTING.html
+- title: Changelog
+  path: /CHANGELOG.html
+- title: Contributing
+  path: /CONTRIBUTING.html

package/docs/_layouts/default.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{% if page.title and page.title != site.title %}{{ page.title }} · {{ site.title }}{% else %}{{ site.title }}{% endif %}</title>
+<meta name="description" content="{{ page.description | default: site.description }}">
+<link rel="stylesheet" href="{{ '/assets/style.css' | relative_url }}">
+</head>
+<body>
+<header class="top">
+  <a class="brand" href="{{ '/' | relative_url }}">{{ site.title }}</a>
+  <span class="tag">{{ site.description }}</span>
+</header>
+<div class="wrap">
+  <nav class="side">
+    <p class="navhead">Documentation</p>
+    <ul>
+      {% for d in site.data.nav %}<li><a href="{{ d.path | relative_url }}">{{ d.title }}</a></li>
+      {% endfor %}
+    </ul>
+  </nav>
+  <main>
+{{ content }}
+  </main>
+</div>
+<footer class="foot">
+  MIT licensed · <a href="{{ site.baseurl }}">repository</a> · documentation source: the docs/ directory of this project
+</footer>
+</body>
+</html>

package/docs/assets/style.css

@@ -0,0 +1,88 @@
+:root {
+  --bg: #ffffff;
+  --fg: #1f2328;
+  --muted: #59636e;
+  --line: #d1d9e0;
+  --link: #0969da;
+  --code: #f6f8fa;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0d1117;
+    --fg: #e6edf3;
+    --muted: #9198a1;
+    --line: #30363d;
+    --link: #4493f8;
+    --code: #161b22;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+}
+a { color: var(--link); text-decoration: none; }
+a:hover { text-decoration: underline; }
+.top {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 0.75rem;
+  padding: 1rem 1.5rem;
+  border-bottom: 1px solid var(--line);
+}
+.brand { font-weight: 600; font-size: 1.05rem; color: var(--fg); }
+.tag { color: var(--muted); font-size: 0.85rem; }
+.wrap {
+  display: flex;
+  align-items: flex-start;
+  gap: 2.5rem;
+  max-width: 1080px;
+  margin: 0 auto;
+  padding: 2rem 1.5rem 4rem;
+}
+.side { flex: 0 0 180px; position: sticky; top: 1rem; }
+.navhead {
+  margin: 0 0 0.5rem;
+  font-size: 0.75rem;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+.side ul { list-style: none; margin: 0; padding: 0; }
+.side li { margin: 0.15rem 0; }
+.side a { font-size: 0.9rem; }
+main { flex: 1 1 auto; min-width: 0; }
+main h1 { font-size: 1.75rem; margin: 0 0 1rem; }
+main h2 { font-size: 1.2rem; margin: 2rem 0 0.6rem; padding-bottom: 0.25rem; border-bottom: 1px solid var(--line); }
+main h3 { font-size: 1rem; margin: 1.5rem 0 0.4rem; }
+code {
+  background: var(--code);
+  padding: 0.1em 0.35em;
+  border-radius: 5px;
+  font-size: 0.88em;
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+}
+pre {
+  background: var(--code);
+  padding: 0.85rem 1rem;
+  border-radius: 6px;
+  overflow-x: auto;
+}
+pre code { background: none; padding: 0; }
+table { border-collapse: collapse; width: 100%; margin: 1rem 0; font-size: 0.92rem; }
+th, td { border: 1px solid var(--line); padding: 0.4rem 0.6rem; text-align: left; vertical-align: top; }
+th { background: var(--code); }
+blockquote { margin: 1rem 0; padding: 0 1rem; border-left: 3px solid var(--line); color: var(--muted); }
+.foot {
+  border-top: 1px solid var(--line);
+  padding: 1rem 1.5rem 2rem;
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+@media (max-width: 720px) {
+  .wrap { flex-direction: column; gap: 1rem; }
+  .side { position: static; }
+}

package/docs/index.md

@@ -0,0 +1,92 @@
+---
+title: agents-handoff
+---
+
+# agents-handoff documentation
+
+agents-handoff turns an AI working session — chat turns, tool calls, reasoning, however the
+client stored it — into a folder of plain files that a different agent, a different harness,
+or a colleague can read and continue from without the original chat. It builds from a
+transcript or an adapter export, keeps a hash chain so a handoff can be re-verified, and
+merges later turns into the same session instead of duplicating it.
+
+## Quick start
+
+```bash
+# 1. Install the skill into every harness found on this machine
+npx agents-handoff --all
+
+# 2. Build a handoff from a transcript
+node tools/handoff.mjs build --source transcript.jsonl --project my-project
+
+# 3. Find it, read it, check it
+node tools/handoff.mjs list
+node tools/handoff.mjs show <id-prefix>
+node tools/handoff.mjs verify <id-prefix>
+```
+
+`build` also accepts `--session`, `--harness`, `--model` and `--objective`. Run
+`node tools/handoff.mjs config` to see which store root the engine resolved and why.
+
+`--all` installs into every harness present on the machine; `--claude`, `--codex`, `--agents`
+and `--skills-dir <dir>` pick one or several instead, and `npx agents-handoff --update` brings
+every copy on the machine up to date in one run. `npx agents-handoff --verify-package` then
+proves the copy on disk is identical to the tarball npm is serving for its version, while
+`npx agents-handoff --doctor` reports what is installed where and whether each copy still
+matches the record written when it was installed. The installer's full surface is in
+[CLI.md](CLI.md) and [INSTALL.md](INSTALL.md).
+
+## Where to start
+
+| If you want to… | Read |
+|---|---|
+| install it | [INSTALL.md](INSTALL.md) |
+| prove an install matches the published package | [INSTALL.md](INSTALL.md) and [CLI.md](CLI.md) |
+| understand how the pieces fit | [ARCHITECTURE.md](ARCHITECTURE.md) |
+| look up a command, flag or exit code | [CLI.md](CLI.md) |
+| know exactly what a handoff folder holds | [FORMAT.md](FORMAT.md) |
+| see captured sessions, and check them | [SESSIONS.md](SESSIONS.md) |
+| fix something that is not working | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
+| feed it a transcript from your own tool | [INTEGRATION.md](INTEGRATION.md) and [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md) |
+| understand what the hashes prove | [PROVENANCE.md](PROVENANCE.md) |
+
+## All pages
+
+| Document | Contents |
+|---|---|
+| [INSTALL.md](INSTALL.md) | Installer commands, install locations, requirements |
+| [UPGRADE.md](UPGRADE.md) | Updating an installation, pinning a version, what a version change touches |
+| [UNINSTALL.md](UNINSTALL.md) | Removing an installation, and which files are deliberately kept |
+| [ARCHITECTURE.md](ARCHITECTURE.md) | The layers, the data flow, the store root, the write-safety discipline, the boundaries |
+| [CLI.md](CLI.md) | Every executable, verb, flag, exit code, environment variable and file written |
+| [FORMAT.md](FORMAT.md) | Handoff folder layout, every file in it, the manifest and the schemas |
+| [SESSIONS.md](SESSIONS.md) | Session index: a sample store, its captured sessions, and how to verify and re-render them. The same rows are published as [sessions.json](sessions.json) (schema `1.0-session-feed`) for anything that would rather read data than markdown, and the page filters in the browser |
+| [INTEGRATION.md](INTEGRATION.md) | Embedding the engine, configuration and environment, CI and pipeline use |
+| [LEVEL4.md](LEVEL4.md) | Dynamic runtime layer: runtime verbs, gates and promotion |
+| [LEVEL5.md](LEVEL5.md) | Collaborative dispatch: routing a handoff to another agent |
+| [PERMISSIONS.md](PERMISSIONS.md) | Permission levels, risk classes, and the policy file |
+| [SECURITY.md](SECURITY.md) | What is read and written, secrets, malicious input, guarantees not made |
+| [COMPATIBILITY.md](COMPATIBILITY.md) | Platforms, Node versions, input formats, exit codes |
+| [PROVENANCE.md](PROVENANCE.md) | The hash chain, how to verify it, what it cannot prove |
+| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Symptom, cause and fix, keyed to the real exit codes |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Test suite, project layout, how to add an adapter |
+| [Changelog](https://github.com/Alot1z/agent-handoff/blob/main/CHANGELOG.md) | What changed in each release, and how to add an entry |
+| [../refs/ADAPTERS.md](https://github.com/Alot1z/agent-handoff/blob/main/refs/ADAPTERS.md) | Canonical input shape and how each session source maps onto it |
+
+## Engine commands
+
+| Command | Effect |
+|---|---|
+| `build --source <file>` | Build or update a handoff from a transcript |
+| `--handoff --source <file>` | Alias of `build` |
+| `list [project-or-prefix]` | List sessions, newest first |
+| `show <id-prefix>` | Print the rendered brief |
+| `verify <id-prefix>` | Re-check the hash chain |
+| `rename <id-prefix> <project>` | Move a session to another project |
+| `retitle <id-prefix> <name>` | Give a session a readable name |
+| `config` | Report the resolved store root, its source and the schema path |
+
+Zero dependencies, Node 18 or newer. [CLI.md](CLI.md) has the full command surface, including
+the runtime layer, bounded execution and the capability registry. See
+[../README.md](https://github.com/Alot1z/agent-handoff/blob/main/README.md) for the repository overview and [../SKILL.md](https://github.com/Alot1z/agent-handoff/blob/main/SKILL.md) for
+the skill definition.

package/docs/sessions.json

@@ -0,0 +1,34 @@
+{
+  "schema_version": "1.0-session-feed",
+  "generated_by": ".github/scripts/build-sessions-index.mjs",
+  "store": "examples/sessions",
+  "index_source": "INDEX.json",
+  "as_of": "2026-10-08T22:53:03.964Z",
+  "count": 2,
+  "projects": 2,
+  "failed": 0,
+  "sessions": [
+    {
+      "id": "typescript-project-setup",
+      "project": "demo",
+      "harness": "claude-code",
+      "model": "claude-3-5-sonnet",
+      "turns": 11,
+      "revisions": 1,
+      "updated": "2026-10-08T22:53:03.865Z",
+      "manifest_sha256": "141e232eb2ad668f59d746828517e646a5cbe2bc914dd976df3c43c209214d3c",
+      "integrity": "pass"
+    },
+    {
+      "id": "fixture-roundtrip",
+      "project": "smoke-test",
+      "harness": "codex",
+      "model": "gpt-5-codex",
+      "turns": 2,
+      "revisions": 1,
+      "updated": "2026-10-08T22:53:03.964Z",
+      "manifest_sha256": "a81d076e3334b8341f2829d0f38daf2cdbaf667269a9909dc523797c74e46ce5",
+      "integrity": "pass"
+    }
+  ]
+}

package/handoff.config.example.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "./handoff.config.schema.json",
+  "version": 1,
+  "handoff_dir": "handoffs/",
+  "project_name": null,
+  "auto_capture": false,
+  "max_brief_tokens": 30000,
+  "exclude_from_handoff": [
+    "node_modules/",
+    ".git/",
+    "dist/",
+    "build/",
+    "*.token",
+    "*.key",
+    "*.pem",
+    ".env",
+    "*.log"
+  ],
+  "capture": {
+    "include_tool_outputs": true,
+    "truncate_tool_outputs": false,
+    "max_tool_output_length": 100000
+  },
+  "linking": {
+    "enabled": true,
+    "min_overlap_score": 0.06
+  },
+  "integrity": {
+    "sha256_manifest": true,
+    "verify_on_read": false
+  },
+  "storage": {
+    "type": "filesystem"
+  }
+}

package/handoff.config.schema.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/Alot1z/agent-handoff/handoff.config.schema.json",
+  "title": "Agent Handoff Configuration",
+  "description": "Schema for handoff.config.json — where handoffs are stored, and how a session is captured. Copy handoff.config.example.json to your project root as handoff.config.json to opt in; with no config file the engine keeps its default store. HANDOFFS_ROOT always overrides anything set here.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema, for editor completion."
+    },
+    "version": {
+      "type": "integer",
+      "enum": [1],
+      "default": 1,
+      "description": "Config format version."
+    },
+    "handoff_dir": {
+      "type": "string",
+      "minLength": 1,
+      "default": "handoffs/",
+      "description": "Where handoffs are stored. Relative paths resolve against the directory holding this file; absolute paths are used as-is.",
+      "examples": ["handoffs/", ".context/handoffs/", "/srv/handoffs/"]
+    },
+    "project_name": {
+      "type": ["string", "null"],
+      "default": null,
+      "description": "Project used for grouping handoffs. Auto-detected when null."
+    },
+    "auto_capture": {
+      "type": "boolean",
+      "default": false,
+      "description": "Accepted and validated; reserved — no tool auto-captures sessions yet."
+    },
+    "max_brief_tokens": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 100000,
+      "default": 30000,
+      "description": "Accepted and validated; reserved — brief truncation is not implemented."
+    },
+    "exclude_from_handoff": {
+      "type": "array",
+      "items": { "type": "string" },
+      "default": [
+        "node_modules/",
+        ".git/",
+        "dist/",
+        "build/",
+        "*.token",
+        "*.key",
+        "*.pem",
+        ".env",
+        "*.log"
+      ],
+      "description": "Accepted and validated; reserved — the engine copies no project trees, so nothing is filtered yet."
+    },
+    "capture": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "exclude_patterns": { "type": "array", "items": { "type": "string" } },
+        "include_tool_outputs": { "type": "boolean", "default": true },
+        "truncate_tool_outputs": { "type": "boolean", "default": false },
+        "max_tool_output_length": { "type": "integer", "default": 100000, "minimum": 0 }
+      }
+    },
+    "linking": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "HONOURED: when false, cross-project link notes are not written."
+        },
+        "min_overlap_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "default": 0.06,
+          "description": "Accepted and validated; reserved — the engine uses its built-in 0.06 threshold."
+        }
+      }
+    },
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "sha256_manifest": { "type": "boolean", "default": true },
+        "verify_on_read": { "type": "boolean", "default": false }
+      }
+    },
+    "storage": {
+      "type": "object",
+      "additionalProperties": false,
+      "default": {},
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["filesystem", "sqlite"],
+          "default": "filesystem",
+          "description": "Only filesystem is implemented; sqlite validates but is not honoured."
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "HONOURED and beats handoff_dir: an explicit store path."
+        }
+      }
+    }
+  }
+}