docs: restructure docs/ tree into user/concepts/design/audits buckets

.github/workflows/post-release-docs-issue.yml

@@ -35,14 +35,14 @@ jobs:
           - [ ] \`README.md\` headline NOTE (\`> v1.0 ships the surface ...\`) reflects anything new in ${TAG} that changes the user-facing pitch
           - [ ] \`README.md\` Install/60-seconds blocks mention any new install-time commands or extras shipped in ${TAG}
           - [ ] \`README.md\` roadmap table — verify next-version row points at the right theme (status flip is gated by CI; theme drift is not)
-          - [ ] \`docs/ROADMAP.md\` — \`## v${version}\` section exists and lists what actually shipped (vs what was originally planned)
-          - [ ] \`docs/ROADMAP.md\` — next-version section reflects scope changes that happened in ${TAG} (deferred items, items pulled in)
-          - [ ] \`docs/RELEASING.md\` — pytest count comment ("~N passing at vX.Y.Z") still in the right ballpark
-          - [ ] \`docs/COMMANDS.md\` — every new CLI subcommand or flag is documented; total command count in the opening line matches
-          - [ ] \`docs/INSTALL.md\` — new optional extras and post-install verification commands present
-          - [ ] \`docs/BENCHMARKS.md\` — "Activation status" version label refreshed if any adapter changed status
-          - [ ] \`docs/LIMITATIONS.md\` — any items resolved by ${TAG} moved out of "known issues at v1.0" into resolved/historical
-          - [ ] \`docs/MCP.md\` / \`docs/SLASH_COMMANDS.md\` — surface counts and new entries reflect ${TAG}
+          - [ ] \`docs/concepts/ROADMAP.md\` — \`## v${version}\` section exists and lists what actually shipped (vs what was originally planned)
+          - [ ] \`docs/concepts/ROADMAP.md\` — next-version section reflects scope changes that happened in ${TAG} (deferred items, items pulled in)
+          - [ ] \`docs/concepts/RELEASING.md\` — pytest count comment ("~N passing at vX.Y.Z") still in the right ballpark
+          - [ ] \`docs/user/COMMANDS.md\` — every new CLI subcommand or flag is documented; total command count in the opening line matches
+          - [ ] \`docs/user/INSTALL.md\` — new optional extras and post-install verification commands present
+          - [ ] \`docs/concepts/BENCHMARKS.md\` — "Activation status" version label refreshed if any adapter changed status
+          - [ ] \`docs/user/LIMITATIONS.md\` — any items resolved by ${TAG} moved out of "known issues at v1.0" into resolved/historical
+          - [ ] \`docs/user/MCP.md\` / \`docs/user/SLASH_COMMANDS.md\` — surface counts and new entries reflect ${TAG}
 
           ## What CI already verified (do not re-check)
 

.github/workflows/replay-soak.yml

@@ -15,7 +15,7 @@ name: Replay Soak
 # scoped to `refs/heads/main` only; `replay-soak-status` is
 # unconstrained, which lets the cron commit and push under the
 # default workflow token without a long-lived signing key or a
-# bypass-roster expansion. See `docs/feature-replay-soak-bot.md`.
+# bypass-roster expansion. See `docs/design/feature-replay-soak-bot.md`.
 
 on:
   schedule:

.github/workflows/staging-gate.yml

@@ -162,8 +162,8 @@ jobs:
             echo "::error file=README.md::Roadmap row for v${head_ver} still says 'next' or 'planned'. Flip status to 'shipped' before cutting the release."
             fail=1
           fi
-          if [ -f docs/ROADMAP.md ] && ! grep -qE "v${head_ver}" docs/ROADMAP.md; then
-            echo "::warning file=docs/ROADMAP.md::No mention of v${head_ver}. Consider adding a section (non-blocking)."
+          if [ -f docs/concepts/ROADMAP.md ] && ! grep -qE "v${head_ver}" docs/concepts/ROADMAP.md; then
+            echo "::warning file=docs/concepts/ROADMAP.md::No mention of v${head_ver}. Consider adding a section (non-blocking)."
           fi
           exit "$fail"
 

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Best categories of PR:
 
 - Bug fixes with a regression test that fails before and passes after.
 - Doc fixes (typo, broken link, stale claim against current code).
-- Closing one of the [known issues at v1.0](docs/LIMITATIONS.md#known-issues-at-v10) — but ping in an issue first to align on approach.
+- Closing one of the [known issues at v1.0](docs/user/LIMITATIONS.md#known-issues-at-v10) — but ping in an issue first to align on approach.
 
 Hard to land without prior alignment:
 
@@ -38,7 +38,7 @@ Don't include `~/.aelfrice/memory.db` from a real project — it contains your p
 
 ## What's likely to land where
 
-The v1.x roadmap is bucketed. See [LIMITATIONS](docs/LIMITATIONS.md#known-issues-at-v10) for each issue's target version.
+The v1.x roadmap is bucketed. See [LIMITATIONS](docs/user/LIMITATIONS.md#known-issues-at-v10) for each issue's target version.
 
 - **v1.0.1** — launch fix-up. Hook → `aelfrice.retrieval.retrieve()` rewrite + `feedback_history` recording (highest-impact gap). `aelf --version` flag. Onboard noise filters. CONTRADICTS auto-supersession. Onboard performance regression baseline.
 - **v1.1.0** — project identity (`.git/aelfrice/memory.db`, `.aelfrice.toml`, orphan-DB cleanup, worktree concurrency). Onboard behavior (git-recency weighting, `agent_inferred` → `user_validated` promotion). Cosmetic surface (edges→threads, split `aelf status` from `aelf health`).

README.md

@@ -13,7 +13,7 @@
 [![CI](https://github.com/robotrocketscience/aelfrice/actions/workflows/ci.yml/badge.svg)](https://github.com/robotrocketscience/aelfrice/actions/workflows/ci.yml)
 [![OSSInsight](https://img.shields.io/badge/OSSInsight-analytics-blue)](https://ossinsight.io/analyze/robotrocketscience/aelfrice)
 <!-- bench-canonical-badge:start -->
-[![Reproducibility](https://img.shields.io/badge/reproducibility-partial%20%286%2F11%20adapters%29-yellow)](docs/v2_reproducibility_harness.md)
+[![Reproducibility](https://img.shields.io/badge/reproducibility-partial%20%286%2F11%20adapters%29-yellow)](docs/design/v2_reproducibility_harness.md)
 <!-- bench-canonical-badge:end -->
 
 You correct your agent. *"Got it,"* it says. Next session, same mistake.
@@ -55,7 +55,7 @@ L2: graph walk       -> typed-edge BFS from L1 seeds (SUPPORTS, CONTRADICTS, SUP
 L2.5: structural HRR -> Plate-FFT bind/probe against anchor text + structural markers
 ```
 
