2.0 docs: delete most docs and reorganize by layer (core, engine, control, api)

Start with docs/architecture/README.md and docs/architecture/_templates/topic.md, then compare the current tree with the target layout in the issue. Use the named crate and source-folder boundaries to guide consolidation, and check links and generated-page tooling where the plan calls them out. Done means the documented layout, page budgets, and standard page shape match the plan, with the specified deletions and moves completed.

Goal

Cut the documentation on layerfs_v2_0_0 down to what a contributor or user needs today, and organize what survives by layer — core, engine, control, api — and their sub-topics, each grounded in a crate or source-folder boundary.

1. Most docs are deleted. Git history plus an archive tag keep them readable.
2. What survives is one tree per layer, with a fixed page shape and a hard page budget.

Snapshot audited: layerfs_v2_0_0 at af2ad92bce. Three read-only audits (deletion; core+engine topics; control+api topics) plus a cross-review round between the two topic audits produced this plan. Counts are .md files and lines on that snapshot.

Size today and after

	Files	Lines
All Markdown on the branch	1,849	~354k
docs/architecture/ (the current layer tree)	229	~33k
Everything else	1,620	~322k
→ delete outright	1,275	~232k
→ fold into an architecture page or the guide, then delete	261	~75k
→ survives (kept, moved or rewritten)	84	~14k
docs/architecture/ pages after the rewrite (below)	229 → ~78

