This directory records the significant architecture decisions behind Hatchdoor — what was decided, why, and what it commits us to. Read it before proposing a structural change: each record is a constraint your PR is expected to respect. If your change would break one, that's fine — but say so, and propose an amendment (see below) rather than quietly working around it.
Most decisions are captured as short sections in this file. One decision with a full evaluation behind it lives in its own file and is linked from the index.
These records are append-only. Don't rewrite an accepted decision to reflect a new one — instead:
- Add a new record (next number) describing the new decision.
- Set the old record's status to
Superseded by ADR-NNNNand leave its text intact.
This keeps the history of why the code is shaped the way it is, which is the whole point.
Copy this for a new record:
## ADR-NNNN — Short title
- **Status:** Proposed | Accepted | Superseded by ADR-XXXX
- **Context:** The problem and the forces at play (constraints, requirements).
- **Decision:** What we decided to do.
- **Consequences:** What this makes easier or harder; the tradeoff accepted.
- **Evidence:** Where this shows up in the code/docs.| # | Decision | Status | PR constraint (what not to break) |
|---|---|---|---|
| 01 | Markdown is the source of truth; SQLite is a disposable read model | Accepted; amended by ADR-50, where a schema version mismatch no longer always wipes | Never make the DB authoritative; it must rebuild from .md |
| 02 | One binary serving three surfaces over one shared core | Accepted; ADR-38 adds a fourth surface | Don't split into services or fork the domain core per surface |
| 03 | Web and MCP writes share one vault/write/ layer |
Accepted | Don't implement writes in a handler or MCP tool directly |
| 04 | Local, CPU-only embeddings; no external inference API | Superseded by ADR-16 | — (see ADR-16) |
| 05 | Pure semantic retrieval by default; rerank and hybrid stay offline | Accepted | Don't add reranking or FTS/vector fusion to the runtime search path |
| 06 | Embedded SQLite: FTS5 + sqlite-vec, WAL, pooled reads | Accepted | Don't add an external DB or an ORM; keep reads non-blocking during reindex |
| 07 | Fail-fast security posture at startup | Accepted | Don't downgrade unsafe configs from refuse-to-start to a warning |
| 08 | Bearer-token auth with a query-param fallback | Accepted; amended in #703: the query token works on three GET routes only | Keep token compares constant-time; don't leak tokens to logs; accept the query token only on QUERY_TOKEN_ROUTES |
| 09 | MCP off by default, own token, Origin allowlist | Accepted | Read-only MCP still requires a token; keep the anti-rebinding checks |
| 10 | Optional git sync as a debounced background task | Superseded by ADR-18 (mechanism only) | Never force-checkout over uncommitted manual vault edits (restated in ADR-18) |
| 11 | Soft delete (trash) and archive-by-move | Accepted | Don't hard-delete note or asset files |
| 12 | Distroless, rootless, multi-stage container | Accepted | Don't assume a shell at runtime; keep the image rootless |
| 13 | Deliberate minimalism: trait seams only where they pay | Accepted | Don't add speculative abstractions, state libraries, or frameworks |
| 14 | No deployment step requires a browser | Accepted; first-boot consequence narrowed by ADR-40 | Don't add a setting the UI can set but the environment can't, or a startup gate only a browser can clear |
| 15 | Search quality is a product feature, not a tunable | Accepted | Don't change the retrieval path without eval numbers (one narrow exemption: ADR-20); don't trade recall or MRR for speed |
| 16 | EmbeddingGemma by default behind a licence gate; representation locked at 800/50 with context | Accepted | Don't change the embedder, chunk size, or contextual headers without re-running the eval |
| 17 | RMCP is the MCP protocol boundary; supported revisions narrow to 2026-07-28 and 2025-11-25 | Accepted | Don't hand-implement MCP wire behavior or re-widen the advertised revision set |
| 18 | Per-Vault Git turns supersede the single-Vault debounced sync task | Accepted; "the commit-on-write debounce has no successor" superseded by ADR-23, "no second execution lane" superseded by ADR-31 | Don't reintroduce an instance-wide sync task; a Git turn holds its Vault's mutation lock and never force-checks out over manual edits |
| 19 | Vault-qualified cores are the only seam an adapter crosses | Accepted | Don't call a handler from an MCP tool or reach past a core from any adapter; orchestration lives in the core, mapping in the adapter |
| 20 | Deleting provably dead retrieval code needs a proof, not an eval run | Accepted | Don't claim this exemption for code that runs; the proof enumerates every producer, and deletion-only means deletion-only |
| 21 | A saved query is derived state, over a refused-by-default subset of Bases | Accepted | Don't index, link or store a query result, and don't accept Bases syntax you have not implemented |
| 22 | A partial write leaves the text it did not name byte for byte | Accepted | Don't reformat, reorder or re-emit anything the caller did not name; a partial write edits, it does not regenerate |
| 23 | Committing is not syncing, so a commit turn is its own kind of background work | Accepted; "one execution lane per Vault" superseded by ADR-31 | Don't put a network call in a commit turn, don't let a commit move the remote schedule, and don't make committing depend on having a remote |
| 24 | A slug folds European letters to ASCII and keeps every other script | Accepted | Don't discard a character because it is not ASCII, don't romanise a non-Latin script, and don't let the two implementations of the rule drift apart |
| 25 | A Vault's write exclusion outlives the control block that carries it | Accepted | Don't mint a fresh mutation lock for a Vault that already has live work; take several Vaults' locks in sorted order or not at all |
| 26 | A write commits atomically where the filesystem can, and says so where it cannot | Accepted | Don't make a write depend on a renameat2 flag being available, don't treat a bare EINVAL as proof a flag is missing, and don't degrade silently |
| 27 | An agent moves attachment bytes through a transfer link, not the MCP token | Superseded by ADR-32 | A transfer link names one file or one upload target and nothing else; it never outlives its expiry, the signing key, MCP being enabled, or (for uploads) MCP write mode; it never grants more bytes or budget than the same read over /mcp |
| 28 | A note link is a wikilink or a Markdown link to a .md path, and both count |
Accepted | Don't let a Markdown note link navigate without also counting it, or count it without also retargeting it on rename, move and delete; only a .md target is a note link |
| 29 | A note is charted by its created date, and a date the author wrote beats any the machine infers | Accepted | Don't chart by modification time or by last change in git; don't let git or the file override a created property; don't walk history per note or per request |
| 30 | A sync conflict is resolved on the Git host, through a recovery branch Hatchdoor publishes on request | Accepted | Publish only on an explicit request, only as a fast-forward of the recovery branch, and only through a Git turn; never touch the configured branch outside a sync, never force-push, never delete a remote branch |
| 31 | Git work never waits behind another Vault's indexing | Accepted | Don't make a Git, commit or recovery turn wait for an Index turn or for another Vault's Git work; keep indexing to one lane, Git work to at most four Vaults at once, and the mutation lock as the only same-Vault guard |
| 32 | A transfer link can upload a note as well as an attachment | Accepted | Don't replace a note through a link without its expected content hash, don't store an uploaded note without the checks create_note applies, and don't make a target that does not end in .md a note |
| 33 | A vault's link style is read from the vault, not set in Hatchdoor | Accepted | Don't add a per-Vault link-style setting without a superseding record; Obsidian's recorded setting beats any count of existing links; never rewrite an agent's text into the vault's style |
| 34 | A transfer link's address follows the proxy's forwarded headers | Accepted | Don't let forwarded headers override a configured public address; don't read them for anything but a transfer link's address |
| 35 | A long Index turn keeps its embedding progress and takes turns with other Vaults | Accepted; decisions 1 and 2 implemented in #382, 3 to 5 in #383 | Don't let a partly embedded Vault answer search; don't embed two Vaults at once; don't let a paused Index turn jump the queue; never make saved progress authoritative |
| 36 | A release is cut by two commands, and only the maintainer approves its notes | Accepted; implemented in #402, #403 and #404; where the checklist lives (decision 3), which pull request publish reads it from (decision 5) and when the draft release is created (decision 1) superseded by ADR-37; ADR-42 adds a refusal to decision 2 (#424); ADR-45 names one public host as a deliberate exception; #486 adds publishing the Docker Hub overview to the hook's images step (decision 7); #705 notes that one build now serves all four tags |
Don't overwrite a published version, don't publish without the maintainer's approval of the notes, and don't put private infrastructure in the public release commands |
| 37 | A release is reviewed on its version-bump pull request | Accepted; implemented in #408 | Don't let anything but the bump branch carry a change into a release after prepare; don't loosen ADR-36 decision 5 to admit "release fix" pull requests |
| 38 | The manual ships inside the binary and is served as Help, never as a Vault | Accepted | Don't serve anything but the bundled manual at the public docs addresses, don't reveal the version on a public route, and don't make Help or the docs tools need a Vault or the embedding model |
| 39 | Hatchdoor checks for a newer release only when asked | Accepted; ADR-45 adds a second opt-in request beside it | Don't check by default, don't send the version or anything about the instance, and never upgrade automatically |
| 40 | A fresh install starts with zero Vaults | Accepted; decisions 1 to 4 implemented in #427, decision 6 in #424 | Don't register a Vault nobody added, don't write starter notes into a user's folder, and don't open on zero Vaults while stored settings still carry the retired single-Vault keys |
| 41 | Hatchdoor lists the folders it can see, inside its Vault mount only | Accepted; ADR-44 adds one write beside the listing; ADR-54 narrows decision 6 for agents | Don't follow a symlink, leave the Vault root, return file names or content, or serve the listing in demo mode |
| 42 | Every release ships plain highlights | Accepted | Don't release without 3 to 6 highlight lines, action-needed items first |
| 43 | A timed folder re-scan backs up the file watcher | Accepted; implemented in #458 | Don't make the re-scan a setting, don't detect filesystems to decide where it runs, and don't give it its own route to an index or commit turn |
| 44 | Hatchdoor makes one new, empty folder inside its Vault mount, on request | Accepted; implemented in #494 | Don't create a folder outside the Vault mount or inside a registered Vault, don't create more than one per request, don't write into it, and don't offer it over MCP or in demo mode |
| 45 | Hatchdoor sends a usage report only when asked | Accepted; ADR-48 supersedes decision 6 only where it says What's new carries no reminder in later releases | Don't report by default, don't send anything outside the listed fields or any behaviour data, don't let an MCP tool change the setting, and don't send to a hosted third-party service |
| 46 | A text match reads every layer from the files on disk, and is neither a search nor a query | Accepted; to be implemented in #500 | Don't rank a text match, don't answer it from the index, don't skip demoted layers by default, don't add patterns, and don't fold it into search_notes or query_notes |
| 47 | A demo instance writes a link preview into the page it serves | Accepted; implemented in #512 | Don't write preview tags outside demo mode, don't put anything in them the unauthenticated demo read would refuse, don't build an address from a request header, don't draw a picture per note, and don't write a value into the page unescaped |
| 48 | What's new asks about the usage report once more in 2.8.1, with the switch on the line | Accepted; implemented in #563; supersedes ADR-45 decision 6 only where it says What's new carries no reminder in later releases | Don't show the switch on any other release's line, don't turn the report on without a click, and don't mention the report in a later What's new except where ADR-45 decision 5 requires it |
| 49 | A commit says where each of its writes came in from, and claims no more | Accepted; implemented in #570 | Don't rename the Hatchdoor-Origin trailer or change the meaning of a value already in history, don't call an origin an actor or present it as proof of who wrote, don't record a client's version or agent family, and don't keep the origin in a second store |
| 50 | A schema change may carry the vectors across in a checked migration | Accepted; implemented in #600; amends ADR-01; rule 2 superseded by ADR-52 | Don't migrate before the model check, don't commit a migration before its checks pass, and wipe on any failure |
| 51 | A multi-note write records its plan first, and a restart finishes it | Accepted; implemented in #631; refines ADR-26; ADR-53 adds canvas rewrites to the plan | Don't take a multi-note write's first step before its plan is on disk, don't roll a write forward over a note edited since the plan read it, and don't finish a write the caller was already told failed |
| 52 | A cache migrates from any schema version since the latest release | Accepted; implemented in #655; supersedes ADR-50 rule 2 | Don't migrate from a version older than the latest release's, and don't delete a step while the latest release's version still needs it |
| 53 | A rename or move repairs the canvases that name the file, and a canvas is otherwise a download | Accepted; implemented in #579; adds one non-Markdown write beside ADR-01 and one kind of rewrite to ADR-51's plan | Don't change any byte of a canvas but the path string of a file node that names the moved file, don't rewrite a canvas on delete, don't let a canvas Hatchdoor cannot read stop a rename, and don't index, link, search or draw a canvas |
| 54 | An agent adds a folder as a Vault only inside the Vault mount | Accepted; implemented in #700; narrows ADR-41 decision 6 for agents | Don't let an MCP tool register or repoint a local folder outside VAULT_PATH, and don't restrict the web UI or managed-Git placement under this record |
Records 01–13 were reconstructed and adopted on 2026-07-19 from the codebase, the CHANGELOG audit fixes (
F-01…F-17), and the semantic-search evaluation. Records 14–16 were added on 2026-08-08. Record 17 was added on 2026-08-24. Records 18–19 were added on 2026-08-28 from the architecture review recorded on #162. Record 20 was added on 2026-08-31 from the review of #211. Record 21 was added on 2026-09-06 from the triage of #272. Record 22 was added on 2026-09-06 from the fix for #257. Record 23 was added on 2026-09-07 from the fix for #267. Record 24 was added on 2026-09-18 from the triage of #306. Record 25 was added on 2026-09-19 from the fix for #321. Record 29 was added on 2026-09-30 from the triage of #300. Record 31 was added on 2026-10-01 from the triage of #81. Record 32 was added on 2026-10-01 from the triage of #303. Record 33 was added on 2026-10-01 from the triage of #357. Record 35 was added on 2026-10-01 from the triage of #375. Record 36 was added on 2026-10-02 for #402, #403 and #404. Record 37 was added on 2026-10-02 for #408. Records 38–42 were added on 2026-10-02 for #420, from the resolution of #416 and its addendum. Record 43 was added on 2026-10-05 from the triage of #458. Record 45 was added on 2026-10-07 for #476, from the resolution of #474 and its addendum. Record 46 was added on 2026-10-08 from the triage of #500. Record 48 was added on 2026-10-11 for #563, from the maintainer's decision that day. Record 49 was added on 2026-10-13 for #570, from its triage. Record 50 was added on 2026-10-26 for #600, from its triage. Record 51 was added on 2026-11-05 for #631, from the maintainer's decision recorded in its brief. Record 52 was added on 2026-11-07 for #655, from the maintainer's decision that day. Record 53 was added on 2026-11-11 for #579, from the decisions the maintainer agreed in its triage. Record 54 was added on 2026-11-12 for #700, from the maintainer's choice of option (b) in #649.
- Status: Accepted; amended by ADR-50: a schema version mismatch no longer always wipes the cache.
- Context: Users own an Obsidian-style vault of
.mdfiles and must never be locked into Hatchdoor's storage. - Decision: The
.mdfiles underVAULT_PATHare authoritative. SQLite is a generated cache built from them and safe to delete; it is rebuilt from the vault on demand. The schema is versioned and the embedder identity is stamped — a mismatch wipes and rebuilds rather than serving stale or mixed-model data. - Consequences: The cache can live outside the vault and be discarded freely; schema or embedding-model changes cost a full reindex, accepted as the price of never corrupting the read model.
- Evidence: README "Data and Safety Model";
cache/vault_snapshots.rs(replace_vault_snapshot, the per-Vault rebuild that replacedapp_state.rs'sbuild_cachein #185);cache/schema.rs(SCHEMA_VERSION,reset_if_embedder_changed).
- Status: Accepted. ADR-38 adds a fourth surface in the same binary: the bundled manual as public plain Markdown and
llms.txt. - Context: Hatchdoor must serve a browser UI, AI agents, and static assets, on modest self-hosted hardware, with a simple deploy story.
- Decision: A single
axumbinary exposes three surfaces — a JSON HTTP API, an MCP server at/mcp, and the built React SPA as static files — over one shared domain core and oneAppState. - Consequences: One container, one process, shared state; the cost is a large composition root (
server.rs) that concentrates routing and startup logic. - Evidence:
server.rsrouter construction;app_state.rs.
- Status: Accepted
- Context: Both the browser and agents can mutate the vault. Divergent write paths would mean divergent safety guarantees — the class of bug that loses user data.
- Decision: All mutations go through the atomic primitives in
vault/write/. The HTTP write API and the MCP write tools are thin adapters over the same functions. Writes use a content-hash (expected_content_hash) for optimistic concurrency. - Consequences: One place to audit for data-loss safety; both surfaces get path-safety, link-rewriting, and atomic rename for free. Adapters must not reach past this layer to touch the filesystem.
- Evidence:
vault/write/{notes,attachments,fs_ops,rewrites}.rs;handlers/write_api.rs;mcp/tools/write.rs.
- Status: Superseded by ADR-16
- Context: Hatchdoor targets private, self-hosted deployment on modest hardware. A dependency on a paid or remote inference API would break privacy and offline operation.
- Decision: Embeddings run locally via fastembed (Nomic Embed Text v1.5, 384-dim). Model weights are prefetched at image-build time so first run is offline.
- Consequences: Fully private and offline; embedding is CPU-bound, which directly constrains the search-strategy decision (ADR-05).
- Evidence:
embed/fastembed_embedder.rs;main.rs --prefetch-embedder; Dockerfile prefetch stage.
- Status: Accepted
- Context: The read model needs keyword search, vector search, links, and stats, with zero external infrastructure and good concurrent-read behavior during reindex.
- Decision: Bundle SQLite (no external database, no ORM). Use FTS5 for keyword search and
sqlite-vecfor vectors. Build in memory; run in WAL mode with a pool of read connections. Reindex commits in one transaction so readers keep serving the prior snapshot. - Consequences: No infra to run; hand-written SQL instead of an ORM; reads stay parallel and non-blocking during a refresh (fixes F-03/F-05).
- Evidence:
Cargo.toml(rusqlitebundled,sqlite-vec);cache/schema.rs;cache/queries/; CHANGELOG F-03, F-05.
- Status: Accepted
- Context: A self-hosted app is easy to misconfigure into exposing a private vault (binding
0.0.0.0without auth; enabling a public demo alongside write surfaces). - Decision: Refuse to start in unsafe configurations rather than warn: no non-loopback bind without
HATCHDOOR_WEB_BEARER_TOKEN; demo mode is incompatible with MCP or git sync and refuses to boot together. - Consequences: Misconfiguration fails loudly at startup instead of silently exposing data; operators must set a token before going public.
- Note (#629): The loopback exemption assumed that only processes on the same machine could reach a loopback port. A browser breaks that assumption: any page it loads can send requests to
127.0.0.1, and DNS rebinding makes such a page same-origin with the API. The exemption stays, and a token-less instance now closes that gap itself: it answers only requests whoseHostis a loopback name orHATCHDOOR_PUBLIC_URL's host, and refuses a state-changing request from another site: anOriginthat is not its own, the public URL's or on the MCP allow-list, or, with noOrigin,Sec-Fetch-Site: cross-site(auth::require_local_host_and_origin). The refused non-loopback start no longer logs its generated token (ADR-08): it saves it tonew-web-token.envin the state directory, mode 0600, and logs the path. - Evidence:
server.rs(check_web_auth_posture,check_demo_mode_posture,check_demo_mode_registry_posture); CHANGELOG F-01.
- Status: Accepted; amended in #703: the query token works on three GET routes only.
- Context: When set, a bearer token must protect
/api/*,/vault-assets/*, and downloads. But images, SSE streams, and download links can't carry anAuthorizationheader from the browser. - Decision: Accept the token via
Authorization: Beareror, where headers can't be set, anaccess_tokenquery parameter. Compare tokens in constant time; redact them from logs. The PWA prompts for the token on a 401 and stores it locally. - Consequences: Works with header-less browser contexts; the query-param path is a deliberate, documented tradeoff (tokens can appear in URLs/proxy logs).
- Amendment (#703): The query form is accepted on
GETrequests to three routes only, the ones the browser builds such URLs for:/api/v1/vaults/{vault_id}/assets/{*path}(<img>, PDF previews, file downloads),/api/v1/vaults/{vault_id}/notes/{slug}/download(note download) and/api/v1/vaults/events(EventSource). Every other route, every write, the token-reveal routes and the manual's private pages included, takes the header alone and answers401to a query-only token. A leaked URL can then fetch a file or follow the event stream, but cannot write or reveal a token. The list isQUERY_TOKEN_ROUTESinauth.rs; a test holds every frontendwithAccessTokencall to it. Transfer links (ADR-27) and MCP auth are unaffected. - Evidence:
config.rs(web_bearer_token);auth.rs(constant_time_eq, redaction,QUERY_TOKEN_ROUTES); CHANGELOG F-01, F-06, #703.
- Status: Accepted
- Context: MCP exposes the whole vault to agents and is mounted at
/mcp, outside the web-auth layer. Browser-originated JSON-RPC also invites DNS-rebinding attacks. - Decision: MCP is disabled unless explicitly enabled. Even read-only MCP requires its own bearer token. Requests are checked against an Origin allowlist (localhost variants only) to block DNS rebinding. The Streamable-HTTP protocol is implemented directly.
- Consequences: Enabling agent access is a conscious, credentialed step; the vault is never exposed by simply turning MCP on.
- Note (#629): The same allow-list also admits a cross-site write to the web API on an instance with no web token (
auth::require_local_host_and_origin, see the ADR-07 note). Its matching is unchanged. - Evidence:
mcp/config.rs(validate,validate_mcp_request, Origin matching);mcp/tools/{read,write}.rs.
- Status: Superseded by ADR-18 for the mechanism (the instance-wide debounced task over
VAULT_PATH); the safety decisions below (opt-in, never force-checkout over uncommitted manual edits, local mode never contacts a remote, writes do not block on sync) remain in force and are restated there for the per-Vault Git turn. - Context: Users want their vault edits versioned and pushed, without blocking writes or fighting manual git usage.
- Decision: Optional (off by default) auto commit-and-push via vendored
git2, on a debounced background loop with conflict-abort semantics. It refuses to force-checkout over uncommitted manual edits to tracked files, surfacing them as an error. The watcher ignores.git/so sync churn doesn't trigger reindexing. - Consequences: Writes stay fast (sync is async); manual edits are never silently discarded; sync is opt-in.
- Evidence:
git/{sync,task,message}.rs; CHANGELOG v2.1.0, F-08.
- Status: Accepted
- Context: Agents and the UI can delete or archive notes. Destructive deletes on user data are unacceptable.
- Decision: Delete moves notes, and the referenced assets that live inside the note's own folder, into
.hatchdoor-trash(excluded from indexing). A referenced asset kept elsewhere stays where it is. A note at the Vault root has the whole Vault as its folder, so for a root note an asset also stays where it is when any other note embeds or links to it, in any link form; only the assets no other note uses go with it, on a delete, a move and an archive alike. Archive moves notes underHATCHDOOR_ARCHIVE_PREFIX(default90-archive/), which also drives archived-link styling. - Consequences: Deletes are recoverable; nothing is unlinked from disk by Hatchdoor. The trash folder is skipped when deciding whether a vault is empty.
- Evidence: README "Data and Safety Model";
vault/write/;config.rs(archive_prefix); CHANGELOG F-12. Asset travel was narrowed to the note's own folder in #225 (vault/write/assets.rs,asset_move_plan), and for a root note to the assets no other note uses in #701 (AssetsUsedElsewhere).
- Status: Accepted
- Context: The shipped image should have minimal attack surface and run without root.
- Decision: Runtime is
distroless/ccasnonroot. The build is multi-stage (cargo-chef dependency cache → Rust build → separate frontend build → slim runtime). Because the runtime has no shell, the health probe is a--healthchecksubcommand built into the binary. - Consequences: Small, rootless, shell-less image; anything needing a shell (like a curl-based healthcheck) had to move into the binary.
- Evidence:
Dockerfile;main.rs(run_healthcheck); CHANGELOG F-17.
- Status: Accepted
- Context: It's tempting to add abstractions "for flexibility" — traits, a state-management library, an ORM, a CSS framework.
- Decision: Introduce abstraction only where it earns its keep. The only trait seams over external ML dependencies are
EmbedderandReranker, exactly where test doubles (StubEmbedder) and theembedder-testsfeature gate need them. No Cargo workspace, no ORM, no frontend state library, no CSS framework. - Consequences: A lean, navigable dependency set; new code should follow suit rather than introduce speculative layers.
- Evidence:
embed/embedder.rs,rerank/reranker.rs;Cargo.toml/frontend/package.jsondependency sets.
- Status: Accepted. ADR-40 narrows the consequence that a first boot from
.envalone is a complete deployment: a fresh install starts with zero Vaults, so it also needs one HTTP API or MCP call to add a Vault. The decision itself stands. - Context: A Hatchdoor deployment must be completable end to end by a script, a compose file, or an agent, with no human at a browser to finish the boot. That pulls against the settings page: once a knob is editable in the UI, the pull is to make the UI its home and drop the environment variable behind it.
- Decision: No step required to bring Hatchdoor to a working state may be reachable only through the browser. For operator settings the mechanism is an environment variable, and that variable is authoritative for the process — the durable
settings.jsonoverlay resolves beneath the environment pins and above the defaults, and the UI renders a pinned value as locked with its source rather than silently discarding the edit. A setting may be added to the UI, but never only to the UI. For anything that is not a setting, the mechanism is an API or MCP path instead. Accepting the Gemma licence is the standing example: it is a deliberate act by a person or their delegated agent, not a config default to be copy-pasted out of someone else's compose file, so it deliberately has no environment variable — butaccept_gemma_terms/decline_gemma_termsover MCP let an agent complete it unattended, and the versioned on-disk receipt persists it across restarts. - Consequences: A first boot from
.envalone — plus, where a licence is involved, one agent call — is always a complete deployment, and a vault can be redeployed from scratch with no manual step. The cost is that every new setting is three things (a key inlive_settings_defaults, a UI row, and the locked/source display), every new startup gate must ship a machine path alongside its UI, and a setting that cannot be expressed as a string in an env var does not get added. - Evidence:
runtime_config.rs(live_settings_defaults,SettingSource,ResolvedSetting::pinned);handlers/settings.rs(SETTINGS,locked,source);model_setup.rs(accept_gemma,acceptance_is_current);mcp/tools/;.env.example; README operator configuration contract.
- Status: Accepted
- Context: Retrieval quality is the reason to run Hatchdoor at all. It is also the easiest thing to erode by accident — a cheaper embedding model, a chunking tweak, a filter added for speed, a smaller candidate count. Each looks locally reasonable, and none of them announce themselves as a regression.
- Decision: No change may knowingly degrade retrieval quality. Any change touching the retrieval path — embedding model, chunk size or overlap, contextual document headers, task prefixes, layer selection, candidate counts, pre- or post-filters — is validated against the eval set in
eval/before merge, on the same metrics the harness already reports (Recall@5/10, MRR, FP-rate@5, correct-heading), with the per-category and per-tier breakdown read, not just the aggregate. Where quality and another axis conflict, quality wins: prefer paying latency, memory, disk, or index time over recall or ranking. A regression ships only with an explicit recorded justification and its measured cost. - Consequences: Retrieval changes cost an eval run and usually a full reindex, so they move slower than other work. Optimisations on the search path must prove neutrality rather than assume it. Swapping the embedder is a deliberate, evaluated decision (ADR-16), never a convenience.
- Evidence:
eval/harness,eval/queries.jsonl,eval/results.md;docs/research/embeddings/;cache/schema.rs(embedder-identity stamp forcing a rebuild on model change).
ADR-16 — EmbeddingGemma by default behind a licence gate; representation locked at 800/50 with context
- Status: Accepted (supersedes ADR-04)
- Context: ADR-04 fixed the principle — local, CPU-only embeddings, no external inference API — but named Nomic Embed Text v1.5 at 384 dimensions with weights baked into the image. The 2026-07 embedding sweep replaced both halves of that. It ran a 24-cell grid over models, chunk settings, and contextual documents against an eval set grown from 26 queries to ~125, tiered and categorised. Separately, shipping Gemma weights in a public image is not something the licence permits us to do on the user's behalf.
- Decision: The principle of ADR-04 stands unchanged: embeddings run locally on CPU via fastembed, with no remote inference. What it resolves to now is EmbeddingGemma 300M Q4 at 768 dimensions — multilingual, with its own retrieval query/document prefixes — as the default, and Nomic Embed Text v1.5 as the fallback for a user who declines the Gemma terms, explicitly labelled English-only and lower quality for multilingual vaults. Public images ship neither model; weights are fetched on first run behind the licence gate (ADR-14). The document representation is locked at 800-token chunks, 50-token overlap, and contextual headers on: context off wins raw recall, but context on wins MRR in 11 of 12 like-for-like comparisons and correct-heading accuracy in all 12, and Hatchdoor routes people into a specific note section, so first-result quality and heading accuracy are worth more than the broader recall. ADR-05 was re-validated against this newer evidence and is unchanged — retrieval stays pure semantic, with reranking and hybrid fusion offline evaluation tools only.
- Consequences: First run is no longer offline: it needs a network fetch and a licence decision, which is why that decision has a machine path. The cache carries the embedder identity, so switching models wipes and rebuilds. 450/50 with context on remains the specialist setting for heading navigation and is not the default. Any future move off these values is an ADR-15 change and needs eval numbers.
- Evidence:
embed/fastembed_embedder.rs(embedding_gemma_300m_q4,DocumentFormat::GemmaRetrievalV1);model_setup.rs;chunk/chunker.rs(max_tokens: 800,overlap_tokens: 50);docs/research/embeddings/embedding-sweep-decisions-2026-07-26.md;eval/results.md; CHANGELOG v2.4.0.
-
Status: Accepted (supersedes the single sentence of ADR-09 that reads "The Streamable-HTTP protocol is implemented directly"; every other ADR-09 decision — MCP off by default, its own bearer token even for read-only access, and the Origin allowlist against DNS rebinding — remains fully in force). The pin moved to
rmcp = "=3.8.0"in #621, checked against that crate's source.ServerHandler::get_infonow returnsServerConfig, of whichServerInfois a deprecated alias. rmcp answers everyinitializewith a revision that still has the handshake, so2026-07-28is reached only throughserver/discover, and the adapter's own negotiation follows the same rule so a legacy session never advertisestools.listChanged: true. A handler's invalid-params error on the modern revision is answered in-band with HTTP 200 instead of 400. The advertised revisions,legacy_session_mode,stateless_protocol_metadata_required, and the emptyallowed_hostsandallowed_originslists that leave Host and Origin checks to Hatchdoor's middleware keep their meaning; the decision text below records the surface as first verified against 3.1.4. -
Context: Hatchdoor's
/mcpsurface is a hand-written, POST-only Streamable HTTP adapter undersrc/mcp/, serving exactly three legacy revisions (2025-03-26,2025-06-18,2025-11-25). The MCP specification's2026-07-28revision adds stateless discovery-based requests, per-request protocol metadata with required HTTP headers, subscription streams, Multi Round-Trip Request (MRTR) wire types, and typed results with machine-readable output schemas. Hand-implementing all of that would grow a bespoke wire layer that every future protocol revision would have to re-earn inside our own code. The refreshed migration baseline (docs/research/mcp-2026-07-28-refresh.md, ticket #163) confirmed the parts we own are healthy and must not change: the explicitvault_id/scopetool catalogue (35 tools), the per-request security ordering, structured error semantics, and the sharedvault/writemutation layer. The reconciled migration package (#43, corrected by #164) chose a deep protocol boundary: future revisions should arrive through an SDK upgrade, not through re-writing transport code. -
Decision: Two halves, decided together:
- Adopt stable rmcp 3.x as the MCP protocol boundary, pinned to exactly
rmcp = "=3.1.4"in Cargo.toml (an exact-version requirement; published on crates.io 2026-08-20; MSRV 1.88; Apache-2.0). RMCP owns JSON-RPC framing, Streamable HTTP serving, lifecycle and version negotiation, discovery, request_meta/header validation, subscription streams, MRTR-aware wire types, and version-specific serialization. The existing tool catalogue and dispatcher remain framework-independent behind a typed adapter implementing rmcp'sServerHandlerseam; the 35 tools are NOT rewritten into rmcp's macro-generated route tables. - Narrow the advertised protocol revisions to exactly
2026-07-28and2025-11-25. Modern clients work without any initialization handshake —server/discoverreplacesinitializefor them, and requests are served statelessly. Legacy clients keep the existing initialize/negotiation flow unchanged.2025-03-26and2025-06-18are no longer advertised (2024-11-05was already absent).
The trait/type surface above was verified against the actual crate source before acceptance — tag
rmcp-v3.1.4, commit4a738b9dd99eaca418b614afa433a0cbdaf8d056:- Protocol version constants incl.
V_2026_07_28andV_2025_11_25:crates/rmcp/src/model.rs:170–171; both parse back:model.rs:215–216. ServerHandlertrait (default methods overridable one at a time):crates/rmcp/src/handler/server.rs:593; defaultdiscover()method returning server discovery information:handler/server.rs:342–343;server/discovermethod string:model.rs:1148.StreamableHttpServiceimplementstower::Servicefor anyS: ServerHandler, so it mounts behind axum without replacing the router:crates/rmcp/src/transport/streamable_http_server/tower.rs:999+. Version advertisement is handler-controlled viasupported_protocol_versions():tower.rs:347, surfaced inServerInfo.supported_versions:model.rs:1187.- Stateless-by-default for modern clients is structural, not optional: sessions are removed from
2026-07-28per SEP-2567 and such requests "are always served statelessly regardless of this setting" (legacy_session_modedoc comment):tower.rs:66–72; a strict per-request metadata gate exists asstateless_protocol_metadata_required:tower.rs:130–155. - MRTR types (SEP-2322
InputRequiredResult, version-gated to ≥2026-07-28):crates/rmcp/src/model/mrtr.rs. - Subscription stream request
subscriptions/listen:model.rs:2073; client opt-in categories incl.tools_list_changed:model.rs:1912–1926. - Typed results:
CallToolResult.structured_content:model.rs:3785–3803;Tool.output_schema(+ builder):model/tool.rs:30,:210— schema generation rides theschemarsfeature.
Branching revision: implementation happens on a single feature branch
feature/mcp-2026-07-28, cut from currentdevelopmentand merged back via PR after verification (ticket #172). This supersedes item 11 of the #43 decision package: the previously planned stacking onfeature/ui-ux-polishis obsolete because that content has already landed ondevelopment. - Adopt stable rmcp 3.x as the MCP protocol boundary, pinned to exactly
-
Consequences: Future MCP protocol revisions primarily arrive through rmcp upgrades instead of hand-written wire code; each upgrade becomes a deliberate, reviewed event against this record's pin. The hand-written JSON-RPC/transport code in
src/mcp/protocol.rsandsrc/mcp/routes.rsshrinks into a thin adapter, so the boundary keeps its file inventory only if the map is updated when files move (module-map rule). Security posture must be re-expressed at the new boundary without weakening: the per-request ordering enabled check → token configured → Origin allowlist → constant-time bearer compare → protocol-version header, plus the v2.5.0 rule that the MCP token works on the attachment endpoint only while MCP and MCP write mode are live-enabled; a dedicated regression test proves it survives the swap (#172). Rate limiting (#171), subscriptions/listen with honestlistChanged(#170), the modern surface (#169), and typed results/outputSchema for all 35 tools (#167) build directly on this seam. Golden wire tests lock both supported revisions across the replacement. Costs accepted: one additional dependency tree (rmcp + tower/hyper ecosystem pieces already present via axum), an MSRV floor of Rust 1.88, and the discipline of keeping domain logic out of the adapter. -
Evidence:
Cargo.tomlgains the pinned dependency during #168 (verified absent/greenfield today by #163); verified surface cited above against tagrmcp-v3.1.4(commit4a738b9dd99eaca418b614afa433a0cbdaf8d056) of https://github.com/modelcontextprotocol/rust-sdk; current hand-written surface:src/mcp/{config.rs,protocol.rs,routes.rs,auth.rs};docs/research/mcp-2026-07-28-refresh.md; tickets #43, #164, #167–#172.
- Status: Accepted, except for the sentence "The commit-on-write debounce has no successor", which is superseded by ADR-23, and the clause "scheduled through the coordinator with no second execution lane", which is superseded by ADR-31 (supersedes ADR-10's mechanism only; every ADR-10 safety decision remains in force and is restated below, and every one of them still binds the commit turn ADR-23 adds)
- Context: ADR-10 fixed optional Git sync as one debounced background task over the process-wide
VAULT_PATH, started from the settings page and locking phase by phase against an instance-wide write lock. The Vault collection runtime (v2.5.0) changed the unit of work: each Vault carries its own definition (source kind, Git mode, credentials, poll interval, commit identity) and gets its own Git turn, requested through the sharedVaultWorkCoordinatorby the managed-Git scheduler, a manual sync or retry, or activation, and executed by runtime composition under that Vault's mutation lock. The old task still compiled and was still reachable from the settings Git lifecycle, which gates on a value the collection runtime never sets, so in production it answered 503; the architecture review of 2026-08-28 (#162) found the two mechanisms had diverged on locking granularity, drift handling, and recovery, and that the instance-wide Versioning console and/api/git-statusreported only the dead task. - Decision: The per-Vault Git turn is the only Git synchronisation mechanism. One turn per Vault, one operation at a time, scheduled through the coordinator with no second execution lane; a turn holds that Vault's mutation lock for its whole blocking duration; the Vault's source kind and Git mode select the operation (acquire-or-reuse then synchronise a managed checkout; synchronise an existing checkout with its one configured remote; commit local history without touching a remote). ADR-10's safety decisions are restated for the turn: sync is optional and off per Vault by default; a turn never force-checks out over uncommitted manual edits, reporting a dirty working copy or a conflict as a structured, non-retryable error with the affected paths; local-history mode never contacts a remote; writes never block on sync except for the one Vault whose turn is running. The instance-wide debounced task, its handle, its write-record hook, and the instance-wide write lock are removed (#185). The boot-time parse of
HATCHDOOR_GIT_*is deliberately kept, now serving only two purposes: refusing to start on a half-configured Git mode, and feeding the demo-mode posture refusal. No runtime behaviour reads its result.HATCHDOOR_GIT_AUTHOR_NAMEandHATCHDOOR_GIT_AUTHOR_EMAILremain as the commit-identity fallback for a Vault without its own and are read per turn (#181); the otherHATCHDOOR_GIT_*keys remain only as first-boot import inputs until #82 closes. - Consequences: One Git code path to audit, and Git behaviour that is configured, reported, and controlled per Vault (status, error detail,
Sync now,Try again). The per-turn lock is coarser than the old per-phase lock: a foreground write to a Vault waits while that Vault's turn runs, a trade accepted in #96 over a finer discipline. The commit-on-write debounce has no successor: the watcher's fixed debounce coalesces writes into the next turn, and the per-Vault poll interval answers how often to look at the remote. The settings page loses its instance-wide Versioning console and/api/git-statusis retired (#183). - Evidence:
git/managed_task.rs(run_managed_git_turn,run_existing_git_remote_turn,ManagedGitScheduler),git/managed_sync.rs(synchronize_managed_checkout),git/managed_checkout.rs(acquire_or_reuse),git/sync.rs(run_local_history_git_turn),vault_executor.rs(dispatch_git_turn_with,plan_git_turn,publish_managed_git_turn_outcome; extracted fromvault_runtime.rsin #197),vault_registry.rs(VaultGitMode,poll_interval_secs,commit_identity); #162, #181, #183; issues #94–#97, #132 for the per-Vault turn's history. The removal itself landed in #185:git/task.rsandgit/status.rsare deleted outright,git/sync.rskeeps only the local commit path (validate_repo,validate_local_repo,init_local_repo,commit_local,run_local_history_git_turn) with its fetch/integrate/push, unpushed accounting, and merge-marker recovery gone,AppStatelosesgit_sync,vault_write_lock, andstartup_git_config,server.rsloses the sync-task shutdown drain but keeps the boot-timeHATCHDOOR_GIT_*parse for configuration validation and the demo posture check (server.rs,legacy_git_configintocheck_demo_mode_posture), andhandlers/settings.rslosespatch_settings_with_git_lifecycleandproduction_sync_ops.
- Status: Accepted (refines ADR-02 and ADR-03; supersedes neither)
- Context: ADR-02 promises one shared core behind three surfaces and ADR-03 one write module behind thin adapters. The adapters did not stay thin. The HTTP and MCP write adapters each re-implemented the same orchestration around
vault/write(Vault gate, capability check, per-Vault lock, authoritative index build, entry lookup, noise and marker refusal, archive-prefix resolution, off-thread execution, error typing) at 1,224 and 1,499 lines, and had drifted: MCP ran writes on the async runtime while HTTP offloaded them. Sixteen MCP tools reached the domain by calling axum handler functions with hand-built extractors and decoding the HTTP response body through a byte cap and two serialisation passes, so a tool could only be tested with the transport on both sides. Vault collection management (registry commit, runtime reconcile, revision response, projections, the structured error type) lived in an HTTP handler that MCP imported as a library.VaultReadCoreandVaultSearchCorealready showed the intended shape: a Vault-qualified core with a small interface, consumed by both adapters (#162). - Decision: Four Vault-qualified cores are the seams adapters cross:
VaultReadCore(exact reads, collection reads, contained resources),VaultSearchCore, the Vault mutation core (every write primitive with its orchestration; #184, #186), and the Vault collection management module (#187). HTTP handlers and MCP tools are wire-shaping adapters: they parse the transport's input, call exactly one core, and map the core's typed outcome or its structured error{code, message, vault_id?, retryable}to a status code or a tool error. An adapter never calls another adapter (no MCP-to-handler proxying; #188), never reaches past a core tovault/write, the registry, the runtime, the scheduler, or the filesystem, and holds no policy a core could hold. Cores own the off-thread execution of blocking work. The cores stay plain structs (ADR-13): no trait seam is added to formalise them. - Consequences: Domain behaviour is tested once, at a core's interface, with a filesystem fixture; each adapter keeps one mapping test per route or tool. A new surface or tool costs a mapping, not a re-implementation, and a new write primitive reaches every surface at once. Wire shapes do not change when orchestration moves; relocating a wire type follows the interface-change checklist. The module map gains two boundaries and its adapter sections shrink to wire shaping. Until #184–#188 land, the HTTP handlers remain the de facto library MCP calls, and that is the debt this record retires.
- Evidence:
vault_read.rs(VaultReadCore),search/vault_scoped.rs(VaultSearchCore); #162 and its child tickets #184, #186, #187, #188;docs/architecture/module-map.md(Vault-qualified read projections, HTTP adapters, MCP adapter).
-
Status: Accepted (refines ADR-15; supersedes neither. ADR-05 needs no exemption — see Context)
-
Context: ADR-15 requires any change touching the retrieval path, "pre- or post-filters" named explicitly, to be validated against the eval set before merge. #210 removed
NoteFilters,include_properties, the property projection they drove, the branch selecting between two semantic retrieval implementations, andsemantic_hitsbehind it — code that sits squarely on that path and could not run. Every producer of aVaultSearchRequestbuilt the filters empty (the web search route, thesearch_notesadapter, the eval harness),search_notesrefuses afiltersargument at the protocol level with a test pinning the refusal, and the branch was guarded by!request.filters.is_empty(). The three live call sites ofNoteFilters::matcheswere a no-op by construction: each check is anall()over an empty iterator and the property arm returnedis_empty() && is_empty(), so it answeredtruefor every note. Read literally, ADR-15 demanded an eval run for a deletion that no eval could speak to: the harness measures what executes, and the claim was that this did not. Running it would have reported the same numbers for a reason unrelated to the change, which is a weaker statement than the proof already in hand, not a stronger one. ADR-05 was cited alongside ADR-15 in that PR but was never actually in tension: its constraint is against adding reranking or FTS/vector fusion to the runtime path, and a deletion adds nothing. -
Decision: An eval run is not required to delete retrieval-path code when all four hold, and every one of them is recorded in the PR:
- The code is dead, and the proof is by enumeration. Either (a) it is unreachable — a guard no producer in the crate can satisfy — or (b) it executes but is provably an identity for every input any surface can construct. Both are established by listing every producer of the input and reading the callee's own definition. "I could not find a caller" is not this proof; neither is "this is always a no-op in practice."
- It is a deletion. Code that survives the change is not modified on the strength of this record. A deletion bundled with a behavioural tweak forfeits the exemption for the whole change.
- A before/after comparison is measured, not argued. The pre-change and post-change builds are run over the real surfaces against fixtures, covering each retrieval route the deletion touches, and return identical results, order, scores and payload bytes. Any field that legitimately differs is named and explained.
- Doubt resolves to the eval. If the enumeration is incomplete, the identity argument leans on typical rather than all inputs, or the comparison differs anywhere unexplained, ADR-15 applies unchanged.
Wire shapes that were only ever produced by the deleted code are pinned by a test asserting the serialized output, so a later change cannot quietly turn a constant into something else.
-
Consequences: Dead weight on the retrieval path can be removed at the cost of an argument rather than a reindex and an eval run, which is what makes removing it likely to happen at all — ADR-15's literal reading gave a standing incentive to leave unreachable code where it sat. The exemption is deliberately hard to claim: it demands an enumeration a reviewer can check line by line, and it collapses to ADR-15 the moment the deleted code turns out to have run. It says nothing about adding, tuning, or reordering anything on the retrieval path, where ADR-15 stands in full. The risk accepted is a wrong reachability proof, and it is mitigated by condition 3: a deletion that changes behaviour shows up as a differing result before it reaches
development. -
Evidence: #210 and its PR #211 (the enumeration of producers, the
debug_assert!(!request.filters.is_empty())that stated the dead branch's own precondition, and the eight-case keyword/semantic/tag comparison over the MCP endpoint and the HTTP search route returning identical results, order, scores and bytes);search/mod.rsandsearch/vault_scoped.rsas they stand after the deletion; the survivingsearch_rejects_legacy_metadata_filterstest;eval/harness and ADR-15 for everything this record does not exempt.
-
Status: Accepted
-
Context: #19 asked for structured metadata querying and v2.3.0 delivered it; the multi-vault rewrite retired the tool that carried it and put nothing back, so selecting notes by tag, path or frontmatter property is currently impossible. #272 then asked for the next thing up: a query definition that lives in a note, evaluated on read and displayed as a table, so that "active subscription" means one thing to a person and to every agent instead of being reconstructed differently on each request. The reporter asked specifically for compatibility with Obsidian Bases, the built-in feature that already does this in the editor many Hatchdoor users keep pointed at the same vault directory. Two forces pull against granting that as stated. Obsidian publishes no specification, no version field and no deprecation policy for the format, is closed source, and already shipped one breaking syntax overhaul in 1.9.2, so "compatible with Bases" is a promise nothing can be checked against. And a note whose displayed content is not in the file collides with ADR-01, which is the record everything else in Hatchdoor rests on.
-
Decision: Four parts, decided together during the triage of #272.
- A query result is derived state and never vault content. It is recomputed on every read, never written into the Markdown, and absent from search, backlinks, statistics and the graph. Indexing it would mean the read model holding content no file contains, and keeping that correct would require tracking which saved query depends on which notes and re-embedding a dependent note on every edit of a matching one. ADR-01 stays literally true: the file is the whole truth about the note.
- A saved query is evaluated on demand, against the vault its note lives in, within an enforced ceiling. On demand rather than precomputed, because a filter comparing against the current time changes its answer with no file change, so a stored result is wrong on a schedule. Its own vault only, not widenable by the definition or by the caller, because a definition whose answer depends on who asks is not a definition. The ceiling on notes scanned and rows returned is Hatchdoor's, separate from the row limit the author sets, and hitting it is reported rather than silently truncating.
- Hatchdoor implements a documented subset of the Bases syntax and refuses the rest. The subset covers filters over tags, note properties and path, comparison and boolean operators, emptiness checks, the current time, column selection and a row limit. Anything outside it is refused with the offending construct named. Refusal splits by effect: a construct that changes which rows appear refuses the whole saved query, since there is no honest partial answer to a filter only partly understood, while a construct affecting only presentation renders correct rows with the ignored instruction stated. The three outcomes, refused, empty and populated, are distinguishable on every surface, and broken never presents as empty. No Hatchdoor-only key is added to the format, which is why row sorting is viewer state rather than something the definition carries. Where a note holds more than one saved query and one of them has to be addressed by name, that identifier is Markdown outside the block, an HTML comment of the form
<!-- hatchdoor-query: name -->immediately preceding it. That placement is the decision, not an incidental detail: anything inside the block, including a name on the fence line, changes what Obsidian is asked to parse, and there is no specification against which to check that it still parses. A marker outside the block cannot affect how Obsidian reads it. - Note reads never render. An exact note read returns the authoritative Markdown always, with no argument that changes it, and reports only that a saved query is present. A separate read evaluates it and returns structured rows. Writes are guarded by a content hash of the real file, so a response pairing computed content with a valid hash would let an agent commit derived rows into the note on its next edit and turn a live saved query into a stale snapshot. Keeping rendering out of the note read makes that impossible by construction rather than merely discouraged.
-
Consequences: Vault authors get one definition that means one thing to every reader, which is the whole point of the feature, and portability with Obsidian holds for simple definitions and visibly fails for complicated ones instead of silently disagreeing. Searching for a value that appears only in a computed row will not find the note displaying it, which is the price of part 1 and the most likely thing a future contributor will try to "fix". Agents pay one extra call to get rows and are handed data rather than a drawn table, which is the better end of that trade. The subset will look arbitrarily narrow to anyone comparing against Obsidian's documentation, and widening it is ordinary work; accepting syntax that has not been implemented is not. Standalone
.basefiles stay unread, so a user who keeps definitions outside notes sees nothing until that is designed, which is a deliberate deferral rather than a rejection. Nothing here touches the retrieval path, so ADR-15 is not engaged: a query selects and does not rank, and it must stay that way for that to remain true. -
Evidence: #272 and its triage; the subset, refusal and ceiling contracts in #275, #276 and #277; the query capability this builds on in #274;
GLOSSARY.md(Query, Saved query, Query result, Note property); ADR-01 for why derived rows stay out of the read model, ADR-03 for the write path whose content hash makes part 4 necessary, and ADR-19 for the core both surfaces reach evaluation through.
- Status: Accepted (refines ADR-03; supersedes nothing)
- Context:
update_frontmatterwas written as a merge: parse the block into a map, apply the caller's keys, serialize the map back. That is the obvious shape and it is quietly destructive.serde_json::Mapis sorted, so the author's key order was gone before anything was written, andserde_yaml_ngemits every sequence in block form, so a one-linetags: [a, b, c]came back as five lines. Setting one field rewrote the whole block. Across the maintainer's vault, the demo vaults and both shipped sample vaults, 530 of the 531 notes carrying frontmatter use a one-line list, so effectively every call reformatted the note it touched, and the diff for a one-field change buried that change in noise deep enough to makegit blameon frontmatter useless (#257). The behaviour was not an accident. It was documented in the function's own doc comment and pinned by two tests. What made it wrong was never the emitter's taste in YAML. It was that the tool rewrote text nobody had handed it. - Decision: Text the caller did not supply is not Hatchdoor's to rewrite. A write that replaces a note's whole content may normalise what it was given, and the CRLF and trailing-newline handling on
update_noteis exactly that, and stays. A write that names a part of a note leaves every byte outside that part as it was: order, whitespace, quoting style, flow versus block collections, comments, blank lines. Where a named part is replaced, its replacement inherits the shape the author used for it. Where there is no prior shape, because the part is new or its kind changed, the house style is written and the caller gets no say in it. When the named part cannot be located and replaced unambiguously, and a key written twice in the same block is the case that occurs, the whole call is refused, naming the part and the reason, rather than guessing. A part the caller did not name is never a reason to refuse: it is copied, oddities and all, and any existing quality warning about it still fires. The one exception is the backstop, and it is deliberate: an editor doing text surgery has to prove its own work, so the edited text is reparsed and compared against the merge that was asked for, and a mismatch refuses the call. That can refuse an edit over a part nobody named, when the file is laid out in a way the editor reads differently from a YAML parser. Refusing there is the right trade, because the alternative is writing a file whose meaning has quietly changed. - Consequences: A one-field change produces a one-line diff, so frontmatter maintenance across many notes becomes something an agent can do without wrecking the history, and
rename_tag(#242) can be built on the same in-place editor rather than avoiding this layer. The cost is that the write layer now parses the block twice, once to know what it means and once to prove the edited text still means that, and carries a small text scanner for locating top-level keys. That is more code thanto_string, and it has to stay honest about the YAML it cannot handle. The reparse check is what keeps it honest: an edit whose reparse does not match the intended merge is refused rather than written. Two refusals exist that did not before, and one class of note, a block with a duplicated key, is now editable only through its unambiguous keys. Nothing repairs a note an earlier call already reformatted; the fix is forward-looking. - Evidence:
src/vault/write/frontmatter.rs(edit_frontmatter_block,top_level_keys,render_key, and the reparse check before returning);src/vault/write/notes.rs(update_note_frontmatter); the tests insrc/vault/write/tests.rsnamed for this behaviour, which replaced the two that pinned the alphabetised, block-style output; #257 as the worked example; #316 for the body text, whereappend_note,edit_noteandreplace_sectioninsrc/vault/write/notes.rsconvert only the caller's text to the note's own line ending (prepare_inserted_text,Splice::join) instead of normalising the whole note; ADR-03 for the layer this constrains, and ADR-01 for why the file's own bytes are the thing worth protecting.
- Status: Accepted, except for the clause "so there is still one execution lane per Vault and no second scheduler", which is superseded by ADR-31 (supersedes one sentence of ADR-18, "The commit-on-write debounce has no successor"; every other ADR-18 decision, and every ADR-10 safety decision ADR-18 restates, remains in force and binds the commit turn added here)
- Context: ADR-18 made the per-Vault Git turn the only Git mechanism, and it welded two operations into it: commit the Vault's own changes, and talk to the remote. Both then ran on one schedule, and that schedule existed only because a remote needed polling. The consequences took a year to show up as one bug (#267). A Local-history Vault has no remote, so it has no poll interval, so
ManagedGitSchedulernever tracked it, so nothing requested a turn for it after the one at activation, and manual sync refused it for the same reason. Every note written to it sat uncommitted until the process restarted, while the Vault's status readreadyand its writes returnedok. Two-way had the same defect in a milder form: its commit lived inside the turn that fetched and pushed, and that turn ran on the sync schedule, which defaults to once a day. The file watcher noticed every change within its debounce window and asked only for a reindex. Meanwhile the two operations have nothing in common on cost or failure. Committing is local, needs no network, and cannot fail for a reason outside the machine. Fetching and pushing cost a round trip and fail for reasons the user does not control, which is exactly why they have a user-facing schedule. - Decision: A commit is its own kind of background work,
VaultWorkKind::Commit, admitted through the same per-Vault coordinator and holding the same per-Vault mutation lock, so there is still one execution lane per Vault and no second scheduler. A commit turn never opens a network connection: the managed-Git commit turn reuses the checkout a Vault already has and reports "up to date" rather than cloning one, because cloning is a network call. The watcher's existing debounce is the only rate limit on it, and it asks for a commit before it asks for an index, so a commit does not wait out a rebuild that can run for minutes. Which Vaults commit is decided by mode, not by whether they have a remote: Local history and Two-way commit, Pull-only does not because it refuses writes and must leave a folder its operator dirtied alone, and a plain local folder has no Git. Fetching, merging and pushing stay exactly where ADR-18 put them, on the Vault's configured poll interval, and a commit turn never touches that schedule. Manual sync and retry admit a commit for a Vault with no remote instead of refusing it; the refusal narrows to a Vault with no Git at all. Because every way a commit can fail is non-retryable and needs a person, a failed commit turn suppresses further automatic commits for that Vault for five minutes, coalescing whatever changes arrive meanwhile into one attempt when the window closes; a success or a manual commit clears it. The trigger is not configurable and gets no setting (ADR-14): committing promptly is the behaviour, not a preference. - Consequences: A Vault's history is now as current as its last save rather than as its last restart, and the write summaries #249 introduced reach the commit that records them instead of ageing out of a bounded batch. The cost is more commits: a Local-history Vault that used to get one commit per process now gets one per burst of writing, which is the point but is also a bigger history. One status field,
git, now answers for two operations, so a commit that succeeds on a Vault whose remote sync is failing clears that failure's status until the next scheduled sync republishes it; the alternative, a commit that can never clear a status it can set, was judged the worse lie. Two-way now commits at two different times for two different reasons, which is one more thing to hold in mind when reading a Two-way Vault's history. And the boundary has to be defended: any future work that adds a fetch, a merge or a push to the commit path breaks the decision, which is why the tests assert the remote is untouched from the remote's own side rather than by inspecting the code path. - Evidence:
src/vault_work.rs(VaultWorkKind::Commit);src/vault_executor.rs(dispatch_commit_turn,plan_commit_turn,finish_commit_turn,run_planned_turn);src/git/managed_task.rs(run_managed_git_commit_turn,run_existing_git_commit_turn);src/git/managed_sync.rs(commit_managed_checkout,open_commit_repository);src/git/managed_checkout.rs(reuse_existing_checkout);src/git/commit_cooldown.rs;src/server.rs(forward_vault_change_intent,request_commit_for_change);src/vault_management.rs(managed_git_control);src/vault_runtime.rs(VaultCapabilities::commit/sync); issue #267.
- Status: Accepted
- Context: A note is addressed by a slug derived from its filename stem, and one function derived it by keeping ASCII letters and digits, mapping space,
-and_to a dash, and silently discarding every other character. Discarding is not folding, soCaféaddressed ascafandVeáasve: correcting a title's spelling to add an accent moved the note's address, which is how #306 was found. Two consequences followed from the same line. A title written with a combining accent rather than a precomposed letter kept its base letter and so produced a different address than the visually identical precomposed form, making a note's address depend on which machine created the file. And a title with no ASCII letters at all produced an empty slug, for which the indexer substitutesuntitledand thenuntitled-2,untitled-3by directory-walk order, so a Vault written in Cyrillic, Greek or any CJK script has no stable addresses at all: adding one note can move every other note's address. A survey of every Vault in this project plus the operator's own (1223 notes) found 20 addresses that the fix moves, all of them accented Latin, no non-Latin script in any filename, and no note currently living atuntitled. So the non-Latin half of this record is insurance and the folding half is the repair. Two alternatives were live. Romanising every script phonetically (資料tozi-liao) addresses everything in ASCII but needs a large lookup table as a new dependency and cannot tell languages apart, so it would spell a Japanese word the Chinese way. Keeping accents in the slug (Cafétocafé) needs nothing new but fails the reporting case outright: it yieldsveá, which is still not theveathe note had before its rename. The third force is internal contradiction.src/vault/layers.rsalready decided that layer names are Unicode, with a comment namingsources-privéesand資料as valid, so slugs discarding both was the odd rule out. - Decision: A slug normalises the title, strips the combining marks that sit on an ASCII letter so an accented Latin letter folds to its base letter, keeps a mark that belongs to a letter held in its own script because dropping a Devanagari virama rewrites the word it is in, maps the European letters that carry a settled conventional spelling through a short explicit table (
ßtoss,øtoo,ætoae,œtooe,łtol,đ/ðtod,þtoth), and keeps letters and digits from every other writing system unchanged. Stated as one sentence: European languages give a plain ASCII address, every other script keeps its own letters. No script is ever romanised phonetically and no character is discarded for being non-ASCII; only marks, punctuation and symbols are. The rule has two implementations, the Rust slug and the TypeScript heading anchor the browser clicks, and they carry the same table and must be changed together. The empty-result fallbacks stay, because a title of pure punctuation or emoji still reaches them. Old slugs are not kept alive: the 20 moved addresses returnnote_not_found, and the alternative, an index of what the discarding rule would have produced consulted on a miss, was rejected because it makes the defect a permanently supported way to address a note and invents a collision question between a legacy address and some future note's real one. - Consequences: Twenty addresses move once, from wrong to right, and are stable afterwards; they are listed in the changelog so an operator can check anything they handed out. Nothing has to be rebuilt to get there, because the indexer already compares each path's cached slug against the one it just computed and replaces the row when they differ, so the first index turn after the upgrade reprocesses only the affected notes. The combining-versus-precomposed split closes as a side effect, since both forms now fold to the same slug; the title-matching path itself still does not normalise, which is left alone deliberately. The costs are a hand-maintained table that a future European letter may need adding to, and a rule living in two languages that a reviewer has to keep in step: a change to one implementation without the other silently splits a note's address from its own headings' addresses. The heading anchor the cache stores is computed by the Rust implementation and read by nothing; it starts holding correct values for free and its removal is deliberately not bundled here, because dropping a column bumps the cache schema, and a schema bump wipes and re-embeds every note (ADR-01), which is the wrong price for deleting something unread.
- Evidence:
src/vault/paths.rs(slugify);frontend/src/lib/noteHeadings.ts(slugifyHeading,assignHeadingId);src/vault/index.rsandsrc/vault/write/notes.rs(theuntitledfallback and slug assignment);src/cache/populate.rs(the cached-path-to-slug comparison that makes the change self-healing);src/cache/parse.rs(extract_headings, the unread anchor);src/vault/layers.rs(the Unicode layer-name precedent this record aligns with); issue #306.
- Status: Accepted (refines ADR-18 and ADR-03; supersedes nothing)
- Context: Every Vault has one mutation lock, and three separate guarantees rest on it being one: optimistic concurrency on the shared write path (ADR-03), a Git turn's checkout reset never landing under a write (ADR-18), and an Index turn labelling a publication Fresh only when nothing mutated during its read phase. The lock was a field on
VaultControlBlock, andreconcile()builds a replacement control block for any Vault whoseVaultDefinitionis not equal to the live one. A rename, a new poll interval, an edited exclude pattern, a re-entered credential — each of those published a block holding a brand-new, unlocked mutex, visible to the write path the instant the state lock dropped, while the retiring block's in-flight write, Git turn or Index read phase still held the old one. The retirement path waited for that old guard, but waiting retires bookkeeping; it does not stop the new block admitting a writer. For the length of that window one directory had two independent mutexes and none of the three guarantees held. The MCPbatchtool had the matching problem from the other side. It is the only caller that holds more than one Vault's lock at once, and it took them lazily, in whatever order the caller's items named Vaults, holding each to the end of the call. Two concurrent batches naming two Vaults in opposite orders wedged both Vaults' entire write paths until the process was restarted, silently. And because it re-resolved the control block per item, a definition edit mid-batch handed later items the replacement block's different mutex, so they wrote with no live lock at all (#321, from the 2026-09-18 pre-release audit). - Decision: A Vault's write exclusion is a value with its own lifetime, not a field whose lifetime is the control block's.
VaultWriteExclusionholds the mutation mutex, the mutation generation counter read under it, and the refresh mutex, and a control block built to replace a live one inherits it — the same way the Git status and the pending write ledger already travel across that rotation. A definition edit therefore rotates the definition and nothing else; the only ways to get a fresh exclusion are a genuinely new Vault and one coming back from disabled, both of which have no live work to exclude. Where more than one Vault's lock is needed at once, acquisition is ordered by Vault ID and complete before any work runs, never lazy and never in caller order.batchpre-scans its items for the Vaults they write, sorts, and acquires up front. There is deliberately no acquisition timeout: a total order over the only multi-lock holder makes a cycle impossible, while a batch may legitimately wait minutes behind a Git turn's network work, and a timeout would convert that wait into a spurious failure. A holder that must keep working across a possible reconcile identifies the exclusion it holds by pointer, not by Vault: when the resolved block is no longer live — whether it was retired while the holder queued for the lock or after the lock was taken — the holder resolves the replacement and continues only when that replacement shares the exclusion, and otherwise refuses with a structured error rather than writing unlocked. - Consequences: Editing a Vault's settings is no longer a way to break write exclusion on it, which is the point, and the mutation generation an Index turn took before an edit stays comparable with the one it takes after, so a turn spanning an edit still reports its freshness honestly. Reconcile's boundary wait can now be delayed by a write admitted after the edit, because both queue on one mutex; that is the correct behaviour and is bounded by one mutation. Two overlapping lifecycles for one Vault now wait at that same lock rather than at two, so they serialize where they used to pass through each other — fine for the polled tasks the process actually runs them as, and a trap for a test that parks one lifecycle mid-wait and then drives another. A Vault whose path changes while it stays enabled keeps one exclusion across two directories for the length of that reconcile, which is conservative rather than wrong.
batchnow blocks on every Vault it will write before running its first item, including the read items ahead of them, and a Vault it could not resolve during that pre-scan is refused for the whole call, reporting the reason the pre-scan recorded, rather than written unlocked — both are visible behaviour changes, and both are the safe direction. The rule a future change has to respect is the narrow one: nothing may construct a mutation lock for a Vault that already has one, and nothing may take two Vaults' locks in an order it chose for itself. Later fixes narrowed "a genuinely new Vault and one coming back from disabled": a Vault resumed while its Pause still waits for an old turn inherits that turn's exclusion (#640), and so does a new Vault added on the folder of a paused, disconnected one (#681), because in both cases the folder still has live work to exclude. A fresh exclusion now needs a folder no retiring control block holds, and a Vault on a folder inside or around a retiring block's folder waits for that block's lock before each of its own (#745). - Evidence:
src/vault_runtime.rs(VaultWriteExclusionand itsalso_waiting_forandlock_mutation,CarriedOverState,carried_over_from_retiring,VaultControlBlock::activate,reconcile,write_exclusion);src/mcp/tools/batch.rs(lock_touched_vaults,lock_one_vault,dispatch_one);src/mcp/tools/write.rs(scoped_vault_by_id,shares_write_exclusion,exclusion_lost_error); the tests named for this behaviour insrc/vault_runtime/tests.rsand insrc/mcp/routes.rs's test module, which is wherebatch's end-to-end locking tests live —src/mcp/tools/batch.rs's ownmod testscovers only the op-set invariants; ADR-03 for the shared write path this protects, ADR-18 for the Git turn that holds the same lock, and issue #96 for the defect this stops being reintroduced. This record covers lock lifetime and acquisition order only. Issue #321 also bound a planned text rewrite's commit-time CAS to the hash read when the plan was built (TextRewrite::original_hashinsrc/vault/write/types.rs,apply_rewrites_with_before_commitinsrc/vault/write/fs_ops.rs,RewriteBase/planned_base/merge_rewritesinsrc/vault/write/rewrites.rs, and the producers insrc/vault/write/assets.rsandsrc/vault/write/tags.rs); that invariant is recorded in the module map under "Vault-qualified mutation core" rather than here, because it is about what a write checks against, not about which lock it holds.
- Status: Accepted (refines ADR-03; supersedes nothing)
- Context: Hatchdoor 2.5.0 replaced the write layer's check-then-rename commit with
renameat2(RENAME_EXCHANGE). The gain is real: the exchange puts the new bytes in place and hands back the bytes it displaced under a private name, so a save made in another editor between the read and the commit is detected and put back instead of being overwritten. What the change assumed is that the flag is always there. It is not.renameat2has been in Linux since 3.15, but each filesystem implements its flags separately, and OpenZFS before 2.2.0 rejects any non-zero flag withEINVAL, as does every FUSE filesystem. Ubuntu 22.04's default kernel ships OpenZFS 2.1.5, which makes this an ordinary self-hosted configuration rather than an exotic one. On such a host every write with a commit point failed: editing, appending, replacing a section, updating frontmatter, and every move, which is to say rename, archive, delete and the attachment operations too, since a move commits with the same exchange. Creating a note still worked, because it passes no expected hash and takes the plain-rename branch, so the instance looked healthy. Managed Git provisioning failed for the same reason at a different flag,RENAME_NOREPLACE, and threw the errno away entirely. Nothing was logged on any of these paths, so the whole failure reached the operator aswrite_failed: Invalid argument (os error 22)in their MCP client, and finding it took an strace of the running container (#345). Two things were wrong, and they are independent: the write path had no path that works where the flag does not, and the software said nothing about either the failure or the reason. - Decision: Writing is not conditional on the flag. Where a flagged rename reports that the filesystem cannot do the flag, the operation falls back to the shape it had before 2.5.0: verify the precondition, then rename. Every precondition still holds and every refusal keeps its code and its wording, so a stale expected content hash is still
write_conflictwith the same sentence and an occupied move destination is still a conflict. The single thing lost is atomicity against a writer outside Hatchdoor, and losing it is preferred to refusing to write at all. The fallback is keyed on a probe, never on the errno alone:EINVALis equally what the kernel returns for genuine misuse of the call, so a blanket errno fallback would silently convert a future bug of that kind into non-atomic writes. The probe performs the real operation on dot-prefixed scratch names in the directory in question, cleans up on every path, caches its verdict per filesystem, and never asks what the filesystem is called or which version it is. It answers in three states, and the third matters: a directory the probe cannot use, because it is missing or read-only, isUndetermined, neverUnsupported, because a Vault that cannot be written has its own reason to report and must not be blamed on the filesystem. Since the verdict is cached per filesystem rather than per directory, a read-only Vault on a filesystem already known to be capable answersSupported, which is the honest answer to a question about the filesystem. The degradation is then stated rather than implied, in three places that serve three different readers. One log line per Vault when its runtime is established names the mechanism and what it costs, not the errno. An I/O write failure that reaches a client is logged server-side, which is the narrow fix for the silence and is independent of the fallback. AndWriteCapabilities, with its HTTP and frontend types, carries the answer so the Vault can tell the person using it that their saves are protected less well than usual. The managed Git checkout's install gets the same treatment at its own flag, and its error stops discarding the errno. - Consequences: A Vault on OpenZFS 2.1.x, on FUSE, or on anything else without flag support is writable again, which is the point, and it is writable with a named, visible weakness rather than a hidden one. The weakness is genuine: between the check and the rename there is a window in which a save made in another editor is overwritten instead of refused, and on the move path there is a comparable instant where the destination name is reserved by nothing. Hatchdoor's own concurrent writes are unaffected either way, because the per-Vault mutation lock serialises them and always did; the exchange only ever guarded against writers outside the process. The probe is one more thing that touches a Vault directory, so it is written to leave nothing behind and to answer
Undeterminedrather than guess. Caching per filesystem means a verdict is not re-derived per write, and it also means a filesystem remounted with different capabilities inside one process lifetime keeps the old verdict until restart, which is accepted. The rule a future change has to respect is narrow and easy to break by accident: a new commit point may use arenameat2flag, but it must ask the probe what to do when the flag is refused, and it must not read a bareEINVALas an answer. - Evidence:
src/rename_flags.rs(support,flag_unavailable,probe, and the test-only override the regression tests drive);src/vault/write/fs_ops.rs(exchange_unavailable,commit_checked_without_exchange,move_checked_without_exchange, and the three exchange call sites that branch to them);src/vault_mutation.rs(WriteCapabilities::atomic_compare_and_swapand thetracingcall onWriteError::Io);src/vault_runtime.rs(report_compare_and_swap_support);src/handlers/vault_write.rsandfrontend/src/types.tsfor the reported capability;src/git/managed_checkout.rs(atomic_install,install_without_noreplace,AtomicInstallFailed); issue #345; ADR-03 for the shared write path this constrains, and ADR-01 for why the file's own bytes are what the guarantee is about.
- Status: Superseded by ADR-32, which restates every rule below and widens upload links to notes (refines ADR-08 and ADR-09)
- Context:
get_attachmentanswers by default with a relativedownload_urlthat works only when the request carries this MCP session's bearer token in anAuthorizationheader, and the recommended upload method is a multipartPOSTauthenticated the same way. Both assume the caller holds the token and knows the server's address. An agent running inside an MCP client holds neither: the client keeps the endpoint and the token in its own configuration and never passes them to the model. The fallback, base64 inside the tool call, puts the whole file through the model's context, and Claude Code truncates tool output at 25,000 tokens by default, so it fails for any ordinary PDF. On 2026-09-18 an agent asked a question answered by a 1.5 MB appliance manual in the Vault and had no route to it (#310). Handing the agent the token is not an answer: it grants write access to every Vault and would sit in shell commands and transcripts, and Claude Code's own classifier refused the attempt. Three alternatives were weighed and rejected. A local helper command that reads the token itself works only where it is installed and still reads a credential file. Paging base64 through the conversation costs hundreds of thousands of tokens per file and cannot upload. Extracting a PDF's text answers one question type and leaves every other file type, and uploads, where they were. - Decision: An authenticated MCP call may mint a transfer link: an absolute URL carrying its own credential, good for one attachment download or one upload to one target, with no MCP token needed to redeem it. It is a new kind of credential, strictly narrower than the token that minted it, and this record is the deliberate exception to ADR-08 and ADR-09's rule that every request carries a bearer token.
get_attachmentwithencoding: "url", its default, returns a download transfer link; a newcreate_upload_linktool mints an upload link, andget_attachment_import_configrecommends it. The bearer-header route stays and keeps working unchanged for clients that hold the token.- Scope. A download link names one Vault and one relative path and is refused for any other. An upload link names one Vault, one target relative path, and whether replacing an existing file is allowed, all fixed when it is minted; minting refuses at once when the target exists and replacing was not allowed, and redemption checks again.
- Lifetime. Every link expires five minutes after minting, checked when a transfer starts so a slow upload that started in time is not cut off. The length is fixed and has no setting. A download link may be redeemed any number of times until it expires; an upload link is redeemed once.
- Revocation. Links are signed with a random key held only in memory, never written to disk, and replaced whenever the MCP token changes. Every live link therefore dies on expiry, on restart, and on an MCP token change. Redemption also re-reads the live configuration per request, as the bearer route does, so disabling MCP refuses every link at once and disabling MCP write mode refuses every upload link.
- Allowance. A link is a cheaper transport, not a larger allowance, which is the rule #176 set for the bearer URL. A download redeemed through a link spends the same tool-call quota and concurrency budget and stops at the same
HATCHDOOR_MCP_MAX_BASE64_BYTESceiling as a read over/mcp. An upload keepsHATCHDOOR_MAX_ATTACHMENT_BYTES. A link obeys the same browse-surface and layer visibility asget_attachment. - Address. The absolute URL uses a new optional public-address setting when one is configured, settable from the environment as well as Settings (ADR-14), and otherwise the scheme, host and port the minting MCP request arrived on. The setting exists for deployments behind a proxy or HTTPS front end, where the arriving request does not show the address clients use.
- Secrecy. A link's credential is redacted from logs and trace spans like any other token (ADR-08).
- Consequences: An agent with no token in its context can fetch an attachment to local disk and upload a local file from a tool response alone, in any MCP client that can make an HTTP request. A leaked link exposes one file, or one upload slot, for at most five minutes, where a leaked token exposed every Vault until rotated. The costs: the server now mints and verifies a credential of its own, which is new security-relevant code; a restart or token rotation breaks links an agent is about to use, so it has to ask again; and when the address is inferred from the arriving request behind a proxy that rewrites it, links point at an address the agent cannot reach until the operator sets the public address. The inference is not a security hole, because the link goes back to the same caller who sent that address, but it is a correctness hole with a one-field remedy. Any future change that lets a link name more than one file, outlive its key, or skip the quota breaks this decision.
- Evidence: issue #310 (the failure and the design); #176 for the bearer URL and the "cheaper transport, not a larger allowance" rule this keeps;
src/auth.rs(require_web_or_live_mcp_read_token,require_web_or_live_mcp_token, the guards a link must not weaken);get_attachmentandget_attachment_import_configin the MCP read tools.
- Status: Accepted (supersedes nothing; widens what the link graph records)
- Context: Hatchdoor has only ever understood one way of linking notes, the wikilink
[[Title]]. Obsidian and a handful of other tools write that form, but it is not Markdown, and every other Markdown tool writes a note link as[text](path/To%20Note.md). Obsidian itself writes that form when its "Use [[Wikilinks]]" setting is off, and Notion's Markdown export writes it too. In Hatchdoor such a link rendered as a clickable anchor to a URL no route answers, and it was absent from backlinks, the Links panel, the graph, statistics and the agent link tools, so a vault written this way looked unlinked and navigated nowhere (#293). The reason for fixing it is a product one: Hatchdoor is meant to serve Markdown vaults whichever editor wrote them, and a vault that only works if its links use one tool's syntax is not that. The hard part is the link graph. Backlink counts and graph edges are things people and agents already read, and counting a second link form moves those numbers for any existing vault that happens to contain one. - Decision: A note link is either a wikilink or a Markdown link whose target, with any
#anchorremoved, ends in.md. Nothing else is a note link: a Markdown link to any other extension or to an external URL keeps its current meaning, and an image-syntax link to a.mdfile is left alone. Both forms are equal everywhere a note link is read or written.- Recognition. All three Markdown spellings count: inline
[t](p.md), angle-bracketed[t](<p.md>), and reference-style[t][r]with a[r]: p.mddefinition. Links inside fenced code and inline code are skipped, as wikilinks are. Links never cross Vaults. - Resolution. A Markdown target is a path, not a title, so it is resolved by the ladder attachments already use (
VaultIndex::resolve_asset): a leading/is Vault-root-relative, then relative to the linking note's folder, then as written from the Vault root, then, for a bare filename only, by name with the nearest match winning. It is deliberately not resolved by the wikilink rule, whose last-segment fallback would send../a/Plan.mdto whichever note titled Plan came first when two exist. Percent-escapes are decoded where%is followed by two hex digits; any other%is literal. - Counting. Markdown note links feed the same link records as wikilinks: outgoing links, backlinks, the Links panel, the graph, link statistics and the MCP link tools.
- Rendering. A resolved link navigates in-app like a wikilink, carrying a
#headingthrough with the same heading-slug rule; an unresolved one renders as the same broken-link affordance a missing wikilink gets. - Rewriting. Renaming or moving a note retargets Markdown links to it, keeping the author's form (relative stays relative, root-anchored stays root-anchored) and never touching the link text. Moving the note that contains Markdown links repoints them from its new folder, as its attachment references already are (#225). Deleting a note removes the link and keeps its text, because a Markdown link's text is the author's prose rather than the target's name. When Hatchdoor writes a path it encodes only what would break the link: whitespace and control characters,
%,#, and brackets or parentheses.
- Recognition. All three Markdown spellings count: inline
- Consequences: A vault written with Markdown links navigates, counts and survives reorganisation the way a wikilink vault always has, which is the point. The visible cost is that backlink counts, graph edges and link statistics rise for any existing vault that already contains Markdown links to
.mdfiles; that is the numbers becoming true rather than changing meaning, and there is no switch to keep the old count. A link written without the.mdextension stays unrecognised, the price of never guessing whether a target names a note or an attachment. Two resolution rules now coexist, title-based for wikilinks and path-based for Markdown links, and a change to one must not be copied to the other on the assumption they are the same. Every rewriter in the write path now has two syntaxes to keep in step, which is the most likely place for this to regress. Hatchdoor still writes new links as wikilinks; making it write in a vault's own style is a separate decision, not taken here. - Evidence: issue #293 (the failure, the triage decisions and the agent brief) and #302 for the unmatched-address pane it exposed;
src/vault/links.rs(extract_wikilink_targets,resolve_target_slug);src/vault/index.rs(resolve_asset, the ladder reused here);src/vault/paths.rs(normalize_link_target);src/vault/write/rewrites.rsandsrc/vault/write/assets.rsfor the rename, move and delete rewriters;frontend/src/components/note-page/wikilinks.tsandrenderers.tsxfor rendering; the Note link entry inGLOSSARY.md.
ADR-29 — A note is charted by its created date, and a date the author wrote beats any the machine infers
- Status: Accepted (applies ADR-01 to note dates; supersedes nothing)
- Context: The Stats page's six-month chart counted notes by file modification time. That clock does not survive the things a Vault routinely goes through. Git stores no modification times, so a clone, a restored container or a re-provisioned host stamps every file with the moment of checkout: a repository with three years of history came out with all 113 files dated to the same minute. A bulk rename stamped every note that linked to a renamed one until #299 put their times back, and #299 cannot help a clone. On the maintainer's 625-note Vault the chart read 630 notes in September and single digits in every other month. The real dates were in the repository the whole time, and many notes also carry a
createdproperty the author wrote. Four sources were measured on that Vault for the same chart (#300): modification time, thecreatedproperty, the commit that first added each note, and lines written per month. The obvious git analogue of modification time, the last commit that changed a note, was measured too and rejected. It still put 717 notes in September, because a link rewrite after a rename is a real content change as far as git knows, and Hatchdoor commits those rewrites in the same automatic commit as real edits, under the same author, so no filter can separate them. - Decision: The chart counts notes by created date (
GLOSSARY.md), the month a note first came into existence, which no rename, move, edit, clone or restore can move. Each note's created date is resolved in a fixed order. First, itscreatedproperty when it reads as a date: a date the author wrote is more deliberate than any the machine infers, and it is the only source that predates the repository for notes imported into one. A stated date keeps the calendar day as written, whatever zone it names, because that is the day the author meant. Second, for a Git-backed Vault, the author date of the commit that first added the note, following renames forward through the whole repository rather than only the Vault's folder, so a note moved in from elsewhere keeps its date. A note is the same note across a commit only when git's rename detection pairs the two paths; a note deleted and recreated, or a copy, is new. Third, the file's modification time, which is all a plain folder has. A shallow repository contributes nothing for the notes its graft point introduced, rather than dating them all to the graft. History is walked once per Vault on a background thread, started when the Vault's runtime comes up, held in memory with the commit it describes, and extended by only the new commits when the branch moves forward; a stats read waits at most two seconds for a walk in progress and never walks itself. A walk made while the repository was shallow is never extended, so fetching the missing history dates what it could not. A note one branch deletes and a merge keeps, or that a merge brings back, keeps its date, because it never stopped existing on the branch that won; the tree at the walked commit decides which notes exist. When git could not date a note that it should have, because the history is shallow, unreadable, or still being read, the stats response says so and the page shows a one-line notice under the chart. Everything that asks what changed recently (the week and month lists, the recently changed panel,recently_modified) stays on modification time, which #299 keeps honest for that question. The chart's wire field is renamed frommodified_counttocreated_count, with no alias. - Consequences: The chart survives a clone, and a vault's history reads the way it was written. It now answers "what did I start" rather than "what did I touch", so a month spent revising old notes looks quiet; a volume chart would answer the other question and is a separate decision. A plain folder without
createdproperties is no better off than before, and the notice deliberately does not fire for it, because nothing is missing that could be had. The cache is memory only, so every restart walks each Git-backed Vault's history again, and a stats read that arrives before a long walk finishes answers with the notice while the page asks again, up to twenty times. That is accepted in exchange for leaving the index build and its schema alone: the walk is disposable and rebuilds from the repository, as ADR-01 asks of every derived read. The rename ofmodified_countbreaks any script reading the old name, which a single-user self-hosted API can afford and a misleading name cannot. A future change must not chart by modification time or by last change in git, must not let git or the file override acreatedproperty, and must not walk history on the request path. - Evidence: issue #300 (the measurements and the triage decisions); #298 for the calendar window this feeds and #299 for the modification-time protection the recent lists rely on;
src/git/note_history.rs(the walk and its cache);src/vault_read.rs(statistics_detail,created_date,activity_window);src/api_types.rs(MonthActivity,CreatedDateStatus);frontend/src/components/StatsPage.tsx.
ADR-30 — A sync conflict is resolved on the Git host, through a recovery branch Hatchdoor publishes on request
- Status: Accepted (refines ADR-18; supersedes nothing, and every ADR-10 safety decision ADR-18 restates stays in force)
- Context: When a two-way Git turn cannot merge the remote into the local branch,
abort_mergerestores the checkout to the local commit, reportsmanaged_git_conflictwith the conflicting paths, and keeps local editing and local commits going. That is safe, and it leaves Hatchdoor's side of the conflict in exactly one place: the checkout on the server. A managed checkout lives under the instance state directory, inside a distroless image with no shell and no Git, so the only documented recovery was to reach the mounted volume from the host and run Git there as the image's user. An operator who resolves conflicts on their Git host, or who has no host access at all, could not see Hatchdoor's side, let alone merge it. ADR-18 also says a Git turn pushes the one configured branch and nothing else, so a fix that pushes anything more has to be recorded rather than slipped in (#80, triaged 2026-10-01). - Decision: An operator can ask Hatchdoor to publish its side of a conflict to a recovery branch (
GLOSSARY.md) and resolve it on the Git host like any other branch. The branch is namedhatchdoor-recovery/<configured branch>/<vault id>. The immutable Vault ID keeps it unique when several Vaults, or several Hatchdoor instances, share one repository, and keeps it stable across a Vault rename. Publishing happens only on an explicit request, never as a side effect of a failed sync: from the Vault's page, the matching HTTP route, and an MCP tool that is gated on write mode likesync_vaultand is not batchable. It is offered for any Vault in two-way mode, managed or existing checkout, while its Git status reports a conflict. Pull-only Vaults never push and cannot reach this state. A request is admitted through the work coordinator as a Git turn of its own, so it holds the Vault's mutation lock and never overlaps a sync or commit turn, and it reports its outcome through the Vault's status rather than on the request. The push is a fast-forward of the recovery branch to the local head and nothing else. It never force-pushes, never touches the configured branch, and never deletes a remote branch, including the recovery branch after the conflict is gone. When the remote's recovery branch holds commits the local head does not, because someone started resolving on it, the push is refused and the status says so; the refusal and any rejection by the remote (a token without rights to create branches, a hook) leave the Vault's conflict status as it was. Nothing new is needed to resume. The scheduler keeps trying on the Vault's interval after a conflict, and the first turn that finds the configured branch containing the resolved history merges cleanly and clears the failure. Notes listed in the conflict stay editable, and the note editor warns on them, since an edit made before the fix lands can conflict again on the same lines. - Consequences: A conflict becomes something the operator fixes with their usual Git host, their usual client, or an agent, with no access to the server. Hatchdoor now writes to a second branch on the remote, which a restrictive token or branch rule can refuse; that is reported, not worked around. A leftover recovery branch stays on the remote until someone deletes it, and the next conflict reuses it: its old head is already part of the configured branch, so the next publish is a fast-forward too. Edits made after a publish are not on the branch until the operator publishes again, which the status makes visible by naming the published commit. A future change must not publish without a request, must not rewrite or delete a remote branch, and must not run the publish outside a Git turn.
- Evidence: issue #80 and its triage notes;
src/git/managed_sync.rs(abort_merge,push, the refspec that names only the configured branch today);src/git/managed_task.rs(classify_sync_error, the scheduler's retry after a non-retryable failure); ADR-18 for the Git turn this adds a kind to, ADR-25 for the lock it holds. Implementation:src/git/managed_sync.rs(publish_recovery_branch,recovery_branch_name,push_refspec,ManagedSyncError::RecoveryDiverged/RecoveryRejected);src/git/managed_task.rs(run_managed_recovery_turn,run_existing_git_recovery_turn,CONFLICT_CODE);src/vault_work.rs(VaultWorkKind::Recovery);src/vault_executor.rs(dispatch_recovery_turn,plan_recovery_turn,finish_recovery_turn, and the clearing inpublish_managed_git_turn_outcome);src/vault_runtime.rs(RecoveryBranchStatus,VaultCapabilities::publish_recovery);src/vault_management.rs(publish_recovery);POST /api/v1/vaults/{vault_id}/recovery-branchand the MCP toolpublish_recovery_branch;frontend/src/features/settings/VaultSettingsIndex.tsx(RecoveryBranchPanel) andNotePage'sSyncConflictNotice. One implementation choice the decision above does not name: admission refuses an ineligible Vault with the existingcapability_unavailablecode rather than a code of its own, so clients handle it like every other refused Vault control.
- Status: Accepted. Supersedes the clause of ADR-18 "scheduled through the coordinator with no second execution lane" and the clause of ADR-23 "so there is still one execution lane per Vault and no second scheduler". Every other ADR-18 and ADR-23 decision, and every ADR-10 safety decision ADR-18 restates, remains in force. The words "exactly as today" in decision 1 are superseded by ADR-35: indexing keeps one lane, but an Index turn may now pause and rejoin it.
- Context: All expensive background work runs through one instance-wide FIFO worker that finishes each turn before it starts the next: Index turns with their embedding, Git sync turns, commit turns, recovery turns and repair. That was chosen for simplicity when the collection runtime landed (#70), and #81 was filed to revisit it once a measurement showed the delay mattered. The measurement, taken during the triage of #81 on 2026-10-01: a local instance on a 4-core VM served two Vaults, a 759-note Vault (7 MB of Markdown, 4,092 chunks) being indexed for the first time and a 49-note Local history Vault. The large Vault's Index turn read its notes in 1.5 minutes and then estimated about 2 hours of embedding at roughly 30 chunks a minute. An edit saved to the small Vault was still uncommitted 33 minutes later, when the run was stopped; on that rate it would have waited over 2 hours. Its own first Index turn waited the same way, so it could not be searched either. Nothing in either Vault's status said why. Embedding speed varies with hardware, but the shape does not: every other Vault waits for the full length of the slowest Index turn, and adding a large Vault or changing the search model starts one. ADR-23 made commits run on every burst of writing rather than once a day, so this wait now lands on routine saves. A Vault's history and its remote copy fall behind silently, which costs data safety; a slow search costs only time, and the user can see it.
- Decision: Git work and indexing are admitted separately.
- Indexing keeps one instance-wide lane. Index and Repair turns run one at a time, FIFO, across all Vaults, exactly as today. Indexing is CPU-bound and the embedder already serializes inference, so a second indexing lane would buy nothing without a larger change.
- Git work runs per Vault. Git sync, Commit and Recovery turns for one Vault never wait for any Index turn, and never wait for another Vault's Git work. A Vault's own Git turns still run one at a time, in FIFO order, with today's coalescing.
- At most four Vaults run Git work at once. The cap is a fixed constant, not a setting (ADR-14). Git work is network- and disk-bound, so a few side by side costs little, and the cap stops a burst of due syncs, or several Git Vaults added together, from swamping a small machine. A Vault beyond the cap waits for a slot, not for indexing.
- The same-Vault guard is the existing write lock. No new working-tree gate is added. An Index turn holds the Vault's mutation lock only while it reads Markdown, and a sync turn holds it for its whole blocking duration and counts as a mutation (ADR-25). On one Vault, a sync therefore cannot rewrite notes while an Index turn is reading them, and an Index turn whose embedding overlapped a sync publishes its generation Stale; the sync's success requests one coalesced follow-up Index turn, which reuses the vectors already embedded. A sync waits at most for its own Vault's read phase, never for embedding.
- Lifecycle waits for both. Disabling, removing, reconciling or shutting down a Vault stops new work in both places, discards queued work in both, and waits for the safe boundary of whatever that Vault has running in either. There is still no forced cancellation and no generic timeout.
- Consequences: The promise a multi-Vault user gets is narrow and checkable: saving and syncing one Vault never stalls because another is indexing. Search fairness is not part of it. A small Vault's first Index turn can still wait hours behind a large one's embedding; that is tracked separately, together with the finding that an interrupted Index turn discards every vector it computed, because a partial build lives in an in-memory candidate cache that is published only on completion. A sync on a Vault mid read phase now waits for that read phase (about a minute for a large Vault on slow hardware), which is the one same-Vault delay accepted in exchange for not splitting today's sync into separately locked phases. Lock ordering stays simple because no Git turn or Index turn ever takes two Vaults' locks; ADR-25's sorted acquisition remains the only multi-lock rule. A future change that wants fetch and push to run during a read phase, a second indexing lane, or a configurable cap needs its own record.
- Evidence: issue #81 and its triage notes; issue #70 for the original single-FIFO contract. Today:
src/vault_work.rs(VaultWorkCoordinator,VaultWorkWorker::run_next,VaultWorkKind);src/vault_executor.rs(dispatch_vault_index_turn_with_embed_layerstakes the mutation lock for the read phase only and retakes it to publish;run_planned_turnholds it for a Git turn; the successful-sync path requests a follow-up Index turn);src/vault_runtime.rs(acquire_mutationcounts a mutation,blocking_retake_mutation_for_indexcompares generations);src/cache/vault_snapshots.rs(the in-memory candidate cache andpublish_vault_candidate);src/embed/fastembed_embedder.rs(inference behind oneMutex).
- Status: Accepted (#303). Supersedes ADR-27, whose transfer-link rules this record keeps whole and widens on the upload side to notes. ADR-27's text stays as the record of #310. Its Address rule is superseded by ADR-34.
- Context: An agent has no way to turn a Markdown file already on its disk into a note without reading it and re-emitting every byte through
create_note. Every upload route takes images and PDFs only and creates an attachment. Retyping pays for the content twice in tokens and depends on the model transcribing it faithfully. On 2026-09-09 an import of six research files (3,459 lines, 416,264 bytes) read one of them in bounded chunks that stopped at line 594 of 599. Five items were never written, nothing errored, and the hole was found only by diffing the Vault's Git mirror against the source files (#303). ADR-27 already lets an agent send a local file with neither the token nor the model in the path, but only as an attachment. Two alternatives were rejected. A file-path argument oncreate_notecannot work, because the server cannot read the agent's disk. A separate note-upload tool would only be found aftercreate_upload_link, the tool an agent holding a file already reaches for, refused the.mdfile. - Decision: ADR-27's transfer link stands with every part (scope, lifetime, revocation, allowance, address, secrecy) unchanged, except that an upload link may now target a note.
- Note or attachment.
create_upload_linkdecides by the target. A relative path ending in.mdmints a note upload; any other path mints an attachment upload under the existing extension list. An uploaded.mdfile is always a note and never an attachment. - Same write. A note upload is the note write
create_noteperforms, with the uploaded file as its content, through the mutation core andvault/write(ADR-03, ADR-19). It gets the same refusals (not UTF-8, a NUL byte, a layer marker or noise path), the same line-ending and final-newline normalisation, the same quality warnings, and the same indexing and commit. Hatchdoor does not store the bytes verbatim, so one definition of a valid note holds however the note arrived. - Replacing. An upload replaces an existing note only when the link was minted with replacing allowed, as for attachments. A replacing note link also carries the note's expected content hash, fixed and signed into the link at minting. Minting refuses a replacing note link without one, and redemption refuses with the same conflict
update_notereturns when the note no longer has that hash. No link replaces a note blindly. - Size. A note upload is capped by
HATCHDOOR_MAX_ATTACHMENT_BYTES, like every upload. There is no separate note setting. - Answer. A note upload answers with what a note write answers: the note's slug, relative path, new content hash and quality warnings, so the next replace can chain from it.
- Who. This is for agents. The web UI's attachment drop keeps refusing Markdown; importing a file through the browser needs its own decision.
- Note or attachment.
- Consequences: An agent moves an existing Markdown file into a Vault with one tool call and one HTTP request, and the content never passes through the model, so a long file cannot be cut short in transcription. A re-import cannot silently overwrite edits made since the agent last looked, at the cost of one
get_frontmattercall to fetch the hash. An uploaded note can differ from its source in line endings and a final newline, and its warnings say so, so a byte diff against the source has to allow for both. The upload link carries one more signed field, which is security-relevant code. Any future change that lets a link replace a note without its hash, stores an uploaded note without the checkscreate_noteapplies, or makes a non-.mdtarget a note breaks this decision. - Evidence: issue #303 and its triage; ADR-27 and #310 for the transfer link;
create_note, andupdate_notewith itsexpected_content_hash, in the MCP write tools;get_frontmatter, which returns a note's content hash without its body; ADR-22 and #316 for why a note keeps one line-ending style.
- Status: Accepted, implemented in #357. Takes the decision ADR-28 left open ("Hatchdoor still writes new links as wikilinks").
- Context: Since ADR-28 Hatchdoor reads a Markdown note link as readily as a wikilink, but every link it inserts is still a wikilink: editor autocomplete inserts
[[Title]], and pasting, uploading or dropping a file inserts![[path]]. In a vault whose author chose Markdown links, usually so other tools can read it, each insert adds a link those tools cannot follow, and the vault drifts into two styles. Agents make it worse: nothing tells them a vault's style, so they write wikilinks everywhere, and in practice they write more new links than the editor does. Four ways to know a vault's style were weighed. A per-Vault setting is predictable but adds a stored field, anedit_vaultchange and a settings control, and goes stale when the author flips the switch in Obsidian. Always writing Markdown links imposes a style on every wikilink vault, which is every vault today. Counting the vault's existing links needs no setup but guesses. Obsidian already records this exact choice inside the vault, in.obsidian/app.json(useMarkdownLinks, andnewLinkFormatfor the path form), and writes a key there only once it differs from Obsidian's default. - Decision: A vault's link style is read from the vault each time it is needed, never configured in Hatchdoor.
- Style. If the vault has Obsidian's
.obsidian/app.json, itsuseMarkdownLinksdecides, and a missing key means wikilinks, Obsidian's default, so Hatchdoor and Obsidian never add different styles to one vault. Otherwise the style is whichever form most of the vault's existing note links and attachment embeds use. No links, or an exact tie, means wikilinks. - Path form. A Markdown link's path follows Obsidian's
newLinkFormatwhen the vault has.obsidian/app.json(a missing key means Obsidian's default, shortest), and is relative to the linking note otherwise, the one form every Markdown tool follows. - What follows it. Every link Hatchdoor inserts where there was none: editor autocomplete, which in Markdown style inserts
[Title](path.md)with the note's title as the link text, and the attachment inserts (paste, upload, drop), which insert. One style covers note links and embeds, as Obsidian's one switch does. - Agents. The Vault shape returned to agents and the HTTP API carries the vault's link style and path form, so an agent can write matching links. Hatchdoor never rewrites the text an agent sends into the vault's style.
- Style. If the vault has Obsidian's
- Consequences: A Markdown-link vault keeps one link style when edited through Hatchdoor, with nothing to configure, and an Obsidian user who flips the switch in Obsidian sees Hatchdoor follow. The cost is a guess on vaults Obsidian never opened: a vault split close to evenly between the two styles can flip as notes change, and nobody can correct a wrong guess, because there is no override. Hatchdoor now reads one file inside
.obsidian/, which it otherwise treats as noise, and only reads it. An agent that ignores the reported style still writes wikilinks, by design. Reading, rewriting and removing existing links is unchanged and stays ADR-28's. If a vault the rule gets wrong turns up, the remedy is a per-Vault override whose default is this rule, recorded in a superseding ADR, not a change to the rule's order. Two consequences of the implementation (#357): without.obsidian/app.jsoneach Vault listing walks the Vault and reads every note changed since the last listing, keeping per-note counts in memory, because the cache's link records carry no form and adding one would mean a cache rebuild; and the note page now resolves a Markdown imagethrough the attachment ladder (resolve_asset), as it already did![[...]], so the root-anchored and bare-name paths these inserts can write render. Image syntax still never counts as a note link. - Evidence: issue #357 and its triage; ADR-28 and #293 for reading both forms; editor autocomplete (
applyWikilinkSelection) and the attachment inserts (insertAttachmentAtCaret,insertEmbedAt) in the frontend; the Vault shapelist_vaultsreturns; the Link style entry inGLOSSARY.md.
-
Status: Accepted (#358). Supersedes only the Address rule of ADR-32 (inherited from ADR-27); every other transfer-link rule stands.
-
Context: ADR-27 builds a transfer link on the public-address setting when one is set, and otherwise on the scheme, host and port the minting MCP request arrived on. Hatchdoor serves plain HTTP, so an arriving request is always
http, and behind a TLS-terminating proxy every inferred link starts withhttp://even though the agent reached the server overhttps://. ADR-27 named this "a correctness hole with a one-field remedy". In practice the hole costs more than one field. On 2026-09-30 an agent fetched a PDF from an instance behind openresty with no public address set. The proxy answered thehttp://link with a 301,curl -o, the example the tool response itself gives, saved the 166-byte redirect page as the PDF and exited 0, and the agent noticed only when text extraction failed. A client that follows the redirect instead sends the signed link across the network in clear text first (#358). Most proxies already tell the server the client's scheme and host inForwarded(RFC 7239) orX-Forwarded-ProtoandX-Forwarded-Host, and Hatchdoor ignored both. Theget_attachmentdescription also told agents the link used "this MCP endpoint's scheme", which was never true behind a proxy. -
Decision: A transfer link's absolute address is chosen in this order, per minting request:
- The public-address setting (
HATCHDOOR_PUBLIC_URL, Public address in Settings) when set. It always wins, and stays the remedy for a proxy that sends no forwarded headers or mounts Hatchdoor under a path prefix. - Otherwise the request's
Forwardedheader: theprotoandhostparameters of its first element. - Otherwise
X-Forwarded-ProtoandX-Forwarded-Host, each taking its first comma-separated value. - Otherwise
httpand theHostheader (or an HTTP/2 request's authority), as before.
Scheme and host are resolved independently down that list, so a proxy that forwards only the scheme still keeps the arriving
Host. A scheme other thanhttporhttps, or a host that does not parse as an authority or carries credentials, is ignored and the next source is used. A malformed header never fails the tool call. The headers are trusted from any sender, with no trusted-proxy list, for the reason ADR-27 already gave forHost: the link goes back only to the caller who sent them, so a forged header misleads nobody but the forger. Nothing else in Hatchdoor reads these headers, and this record does not make them meaningful anywhere else (origin checks, logging, rate limiting). Tool descriptions and user docs describe the address as the public address if set, else the address the client reached the server on as the proxy reports it. - The public-address setting (
-
Consequences: An instance behind a proxy that sends the standard headers (Caddy, Traefik and Nginx Proxy Manager do by default; plain nginx and openresty need
proxy_set_header) mintshttps://links with nothing to configure, and the silent wrong-file download goes away for it. A proxy that sends neither header, or forwards a wrong one, still produces a wrong link, and the remedy is still the public address, which the install guide now has to mention for proxied installs. Reading two more request headers is small, security-adjacent code. Any future change that lets these headers affect anything other than a transfer link's address, or lets them override a configured public address, breaks this decision. -
Evidence: issue #358 and its triage; ADR-27 and ADR-32 for the transfer link;
request_origininsrc/mcp/adapter.rs, which hardcodedhttpbefore #358;McpConfig::link_baseinsrc/mcp/config.rs; theget_attachmenttool description insrc/mcp/tools/read.rs; RFC 7239.
- Status: Accepted. Decisions 1 and 2 are implemented in #382, decisions 3 to 5 in #383. Supersedes the words "exactly as today" in decision 1 of ADR-31. ADR-31's single instance-wide indexing lane, its Git lanes and every other decision stand.
- Context: ADR-31 freed Git work from indexing and deliberately left search fairness out. The measurement that motivated it, taken on 2026-10-01 on a 4-core VM, still applies to indexing: a 759-note Vault (4,092 chunks) indexed for the first time read its notes in 1.5 minutes and then estimated about 2 hours of embedding at roughly 30 chunks a minute, and a 49-note Vault added alongside it could be neither browsed nor searched for that whole time, because its first Index turn queued behind the large one. Two facts in the code shape the fix. First, an Index turn builds into an in-memory candidate cache, seeded from the Vault's last searchable generation and copied to disk only when the whole build finishes, so an interrupted turn discards every vector it computed: a restart at 90% of a two-hour first build starts from zero, on a single-Vault instance too. Second, two Index turns cannot embed at once: the embedder serializes inference behind one mutex, and a process-wide model-epoch lock spans a whole candidate build and publish. Three directions were weighed: saving progress alone, saving progress and slicing long turns so they yield, and running Index turns for several Vaults concurrently.
- Decision:
- Embedding progress is saved as it is made. Vectors an Index turn computes are written to disk in the disposable cache as the turn goes, and a later turn for the same Vault and the same search model reuses them by content, as it already reuses a published generation's vectors. A restart, a crash or a pause therefore resumes instead of starting over. Saved progress is disposable like the rest of SQLite (ADR-01): losing it costs time, never data. A search-model change discards it. Removing a Vault deletes it; disabling a Vault keeps it.
- Saved progress is not searchable. A Vault stays all-or-nothing for search: it becomes searchable only when every chunk has a vector, exactly as now, and until then a Vault that had a searchable generation keeps serving it, marked stale. A result set never silently omits the part of a Vault that has not been embedded yet.
- A long Index turn takes turns. After about five minutes of embedding, an Index turn checks whether another Vault's Index or Repair turn is queued. If one is, it stops at the next chunk boundary with its progress saved, and its Vault rejoins the back of the indexing queue; it resumes from its saved progress when its turn comes round again. If nothing is waiting it carries on without pausing, so a single-Vault instance never pays for this. The five minutes is a fixed constant, not a setting (ADR-14), and it is measured in time, not chunks, so the bound on a waiting Vault holds on any hardware. Resuming re-reads the Vault's Markdown, about 1.5 minutes for the large Vault above; that overhead is accepted while another Vault is waiting, and if it hurts the fix is a cheaper re-read, not a longer slice.
- The queue stays first come, first served. A paused Vault goes to the back, behind everything already queued, and nothing jumps ahead of anything else. One Vault embeds at a time; Index turns for several Vaults never run concurrently.
- A waiting Vault says so. A Vault's status, in the web UI and over MCP, distinguishes an Index turn that is embedding from one that is waiting for its turn. The progress percentage survives pauses and restarts, and the time estimate counts embedding time only, so a paused Vault's countdown does not look frozen.
- Consequences: On the measured case, the 49-note Vault becomes browsable and searchable within about five minutes of being queued instead of after two hours, and an interrupted first build loses at most the chunk in flight. The large Vault finishes later while others are waiting, by roughly a quarter on the measured hardware, and is no slower when nothing is. CPU and memory stay where they are, which matters most on the small hosts where the wait hurt most. The large Vault itself still cannot be searched until it is fully embedded; partial search was rejected because a result set that silently skips unembedded notes is wrong in a way the reader cannot see. The status change is externally observable and goes through the interface-change checklist. A change that wants partial search, concurrent embedding, a priority order, or a configurable slice needs its own record.
- Evidence: issue #375 and its triage; ADR-31 and issue #81 for the lanes. Today:
src/cache/vault_snapshots.rs(replace_vault_snapshot_with_embed_layers_and_progressbuilds an in-memory candidate seeded byseed_candidate_from_snapshotand holdssnapshot_model_epochacross build and publish;publish_vault_candidateis the only write to disk);src/embed/fastembed_embedder.rs(inference behind oneMutex);src/vault_work.rs(the indexing FIFO);src/vault_runtime.rs(VaultRuntimeSnapshot,VaultPhase,set_indexing);src/startup.rs(IndexingProgressSnapshot).
- Status: Accepted.
just release-prepareis implemented in #402,just release-publishin #403, and the runbook and theAGENTS.mdapproval rule in #404. v2.7.0 is to be the first release cut this way. Decisions 3 and 5 are superseded by ADR-37 only where they name the release pull request: the checklist lives on the version-bump pull request, andrelease-publishreads it there. Decision 1 is superseded only on when the draft GitHub Release is created, which is now beside the version-bump pull request. Every other decision, and every check decision 5 makes, stands. ADR-42 adds one refusal to decision 2, implemented in #424:release-preparerefuses until the release's What's new highlights have 3 to 6 lines. ADR-45 makes one deliberate exception to keeping private infrastructure out of public artefacts: the usage report's collector host name is public, in the source and the docs. #486 amends decision 7 with one more duty for the hook'simagesstep: after the image tags are in place it publishes the Docker Hub overview and short description fromdocs/maintenance/docker-hub/overview.mdanddocs/maintenance/docker-hub/short-description.txt, read from the tagged commit. The contract keeps its two steps, and the public commands still hold no Docker Hub credentials and make no Docker Hub calls. Note of 2026-11-12 (#705): the attestation manifests the context below gives as the reason for two builds no longer matter. The release build now pushes Docker v2 manifests with none, and the image has never carried aHEALTHCHECKfor Podman to drop: the health check is the Compose file's, which Docker and Podman both apply. Soimagesbuilds once and publishes the same image under all four tags of decision 8; thepodman-tags stop after the third release that follows the first single build. The context is left as it was written. - Context: Every release so far was assembled by hand from
docs/maintenance/release-runbook.md, and the hand steps drifted. Docker Hub carriesv2.3.0beside2.4.0andpodman-v2.4.0besidepodman-2.5.0. The v2.6.1 Podman tags on Docker Hub were copied from the movingpodman-latestinstead of the fixed version. The README's publishing section still describes a single-architecturedocker build. Nothing updates the servers that run release images, so they keep the previous version until someone pulls by hand. A release publishes four images: a Docker BuildKit build and a Podman build, each for amd64 and arm64, as a multi-archX.Y.Z/latestpair and apodman-X.Y.Z/podman-latestpair. The two pairs are separate builds, not copies: the BuildKit pair carries attestation manifests the Podman pair does not, and Podman users are told to pull thepodman-tags. Some steps are generic (version files, changelog, checks, the release pull request, the git tag, the GitHub Release). Others depend on the maintainer's own infrastructure: the build machines, an internal registry, and the deployment configuration of the servers that run releases. This repository is public, and that infrastructure is not documented in it. Releases are carried out by an agent; the maintainer's only release task is approving the release notes. The agent works through the maintainer's GitHub account, so no GitHub permission can tell the two apart. Three homes for the pipeline were weighed: a command run on the maintainer's build machine, GitHub Actions, and a self-hosted Actions runner. - Decision:
- Two commands, run on the maintainer's build machine.
just release-prepare <version>opens a pull request intodevelopmentthat sets the version inCargo.toml,Cargo.lock,frontend/package.jsonandfrontend/package-lock.jsonand renames the changelog's## Unreleasedheading to## v<version> - <date>. Once that merges, it opens thedevelopmenttomainrelease pull request and creates a draft GitHub Release from the changelog section.just release-publish <version>does everything from the merge on, including the merge itself. Hosted CI plays no part. - Prepare refuses on any mechanical failure. It refuses unless the four version files agree, the version is higher than the last release, the changelog section is not empty, every
[#N]reference in it has a link definition, andjust check-fullpasses. The documentation freshness review is not mechanical:just docs-freshness mainnames the notes the whole release touched, and reading them is a judgment check (decision 3). - Judgment checks are tick boxes the agent must complete. The release pull request lists the checks only a reader can make: the changelog lists everything that shipped, the README describes what shipped, the roadmap is current, the notes named by
just docs-freshness mainwere read and the review recorded withjust docs-freshness-ack main, no ADR is contradicted, an MCP conformance run is recorded when MCP behavior changed, and the release title and notes are drafted. The agent does this review and ticks the boxes.release-publishrefuses while any box is unticked. - Only the maintainer approves the release notes, in the agent's session. After its review, the agent drafts the GitHub Release title and notes, gives the maintainer the draft, and stops. It runs
release-publish, which merges the release pull request, only after the maintainer replies "approved" to that draft in the same session. A resumed or new session that cannot see that reply in its own conversation asks again, and so does a session whose title or notes changed after the reply. This is a rule the agent follows, not a check the script makes; it is stated inAGENTS.mdand the runbook. - Publish refuses a release that drifted after prepare. Before it merges, and only then, it refuses if
developmenthas any entry under## Unreleased, or if the tip ofdevelopmentis anything other than the merge commit of the version-bump pull request. A change merged intodevelopmentduring review therefore cannot ship under a version whose changelog does not list it. Because nothing follows the bump, the merge brings intomainexactly what prepare tested, and publish does not run the tests again. - The order is tag, images, announcement, deployment.
release-publishpushes thev<version>git tag, calls the private hook'simagesstep, publishes the GitHub Release, then calls the hook'sdeploystep. The release goes public once the images are on Docker Hub; a failure while deploying to the maintainer's servers does not hold it back. - Private infrastructure lives behind a hook outside this repository. The public commands know only a hook named by
HATCHDOOR_RELEASE_HOOK(amended by #617: exported, or set in the git-ignored.release.envat the repository root, the environment winning), called as<hook> images <version>and<hook> deploy <version>, and refuse with a clear message when it is unset or missing.imagesbuilds and pushes the four images to the internal registry and copies them to Docker Hub from the fixed version tags, never from a moving one. Amended by #705:imagesbuilds one image, run by both Docker and Podman, and publishes it under the four tags with one digest; thepodman-tags are a second name for it until the third release after v2.10.0. Amended by #486: it then publishes the Docker Hub overview and short description from the two files underdocs/maintenance/docker-hub/at the tagged commit; publishing the same text twice changes nothing, and a failure fails the step, so the release stays a draft and a re-run retries.deploypins the servers that run releases to the new version in their own deployment repository, runs that repository's validation, and pushes it, which deploys. Because the agent runsrelease-publishonly after the maintainer's approval (decision 4), that approval is also the authorization for this push. It refuses when the deployment checkout holds any change other than its own pin for this version, waits until each server reports the new version, and on failure prints the exact revert that rolls the pin back. The hook and everything it names live in the maintainer's private repository. - Image tags carry the bare version; the git tag keeps the
v. Both registries useX.Y.Z,latest,podman-X.Y.Zandpodman-latest. Only the git tag and the GitHub Release usevX.Y.Z. Tags already published keep their spelling. - A published version is never overwritten. Re-running
release-publishresumes from the first step not yet done. A step that finds its result already in place, such as a Docker Hub tag pointing at the same image digest it would copy, skips it; a step that finds a different image under the version refuses. Nothing ever replaces the image behind a published version; a broken release is fixed by releasing the next patch version.
- Two commands, run on the maintainer's build machine.
- Consequences: The maintainer's part of a release becomes reading and approving one draft. Tag spelling, the copy from a fixed tag, and server updates stop depending on memory. A release can only be cut where the hook and the registry credentials exist, so contributors cannot publish one; that is intended. The approval gate rests on agent instructions, so nothing on GitHub records when the notes were approved; a recorded approval needs its own record. The release commands span two repositories, and a change to the hook's two-step contract changes both. Replacing the build machine with hosted CI, allowing a forced republish of a version, or letting a release go public before its images exist needs a superseding record.
- Evidence:
docs/maintenance/release-runbook.md(the hand procedure this replaces);.github/workflows/release-source.yml(onlydevelopmentmerges intomain);CHANGELOG.md(## Unreleased); the Docker Hub tag list forbattermanz/hatchdoor; README section "Container Image And Paths" and its out-of-date publishing commands.
- Status: Accepted; implemented in #408. Supersedes ADR-36 decisions 3 and 5 only where they name the release pull request, and decision 1 only on when the draft GitHub Release is created; every other ADR-36 decision stands.
- Context: ADR-36 put the judgment checklist on the
developmenttomainrelease pull request, whichrelease-prepareopens only after the version-bump pull request has merged. From then on decision 5 makesrelease-publishrefuse if anything else merges intodevelopment. A stale note, README section or roadmap entry found by the review therefore could not ship in the release it was found for. The runbook worked around this by asking for the review before the bump and for a stop to ask the maintainer when something turned up later, which is discipline standing in for a mechanism. Loosening decision 5 to admit "release fix" pull requests was rejected: it reopens the window in which a change can ship under a version whose changelog does not list it. - Decision:
- The checklist lives on the version-bump pull request.
release-prepareopens the version-bump pull request with the ADR-36 decision 3 checklist, including the output ofjust docs-freshness maintaken on the bump branch, and creates the draft GitHub Release in the same step. The checklist items and their wording do not change. - A fix the review needs goes onto the bump branch. The agent commits it to
docs/release-v<version>and runsrelease-prepareagain. While the bump is open, that run opens nothing new: it checks the branch again, runsjust check-fullon the new commit, and pushes it. The fix merges with the bump, so what reachesmainis still what prepare tested. - The release pull request is mechanical. After the bump merges,
release-prepareopens thedevelopmenttomainrelease pull request with no checklist; its body links the version-bump pull request. release-publishreads the checklist from the merged version-bump pull request. It refuses while any item there is missing or unticked. Decision 5's checks are unchanged: before merging, it refuses if## Unreleasedondevelopmenthas entries or if the tip ofdevelopmentis anything other than the bump merge.- Approval is unchanged. The maintainer's approval of the release title and notes (ADR-36 decision 4) still gates
release-publish.
- The checklist lives on the version-bump pull request.
- Consequences: A late doc fix ships in the release that found it, with no extra pull request and no change to the drift checks. The bump pull request now stays open for the whole review. A pull request merged into
developmentin that time rides into the release with the bump merge, which decision 5 cannot see, so nothing else merges intodevelopmentfrom the moment the bump branch is cut.release-preparetrusts that a bump branch already on the remote at the local commit passedjust check-full, so the bump branch must be pushed only throughrelease-prepare; a hand push skips the test run. Changing the checklist's home again, or letting anything but the bump branch carry a change into a release after prepare, needs a superseding record. - Evidence: issue #408;
scripts/release-prepare.mjs,scripts/release-publish.mjs,scripts/release-common.mjs;docs/maintenance/release-runbook.md.
- Status: Accepted (#420), from the resolution of #416 and its addendum. Adds a fourth surface beside ADR-02's three, in the same binary, and builds on ADR-08 and ADR-09 without amending them.
- Context: Hatchdoor's manual is the Obsidian-style folder
docs/user-vault. A reader finds it on GitHub or on a separate instance that serves it as a Vault, and both copies follow the repository, not the version the reader runs. A beginner who is stuck has nowhere inside Hatchdoor to look, and an agent helping them cannot read the manual for the version in front of it. Agents need it most during model setup, which is exactly when the Vault tools refuse. Serving the manual as an ordinary Vault was rejected: it would show up in note search, the graph, stats and the Vault list beside the user's own notes, and it would need the index and the embedding model before anyone could read it. - Decision:
- Bundled per version.
docs/user-vaultis bundled into the binary at build time, so every install carries the manual for its own version. - Help, never a Vault. The bundled manual never appears in note search, the graph, stats, Vault lists or the Vault registry.
- People read it in a Help panel that works signed out. Signed out, Help serves the bundled manual and nothing else: no Vault names, no settings.
- Agents read it through two read-only MCP tools.
read_docsreturns the index when called with no argument, and one page as Markdown, with links resolved to page names, when given a page name.search_docsreturns the best-matching pages with excerpts. Both follow ADR-09: MCP must be enabled and the call carries the MCP token. They work with or without write mode, take no Vault, sit outside the Vault read catalogue andbatch, and stay available while model setup is pending. Both MCP instruction variants, the normal one and the setup one, point agents to them. - Public plain Markdown. Every instance serves the bundled manual as plain Markdown at public, unauthenticated addresses outside
/api/, with wikilinks rewritten into real links, plus anllms.txtindex. These addresses never serve Vault content, settings or tokens. - No public route reveals the instance's version. A manual page can be marked private. The What's new page (ADR-42) is private, because its top section names the running version. A private page is kept off the public addresses: there it is served only with the web token (ADR-08), and it never appears in
llms.txt, the index or public search. Signed-in Help and the MCP tools still serve it. - Docs search is plain word matching, with no embedding model. Help and
search_docstherefore work before any model has downloaded. The Help search box uses the same search.
- Bundled per version.
- Consequences: The manual a reader sees always matches the binary they run, and an agent can help a beginner before any Vault exists or any model has finished downloading. The binary grows by the size of the manual, and a fix to the manual reaches an install only with its next release. The public addresses stay open even when a web token is set, so their boundary is fixed: the bundled manual, minus private pages, and nothing else. Word matching ranks a paraphrased question worse than semantic search would; that is accepted because Help must work before setup finishes. Serving anything but the bundled manual at the public addresses, revealing the version on a public route, or making Help or the docs tools depend on a Vault or the embedding model needs a superseding record.
- Evidence: issue #416 (resolution, section A, and the addendum on docs tools during model setup and on What's new); #421 (bundle and MCP tools), #422 (public Markdown), #417 (Help panel). Today:
docs/user-vault;SERVER_INSTRUCTIONSandSETUP_INSTRUCTIONSinsrc/mcp/config.rs, chosen bymodel_setup_pendinginsrc/mcp/adapter.rs; the model-setup gate inhandle_tools_callinsrc/mcp/tools/mod.rs.
- Status: Accepted (#420), from the resolution of #416 and its addendum. Applies ADR-13 to the one new outbound request. ADR-45 adds a second opt-in request beside this one, the usage report, with its own setting; every decision here stands. The context's sentence listing the outbound requests Hatchdoor makes is out of date, and ADR-45 decision 12 gives the list as it stands.
- Context: An install learns about a new release only if its operator goes looking, so most installs run old versions without knowing it. Hatchdoor otherwise makes outbound requests only to download a search model and, for Git-backed Vaults, to reach the configured remote. A check that phoned home by default would be a new, unannounced request from every install, and would tell a third party which instances exist and what they run.
- Decision:
- Opt-in, off by default. A setting turns the check on. It is offered in the first-run checklist, and like every setting it follows ADR-14.
- One request a day, to GitHub's public latest-release API for this repository. No key. The request sends the user-agent
Hatchdoorwithout a version, and nothing about the instance travels beyond what any web request carries. The setting's documentation says exactly that. - The result only feeds a banner. The banner shows the newer version, a "What's new" link to the GitHub release page and a "How to upgrade" link into Help. Hatchdoor never upgrades itself.
- Not in demo mode. A demo instance never runs the check.
- The client is
ureq. It is already compiled into every build throughhf-hub, which downloads the search models with it (hf-hubfeaturesureqandnative-tls). Using it directly adds a direct dependency but no new crate to the build, which keeps the dependency set as lean as ADR-13 wants it. A second HTTP client would not earn its place.
- Consequences: An operator who opts in hears about a release within a day, and one who does not sees no change and no traffic. GitHub sees the instance's IP address once a day, which the setting's documentation states.
ureqbecomes a direct dependency, so a futurehf-hubthat drops it leaves this check holding it alone. Checking by default, sending the version or any instance detail, or upgrading automatically needs a superseding record. - Evidence: issue #416 (resolution, section B, and the addendum on the update-check request); #425. Today:
hf-hub = { ..., features = ["ureq", "native-tls"] }inCargo.toml, andureq3.3.0 inCargo.lock.
- Status: Accepted (#420), from the resolution of #416 and its addendum. Removes the legacy single-Vault import (#82) that ADR-18 left in place for first boot. Applies ADR-07 to one new startup refusal. Narrows a consequence of ADR-14. Decisions 1 to 4 are implemented in #427. Decision 6, the instance-state record, is implemented in #424.
- Context: On first boot Hatchdoor registers the mounted folder as a Vault by itself and, when it holds no Markdown, writes starter notes into it. A beginner therefore opens on a Vault they did not choose, filled with notes they did not write, sometimes in a folder they meant for something else, and the starter notes are copied into the user's own files where they outlive every upgrade. The same first-boot path carries the legacy single-Vault import, which converted 2.4.x deployments to the Vault registry in 2.5.0 and has had nothing to convert on any install that has run a 2.5.0 or later release. A first-run checklist and a folder picker (ADR-41) replace both as the way a beginner gets set up. Upgrades also need to know which version ran before, to show what changed (ADR-42), and nothing records that today.
- Decision:
- Zero Vaults on a fresh install. A deployment with no registry starts with an empty one, whatever
VAULT_PATHholds and whether or not it is set. The mounted folder is no longer registered as a Vault by itself. - The legacy single-Vault import adapter is removed (#82). Direct upgrades from 2.4.x or earlier are unsupported; those installs upgrade to a 2.5.0 to 2.7.x release first. The import's
legacy_migration_requiredrecovery and its confirmed Start with no Vaults action go with it; decision 3 is what an unconverted install meets instead. - An unconverted old install refuses to start. When no registry exists but stored settings still carry the retired single-Vault keys, startup refuses with a message naming the migration document, instead of opening silently on zero Vaults (ADR-07).
- The retired Git-lane keys are still purged at startup. The purge that keeps a plaintext Git token from surviving in stored settings stays.
- Starter notes are no longer written into any folder. Existing installs and their Vaults are untouched, and notes already seeded stay where they are.
- The server keeps a small instance-state record: the running version, the version before it, and whether the install started fresh. On the first start of 2.8.0, an existing registry or stored settings counts as an upgrade from 2.7.x.
- Zero Vaults on a fresh install. A deployment with no registry starts with an empty one, whatever
- Consequences: A beginner's first screen is the checklist, and every Vault on it is one they added. Adding a Vault stays possible without a browser, through the HTTP API or
create_vault, so ADR-14's decision holds, but a first boot from.envalone is no longer a complete deployment: it also needs that one call. An install still on 2.4.x or earlier cannot jump straight to 2.8.0, and says so instead of opening empty, which would look like lost notes. The first-boot path loses its import code and its starter-note seeding, sovault::seed_new_vaultanddocs/starter-vaultlose their reason to exist. The instance-state record is new persistent state. Restoring an automatic first Vault, seeding notes into a user's folder, or importing a pre-registry deployment again needs a superseding record. The 2.8.0 release itself must not ship this without the checklist and the folder picker; nightly development builds may carry intermediate first-run states. - Evidence: issue #416 (resolution, section C, and the addendum on old single-Vault installs and build order); #427 (zero Vaults and removal of the import), #428 (starter notes), #424 (previous version). Today:
src/vault_migration.rs(migrate_legacy_vault,LEGACY_STORED_KEYS,RETIRED_LEGACY_STORED_KEYS);src/vault/seed.rs(seed_new_vault,seed_empty_vault) anddocs/starter-vault;docs/migrations/legacy-single-vault.md; the Legacy single-Vault import section ofdocs/architecture/module-map.md.
- Status: Accepted (#420), from the resolution of #416 and its addendum. Uses the web token of ADR-08. The listing itself stays read-only. ADR-44 adds one write beside it: a new, empty folder inside the same mount. ADR-54 narrows decision 6 for agents: an agent can add a folder as a Vault only inside the mount.
- Context: With no Vault registered on a fresh install (ADR-40), a beginner has to name a folder. Typing a container path they cannot see is where most of them would get stuck: the folder they know is on the host, while Hatchdoor sees it under a mount such as
/data/vault. A picker over the folders the container can actually see removes the guessing. This listing is the first surface that walks the filesystem outside a Vault, so its limits need writing down. - Decision:
- One authenticated, read-only listing. It lists the folders under the configured Vault root (
VAULT_PATH), with a count of the Markdown files in each, and feeds the folder picker. It sits behind the web token like the rest of the HTTP API (ADR-08). - It stays inside the root. It never follows a symlink and never leaves the root.
- Folder names and counts only. It never returns file names or file content.
- Hatchdoor's reserved directories are skipped.
- Refused in demo mode.
- Outside the mount, the answer is an explanation. A folder outside the mount gets a plain explanation, a Help link and "or ask your agent to add it". Git-backed Vaults are added as they are today.
- One authenticated, read-only listing. It lists the folders under the configured Vault root (
- Consequences: A beginner picks a folder from a list with Markdown counts instead of typing a container path. The cost is a new read that walks the filesystem outside any Vault, which is security-relevant code, and these invariants are its whole contract. A folder the operator did not mount stays invisible by design; mounting it is a deployment change, which Help explains. Returning file names or content, following symlinks, listing anything outside the Vault root, or serving the listing in demo mode needs a superseding record.
- Evidence: issue #416 (resolution, section C, and the addendum on layout choices); #429 (listing), #430 (picker). Today:
VAULT_PATHinsrc/config.rs, mounted at/data/vaultbydocker-compose.yml; the instance-state directories no Vault may contain, insrc/vault_registry.rs(with_reserved_directories,ensure_outside_instance_state) and filled in bysrc/server.rs, plus Hatchdoor's own trash folder,.hatchdoor-trash/insrc/vault/exclude.rs.
- Status: Accepted (#420), from the resolution of #416 and its addendum. Adds one refusal to ADR-36 decision 2. The What's new page, the release-prepare draft and refusal, and the version record behind the pop-up are implemented in #424; the pop-up itself is #418.
- Context: The changelog is written for people who read changelogs. A beginner who upgrades has no idea what changed or whether they must do something, and an action-needed item is buried among fixes. The What's new pop-up, Help and agents all need one short, plain account of each release, and it has to be written every time, which a manual step would not guarantee.
- Decision:
- A What's new page in the manual. It holds 3 to 6 plain lines per release, counted in total, action-needed items first, newest release first. The pop-up, Help and agents all read the highlights from there, and the MCP opening instructions carry one fixed line pointing agents to it. The page names the running version, so it is private (ADR-38).
just release-preparedrafts the section and refuses without it. It drafts the release's section from the Unreleased changelog and refuses until the section has 3 to 6 lines. This adds a refusal to ADR-36 decision 2.- Approval covers them. The maintainer's approval of the release title and notes (ADR-36 decision 4) covers the highlights, and an edit after approval means asking again. The release runbook says so.
- Consequences: Every release reaches a beginner as a few plain lines, with anything they must do first, and an agent can read the same lines over MCP. Each release costs the maintainer one more short text to read before approving. Six lines cannot list everything, so a release with many visible changes has to choose; the changelog stays the full record. Releasing without highlights, or with more than six lines, needs a superseding record.
- Evidence: issue #416 (resolution, section B, and the addendum on highlights and What's new); #424 (highlights and release script), #418 (pop-up). Today:
scripts/release-prepare.mjs;docs/maintenance/release-runbook.md;CHANGELOG.md(## Unreleased).
- Status: Accepted, implemented in #458. Supersedes nothing. The re-scan reports through the watcher's existing change channel, so ADR-18, ADR-23 and ADR-31 bind the turns it causes exactly as they bind a watcher event's.
- Context: Hatchdoor learned about changes made outside it from one source: file change events from the kernel, through
notify'sRecommendedWatcher, which is inotify on Linux. Some filesystems deliver no such events for changes made on their other side. A Windows folder shared into a Linux container by Docker Desktop is the common case, and it is the normal setup for every Windows user. There the watcher starts without error and the Vault reportswatcher: running, while a note added, changed or removed from Windows never reaches the tree or search. In the 2.8.0 deploy rehearsal (#434, run 4) a note added from Windows was still missing after four minutes, with nothing on screen saying so. Two remedies were weighed. Detecting the filesystem and switching those Vaults to polling fixes the cases already known and silently misses every case nobody has met yet, which is the same failure again. Re-scanning every Vault on a timer needs no knowledge of the filesystem at all. - Decision:
- Kernel events stay the fast path. Nothing about the watcher, its debounce or its ceiling changes, and a change the kernel reports is still acted on within seconds.
- Every Vault with a running watcher is also re-scanned on a timer. The re-scan compares file names, sizes and modification times against the previous round, never file contents, and reports a difference on the same channel a watcher event uses. It applies the watcher's own rule for what counts as a change, and it lives and dies with the Vault's watcher handle. The first round only sets the baseline.
- The interval is 60 seconds, fixed. It is a constant beside the watcher's debounce, with no setting and no environment variable (ADR-14): noticing outside changes is the behaviour, not a preference.
- No filesystem detection. The re-scan runs on every Vault, including those where kernel events work.
- Consequences:
watcher: runningis true again on every filesystem: an outside change is noticed within about a minute at worst. The cost is one metadata walk per Vault per minute, paid on filesystems that never needed it, and an unchanged Vault causes no index or commit turn however long it runs. Where kernel events do work, a change is reported twice, once by its event and once by the next round, so it gets a second index turn that finds nothing to embed. A change that keeps a file's size and lands inside the same modification-time tick as the previous one is invisible to the re-scan; kernel events and Hatchdoor's own write reports cover it wherever they exist. Making the interval configurable, skipping the re-scan on some filesystems, or giving it a route to turns other than the change channel needs a superseding record. - Evidence: issue #458 and its triage; #434 run 4 for the failure;
src/vault_watcher.rs(RESCAN_INTERVAL,run_vault_folder_rescan,fingerprint_vault_folder,is_vault_change_path, and the tests namedrescan_*); ADR-14 for no setting, ADR-23 for the commit turn a change asks for, ADR-26 for the two-step save the same folders use.
- Status: Accepted, implemented in #494. Supersedes nothing. It adds one write beside the read-only listing of ADR-41, whose six decisions stand. Uses the web token of ADR-08.
- Context: A local Vault must point at a folder that already exists, and Hatchdoor could not make one. Starting a Vault from nothing therefore needed a shell, a script or an agent with file access, which is exactly what the folder picker (ADR-41) was built to spare a beginner. It hurts most where the mount is a parent folder holding several Vaults, such as
/data/vaults/<name>: every new Vault there needs a new subfolder, and the mount itself cannot be a Vault once one lives under it. Until now Hatchdoor wrote only inside a Vault, through the Vault write module, and inside its own state directories. A folder made for a Vault that does not exist yet is in neither place, so this is the first write outside both and its limits need writing down. Creating a missing typed path on "Create Vault" was weighed and dropped: a typed path can name any place the process can write, and a typo would silently become a folder. - Decision:
- One new, empty folder per request. The request names a parent folder and one name. Hatchdoor makes that single directory and nothing else: no chain of folders, and no file inside it.
- Only inside the Vault mount. The parent is a folder the listing of ADR-41 can show, under the Vault mount (the folder
VAULT_PATHnames), reached without following a symlink. A parent that is absolute, climbs out with.., or resolves outside the mount is refused. - Never inside a registered Vault. A parent that is a registered Vault, or sits inside one, is refused, and so is a name that would land on a registered Vault's own folder. Writes inside a Vault stay with the Vault write module.
- The name is one plain segment. No slash or backslash, no leading dot (which covers
.and..), no control character, no space at either end, at most 255 bytes, and not a folder the listing hides as instance state. The backslash and the spaces are refused because a mount shared from Windows treats them differently from Linux. A name already taken is refused; an existing folder is never reused. - A signed-in person asks, in the web app. The write sits behind the web token and is offered as "New folder" in the folder picker. It is not an MCP tool, and
create_vaultstill refuses a folder that does not exist. - Refused in demo mode.
- It refuses when it cannot tell. While the Vault registry cannot be read, nothing says which folders belong to a Vault, so no folder is made.
- Nothing is ever cleaned up. Hatchdoor does not delete or rename folders, so a folder made for a form the person then cancels stays where it is, empty.
- Consequences: A beginner can start an empty Vault from the browser, and a mount that holds several Vaults gets a new one without a shell. The cost is security-relevant code that writes to the operator's disk outside any Vault, and these limits are its whole contract. The checks run before the directory is made, not atomically with it: someone who can already swap a folder in the mount for a symlink between the two could redirect the new folder, and that person can already write to the mount. Empty folders left by cancelled forms accumulate until the operator removes them. Agents gain nothing: an agent that needs a new folder still needs file access or the operator. Creating a folder outside the mount, inside a Vault, more than one level at a time, over MCP or in demo mode, creating a missing typed path, or deleting and renaming folders needs a superseding record.
- Evidence: issue #494 and its agent brief.
src/folder_listing.rs(create_folder,FolderCreateError, besidelist_foldersand sharing its root, symlink and hidden-name checks);src/handlers/folders.rs(POST /api/v1/folders);src/server.rs(the route, its web-token gate and demo refusal);frontend/src/features/settings/FolderPicker.tsx("New folder"); the registry'sensure_outside_instance_stateinsrc/vault_registry.rs, reused for the instance-state rule.
- Status: Accepted (#476), from the resolution of #474 and its addendum. Extends ADR-39 and supersedes nothing: the update check still sends nothing about the instance, and the usage report is a second, separate request with its own setting. One sentence of ADR-39's context is out of date, the one that reads "Hatchdoor otherwise makes outbound requests only to download a search model and, for Git-backed Vaults, to reach the configured remote"; decision 12 gives the list as it stands now. A deliberate exception to ADR-36's rule that private infrastructure stays out of public artefacts (decision 9). Applies ADR-13 and ADR-14. ADR-48 supersedes decision 6 in one place: What's new mentions the report a second time in 2.8.1, with the switch on the line. Every other door still asks once.
- Context: The usage report is telemetry, and this record, the manual and the README say so in that word. The question was how Hatchdoor should learn how it is used, and by how many people. The installs that matter are run by other people, and the only way to see them is for an install to report something about itself. Pull counts from Docker Hub are the ceiling and the reports are the floor; the maintainer already records the pull counts daily, outside this repository. ADR-39 made the update check opt-in and kept everything about the instance out of it. The usage report extends that position and does not reverse it. A hosted third-party service was rejected. The demo and docs sites, and usage statistics shown to an operator about their own install, are out of scope. While the question was open, a third-party request that was documented nowhere turned up: the web app asked Google for its four font families on every page load. The link was malformed, so since 2.0.0 Google answered 400 and installs showed fallback fonts, but every visitor's address still reached Google. A running instance should contact no third party its operator did not ask for, so that request had to go before this record was written.
- Decision:
-
Opt-in, off by default, and called what it is. The setting is
HATCHDOOR_USAGE_REPORT_ENABLED, declared like every other setting (ADR-14), in a Settings section of its own. It takes effect without a restart, and an environment value pins it. The name is "usage report" everywhere. Two phrases stay out of the copy: "anonymous", because the report carries a stable ID and is pseudonymous, and "help improve Hatchdoor". The question says what is sent and what it is for: deciding which platforms to test and which parts of Hatchdoor people rely on. -
One report a day, describing the install's state. Every value is a fixed word from a list, a yes or no, or a bucket. Nothing in it is behaviour data: no counts per tool, no searches, no clicks, no errors. The complete payload of schema 1:
Field Values The decision it informs schema1, a numberHow to read every other field; lets a later collector tell report formats apart id, the install IDa random ID (decision 4) Whether enough installs report for any of these numbers to mean something versionsuch as 2.8.0; no Git commitWhich releases are still running, so which upgrade paths to keep working channelstable,devWhether other people run development builds, so how carefully those have to be treated os,archas the program sees them Which platforms to build for and test imagedocker,podman,sourceWhether Podman and source installs earn their testing search_modelgemma,nomic,noneWhich search model to keep evaluating, and whether installs end up with no search vaults0,1,2-3,4+How much the multi-Vault features are relied on notes, across all Vaults0,1-99,100-999,1k-9k,10k+What size of Vault indexing and search must be tested against git_syncnone,pull_only,two_way,mixedWhich Git sync modes people rely on mcp_enabled,mcp_writesyes or no Whether agent access, and agent writing, is a main use or a side one mcp_active_7d,web_active_7dyes or no Whether an install is in use at all, and through agents, the web app or both agent_claude_code,agent_claude_desktop,agent_codex,agent_cursor,agent_vscode,agent_chatgpt,agent_openclaw,agent_hermes,agent_otheryes or no each Which agent clients to test against and write setup guides for git_syncisnonewhen no enabled Vault has a remote (no Git, or local history only),pull_onlyortwo_waywhen every enabled Vault with a remote uses that mode, andmixedotherwise.mcp_active_7dsays whether any MCP call arrived in the last seven days.web_active_7dsays the same for a request that reaches a part of the web API the web token would protect (ADR-08), whether or not the install has a token set. An agent field says whether that family was seen in the last 30 days. The families are a closed list, matched on the name a client sends and not on its display title; the name itself is free text, so it is mapped onto the list and never sent. Windows installs run through Docker Desktop and report as Linux; that blind spot is accepted. Whetherimagecan be anything butsourceis set when the image is built, by builds that run outside this repository, so a build that sets nothing reportssource. Since #705 one published image serves both engines: the build marks it as published, and the image reportspodmanwhen it finds the file Podman creates in every container (/run/.containerenv) anddockerotherwise. Another engine that creates the same file also reportspodman; Hatchdoor documents Docker and Podman installs only, so that blind spot is accepted. -
The request and what is never sent. The body is exactly
{"type":"event","payload":{"website":<website ID>,"hostname":"hatchdoor","url":"/report","name":"report","id":<install ID>,"data":{…}}}, posted tohttps://telemetry-hatchdoor.battercloud.cc/v1/reportwith the user-agentHatchdoor, no version, as the update check sends it.dataholds the fields of decision 2 other than the install ID, and nothing else.schemais a JSON number, the yes or no fields are true or false, and every other field is a string from its list. The parts of that format the analytics service needs but Hatchdoor has no value for are fixed placeholders. Never sent: note content, titles, paths, tags, search queries, Vault names or IDs, Git remote addresses, host names, tokens, language, time zone, exact counts, the raw agent name. -
A random install ID, deleted when the setting goes off. It is made on first use from nothing on the machine: no host name, no hardware address, no path. Switching the report off deletes the ID and everything kept for the report, the activity record and the time of the last report included. Switching it on again starts a new identity. The report's state is brought in line with the setting at startup and after every settings save, because the setting can also change through the environment at a restart. An ID that could not be saved is never shown or sent. The ID and the activity record live in the instance state (ADR-40 decision 6), not in SQLite, which is disposable (ADR-01, ADR-06).
-
The payload changes only in the open. A field may be dropped in a later schema freely. A field may be added only with a schema bump, a change to the manual page and a line in What's new (ADR-42), and it must show in the Settings preview before the first report that carries it. A new agent family is a schema bump. No field is ever behaviour data; behaviour data would need a new setting and a new question.
-
The question is asked once at each of five doors, and never twice at the same one. The first-run checklist, as a second optional switch under the update-check one and independent of it. The README, as a paragraph under Configuration that names the variable; it is kept out of
.env.example(amended in #479: a line there, even commented out and set tofalse, reads as the recommended answer). The agent install page, as one question in fixed wording: on a yes the agent turns the report on through the settings API with the web token (ADR-08) and never writes the variable to.env, where it would be pinned and the operator could not switch it off in Settings; an unanswered question leaves the setting alone. What's new, for people who upgrade, with no banner, no pop-up of its own and no reminder in later releases. And one sentence to agents over MCP (decision 7). Every door links to the same manual page. -
Agents are told once and can change nothing. On an install that existed before 2.8.0, the first MCP opening handshake after the upgrade, a legacy
initializeor a modernserver/discover(ADR-17), carries one sentence saying the optional report exists and where the operator can turn it on. Hatchdoor records that it was delivered and never sends it again. If the report is already on at that handshake, the sentence is marked delivered without being sent. The mark lives in a section of its own in the instance state, because the report's own section is empty while the report is off. A client's connection test can spend the sentence; that is accepted. No MCP tool may change the setting (ADR-09): only a person in Settings, or the environment, can. -
Sending is a quiet background job. Like the update check it reads the live setting and uses the HTTP client already compiled in. The first report goes within a minute of switching on. After that there is at most one successful report in 24 hours per install ID, with the time of the last success kept in the instance state so restarts do not multiply reports. An operator who switches off and on again has a new ID, so a first report follows within a minute. After a failure it tries again in an hour. Nothing is queued, failures are logged quietly, the timeout is ten seconds, and the job never holds up startup or a request (ADR-07 gains no new refusal). Switching off stops at once and sends nothing, not even a last report. Tests never reach the network.
-
Reports go to a collector the maintainer runs, at a public name.
https://telemetry-hatchdoor.battercloud.ccis used for nothing else. The request passes through Cloudflare, as the demo and docs sites do, to a proxy that discards the sender's address before anything is stored, and from there to the maintainer's existing analytics service (Umami). Schema 1 uses that service's event format, with the install ID as the visitor ID and the fields as event data. The collector never stores the sender's address next to the ID. The collector is set up outside this repository. Its host name in the source and the docs is a deliberate exception to ADR-36's rule against private infrastructure in public artefacts: it is public so an operator who sees it in a network log knows what it is and can block it. It must keep answering for as long as 2.8.x installs run. -
Invented reports cannot be prevented, only noticed. Reports are not signed, because the key would ship in the same public source. The proxy caps the size and the rate. Every report is kept, so the history can move into a collector written for Hatchdoor later; a flat format of Hatchdoor's own, a removal button in Settings and real protection against invented reports all wait for that collector. A report must be stored to count: the analytics service can accept a request and discard it as a bot, so the proxy is responsible for presenting the report so that it is kept, Hatchdoor's user-agent stays
Hatchdoor, and "sent" is checked against what the collector stored. -
An operator can check all of it. Settings shows the exact report the next send would carry, built by the same code that builds the real one, while the setting is off as well as on. While it is on, Settings also shows the install ID and the time of the last report. A test fails the build when the manual page's field list and the report disagree. An operator can have their past reports removed by sending their install ID by email, and the manual tells them to copy the ID before switching off. The address is not chosen yet.
-
The outbound list is complete, for browsers as well as the server. A running instance makes four kinds of outbound request: the search model download, the configured Git remote, the opt-in update check (ADR-39) and the opt-in usage report. The fonts are bundled into the app (#475), so a page load contacts no third party.
-
No new dependency. The report is sent with
ureq, which ADR-39 decision 5 already justified against ADR-13. -
Never in demo mode. A demo instance never reports, as it never runs the update check (ADR-39 decision 4), and nothing is created there, the ID included, even with the variable set.
-
Results are quoted as totals, and the report is reviewed. Numbers may be quoted where they explain a decision, in a release note or an issue, always as totals and never per install. The manual says so, and there is no public page of numbers. When the second release after 2.8.0 is prepared, a review asks four things: is the number of reports enough to mean anything, has each field informed a decision, has the analytics service been enough, and did any agent set the variable without asking. Reporting by default is not on the table at that review.
-
- Consequences: The maintainer gets a floor under Docker Hub's ceiling, and platform and feature decisions can cite numbers. An operator who does nothing sees no change and no traffic, and one who opts in can read the exact report before it leaves. Opt-in means the reports undercount, so they are a floor and never a census. ADR-38 keeps the version off every public route, and this record does not loosen it: the version here travels outward, in a request the operator chose, to one collector, and no public route on the instance serves it. The request passes through Cloudflare before the proxy discards the sender's address, and the manual says both things. Hatchdoor's source now names a host the maintainer has to keep running; if it stops answering, opted-in installs fail quietly once an hour. The report is tied to one analytics service's event format until a collector of Hatchdoor's own replaces it. Published images report
sourceuntil the image builds pass the new build argument. Reporting by default, adding behaviour data or a field outside decision 5, letting an MCP tool change the setting, signing or queueing reports, sending to a hosted third-party service, or repeating the question at a door needs a superseding record. - Evidence: issue #474 (the resolution and its addendum); #475 (fonts); #477 (the report and its Settings preview), #478 (sending), #479 (the five doors and their wording), #480 (rehearsal). Today:
src/update_check.rs(the background job this follows:UPDATE_CHECK_SETTING,USER_AGENT,TICK_INTERVAL, andFetchLatest, the seam that keeps tests off the network);src/instance_state.rs(InstanceStateStoreand its named sections);live_settings_defaultsinsrc/runtime_config.rsandSETTINGSinsrc/handlers/settings.rs;ureqinCargo.toml;HATCHDOOR_GIT_SHAinsrc/config.rsandDockerfile(the build argumentimagefollows);frontend/src/assets/fonts/fonts.css(the bundled fonts).
- Status: Accepted, implemented in #500. Supersedes nothing. ADR-05 is untouched: a text match is unranked and literal, so it adds no reranking and no keyword and vector fusion to the runtime search path, and
search_noteskeeps both of its modes as they are. - Context: Both
search_notesmodes rank. Keyword mode splits the query into words and accepts a passage that contains any one of them, so no call answers "which notes contain exactly this string", and no call counts occurrences. In the triage of #500 a keyword search for a filename that one note contained returned seven hits, six of them notes that only mention some other.mdfile, and a search for a note's exact title ranked a note linking to it first. Nothing in either reply told the caller the list was not a list of occurrences. The questions this leaves unanswered are ordinary Vault work: a rename sweep, checking that a bulk edit landed everywhere, finding every note that cites a path or an ID. The only working fallback was a grep on the Vault host, which most agents cannot run. Three shapes for the fix were weighed. A thirdsearch_notesmode would make one tool return two unlike things, and an agent that forgets the mode gets the ranked answer and misreads it, which is the reported failure. A text condition onquery_noteswould stretch a query, which tests properties, tags and paths and returns rows of properties, into something that reads note text and returns counts and snippets. A tool of its own has one job and one result shape. - Decision:
- A text match is its own concept and its own MCP tool,
find_text. It selects and never ranks: a note either contains the string or it does not, each matching note appears once with its number of occurrences, and notes come back in the stable path order a query uses. It is not a search, which ranks by relevance, and not a query, which tests properties, tags and paths. - It reads the Markdown files on disk at call time, never the indexed copy and never the chunks. It covers the body, the frontmatter block and the Vault-relative file path, and each match says which of the three it sits in. The set of Notes it walks is still the Vault's published one, so a Note too new to have had its Index turn is absent, and the reply's
participantsreport that Vaultstaleas every collection read does. - It covers every layer by default. Each match carries its layer, and
layersnarrows the sweep. This departs fromsearch_notes, which covers the default surface unless layers are named. - One literal string. Every character means itself: no wildcards, no regular expressions, no multiple terms. Case is ignored unless the caller asks for a strict match. Accents count. The composed and decomposed forms of one accented letter are equal always, because nobody can see the difference to ask for it.
- The totals are always true. Every reply carries the number of matching notes and of occurrences across the whole scope, and says when the list of notes was cut short. There is no paging: a caller narrows by folder with
path_prefixor raiseslimit, up to 500 notes. Each note shows a few short snippets, three by default and adjustable down to none. - MCP only for now. The matching lives in the shared read core (ADR-02), so the web interface can call it later; offering it there is a separate decision with its own design pass.
- A text match is its own concept and its own MCP tool,
- Consequences: An agent can answer "does anything still say X" inside the MCP tools, with a count that agrees with a grep, seconds after the edit it is checking. The price of reading the files is one file read per Note per call, slower on a large Vault than an index lookup, which is accepted because an answer that is wrong for the length of an Index turn defeats the verification the tool exists for. Two behaviours now differ on purpose between tools that sit side by side:
find_textsees demoted layers by default andsearch_notesdoes not, andfind_textreads disk while every other collection read answers from the published snapshot. Layers exist to keep ranked results free of noise, and an unranked match has no ranking to protect; a default that skipped them would report a clean sweep while the string still sat in an archived note. Aligning either behaviour withsearch_notes, adding patterns, adding paging, ranking the result, or answering from the index needs a superseding record. - Evidence: issue #500 and its triage, with the two reproductions;
src/cache/parse.rs(build_fts_query, which joins the query's words withOR) andsrc/cache/queries/search.rs(vault_fts_search_chunks) for why keyword mode cannot answer the question;GLOSSARY.mdfor Text match beside Query; ADR-01 for Markdown as the authority a text match reads, ADR-02 for the shared core, ADR-05 for the search path this leaves alone, ADR-21 for what a query is.
- Status: Accepted, implemented in #512. Supersedes nothing. ADR-07 is untouched: outside demo mode a request without a token still learns nothing about a note.
- Context: A chat app builds the preview of a shared link from tags in the HTML the server returns (
og:title,og:description,og:image), and its fetcher runs no JavaScript. Hatchdoor returns one static page for every browser address and loads the note in the browser afterwards, so a link to the public demo or to the docs site arrives in WhatsApp or Telegram as a bare address. Those are the links that get shared. The page a private instance returns must stay anonymous, because it is served before any token is checked. A demo instance already serves every note on its default surface to anyone, so a preview of such a note tells a fetcher nothing it could not read by asking the API. Two ways to get an absolute address for the picture were weighed: reading theHostheader, which lets whoever sends the request choose the address written into the page, and the existingHATCHDOOR_PUBLIC_URLsetting, which the operator sets. - Decision:
- Demo mode is the only switch. On a demo instance (
HATCHDOOR_DEMO_MODE=true) the page carries a link preview. Outside demo mode every page response is byte for byte the built file, for every address, with or without a web token configured. There is no new setting. - The picture is one fixed image shipped with the frontend's static files, 1200 by 630, the same for every address. No picture is drawn per note and no note attachment is used as one, so no image-drawing dependency enters the binary.
- A preview never reveals more than the demo already serves. A note address gets that note's title and description only when the unauthenticated demo read of that Vault and slug succeeds, and the preview reads the note through that same read core. A missing note, an unknown or disabled Vault, a note on a demoted layer, or any refused read gets the general wording every other page gets, with the status code unchanged.
- Everything written into the page is escaped for the place it lands in. A note title or description holding quotes, angle brackets or a closing tag cannot leave its attribute or element.
- Absolute addresses come from
HATCHDOOR_PUBLIC_URLonly. With it set, the page carries the picture and its own address. With it empty, both are left out and the title and description are still sent. No address is ever built from theHostheader or a forwarded header.
- Demo mode is the only switch. On a demo instance (
- Consequences: A shared demo or docs link shows a title, a short description and a picture, and a search engine reads a plain title and description from the same response. The tags are written at response time into the built page, so a demo note address costs one note read per page load. The preview picture appears only after the operator sets
HATCHDOOR_PUBLIC_URL, which is the price of never trusting a request header. Every link shows the same picture. A private instance gains nothing, on purpose: a preview there would hand a note's title to anyone who guesses an address. Previews outside demo mode, a picture per note, per-instance wording, or an address taken from the request each need a superseding record. - Evidence: issue #512 and its triage;
src/handlers/spa.rsfor the page handlers andsrc/handlers/link_preview.rsfor the tags;VaultReadCore::exact_noteinsrc/vault_read.rsfor the shared read and its layer rule;parse_public_urlinsrc/mcp/config.rs;GLOSSARY.mdfor Link preview; ADR-01 for Markdown as the authority the description is read from, ADR-02 for the shared core, ADR-07 for the posture a private instance keeps.
- Status: Accepted, implemented in #563. Supersedes ADR-45 decision 6 in one place only: What's new no longer mentions the report once. Every other door still asks once, and every other decision of ADR-45 stands, including that no MCP tool may change the setting.
- Context: ADR-45 decision 6 let What's new mention the usage report once, in the release that added it, "with no banner, no pop-up of its own and no reminder in later releases". 2.8.0 did that. Its line says the report exists and that it is turned on in Settings under Usage report, so an operator who wants to say yes has to close the pop-up, open Settings and find the section. On 2026-10-11 the maintainer decided that 2.8.1 mentions the report a second time and puts the switch on the line, so that turning it on takes one click. The manual's Usage report page told operators that Hatchdoor "never reminds you afterwards", so that page has to change with this record. The first-run checklist already carries the same switch outside Settings (ADR-45 decision 6), so a switch in a second place is not new.
- Decision:
- The 2.8.1 section of What's new carries one more line about the usage report. It says what ADR-45 decision 1 requires the question to say, keeps "anonymous" and "help improve Hatchdoor" out, and ends with the link to the Usage report page, as every door does.
- The pop-up shows the switch on that line and on no other. The line is the highlight of release 2.8.1 that links to the Usage report page. The 2.8.0 line shows no switch, and neither does any later line about the report, such as the one ADR-45 decision 5 requires when a field is added.
- The switch reports the setting and changes it only on a click. It reads the live setting and shows it as on or off. A click sends the request Settings sends, for that key alone, and the pop-up stays open. A value pinned by the environment is shown and cannot be changed there. When the setting cannot be read, the line shows without a switch.
- Nothing else about the pop-up changes. It is still not shown in demo mode or on a fresh install (ADR-42), so the switch is not either, and it is still one pop-up: the report gets no banner and no pop-up of its own.
- No later release repeats it. After 2.8.1, What's new mentions the report only where ADR-45 decision 5 requires it, and never with a switch.
- Consequences: An operator who upgrades to 2.8.1 can turn the report on with one click. The exact report is shown in Settings and not in the pop-up, so the line names Settings for anyone who wants to read it first. An operator who read the 2.8.0 line is asked a second time, which ADR-45 and the manual had said would not happen; the manual now says what happens instead. Someone who upgrades from 2.7.x or earlier straight to 2.8.1 or later sees both lines in one pop-up, with the switch on the 2.8.1 one. Help and agents read the What's new page as plain Markdown and see the line without a switch. The release is named in the pop-up's code, so the switch cannot spread to another release by the wording of a line. Showing the switch on another release's line, turning the report on without a click, or mentioning the report in a later What's new outside ADR-45 decision 5 needs a superseding record.
- Evidence: #563. Today:
carriesUsageReportSwitch,fetchUsageReportSettingandsaveUsageReportinfrontend/src/features/whats-new/whatsNew.ts;UsageReportSwitchinfrontend/src/features/whats-new/WhatsNew.tsx;patchSettingsinfrontend/src/features/settings/settingsApi.ts(the request Settings sends); "Where you are asked" indocs/user-vault/03 Reference/Usage report reference.md.
- Status: Accepted, implemented in #570. Extends ADR-23 and amends nothing: ADR-27 and ADR-32 stand as written, and a transfer link's URL and signature do not change.
- Context: With versioning on, Hatchdoor commits a Vault's writes itself (ADR-18, ADR-23). The message said what changed and never where the change came from, so a commit made from the browser and one made by an agent looked the same, and two agents could not be told apart. The roadmap's "Trustworthy human + agent collaboration" workstream wants the web UI to show which agent changed a note, and a change made before recording starts can never be attributed. Three forces shape the record. Every MCP client shares one token and chooses its own name, so a name proves nothing. A commit also sweeps up whatever else changed in the Vault's folder, such as an edit made in Obsidian, and the write batch a commit is named from lives in memory and is bounded, so a restart or a long gap loses records. And Git history is permanent: a trailer name or a value written today is read by every tool that parses these messages for as long as the repository exists.
- Decision:
- The word is "origin", not "actor". An origin is where a write came into the Vault from. It says which door, and cannot say who walked through it. "Actor" stays free for an identity Hatchdoor can verify, which needs per-agent credentials.
- An origin has four values, written as they appear in a trailer.
webfor a write over the web API.mcp/<name>for a write over MCP from a client that sent a name.mcpfor a write over MCP from a client that sent no name, or whose name is empty once cleaned.unknownwhen the commit holds at least one changed path that no write record in its batch accounts for. unknownclaims no more than Hatchdoor knows. It covers an edit made outside Hatchdoor and a write whose record was lost to a restart or to the batch's capacity limit, and says nothing about which. A commit made from an empty batch carries it alone.- The client name is stored as sent, not as a usage-report family. History cannot be rewritten, and a family can be derived from a name at display time but a name cannot be recovered from a family. The name is cleaned only so far as a trailer needs: one line, no control or invisible formatting characters, trimmed, at most 100 characters. Case and inner characters such as
/and spaces are kept, soAnthropic/ClaudeAIis recorded asmcp/Anthropic/ClaudeAI. The client's version is not recorded. The name is the one the client sends, not its display title. - The record is a trailer block at the end of the commit message. A commit named from the write batch ends with one blank line and then one
Hatchdoor-Origin: <value>line per distinct origin, in order of first appearance in the batch, withunknownlast. The title line and the summary lines are byte for byte what they were. Only this final paragraph is the record: aHatchdoor-Origin:line anywhere above it, in a caller's summary for instance, is not one. - Every operation inside one MCP
batchcall has the origin of that call, and an upload through a transfer link has the origin of the client that asked for the link. The link's URL and signed content do not change. The name is remembered in memory until the link expires, and an upload whose name can no longer be found ismcp. - Git history is the only store. A Vault without versioning keeps no origin record, and a batch put back after a commit that did not happen keeps its origins.
- Consequences: Any Git host shows the origin, and Hatchdoor can read it back later with no migration. An agent can claim any name, including another agent's, so the manual says the name is a label. A commit that mixes origins says which origins it holds and not which paths each one touched. A write that produced no change Git can see, a path the checkout ignores for instance, lends its origin to the next commit that does happen, as its summary line already does. A Local history commit runs without the Vault's write lock (ADR-18), so a write that lands while one is being made can be committed before its record is filed: that commit reads the file as
unknown, and the write's origin arrives on the next commit, one late, as its summary line does. A request that carries no client identity reaches Hatchdoor with the MCP SDK's own placeholder name and version, which Hatchdoor reads as no name, so a client that sends exactly that pair is recorded asmcp. Anyone who matches the whole commit message, not its title, sees a longer message. Commits whose message does not come from the write batch, such as the merges a sync makes and a recovery branch's commits, carry no trailer. Renaming the trailer, changing what a value means, recording a version or a family, or adding a second store needs a superseding record. - Evidence: #570. Today:
WriteOrigin,PendingBatch::messageandbuild_commit_messageinsrc/git/message.rs;stage_vault_driftinsrc/git/sync.rsandsrc/git/managed_sync.rs(the paths a commit changes);VaultMutationCore::newandVaultMutation::gatedinsrc/vault_mutation.rs;sent_client_nameinsrc/mcp/adapter.rs;TransferLinks::remember_clientandRedeemedLinkinsrc/transfer_link.rs;clean_client_nameinsrc/instance_state.rs; "Where each change came from" indocs/user-vault/02 Guides/How to set up a Git-backed Vault.md.
- Status: Accepted; rule 2 superseded by ADR-52. Amends ADR-01: a schema version mismatch no longer always wipes the cache. ADR-01's source-of-truth rule and its model-change wipe stand as written.
- Context: ADR-01 made every cache schema change wipe the cache and rebuild it from Markdown, accepting a full reindex as the price. Most of that price is re-embedding every chunk on CPU (ADR-04). Measured on #600, a 3-vCPU host re-embeds about 300 notes an hour, so a 10,000-note Vault would search incompletely for more than a day after an upgrade. Nothing tells us how large other installs' Vaults are. #600 needs a schema change to fix a memory leak, and #308 was waiting for one. The closest comparable tool, Basic Memory, keeps its embeddings across schema changes with migrations and rebuilds only cheap data.
- Decision:
- Markdown stays the source of truth and the cache stays disposable. A migration only saves time. Correctness never depends on one.
- A migration runs from the previous schema version only. Any other version, a missing version or a half-built cache wipes and rebuilds, as before. When the next schema change lands, the previous migration is deleted.
- The model check runs first. A changed embedder identity wipes, as ADR-01 says, so a migration never carries vectors from one model to another.
- A migration proves the result before it commits. In the same transaction it checks, for every Vault and every vector table: the row counts match, every vector is byte for byte the one it replaced, every row belongs to its chunk's Vault, a sample of stored vectors each find themselves as their own nearest neighbour, and
PRAGMA integrity_checkpasses. - Any failure wipes and rebuilds. The log names the check that failed. Hatchdoor does not trust a rollback to have restored the old tables (sqlite-vec #333), so it wipes instead.
- Each migration ships with two tests. A fixed set of searches returns the same notes in the same order at the same distances before and after the migration, on a fixture with several Vaults. And a migration made to fail ends with a wiped, rebuilt, working cache.
- Consequences: An upgrade that only changes the cache layout costs seconds instead of a re-embed. Every schema change now decides whether to migrate or to wipe, and a migration is code that must be tested against a cache written by the previous version. A user who skips a schema version gets a wipe. The worst case of a failed migration is what every upgrade cost before this decision.
- Evidence: #600 (the leak fix and the first migration), #308 (tables dropped by the same migration). Today:
SCHEMA_VERSION,existing_schema_versionandwipe_schemain the cache schema module; the embedder-identity check that wipes on a model change.
- Status: Accepted (refines ADR-26; supersedes nothing)
- Context: A rename, move, archive or delete of a note, an attachment move, and a Vault-wide tag rename or delete each change many files, one at a time: a move, then each backlink as its own compare-and-swap write. ADR-26 makes each single step atomic where the filesystem can, and the write layer's journal undoes the completed steps when a later one fails. That undo lived only in memory. A process killed part-way (SIGKILL, the out-of-memory killer, a reboot) left the note under its new name, a few hundred backlinks pointing there and a few thousand naming a note that no longer existed, a move's reservation folder at the old name, and temporary files beside notes, with nothing on disk describing the operation and nothing at startup noticing (#631, reproduced with 3,000 backlinks). The maintainer chose a durable record rolled forward on startup over detecting and reporting only, and over documenting the gap.
- Decision:
- The plan is on disk before the first step. The journal writes one record per Vault,
write-intents/<vault-id>.jsonin the folder that holds the Vault registry, outside the Vault content and its Git history. It holds the operation's name, every move (source and destination) in order, and every rewrite with the note's hash when the plan read it, the hash of the new text, and the new text. Paths are Vault-relative, with%and any byte that is not UTF-8 written%XX, so a filename that is not UTF-8 survives. The record is written to a staged name, synced, renamed into place and its folder synced. A plan that cannot be recorded is refused with nothing changed: a rename that could not be finished after a crash is worse than one refused up front. A record already present is never replaced, so a new multi-note write is refused while one waits: replacing it would lose a plan the repair kept to retry, or one from a newer build, and a stale record left behind would later be replayed over the newer write. - The record lives exactly as long as the in-process outcome is unknown. It is removed when the operation finishes, and when the journal's in-process undo has run, whether or not that undo was complete: the caller has been told the outcome (a plain failure, or
recovery_requirednaming what is left), so a restart must not finish an operation that was reported as failed. - A restart finishes what had started, and only that. When a Vault is activated, before its watcher starts or any write is admitted, a record still present is one a dead process left. If no step had landed (no move done, no rewrite at its new hash), the Vault is left as it was, apart from removing a move's reservation folder, because nobody was told the operation happened. Otherwise every remaining step is rolled forward. A move counts as done when its source is gone, or is the empty reservation folder the exchange swapped there, and its destination is a file. Every move must stand before any backlink is rewritten: when one cannot be finished because its source or destination no longer look as planned, it needs attention and no rewrite runs, since a backlink pointed at it would name a note that is not there. A rewrite is applied only when the note still carries the plan's base hash, through the same compare-and-swap write that keeps the note's modification time; a note at the new hash is done, and a note at any other hash, or missing, was changed by someone else and is listed in the log as needing attention, never overwritten. A step that fails with a filesystem error, rather than a refusal, may pass (a folder briefly read-only), so the record is then kept and the next start carries on; otherwise it is removed. Each action is a log line.
- Leftover temporary files leave the Vault at the same moment, and are kept. Every regular file named
.<name>.hatchdoor-tmp-<32 hex digits>outside the Vault's.gitfolder is moved, without following symlinks, towrite-intents/<vault-id>.leftovers/at the same Vault-relative path, and logged. It is not deleted because it can hold the only copy of an edit: a compare-and-swap write's exchange displaces a save made in another editor into it, and a crash, or a failed undo whoserecovery_requiredmessage points the person at that file, can keep it from being put back. - A Vault is repaired once per process, at its first activation. Leftovers come only from a process that died. Any later activation of the same Vault in the same process (an edit of a running Vault, a disable followed by a quick re-enable, a managed Git checkout cloned again) can overlap a write the retiring control block is still running, which owns the record and its temporary files. So the repair runs when a Vault first becomes Active in a process (at startup, when it is added, or when a managed Git checkout first makes it available) and never again. One process-wide lock keeps two repairs from running at once. What the repair changes is not recorded in the Git write ledger, so a synced Vault commits it as an outside edit.
- A record this build cannot read is left alone. One from a newer schema version, or one that does not parse, is logged and kept, so a downgrade cannot act on, or destroy, a newer build's plan. Multi-note writes in that Vault are refused until it is dealt with.
- The plan is on disk before the first step. The journal writes one record per Vault,
- Consequences: A crash part-way through a large rename now costs one restart: the rename completes, and the log names any note that changed meanwhile. The price is one durable write of the whole plan before each multi-note operation, which for a rename with thousands of backlinks is the text of every rewritten note; single-note writes, which are already atomic, are not journaled. A Vault whose state folder cannot be written can no longer rename or move notes, though single-note edits still work. Completion is not atomic either: a second crash during the repair leaves the record in place and the next start carries on from there, since every step is idempotent. A record that keeps failing, or that this build cannot read, blocks renames, moves and deletes in its Vault until a person removes it, which the refusal and the log both point to. Leftover temporary files accumulate in the state folder rather than the Vault, for a person to inspect and delete. A reservation folder or temporary file that predates this change, or that a write left without a record, is identified only by name (a temporary file) or not at all (a reservation folder, which looks like any empty folder).
- Evidence:
src/vault/write/intent.rs(IntentLog,IntentRecord,repair_interrupted_writes,sweep_temporary_files);src/vault/write/fs_ops.rs(MutationJournal::begin,finish,rollback, and the test-onlycrash_after_steps);src/vault_runtime.rs(repair_once,VaultControlBlock::activate,set_local_content_status,intent_log);src/vault/write/tests/journaled.rs, which stops each kind of operation at every step boundary and checks the repaired Vault against an uninterrupted run; issue #631; ADR-26 for the single-step atomicity this builds on, ADR-22 for the bytes a rewrite may touch, and ADR-01 for why the Markdown files are what the record protects.
- Status: Accepted (supersedes ADR-50 rule 2; ADR-50's other rules stand)
- Context: ADR-50 rule 2 let a cache migrate from the previous schema version only, and deleted that migration at the next schema change. Schema versions change on
development, not per release. #634 moved the cache from 12 to 13, and #655 needed 14 before any release had shipped 13. v2.9.0 wrote 12, so every install upgrading from it would have been two versions behind and re-embedded every chunk, about 300 notes an hour on a 3-vCPU host (ADR-50). The maintainer chose to migrate from both starting versions over holding #655 until a release or accepting the re-embed. - Decision:
- A migration is a list of steps, each from one schema version to the next. A cache several versions behind runs every step from its version, in order, in one transaction, and ADR-50's checks run once on the result before it commits.
- The oldest step starts from the version the latest release wrote. An install upgrading from the last release never wipes, however many schema changes landed in between. Any older version, a missing version or a half-built cache wipes and rebuilds, as before.
- A step is deleted once its starting version is older than the latest release's. When a release ships, every step that starts before that release's version goes, and the steps from its version on stay.
- Consequences: An upgrade from the last release costs seconds, not a re-embed, however many schema changes it crosses. The price is more migration code to keep between releases. ADR-50's tests apply from every version a step can start from, because a cache two steps behind is a different starting point from one step behind. A user who skips a release still gets a wipe.
- Evidence:
STEPS,can_migrate_fromandmigrate_to_currentinsrc/cache/migrate.rs;SchemaState::Behindinsrc/cache/schema.rs; issue #655 and the tests inmigrate.rsthat start from versions 12 and 13.
ADR-53 — A rename or move repairs the canvases that name the file, and a canvas is otherwise a download
- Status: Accepted (adds to ADR-01, ADR-22 and ADR-51; supersedes nothing)
- Context: A canvas is Obsidian's whiteboard: a
.canvasfile in the open JSON Canvas format (jsoncanvas.org) that places notes, images, text cards and links on a board. A card that shows a file is a node with"type": "file"whosefilevalue is that file's Vault-relative path, extension included. Hatchdoor read none of this. A rename, move or archive retargeted every wikilink and Markdown link (ADR-28) and left the canvas naming a path that no longer existed, so the damage showed up later in Obsidian, also for a person who never opens a canvas in Hatchdoor. A canvas was also missing from the explorer and refused by the asset route (#573, #579). Repairing it means Hatchdoor writes a file that is not Markdown, which ADR-01 never had to consider, and that the write joins a multi-note plan, which ADR-51 describes for notes only. In the triage of #579 the maintainer chose repair plus visibility, and ruled out drawing a canvas, counting it as a link, and agent tools for it. - Decision:
- Hatchdoor writes a canvas for one reason. When a note or an attachment is renamed, moved or archived through Hatchdoor, an asset that travels with its note included, every
.canvasfile the Vault's catalogue lists, so none in a folder its exclusion rules hide, is read, and eachfilenode whose value equals the old Vault-relative path is given the new one. Nothing else makes Hatchdoor write a canvas: it never creates one, never edits one for any other reason, and never touches one after an edit made outside Hatchdoor. - Delete leaves a canvas alone. A deleted note or attachment goes to the trash and its cards keep the old path, so Obsidian shows them as missing, as it does after a delete in Obsidian. Archive is a move (ADR-11), so it repairs.
- Only the path string changes. ADR-22's rule for a partial write holds for a canvas: the rewrite replaces the characters between the quotes of the matching
filevalue with the new path, escaped as JSON, and copies every other byte, so key order, whitespace, unknown fields, other nodes, edges and the trailing newline survive. The match is exact, on the decoded string. As in ADR-22 the editor proves its own work: the edited text is parsed again and must equal the original document with those values replaced, or the canvas is skipped. - A canvas rewrite is one more rewrite in the plan. It is recorded with the note rewrites before the first step (ADR-51), commits against the hash the plan read, keeps the file's modification time, is undone with the rest when a later step fails, and is finished by a restart. A canvas that travels with the operation, as an attachment being moved or an asset following its note, is rewritten at its destination.
- A canvas Hatchdoor cannot read never stops the operation. A canvas that is not valid UTF-8 JSON, is over the note size bound or fails the check in decision 3 is skipped whole, never half-written. One that is over the size bound or cannot be opened is always named, and any other is named when its text contains the old path. A rewrite that was planned is then an ordinary step of the plan: a canvas saved elsewhere between the plan and its commit fails the operation with a conflict, and everything is undone. The names go in the result's existing warning field (
quality_warningsfor a note,cleanup_warningfor an attachment) and in the log. This differs on purpose from a note that is not UTF-8, which refuses the operation (#360): the notes are the Vault, and a whiteboard that cannot be read must not block renaming one. - A canvas is a file to download, not content.
.canvasjoins the servable asset extensions, so the asset route serves it, asapplication/jsonwith a download disposition, and the web explorer lists it under its folder. It is not indexed, searched, embedded, counted in links, backlinks or the graph, or drawn. Agents get no canvas tool and no canvas inget_tree; the existing attachment read (get_attachment) can fetch one, and a wikilink to one resolves as a link to any other served file does. The upload allowlist is unchanged.
- Hatchdoor writes a canvas for one reason. When a note or an attachment is renamed, moved or archived through Hatchdoor, an asset that travels with its note included, every
- Consequences: A rename in Hatchdoor no longer breaks a board in Obsidian. The price is a read of every catalogued canvas on each rename, move and archive, which is small beside the read of every note those operations already make. Markdown stays the only authoritative content (ADR-01): the canvas write is bookkeeping about a name, like a backlink rewrite. A canvas that names a file by a path that differs in case or Unicode form from the one on disk is not repaired. A card that names a heading keeps working, because the heading sits in a separate
subpathvalue. A canvas inside an excluded folder is not repaired, since Hatchdoor does not write there. Standalone.basefiles are not covered. - Evidence:
src/vault/write/canvas.rs(canvas_rewrite_plan,retarget_canvas); its callers insrc/vault/write/notes.rs(execute_note_mutation) andsrc/vault/write/attachments.rs;servable_asset_extensionsinsrc/vault/paths.rs;content_type_for_pathinsrc/vault_read/assets.rsandasset_responseinsrc/handlers/assets.rs; thefileslist ofVaultExplorerFolderinsrc/vault_read.rsandfrontend/src/components/Explorer.tsx; the canvas tests insrc/vault/write/tests.rsandsrc/vault/write/tests/journaled.rs; issue #579; ADR-22 for the bytes a rewrite may touch and ADR-51 for the plan it joins.
- Status: Accepted, implemented in #700, from the maintainer's choice of option (b) in #649 (item 1 of the code audit of 2026-11-04). Narrows ADR-41 decision 6 for agents: "or ask your agent to add it" now holds only for a folder inside the mount. The web UI keeps every power ADR-41 and ADR-44 describe.
- Context: A local Vault is any folder the process can read, and the registry refuses only Hatchdoor's own state, cache and settings directories (ADR-41's evidence,
ensure_outside_instance_state). The HTTP API and the MCP toolscreate_vaultandedit_vaultcall the same management core (ADR-19), so an agent could register any reachable folder. Notes are untrusted text (the agent guide says so), and a note can carry instructions planted for an agent. An agent that obeyed one could register/etc, a home folder or another application's data as a Vault, then read and write there through the ordinary note tools. Anexisting_gitVault inlocal_historymode goes further: Hatchdoor creates a Git repository in the folder. Three options were weighed in #649: leave it, refuse agents outside the mount, or refuse everyone outside it. The maintainer kept the power for a signed-in person and took it from agents. - Decision:
- Over MCP, a local folder must sit inside the mount. A
create_vaultwhose source names a folder on this machine,local(path) orexisting_git(repository_path), is refused unless that folder, after resolving symlinks and.., is the folderVAULT_PATHnames or sits inside it. The mount is resolved the same way. Anexisting_gitVault's subdirectory already has to stay inside its repository, so checking the repository covers the folder Hatchdoor reads. - An edit is checked only when it moves the folder.
edit_vaultis refused under the same rule when the resolved folder it names differs from the one the Vault has: its path, or its repository and the folder Hatchdoor reads inside it. The saved folder is compared as the registry saved it, not resolved again, so a symlink that appeared there since cannot make an outside folder look unchanged. Changing the kind of source on the same folder,localtoexisting_gitor back, counts as a move: on a folder outside the mount it would let an agent make Hatchdoor create a Git repository there. A Vault that already lies outside the mount, added from the web UI, keeps working over MCP for every other field, and an agent can resend its path unchanged. The rule is checked once before the registry is touched, so a folder outside the mount is refused before Hatchdoor says whether it exists, and again against the definition the registry is about to replace, so a concurrent change cannot slip past it. - The refusal is its own code.
vault_path_outside_mount, not retryable, and its message names the mount and says the maintainer can add the folder from Settings in the web app. - Managed Git is unaffected. Hatchdoor places a managed checkout in its own state folder, so no agent-supplied path is involved.
- The web UI and HTTP API are unchanged. The rule is chosen by the caller of the management core: the MCP tools ask for it, the HTTP routes do not. HTTP never returns the new code; its status table maps it to
403only because every management code must have one. - Reads and writes inside existing Vaults are unchanged. The rule governs which folder a Vault names, not what an agent may do in a Vault it can already reach.
- Over MCP, a local folder must sit inside the mount. A
- Consequences: A planted instruction can no longer make an agent open a folder outside the mount. An operator who wants an agent to manage a Vault elsewhere adds it once from Settings, or mounts the folder under
VAULT_PATH; the agent then manages it like any other. The check resolves the path and the registry resolves it again when it saves, so someone who can swap a folder inside the mount for a symlink between the two could redirect it; that person can already write to the mount, as ADR-44 notes for its own check. An agent can still learn that the mount exists and what it is called, whichlist_vaultsalready shows. Letting an MCP tool register or repoint a local folder outside the mount, or restricting the web UI the same way, needs a superseding record. - Evidence: issue #700 and its agent brief; #649 item 1.
src/vault_management.rs(VaultCollectionManagement::within_vault_mount,ensure_folder_inside_mount, thevault_path_outside_mountrefusal and its tests);src/mcp/tools/read.rs(create_vault_tool,edit_vault_tooland their descriptions);src/handlers/vaults.rs(the status table);canonical_or_normalizedinsrc/vault_registry.rs, shared for the resolution;AppState::vault_mount_root, the mount ADR-41 lists.