-L0 always ships. L1, L2, and L2.5 are budget-trimmed against the merged candidate set in score-descending order; locked beliefs win every overflow. Default budget: 2,400 tokens per prompt. The default ranking stack is `stack-r1-r3` (entity expansion + per-store IDF clipping); bench evidence on the labelled query-strategy corpus measured **+0.2851 absolute NDCG@k (+94.8%)** versus the v1.4 raw-BM25 baseline at p99 latency 4.5 ms. Full lane wiring, composition, and federation peer DBs: [ARCHITECTURE § Retrieval](docs/ARCHITECTURE.md#retrieval).
+L0 always ships. L1, L2, and L2.5 are budget-trimmed against the merged candidate set in score-descending order; locked beliefs win every overflow. Default budget: 2,400 tokens per prompt. The default ranking stack is `stack-r1-r3` (entity expansion + per-store IDF clipping); bench evidence on the labelled query-strategy corpus measured **+0.2851 absolute NDCG@k (+94.8%)** versus the v1.4 raw-BM25 baseline at p99 latency 4.5 ms. Full lane wiring, composition, and federation peer DBs: [ARCHITECTURE § Retrieval](docs/concepts/ARCHITECTURE.md#retrieval).
 
 The result is prepended to your prompt verbatim:
 
@@ -86,7 +86,7 @@ aelf status                          # quick health summary
 aelf setup / aelf doctor            # initial install + verification
 ```
 
-`aelf --help` shows the everyday surface; `aelf --help --advanced` lists the rest. Full reference: [COMMANDS](docs/COMMANDS.md). The same operations are exposed as MCP tools and `/aelf:*` slash commands — same library underneath. See [MCP](docs/MCP.md) and [SLASH_COMMANDS](docs/SLASH_COMMANDS.md).
+`aelf --help` shows the everyday surface; `aelf --help --advanced` lists the rest. Full reference: [COMMANDS](docs/user/COMMANDS.md). The same operations are exposed as MCP tools and `/aelf:*` slash commands — same library underneath. See [MCP](docs/user/MCP.md) and [SLASH_COMMANDS](docs/user/SLASH_COMMANDS.md).
 
 ---
 
@@ -98,7 +98,7 @@ Two slash commands let the agent reach back into the belief graph mid-turn, beyo
 
 **`/aelf:reason <query>`** — the structured-walk surface. Walks the belief graph from BM25-seeded starting points and emits a typed reasoning trace: hops with edge-type breadcrumbs, a `VERDICT` (`SUFFICIENT` / `INCOMPLETE` / `CONTRADICTED` / `IMPASSE`), `IMPASSES` (typed gaps, ties, or constraint failures), and `SUGGESTED UPDATES` — `(belief_id, direction, note)` rows that map straight to `aelf feedback` so the conclusion closes the loop on the beliefs that fed it. Each impasse is dispatched to a role-tagged subagent (Verifier / Gap-filler / Fork-resolver). Peer hops in foreign federation scopes are annotated `[scope:<name>]`.
 
-The pair-rhythm is the point: `/aelf:wonder` adds fresh thinking to the graph, then `/aelf:reason` draws conclusions across it. Both surfaces are deterministic in the aelfrice layer (verdict classification, impasse derivation, axis generation, suggested-update mapping). The only LLM calls happen when the host agent dispatches a subagent per impasse or research axis — and those calls run under the host's own credentials, not aelfrice's. Specs: [COMMANDS § `wonder`](docs/COMMANDS.md), [COMMANDS § `reason`](docs/COMMANDS.md), [v3.0 wonder+reason parity (#645)](https://github.com/robotrocketscience/aelfrice/issues/645).
+The pair-rhythm is the point: `/aelf:wonder` adds fresh thinking to the graph, then `/aelf:reason` draws conclusions across it. Both surfaces are deterministic in the aelfrice layer (verdict classification, impasse derivation, axis generation, suggested-update mapping). The only LLM calls happen when the host agent dispatches a subagent per impasse or research axis — and those calls run under the host's own credentials, not aelfrice's. Specs: [COMMANDS § `wonder`](docs/user/COMMANDS.md), [COMMANDS § `reason`](docs/user/COMMANDS.md), [v3.0 wonder+reason parity (#645)](https://github.com/robotrocketscience/aelfrice/issues/645).
 
 ---
 
@@ -157,25 +157,25 @@ By that bar, "a vector store with a similarity query" is not a memory system —
 
 Running in the background. No action required after `aelf setup`.
 
-- **Passive capture.** Default-on transcript-ingest, commit-ingest, and session-start hooks. Session activity flows into the belief graph without you typing `aelf` at all; opt out per-hook via `aelf setup --no-transcript-ingest`, `--no-commit-ingest`, `--no-session-start`. See [INSTALL § default-on hooks](docs/INSTALL.md).
+- **Passive capture.** Default-on transcript-ingest, commit-ingest, and session-start hooks. Session activity flows into the belief graph without you typing `aelf` at all; opt out per-hook via `aelf setup --no-transcript-ingest`, `--no-commit-ingest`, `--no-session-start`. See [INSTALL § default-on hooks](docs/user/INSTALL.md).
 - **Determinism.** Stdlib + SQLite. No embeddings, no learned re-rankers, no LLM in the retrieval path. Every result traces to the action that wrote it.
-- **Local-only.** SQLite at `<git-common-dir>/aelfrice/memory.db`. aelfrice itself makes no network calls and emits no telemetry; no accounts. (Subagent LLM dispatches in `/aelf:wonder` / `/aelf:reason` flows do reach the network — under the host agent's credentials, not aelfrice's. The retrieval path stays local.) Per-project isolation by construction. v3.0 ships *read-only* cross-project federation via `knowledge_deps.json` — peer DBs are opened read-only, foreign-id mutations are rejected at the API surface, no multi-writer extension. See [PRIVACY.md](docs/PRIVACY.md).
+- **Local-only.** SQLite at `<git-common-dir>/aelfrice/memory.db`. aelfrice itself makes no network calls and emits no telemetry; no accounts. (Subagent LLM dispatches in `/aelf:wonder` / `/aelf:reason` flows do reach the network — under the host agent's credentials, not aelfrice's. The retrieval path stays local.) Per-project isolation by construction. v3.0 ships *read-only* cross-project federation via `knowledge_deps.json` — peer DBs are opened read-only, foreign-id mutations are rejected at the API surface, no multi-writer extension. See [PRIVACY.md](docs/user/PRIVACY.md).
 - **Removable.** `aelf uninstall --archive backup.aenc` encrypts the DB to a file, then deletes it. Or `--purge` for a full wipe.
 
 ---
 
 ## Status
 
-Latest stable: **v3.0.1** (2026-05-13). Per-entry detail in [CHANGELOG § 3.0.1](CHANGELOG.md). Per-version history: [docs/ROADMAP.md](docs/ROADMAP.md). Known limits: [docs/LIMITATIONS.md](docs/LIMITATIONS.md).
+Latest stable: **v3.0.1** (2026-05-13). Per-entry detail in [CHANGELOG § 3.0.1](CHANGELOG.md). Per-version history: [docs/concepts/ROADMAP.md](docs/concepts/ROADMAP.md). Known limits: [docs/user/LIMITATIONS.md](docs/user/LIMITATIONS.md).
 
 ---
 
 ## Documentation
 
-- **Getting started:** [Install](docs/INSTALL.md) · [Quickstart](docs/QUICKSTART.md)
-- **Reference:** [Commands](docs/COMMANDS.md) · [MCP](docs/MCP.md) · [Slash commands](docs/SLASH_COMMANDS.md) · [Config](docs/CONFIG.md)
-- **Background:** [Architecture](docs/ARCHITECTURE.md) · [Philosophy](docs/PHILOSOPHY.md) · [Privacy](docs/PRIVACY.md) · [Limitations](docs/LIMITATIONS.md)
-- **Development:** [Releasing](docs/RELEASING.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
+- **Getting started:** [Install](docs/user/INSTALL.md) · [Quickstart](docs/user/QUICKSTART.md)
+- **Reference:** [Commands](docs/user/COMMANDS.md) · [MCP](docs/user/MCP.md) · [Slash commands](docs/user/SLASH_COMMANDS.md) · [Config](docs/user/CONFIG.md)
+- **Background:** [Architecture](docs/concepts/ARCHITECTURE.md) · [Philosophy](docs/concepts/PHILOSOPHY.md) · [Privacy](docs/user/PRIVACY.md) · [Limitations](docs/user/LIMITATIONS.md)
+- **Development:** [Releasing](docs/concepts/RELEASING.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md)
 
 ## Citation
 

SECURITY.md

@@ -36,7 +36,7 @@ Out of scope:
 - **All data is local.** Your beliefs live in a single SQLite file at `~/.aelfrice/memory.db` (or `$AELFRICE_DB`). aelfrice does not back this up, sync this, or transmit any portion of it.
 - **Auditable update math.** Every Bayesian update is one function (`apply_feedback`). Every retrieval ordering is one function (`retrieve`). Both are short, plain, and reviewable.
 
-See [docs/PRIVACY.md](docs/PRIVACY.md) for verifiable details.
+See [docs/user/PRIVACY.md](docs/user/PRIVACY.md) for verifiable details.
 
 ## Disclosure
 

benchmarks/bfs_latency_v3.py

@@ -12,7 +12,7 @@
 
 The original #739 body proposed absolute thresholds (p50 ≤ 25 ms,
 p95 ≤ 100 ms) borrowed from the v1.3 acceptance band published in
-``docs/bfs_multihop.md:518-525``. Run 1 (commit 62ce0b3) showed the
+``docs/design/bfs_multihop.md:518-525``. Run 1 (commit 62ce0b3) showed the
 v3.0 baseline alone already exceeds those absolutes — eight+ minors
 of HRR / BM25F / heat / clustering / posterior-rerank work have
 moved the baseline. The gate was reframed to a **delta** criterion

benchmarks/context-rebuilder/eval_harness.py

@@ -1,6 +1,6 @@
 """Context-rebuilder eval harness — skeleton.
 
-Backs docs/context_rebuilder.md. NOT runnable as-is — the TODOs
+Backs docs/design/context_rebuilder.md. NOT runnable as-is — the TODOs
 mark integration points that fill in as the rebuilder
 implementation lands across v1.2.0–v1.4.0. The shape of this file
 is the contract: the spec's acceptance criteria reference these
@@ -246,7 +246,7 @@ def run_rebuilder(
 )
 """Cooperative-reader instruction prepended to every post-clear replay
 prompt (#797). Measurement scope is documented in
-`docs/BENCHMARKS.md` § "Bench measurement scope". Wording is
+`docs/concepts/BENCHMARKS.md` § "Bench measurement scope". Wording is
 deliberately conservative — it tells the reader which atom to anchor
 on, not which atoms to recite. Verbatim-recap wording was rejected
 because it would let any pack containing the named atoms score 1.0
@@ -398,7 +398,7 @@ def replay_post_fork(
     `aelf:replay-eval` skill) can spawn one child task per row,
     prompted with the row's `prompt` field (the canonical post-clear
     replay prompt assembled by `_assemble_post_clear_prompt`, prepending
-    `POST_CLEAR_INSTRUCTION`; see #797 and `docs/BENCHMARKS.md`
+    `POST_CLEAR_INSTRUCTION`; see #797 and `docs/concepts/BENCHMARKS.md`
     § "Bench measurement scope"). The legacy `rebuilt_block` and
     `user_turn` fields remain in the row for inspection. Dispatchers
     are expected to write `<run_dir>/replay_responses.jsonl`. On the

benchmarks/context-rebuilder/judges/llm_judge.py

@@ -8,7 +8,7 @@
 
 ## Contamination protocol
 
-`docs/BENCHMARKS.md` is explicit: generation and scoring run as separate
+`docs/concepts/BENCHMARKS.md` is explicit: generation and scoring run as separate
 passes, and **the judge never sees the retrieval context.** The request
 schema therefore carries only `(turn_idx, expected, actual)` — not the
 rebuilt block, not the user turn. Including the rebuilt block in the

benchmarks/context_rebuilder/__init__.py

@@ -21,7 +21,7 @@
   * `measure.token_budget_delta(...)` / `measure.hook_latency_ms(...)`
     -- the two scaffolding metrics.
 
-Per `docs/eval_fixture_policy.md`: synthetic fixtures only on the
+Per `docs/design/eval_fixture_policy.md`: synthetic fixtures only on the
 public-repo path. Captured fixtures live lab-side and never gate CI.
 """
 from __future__ import annotations

benchmarks/context_rebuilder/calibrate.py

@@ -6,7 +6,7 @@
 `aelfrice.context_rebuilder.DEFAULT_THRESHOLD_FRACTION`.
 
 The threshold default MUST come from this measurement, not from a
-hand-picked number. See `docs/context_rebuilder.md § Threshold
+hand-picked number. See `docs/design/context_rebuilder.md § Threshold
 calibration` for the chosen value and rationale.
 
 ## Method

benchmarks/context_rebuilder/dynamic_probe.py

@@ -304,7 +304,7 @@ def probe(fixture: Path) -> DynamicProbeResult:
             f"no candidate clears the v1.4 ship-gate "
             f"(>= {DYNAMIC_FIDELITY_MARGIN} absolute fidelity at "
             f"same-or-lower token cost). Measurements: {deltas}. "
-            f"Parked for v1.5; see docs/context_rebuilder.md "
+            f"Parked for v1.5; see docs/design/context_rebuilder.md "
             f"§ Dynamic mode (parked v1.5)."
         )
 

benchmarks/context_rebuilder/kappa.py

@@ -3,7 +3,7 @@
 Computes pairwise inter-judge κ across N≥3 independent judge runs over
 the same `(expected, actual)` pairs, plus a judge-vs-baseline κ where
 the baseline is the zero-LLM substring-exact-match path. Emits the
-`judge_kappa.json` artifact specified in `docs/BENCHMARKS.md
+`judge_kappa.json` artifact specified in `docs/concepts/BENCHMARKS.md
 §Eval-judge calibration` (PR #700).
 
 Inputs are judge-response JSONL files in the shape written by
@@ -183,7 +183,7 @@ def compute_kappa_report(
     """Build the κ report from N judge runs and an optional baseline.
 
     The report's `calibrated` boolean encodes the gate from
-    `docs/BENCHMARKS.md §Eval-judge calibration`:
+    `docs/concepts/BENCHMARKS.md §Eval-judge calibration`:
 
     - inter_judge_kappa.min ≥ 0.70
     - hot_start_fidelity_mean ≥ 0.80
@@ -265,7 +265,7 @@ def compute_kappa_report(
 
 def report_to_json(report: KappaReport) -> dict:
     """Project a KappaReport into the artifact-contract JSON shape
-    documented in `docs/BENCHMARKS.md §Eval-judge calibration`.
+    documented in `docs/concepts/BENCHMARKS.md §Eval-judge calibration`.
 
     Keys match the documented schema exactly so downstream tooling
     (CI gate, release-prep checklist) can rely on stable field names.

benchmarks/context_rebuilder/replay.py

@@ -1,6 +1,6 @@
 """Transcript-replay loader for the context-rebuilder eval harness.
 
-Reads a `turns.jsonl` file (per `docs/transcript_ingest.md` schema)
+Reads a `turns.jsonl` file (per `docs/design/transcript_ingest.md` schema)
 and walks the per-turn agent state, returning a structured
 `ReplayResult` that includes per-turn `token_budget_delta` and
 `hook_latency_ms` measurements.