About 3,600 non-Markdown evidence files (json, sh, log, jsonl, 49 .rs) leave with the deleted folders (~43 MB under core/docs/issues, ~9 MB under docs/release-notes and docs/research). Production LOC is unaffected (tools/production_loc.py counts only */crates/*/src); every commit in this work reports an unchanged total, delta 0.

Target layout

docs/
  README.md            one index: guide, the four layers, flows, process
  guide/               user how-to (today docs/versioned/2.0.0, unversioned)   [owner decision Q3]
  architecture/        core / engine / control / api + flows + glossary
  process/             documentation, release, measurement, cleanup, worktrees   [owner decision Q2]
  plugins/             unchanged (website and plugin_check.py depend on the path)
  assets/

Everything under core/docs/, docs/versioned/, docs/release-notes/, docs/releases/, docs/research/ and docs/general/ goes (fold first where listed).

Architecture sub-topics

Each topic is a folder with one README.md and at most 2 extra pages; an extra page must map to a code directory of ~2.5k LOC or more, a separate crate or a backend. Two named exceptions: engine/store/ (3 extras: SQLite, PostgreSQL, diagnostics) and api/sdk/ (one generated page per call family).

Docs tree, not production source, so no LOC column. + new, - removed, space kept (possibly rewritten).

  docs/architecture/
    README.md                  (layer table, flows index, the standard page shape; no prev/next chain)
    glossary.md                (one row per term → owning topic; separate rows for Physical storage / Store / Store record)
    _templates/
      README.md
-     component.md             (one topic.md in the standard shape)
      topic.md
    flows/                     (cross-layer: steps and links only, no component internals)
      README.md
      call.md                  (links the "where each call runs" table in control/README.md)
      init.md
      workspace.md
      commit.md
      merge.md
-     backup.md                (moves to control/backups)
    core/
      README.md                (+ "which root you hold" stack from cluster_one_handbook §2)
      objects/                 (layerfs-content object/, contract/)
        README.md              (merges identity, kinds, access)
      files/                   (layerfs-content file/)
        README.md              (merges chunking, construction, reads-and-views)
        edits.md               (file/edit, file/mapping)
      filesystem-trees/        (layerfs-content filesystem/)
        README.md              (merges representation, attributes-and-links)
        updates.md
        validation.md
      compare-and-merge/       (layerfs-content compare/, merge/)
        README.md
        merge.md
      physical-storage/        (layerfs-storage; name kept to avoid Storage/Store/stores clash)
        README.md              (merges packs, saves, reads, ports; + cas_cdc §6/§8 reuse and read-cost table)
        encoding.md            (encoding/ delta, pool, pack_cache)
-     history-model/
+     history/                 (layerfs-history; renamed to the crate)
+       README.md              (merges entities, catalog-and-queries, allocation)
      telemetry/               (layerfs-telemetry)
        README.md              (merges timers, runtime, output, crate USAGE.md; + "who records" table of engine timing roots)
    engine/
      README.md
      store/                   (layerfs-persistence)
        README.md              (merges lifecycle, backends, history-publication, metadata-and-objects)
        sqlite.md
        postgresql.md          (+ PostgreSQL authority from postgresql-diagnostics)
        diagnostics.md         (merges diagnostic-coverage, postgresql-diagnostics; persistence diagnostic/)
      store-calls/             (layerfs-store-service read/, write/, history/, methods/, operator/)
        README.md              (merges service, writes, branches, sdk-facade; + core/docs/issues/352/DIRECT_STORE.md)
        reads.md
      project-init/            (layerfs-project)
        README.md              (merges import, construction, seal-and-install)
      overlay/                 (layerfs-overlay + store-service overlay/ roster and lock)
        README.md              (merges database, namespace, open-state, operation-records; + explicit roster/lock section)
        payload.md
        lifetimes.md           (was lifetimes-and-reclamation.md)
      workspace/               (layerfs-workspace base/, operations/, mutation/, ports/)
        README.md              (merges base, mutation, state, ports)
        operations.md
      commit/                  (workspace construction/ + store-service store/commit*, install)
        README.md              (merges capture, publish-and-merge, install)
        construction.md
      kernel-routes/           (layerfs-mount-ports, layerfs-fuse, layerfs-nfs)
        README.md              (merges ports, coherence)
        fuse.md                (+ fuser-patches; patch provenance rules stay in engine/AGENTS.md)
        nfs.md                 (+ docs/general/sqlite-on-network-filesystems.md)
+     bridge/                  (layerfs-bridge: wire contract once; control and api only link it)
+       README.md              (duplex, auth/handshake, control and SDK records, daemon_setup, provision, process, network)
      daemon/                  (layerfs-daemon)
        README.md              (merges startup, operator)
        control-calls.md       (+ forced-teardown)
    control/
      README.md                (crate chain picture; the single "where each call runs" table; sealed-trait extension points)
+     home/                    (layerfs-home)
+       README.md              (layout, records, locks, op intent, names, secrets, trace, call log; from management/home-and-records)
+       migration.md           (layerfs-control migrate/, inventory.rs)
      machines/                (layerfs-machine + layerfs-platform)
        README.md              (absorbs adapter, platforms-and-profiles)
+       platforms.md           (native, docker, apple_container, lima + support matrix/SUPPORT.json; absorbs platforms/*, adding-a-platform, support-matrix/*)
+       workers-and-reach.md   (machine worker/, control worker_server, platform setup/, reach.rs, forwards; absorbs routing/workers, network/*)
+     stores-and-projects/     (layerfs-store except backup/; control store.rs, project.rs)
+       README.md              (records, placement, leases, resolve; design now scattered over sdk/store/* and management/families)
+       sqlite-and-postgresql.md  (sqlite/ transfer, postgresql/ connect/attach; + network/credentials)
+       projects.md            (layerfs-store project/)
      sandboxes/               (layerfs-sandbox + layerfs-sandbox-backend)
        README.md
+       daemon-channel-and-exec.md  (daemon/, exec/, route.rs, direct.rs: caller side only, links engine/bridge)
        backends.md            (absorbs native-and-namespaces, adding-a-backend, docker.md record rule, PROVIDERS.md)
      backups/                 (layerfs-store backup/ + layerfs-bucket)
        README.md              (absorbs backup-and-restore, pieces-and-manifest, flows/backup.md)
        buckets.md             (+ tested-provider facts from docs/general/backups-minio-r2.md)
+     doctor/                  (layerfs-control doctor/, layerfs-api doctor/, layerfs-cli doctor.rs)
+       README.md              (target table; absorbs doctor-{host,machine,sandbox,backup}.md)
+       checks.md              (scan, checks, report, workers, capacity)
-     management/              (catch-all; split into home/, stores-and-projects/, doctor/; doctor-remaining-spec.md is historical)
-     routing/                 (no crate; table → control/README, workers → machines/, daemon channel → sandboxes/)
-     network/                 (no crate; → machines/workers-and-reach, stores-and-projects/)
-     support-matrix/          (→ machines/platforms.md)
    api/
      README.md                (layerfs-api shape; calling conventions once: names, options, answers, paging, scope)
+     calls/                   (layerfs-api calls/)
+       README.md              (table, check, scope, keys, dispatch, render)
+       errors-and-events.md   (current parts of call-table errors/events only)
+       coverage.md            (moved; gen-coverage.mjs path updated)
-     call-table/
      sdk/
        README.md              (index; call/family count stated once and checked)
+       backup.md              (one page per family: generated signature block per call + hand-written Returns/Errors/Notes)
+       branch.md              (+ saved-queries.md)
+       commit.md
+       file.md                (+ saved-queries.md)
+       logs.md
+       machine.md
+       project.md
+       sandbox.md
+       store.md
+       workspace.md
-       <family>/<call>.md     (70 per-call pages)
-       <family>/README.md     (10 family READMEs)
-       saved-queries.md
      front-ends/
        README.md              (shared model + CLI (layerfs-cli, api/cli) + packaging/release from cli-release.md, npm-release.md)
+       bindings.md            (layerfs-node + api/node, layerfs-python + api/python; absorbs node.md, python.md)
        mcp.md                 (api/mcp; generated profile block kept)
-       cli.md
-       node.md
-       python.md

Page counts (layer README included): core 30 → 13, engine 53 → 21, control 41 → 16, api 93 → 18 (10 of them generated family pages), flows 7 → 6.

Standard topic page

README.md, in this order, ≲300 lines:

1. Title, one-sentence purpose, Status line
2. Facts — crates and source folders, uses, used by, flows
3. Picture — one ASCII diagram, ≤80 columns
4. What it does — behaviour table, a source link on every row
5. Invariants — rule and what enforces it
6. Limits and failures — value or error, and source
7. Tests — test or example, exact command, platform
8. Pages — only when extra pages exist

Extra page (≲250 lines): one-line purpose, one ## per code sub-module (diagram, table, prose), Related.

Dropped everywhere: breadcrumbs, the previous/up/next chain, "Earlier material", per-page history, receipts and "what was run / not run" sections. Merging means cutting, not concatenating.

What goes, what folds

Delete outright

• core/docs/issues/* — closed historical folders: 232, 236, 237, 241, 243, 245, 252, 284, 286, 301, 316, 318, 319, 327, 334, 337, 340, 342, 347, 353, 354, 355, 373, 428, 460, 463, 496, 506, 511, 527, 529, 536, 537, 540, 659, project-7, project-53, project-137; plus 302 and 320 after fixing the one link each (layerfs-persistence/README.md, engine/AGENTS.md:196).
• core/docs/issues/307 and 321 except the fuser decision records (see breakage 1).
• core/docs/issues/352 except DIRECT_STORE.md (folds into engine/store-calls).
• core/docs/benchmark/ (fs-bench-pro lives in layerfs-benchmark and is frozen) [Q8], core/docs/api/ (stale "proposal" banner).
• docs/versioned/0.1.0–0.1.7, docs/release-notes/**, docs/releases/** — tags and GitHub Releases hold them [Q9 for 1.1.0].
• docs/research/**.
• docs/general/: sdk.md (pinned to sdk-refactor), workspace-queue-scheduling.md (archived), workspace-filesystem-view.md (§5 contradicts the per-Workspace overlay since #321), symlink-hardlinks.md (covered by filesystem-trees), sandbox-cache-design.md (stale; one invariant row → engine/workspace), optimization-guide.md, optimization-handbook.md, artifact-qualification-2.0.0.md, interface-report-2.0.0.md (fold their known gaps into guide/limitations.md, then re-point the 9 links).
• api/crates/layerfs-api/PROVIDERS.md (stale), docs/architecture/control/management/doctor-remaining-spec.md (historical spec).
• docs/versioned/2.0.0/calls.md (645 lines duplicating the SDK reference, still says "61 calls") → link to architecture/api/sdk/.

Fold, then delete

Source	Into
core/docs/architecture/ numbered papers 01–86, proposal/, deferred/ (185 files)	Already mapped by docs/architecture READMEs for 59 papers. 27 papers are unmapped (06, 11, 14, 23, 28, 33–35, 37, 38, 40, 42, 46, 48, 49-scratch, 51–53, 55–59, 66, 68, 71, 74): confirm obsolete or assign a topic before deleting. 68 and 74 are cited by engine/AGENTS.md.
core/docs/issues/303 (AGENTS.md still calls it the "current design index"; its own banner says "Proposal; target 0.1.7")	engine/daemon, overlay, kernel-routes, store-calls
core/docs/issues/533 README + DECISIONS (2.0 work order)	the architecture pages that own each decision
core/docs/issues/535 README; project-113/machines-live/RESULTS.md	control/machines; receipts per Q5
core/docs/proposals/{compute-plane-2.0, host-platform-connections, layerfs-sdk-cli}	control/, api/
docs/general/cluster_one_handbook.md §2	core/README.md
docs/general/cas_cdc_deltaencoding_handbook.md §6, §8	core/physical-storage/README.md
docs/general/concepts.md	glossary.md + guide
docs/general/backups-minio-r2.md	guide (setup) + control/backups/buckets.md (tested providers)
docs/general/sqlite-on-network-filesystems.md	engine/kernel-routes/nfs.md (+ guide for user steps)
docs/general/{cli,npm}-release.md	api/front-ends/README.md
Crate READMEs: layerfs-content, layerfs-storage, layerfs-telemetry (+ USAGE.md), layerfs-persistence (~1,000 lines)	matching topic; leave a 1–3 line pointer [Q10]
control/crates/layerfs-sandbox-backend/PROVIDERS.md	control/sandboxes/backends.md

Keep

Package READMEs (api/{node,python,cli}: packaging tests assert they exist), plugins/*, docs/plugins/, .agents/skills/** (fix 2 links into 533; consider generating layerfs-js-sdk/references/methods/* from the SDK reference), engine/patches/fuser-0.18.0/README.md, engine/vendor/** (third-party, untouched), the five AGENTS.md files (rewritten), root/layer READMEs (rewritten as pointers).

Breakage to handle in the same change

1. Fuser provenance guard. engine/patches/fuser-0.18.0/lifecycle-provenance.json:4 and receive-buffer-provenance.json:4 point at core/docs/issues/307/FUSER-LIFECYCLE-DECISION-20261008.md and core/docs/issues/321/FUSER-RECEIVE-BUFFER-DECISION-20261014.md; the JSON bytes are pinned by checksums in tools/check_fuser_integrity.py:30,33 (run in CI). Either keep the fuser records at their paths, or move all four (+ FUSER-REGISTRY-PATCH-20261006, FUSER-OFFICIAL-CANDIDATE-20261006) under engine/patches/fuser-0.18.0/records/ and update the JSON and checksums together [Q4].
2. SDK guards and generators. api/node/test/branch-file/inventory.mjs requires one sdk/<family>/<call>.md per call and the literal "70 calls in 10 families" → change to one ### family.call heading per call in the family page. api/scripts/gen-coverage.mjs writes call-table/coverage.md → new path. api/mcp/scripts/gen-profiles.mjs writes into front-ends/mcp.md (path unchanged). New: a generated signature block per call with a --check mode.
3. Links from surviving docs into the deletion set: AGENTS.md files 74 distinct targets (307 ×24, docs/general ×17, core/docs/architecture ×16, 303 ×8, …), docs/architecture 116 (core/docs/architecture ×64, 535 ×27, versioned ×12, …), docs/README.md 57 of 59, READMEs 30, 2.0.0 manual 16, skills 2, plugins 1. Rewrite to the new page or to a pinned blob/<archive-tag>/… URL; finish with a link check over every surviving .md.
4. Paths named outside Markdown: tools/linux_bundle.py:15 and plugins/dsh-layerfs/install.md cite docs/general/parallel-worktrees.md; control/crates/layerfs-platform/src/support.rs:5 and engine/crates/layerfs-daemon/tests/fp2_negotiation_flags.rs:4 cite issue folders in comments; ci.yml:27,43 !core/docs/** filters become dead.
5. Already broken today (fix while here): engine/crates/layerfs-daemon/tests/mounted_store_read.rs:6-7 links a nonexistent 73-kernel-read-custody.md; docs/architecture links versioned/2.0.0/{backups,stores,connect,machines}.md, which do not exist.
6. Drifted facts to correct while rewriting: call counts ("61 calls in nine families", "64 calls", "70 calls in 10 families"); the API family table misses logs, stats, attach, detach, commits, get_commit, revision, exec_cancel; api/README.md lists retired machine.connect/disconnect and store.move; control/README.md lists 4 of 8 crates; SDK pages have sections appended after their footer; store/lifecycle.md, project-init and daemon/operator describe Durable as a default — say once that Durable is NOT_RUN — disabled by owner; the 2.0.0 guide's banner says "Proposal; not a released contract".

Rules that need amending first

Deleting contradicts current wording; these must change in the same PR (or before it):

• AGENTS.md:17 "Historical evidence, receipts and verdicts are retained unchanged"; :54-55, :212, :246, :279, :301 (preserve/retain historical receipts and verdicts).
• AGENTS.md:238-242, core/AGENTS.md:24, engine/AGENTS.md:167-169 route cluster-two work through core/docs/issues/303 as the "current design index" → point at docs/architecture/.
• AGENTS.md:365 "List deleted tests in the commit message and the fix record" — fix records lived in core/docs/issues/; new home needed [Q6].
• engine/AGENTS.md:106, 187, 266 (keep receipts with original IDs), :550-601 (fuser authorization records), and its 165-line "Architecture and public contracts" section (move current facts into overlay/workspace, drop history).
• docs/general/documentation-policy.md:8-9, 20, 23-26, 30 (document classes: versioned manuals, general, research, release-notes) → rewrite for the layer layout.
• docs/general/release-policy.md:5-6, 17, 89-90 (one immutable manual per release; immutable release records).
• docs/general/agent-measurement-policy.md:47 (no rewriting a historical receipt).
• docs/architecture/README.md:8, 124 ("read its issue under core/docs/issues"; "older papers stay where they are").

Proposed reading of "retained": git history plus an archive tag (precedent: docs/roadmap/ removed by #398, archive commit 792715f00a cited in documentation-policy.md:10-12).

Owner decisions

• Q1 Retention. Accept "archive tag docs-archive-2.0 + pinned links" as satisfying the retention rules, and reword them?
• Q2 Process docs. Home for documentation/release/measurement/benchmark policy, cleanup and parallel worktrees: docs/process/ (proposed), tools/, or measurement rules to layerfs-benchmark?
• Q3 User guide. Is docs/versioned/2.0.0 the surviving guide (status changed from "Proposal")? Proposed home docs/guide/, unversioned, with per-release docs/versioned/ dropped.
• Q4 Fuser records. Keep at current paths (no guard change) or move under engine/patches/fuser-0.18.0/records/ and update the provenance JSON + checksums?
• Q5 Evidence cited by control pages (535 receipts, project-113 RESULTS): pinned URLs or a small kept evidence folder?
• Q6 Fix records and open proposals from now on (e.g. open #379, project#41 GC spec): PR/issue bodies, or an active proposals folder?
• Q7 The 27 unmapped core/docs/architecture papers: confirm obsolete, or assign to topics.
• Q8 Does the fs-bench-pro "frozen" rule cover core/docs/benchmark/fs-bench-pro*?
• Q9 Keep the 1.1.0 release record (holds the major-version waiver)?
• Q10 Crate READMEs: delete, or keep a 1–3 line pointer to the topic?
• Q11 SDK reference: per-family pages with generated signatures replace the 70 per-call pages? Is it user-facing (linked from the guide) or contributor-only?
• Q12 Topic names: history-model → history; control stores-and-projects/ (avoids Storage / Store / stores collisions); engine/bridge/ as its own topic.

Plan (separate PRs on layerfs_v2_0_0)

1. Rules and archive. Owner answers Q1–Q12; tag docs-archive-2.0 at the pre-deletion commit; amend AGENTS.md files, documentation and release policy.
2. Architecture rewrite. Restructure docs/architecture/ to the tree above: merge-by-cutting, standard page shape, fold the listed sources in, fix drifted facts, SDK family pages + generator + guard update.
3. Guide and process. Move the 2.0.0 manual to docs/guide/, drop calls.md; move process docs; rewrite docs/README.md as the one index.
4. Delete. Remove the deletion set and its evidence files; rewrite every surviving link (new page or pinned archive URL); handle the fuser provenance per Q4; drop dead CI path filters.
5. Verify. Link check over every surviving .md; tools/check_fuser_integrity.py; SDK inventory, coverage and MCP generator --check; package tests that assert READMEs; production LOC unchanged (delta 0) in every commit message.

Done when

• No Markdown remains under core/docs/, docs/versioned/, docs/release-notes/, docs/releases/, docs/research/ or docs/general/ (except what Q4/Q5 keep).
• Every architecture topic maps to named crates/folders, follows the standard shape and stays within its page budget; every crate and major source folder has exactly one owning topic.
• Zero broken relative links across surviving docs; guards and generators pass.
• AGENTS.md files and policies no longer require the deleted material.