docs: re-author the three specs into docs/, plain style, anchors kept

ADRs/0001-design-docs-are-normative.md

@@ -1,7 +1,7 @@
 # ADR-0001 — Design docs are normative; the code is a projection of them
 
 - **Status:** Accepted · 2026-06-28
-- **Refs:** `design/invariants.md`
+- **Refs:** `docs/invariants.md`
 
 ## Context
 
@@ -10,7 +10,7 @@ redefine what the product promises. Prose that merely *describes* the code canno
 
 ## Decision
 
-- `design/invariants.md` is the **normative register** — one testable claim per entry, cited
+- `docs/invariants.md` is the **normative register** — one testable claim per entry, cited
   by id (S2, G2, D1…). **On conflict with any other doc or with the code, the register wins** and
   the other side gets fixed.
 - `data-model.md` is the *what*, `index-engine.md` the *how*. Code comments cite them by section.

ADRs/0013-model-quality-is-measured-out-of-ci.md

@@ -1,7 +1,7 @@
 # ADR-0013 — Model quality is measured out of CI, by a labelled harness
 
 - **Status:** Accepted · 2026-07-13
-- **Refs:** invariants E2 · `crates/b2-embed/evals/README.md` (the process rules) · GH #44, #141, #187
+- **Refs:** invariants E2 · `docs/evals.md` (the process rules) · GH #44, #141, #187
 
 ## Context
 

ADRs/README.md

@@ -7,7 +7,7 @@ an ADR. Feature history lives in [GitHub Issues](https://github.com/AlteredCraft
 **Keep them terse** — Context / Decision / Consequences, a page at most. When a decision is
 overturned, mark the old ADR `Superseded by ADR-NNNN` and write a new one; never edit history.
 
-Normative detail lives in `design/invariants.md` (the register — it wins on conflict); these
+Normative detail lives in `docs/invariants.md` (the register — it wins on conflict); these
 records say *why* an entry reads the way it does.
 
 | # | Decision |

CLAUDE.md

@@ -16,11 +16,11 @@ constantly (`data-model.md §2`, `index-engine.md §6`, invariant ids like `S2`,
 
 | Source | Role |
 |---|---|
-| [`design/invariants.md`](design/invariants.md) | The **invariant register** — the normative list of what must always be true, cited by id. **On conflict with any other doc, it wins.** |
-| [`design/data-model.md`](design/data-model.md) | The *what*: note + connection in Markdown, the two storage tiers, the relation vocabulary. |
-| [`design/index-engine.md`](design/index-engine.md) | The *how*: the SQLite (FTS5 + in-process vector scan) projection, table DDL, data flows. |
+| [`docs/invariants.md`](docs/invariants.md) | The **invariant register** — the normative list of what must always be true, cited by id. **On conflict with any other doc, it wins.** |
+| [`docs/data-model.md`](docs/data-model.md) | The *what*: note + connection in Markdown, the two storage tiers, the relation vocabulary. |
+| [`docs/index-engine.md`](docs/index-engine.md) | The *how*: the SQLite (FTS5 + in-process vector scan) projection, table DDL, data flows. |
 | [`ADRs/`](ADRs/README.md) | **Architecture Decision Records** — why each of the above reads the way it does. Key architectural choices only, terse. Add one when a decision is expensive to reverse and its *why* isn't readable off the code; do **not** add one per feature or bug. |
-| [`crates/b2-embed/evals/README.md`](crates/b2-embed/evals/README.md) | The **eval suite guide** — every instrument, how to read its output, the exit gate, the verdict record, and the **process rules**; read before touching the corpus, the labels, or the metrics. |
+| [`docs/evals.md`](docs/evals.md) | The **eval suite guide** — every instrument, how to read its output, the exit gate, the verdict record, and the **process rules**; read before touching the corpus, the labels, or the metrics. |
 | [GitHub Issues](https://github.com/AlteredCraft/B2/issues) | Backlog and planned work. Decision history = the issue that drove a verdict + the commit that shipped it. |
 
 ## Commands

Cargo.toml

@@ -9,17 +9,17 @@ members = [
 ]
 
 # B2 — local-first Markdown PKM with AI connection discovery.
-# Design lives in design/; this workspace is the index engine
-# (design/index-engine.md), built step 0→5 against the
-# golden-vault fixtures in fixtures/golden-vault/ (design/data-model.md §8).
+# Design lives in docs/; this workspace is the index engine
+# (docs/index-engine.md), built step 0→5 against the
+# golden-vault fixtures in fixtures/golden-vault/ (docs/data-model.md §8).
 
 # Build DEPENDENCIES optimized even in dev/debug builds, while keeping our own `b2-*`
 # crates at opt-level 0 so the TDD loop and `cargo test -p b2-core` stay fast. Candle's
 # embedder forward pass (matmul + transformer ops, spread across candle *and* its gemm
 # matmul backend) is ~13× slower unoptimized, so a plain `tauri dev` / `cargo run`
 # reindex was painfully slow (a 16-chunk embed batch took ~35s instead of ~2.5s). That
 # mattered doubly for the desktop app: a reindex cancel is only observed at each embed-
-# batch boundary (design/index-engine.md), so a slow batch made the
+# batch boundary (docs/index-engine.md), so a slow batch made the
 # **Cancel** button feel stuck. The `"*"` glob optimizes every dependency (targeting
 # just the candle crates missed the matmul backend and left it ~4× slower); the per-
 # crate opt-0 overrides below exclude our own crates so their rebuilds stay instant.

Makefile

@@ -250,7 +250,7 @@ coverage-app: ui-build ## Coverage for the desktop host's own unit tests.
 # *sensitivity* rather than model quality, so it is machine-independent (fake embedder) and
 # needs no model — but it is the other half of the same harness (GH #141).
 #
-# **crates/b2-embed/evals/README.md is the guide**: what each instrument measures, how to
+# **docs/evals.md is the guide**: what each instrument measures, how to
 # read every block it prints, the exit gate, and the process rules that bind any edit to the
 # corpora, the labels, or the metrics. The recipe comments here stay operational only.
 

README.md

@@ -22,7 +22,7 @@ explained connections between them yourself.
 > the fake stays the CI default). **Connection discovery** ships as **`b2 similar`** (surface the
 > nearest *unlinked* notes — local, free, no model call) **+ `b2 link`** (you commit a typed relation
 > to frontmatter) — the human is the precision gate; there is no LLM in the loop. A tour
-> grounded in the test suite: [docs/architecture.html](docs/architecture.html).
+> grounded in the test suite: [docs/architecture.md](docs/architecture.md).
 >
 > **Grounded chat is live in the CLI** — **`b2 ask "…"`** and **`b2 chat`** answer questions *from your
 > notes*, streaming, with `[n]` citations back to the notes the answer came from
@@ -53,12 +53,12 @@ connected yet** — so the structure of your knowledge grows as you link them, i
 The files stay plain Markdown on your disk, yours forever; B2 is the **intelligence layer over them,
 not a container around them**. Humans and AI agents are both first-class users.
 
-Full motivation, scope, and locked decisions: **[design/invariants.md](design/invariants.md)**.
+Full motivation, scope, and locked decisions: **[docs/invariants.md](docs/invariants.md)**.
 
 ## How we build it
 
 Two architectural tenets shape every decision (full text:
-[design/invariants.md](design/invariants.md)):
+[docs/invariants.md](docs/invariants.md)):
 
 - **A volatile vault over a disposable index.** Refactor fearlessly — move, split, merge, compress,
   trim orphans. The index is a pure projection of your vault (drop it, rebuild it identical);
@@ -70,26 +70,26 @@ Two architectural tenets shape every decision (full text:
 
 …in service of five product non-negotiables — plain-Markdown source of truth · local-first · zero
 lock-in · AI-native (not bolted-on) · single binary
-([design/invariants.md](design/invariants.md)).
+([docs/invariants.md](docs/invariants.md)).
 
 ## The docs
 
-### HTML guides — [alteredcraft.github.io/B2](https://alteredcraft.github.io/B2/)
-
-New here? Start with the **[Quick start](https://alteredcraft.github.io/B2/quickstart.html)** — set up
-and work with a vault in about ten minutes. Then go deeper:
-[system architecture](https://alteredcraft.github.io/B2/architecture.html) ·
-[indexing pipeline](https://alteredcraft.github.io/B2/indexing.html) ·
-[the retrieval deep dive](https://alteredcraft.github.io/B2/retrieval.html) ·
-[search & similarity, in plain language](https://alteredcraft.github.io/B2/search-and-similarity.html).
+Everything lives in [docs/](docs/README.md) — one page per topic, and that page is the map.
+New here? Start with the **[Quick start](docs/quickstart.md)** — set up and work with a vault
+in about ten minutes. Then go deeper:
+[architecture](docs/architecture.md) ·
+[search & similarity, in plain language](docs/search-and-similarity.md).
 
 | Doc | What it owns |
 |---|---|
-| [design/invariants.md](design/invariants.md) | The **invariant register** — the one-page normative list of what must always be true, and the source of *why*, cited by id. On conflict with any other doc, it wins. |
-| [design/data-model.md](design/data-model.md) | What a **note** and a **connection** are, in plain Markdown · the two storage tiers · the relation vocabulary · the invariant *definitions*. The canonical *what*. |
-| [design/index-engine.md](design/index-engine.md) | How the derived index is *built* — SQLite (FTS5 + an in-process vector scan) as a disposable projection. The canonical *how*. |
+| [docs/invariants.md](docs/invariants.md) | The **invariant register** — the one-page normative list of what must always be true, and the source of *why*, cited by id. On conflict with any other doc, it wins. |
+| [docs/data-model.md](docs/data-model.md) | What a **note** and a **connection** are, in plain Markdown · the two storage tiers · the relation vocabulary · the invariant *definitions*. The canonical *what*. |
+| [docs/index-engine.md](docs/index-engine.md) | How the derived index is *built* and queried — SQLite (FTS5 + an in-process vector scan) as a disposable projection, and the four flows over it. The canonical *how*. |
+| [docs/quickstart.md](docs/quickstart.md) | Set up and use B2: the walkthrough, the command reference, config and every environment variable. |
+| [docs/architecture.md](docs/architecture.md) | How the system is built: the crates, the flows, the seams, the tests. |
+| [docs/search-and-similarity.md](docs/search-and-similarity.md) | What search and the related-notes panel do, in plain language, for everyone who uses B2. |
 | [ADRs/](ADRs/README.md) | **Architecture Decision Records** — one terse record per key architectural choice: the context, the ruling, and what it costs. The *why* behind the register's entries. |
-| [crates/b2-embed/evals/README.md](crates/b2-embed/evals/README.md) | The **eval suite guide** — every instrument and how to read it, corpora, labels, the exit gate, process rules, and the record of every measured verdict. Lives beside the corpus it governs. |
+| [docs/evals.md](docs/evals.md) | The **eval suite guide** — every instrument and how to read it, corpora, labels, the exit gate, process rules, and the record of every measured verdict. |
 
 Planned work and the backlog live in [GitHub Issues](https://github.com/AlteredCraft/B2/issues); shipped build history lives in git.
 
@@ -172,4 +172,4 @@ Point B2 at a vault with `-C <path>` (a.k.a. `--vault`) on any command, or set `
 every command finds it without the flag (an explicit `-C` wins). Read-only commands (`search`,
 `neighbors`, …) fall back to the current dir; commands that write (`reindex`, `add`, `mv`, `link`) require an
 explicit vault and refuse otherwise, so they can't silently touch the wrong place. Full walkthrough:
-**[Quick start](https://alteredcraft.github.io/B2/quickstart.html)**.
+**[Quick start](docs/quickstart.md)**.

crates/b2-desktop/CLAUDE.md

@@ -40,7 +40,7 @@ what makes that architecture pay off:
 - **Inherited tests.** A thin host means the façade's existing suite already covers the behavior; this crate
   needs only a few per-command tests (args in → right façade call → view out). Logic here would need its own
   parallel tests that the CLI already has.
-- **The promise stays true.** [invariants.md](../../design/invariants.md) (E3) says the GUI is "a
+- **The promise stays true.** [invariants.md](../../docs/invariants.md) (E3) says the GUI is "a
   second dumb adapter over the same contract, inheriting every test the CLI bought." That is only true while
   this crate stays dumb. Thinness is not tidiness; it's the load-bearing property.
 
@@ -108,7 +108,7 @@ add a UI concern to `b2-core`, that's the signal you're putting logic in the wro
 
 ## The keyboard contract (invariant K1)
 
-[invariants.md](../../design/invariants.md) **K1** — *B2 is fully operable from the keyboard; the
+[invariants.md](../../docs/invariants.md) **K1** — *B2 is fully operable from the keyboard; the
 mouse is an accelerator, never a requirement* — names this file as its elaboration home. This is it.
 K1 governs the **GUI**: the `b2` CLI satisfies it by nature, so everything below is about
 `b2-desktop` + [`ui/`](../../ui) ([#78](https://github.com/AlteredCraft/B2/issues/78)).
@@ -293,7 +293,7 @@ Every new surface owes all four. They are cheap while you're building it and exp
 
 ## The rendering trust boundary (invariant E5)
 
-[invariants.md](../../design/invariants.md) **E5** — *note content is untrusted input; rendering is a
+[invariants.md](../../docs/invariants.md) **E5** — *note content is untrusted input; rendering is a
 trust boundary* — names this file as its elaboration home, the way K1 does above. E5 governs the **GUI**:
 the `b2` CLI prints text, so nothing there parses into a document
 ([#77](https://github.com/AlteredCraft/B2/issues/77)).