docs: reorganize per Diátaxis + add OSS root files

Three threads:

1. Drop `docs/spec-audit/` (internal scratch, no longer needed)
   + the in-source-code comment references to its fix-plan
   identifiers (the F-N markers stay; just the broken path
   pointers go).

2. Restructure `docs/` to follow the Diátaxis framework — the
   de-facto OSS doc standard (used by Django, Kubernetes,
   Numpy):

       docs/
       ├── README.md          # Navigation hub (new)
       ├── tutorials/         # Learning-oriented
       ├── guides/            # Task-oriented (install / configure / operate / upgrade / observability)
       ├── reference/         # Info-oriented (new; perf targets, error codes)
       ├── runbooks/          # Operator procedures (RB-1 … RB-11)
       └── development/       # Contributor-oriented (new bucket)
           ├── README.md
           ├── usage/         # Build + run + debug + test (was docs/usage/)
           ├── spec-deviations.md  (was docs/spec-deviations.md)
           └── phases/        # Per-phase plans (was docs/phases/)

   Plus `monitoring/` at repo root (Grafana JSON dashboards
   + Alertmanager rules; was `docs/analytics/` — these are
   deployment assets, not docs). `docs/performance/README.md`
   collapsed into `docs/reference/performance.md`.

3. Add the OSS root files GitHub auto-surfaces:
   - `CONTRIBUTING.md` (new) — spec-first, plan-first
     workflow + invariants + anti-patterns. Points to
     `docs/development/` for the build / test / debug loop.
   - `SECURITY.md` (new) — disclosure policy + threat model.
   - `CODE_OF_CONDUCT.md` (new) — Contributor Covenant v2.1.

Plus housekeeping:
- `RELEASE-NOTES-v1.0.0.md` deleted (CHANGELOG.md has the
  same v1.0.0 entry; single source of truth).
- All cross-references in non-historical files updated via
  `sed` to the new paths. `.claude/plans/` (historical record)
  left untouched. The 4 spec/*/0[78]_references.md files
  carry forward pointers to docs/phases/ — updated to
  docs/development/phases/ to keep them resolving.

Verified:
- `cargo zigbuild --target x86_64-unknown-linux-gnu --workspace` clean.
- `cargo clippy --workspace --all-targets -- -D warnings` clean.
- `bash scripts/spec-link-check.sh` shows only the 7
  pre-existing spec-internal broken links (unchanged from
  before this commit; not introduced by the reorg).

Author: nirajgeorgian

.claude/commands/commit-task.md

@@ -10,7 +10,7 @@ Steps:
 
 1. **Pre-commit verification.** Run `just verify` (or the equivalent `cargo` chain). If it fails, abort the commit and surface the failure — never commit red. Per `AUTONOMY.md` §2 rule 3.
 
-2. **Identify the spec file(s) referenced** in the sub-task. From `docs/phases/phase-NN-*.md`, find the sub-task by ID. Extract the entries from its "Reads:" list.
+2. **Identify the spec file(s) referenced** in the sub-task. From `docs/development/phases/phase-NN-*.md`, find the sub-task by ID. Extract the entries from its "Reads:" list.
 
 3. **Compose the commit message** in the format from `AUTONOMY.md` §5:
 

.claude/commands/next-task.md

@@ -13,7 +13,7 @@ Algorithm:
    - If no `phase-*-complete` tag exists at all, active phase is **Phase 0** (verify scaffolding) or **Phase 1** (start wire protocol) depending on whether `just verify` passes.
 
 2. **Open the relevant phase doc.**
-   - `docs/phases/phase-NN-*.md` — the file matching the active phase.
+   - `docs/development/phases/phase-NN-*.md` — the file matching the active phase.
    - For Phase 0, there is no detailed doc — the work is just `just verify` then tag.
 
 3. **Find the lowest unfinished sub-task.**
@@ -29,7 +29,7 @@ Algorithm:
 
    ```
    Active phase: <N> — <Title>
-   Phase doc: docs/phases/phase-NN-*.md
+   Phase doc: docs/development/phases/phase-NN-*.md
    
    Next sub-task: <task-id> — <title>
    

.claude/commands/status.md

@@ -14,7 +14,7 @@ Steps:
 
 2. **Active phase**
    - The lowest-numbered phase that does NOT have a `phase-N-complete` tag is the active phase.
-   - Open `docs/phases/phase-NN-*.md` for that phase.
+   - Open `docs/development/phases/phase-NN-*.md` for that phase.
    - Count `[x]` vs `[ ]` checkboxes in sub-task headers and the phase exit checklist.
 
 3. **Next sub-task**

AUTONOMY.md

@@ -15,7 +15,7 @@ LOOP:
   1. Read current state:
      - git status, git log -5
      - last commit's tag (phase-N-task-M-complete or similar)
-     - check ROADMAP.md and the active docs/phases/phase-NN-*.md
+     - check ROADMAP.md and the active docs/development/phases/phase-NN-*.md
 
   2. Decide the next sub-task:
      - The lowest-numbered sub-task in the current phase that isn't ✓ done
@@ -411,7 +411,7 @@ This is not a "legacy mode" or "compatibility mode" — it is a real v1.0 deploy
 
 ### Phase progression for knowledge layer
 
-Phases 16–22 may partially overlap once 15 is done (see DAG in `docs/phases/README.md`). Phase 23 strictly requires 17, 21, 22. Phase 24 is final.
+Phases 16–22 may partially overlap once 15 is done (see DAG in `docs/development/phases/README.md`). Phase 23 strictly requires 17, 21, 22. Phase 24 is final.
 
 After each knowledge-layer phase:
 - Run that phase's tests.

CHANGELOG.md

@@ -40,7 +40,7 @@ operator runbook; full acceptance suite.
 **Known limitations** — see
 `spec/30_knowledge_open_questions/00_purpose.md` for OQ-23-A
 through OQ-23-E and the v2 deferrals. Phase-24 v1 scope cuts
-documented in `docs/phases/phase-24-acceptance.md`.
+documented in `docs/development/phases/phase-24-acceptance.md`.
 
 Tags: `v0.9.0-substrate-rc` (substrate gate), `phase-24-complete`
 + `v1.0.0` (this release).

CLAUDE.md

@@ -56,7 +56,7 @@ The full directory map is in [`spec/00_master_overview/02_doc_map.md`](spec/00_m
 The roadmap is in three layers:
 
 1. **[`ROADMAP.md`](ROADMAP.md)** — high-level phase index. One-line per phase.
-2. **[`docs/phases/phase-NN-*.md`](docs/phases/)** — detailed sub-task breakdown for each phase. Reads, writes, "done when" criteria.
+2. **[`docs/development/phases/phase-NN-*.md`](docs/development/phases/)** — detailed sub-task breakdown for each phase. Reads, writes, "done when" criteria.
 3. **[`AUTONOMY.md`](AUTONOMY.md)** — operating rules (commit format, stop conditions, scope guards).
 
 When asked "what's next?", the answer is always: the lowest-numbered unfinished sub-task in the active phase doc.
@@ -221,7 +221,7 @@ If running for the first time on a fresh checkout:
 2. `just verify` — confirm Phase 0 passes.
 3. If green: `git tag phase-0-complete` (if not already tagged).
 4. Read [`AUTONOMY.md`](AUTONOMY.md) end-to-end.
-5. Read the relevant phase doc (`docs/phases/phase-NN-*.md`) end-to-end.
+5. Read the relevant phase doc (`docs/development/phases/phase-NN-*.md`) end-to-end.
 6. Begin sub-task 1.1 (or current).
 
 ## 15. When in doubt

CODE_OF_CONDUCT.md

@@ -0,0 +1,64 @@
+# Code of Conduct
+
+Brain follows the
+[Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+## Our pledge
+
+We pledge to make participation in our project and community a
+harassment-free experience for everyone, regardless of age,
+body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality,
+personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our standards
+
+Examples of behaviour that contributes to a positive
+environment:
+
+- Demonstrating empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and
+  experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility and apologising to those affected
+  by our mistakes, and learning from the experience.
+- Focusing on what is best for the overall community.
+
+Examples of unacceptable behaviour:
+
+- Sexualised language or imagery, and sexual attention or
+  advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or
+  political attacks.
+- Public or private harassment.
+- Publishing others' private information, such as a physical
+  or email address, without their explicit permission.
+- Other conduct which could reasonably be considered
+  inappropriate in a professional setting.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable
+behaviour may be reported to the maintainer at the contact
+listed on the GitHub profile, or via GitHub's
+[abuse-report flow](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam).
+
+All complaints will be reviewed and investigated promptly and
+fairly. Maintainers are obligated to respect the privacy and
+security of the reporter of any incident.
+
+## Scope
+
+This Code of Conduct applies within all community spaces
+(GitHub issues, pull requests, discussions, and any
+project-affiliated channel), and also when an individual is
+officially representing the community in public spaces.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org/),
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

CONTRIBUTING.md

@@ -0,0 +1,171 @@
+# Contributing to Brain
+
+Thanks for considering a contribution. Brain has strong design
+constraints — read this end-to-end before you start.
+
+## TL;DR
+
+1. The [spec](spec/) is authoritative. Code disagreements get
+   fixed in the code, not the spec. Spec changes go through
+   the maintainer.
+2. Every sub-task: **read the spec → read the phase doc → write
+   a plan in `.claude/plans/phase-NN-task-MM.md` → wait for
+   approval → implement → verify → commit**.
+3. No `unwrap()` outside tests. Use `expect("invariant:
+   <reason>")` for unreachable.
+4. Run `just verify` (or `cargo zigbuild --target
+   x86_64-unknown-linux-gnu --workspace --tests` on macOS)
+   before opening a PR.
+
+See [`AUTONOMY.md`](AUTONOMY.md) for the full operating
+contract Brain's autonomous mode runs under — much of it
+applies to human contributors too.
+
+## Architecture in one paragraph
+
+Linux server. Connection layer (Tokio) accepts TCP; each
+request dispatches to one of N **shards**. Each shard runs a
+**Glommio** executor (thread-per-core, io_uring) and owns its
+data: a memory-mapped **arena** for vectors, a **WAL** with
+O_DIRECT + `pwritev2(RWF_DSYNC)` group commit, a **redb**
+B-tree for metadata, an **HNSW** index in RAM.
+Single-writer-per-shard, lock-free reads via
+**ArcSwap** + **crossbeam-epoch**. When a schema is declared,
+the same shard additionally owns entity / statement HNSWs,
+two **tantivy** indexes, an LLM extractor cache, and runs the
+three-tier extractor pipeline.
+
+## Where to start reading
+
+- [`README.md`](README.md) — what Brain is + capability tour.
+- [`spec/00_master_overview/`](spec/00_master_overview/) — design
+  start.
+- [`ROADMAP.md`](ROADMAP.md) — phase index.
+- [`CLAUDE.md`](CLAUDE.md) — operating rules + invariants.
+- [`docs/development/`](docs/development/) — contributor
+  workflow.
+
+## Core invariants — DO NOT violate
+
+Code that violates these is wrong regardless of test results:
+
+1. **WAL-before-acknowledge.** No operation returns success
+   until its WAL record is fsynced.
+2. **Single writer per shard.** No locks needed; the discipline
+   enforces it.
+3. **CRC everywhere.** Every WAL record + arena slot.
+4. **Slot version on `MemoryId`.** Stale references →
+   `NotFound`.
+5. **Idempotency by `RequestId`.** 24h TTL. Same params →
+   cached response. Different params → `Conflict`.
+6. **Tombstone grace before reclamation.** Default 7 days. Hard
+   FORGET zeroes immediately.
+7. **No silent corruption.** Fail-stop and alert.
+
+## Anti-patterns
+
+- Don't add Tokio inside a shard. Shards use Glommio.
+- Don't hold a lock across `.await`.
+- Don't allocate in the hot path (encode/recall serving).
+- Don't add `Send + Sync` to per-shard types.
+- Don't use `tokio::fs` in shard code.
+- Don't introduce a thread pool for parallel work. Sharding is
+  the parallelism.
+- Don't trust user input. All wire input is untrusted.
+- Don't `panic!` on user-input errors.
+
+## Workflow
+
+### 1. Pick a sub-task
+
+The lowest-numbered unfinished sub-task in the active phase
+doc. Use `/next-task` if you're in Claude Code.
+
+### 2. Read the spec
+
+The spec section that section governs the work. Don't infer
+from the code if the spec covers it — read the spec.
+
+### 3. Plan
+
+Write `.claude/plans/phase-NN-task-MM.md` with:
+- Scope.
+- Spec references.
+- Architecture sketch.
+- Trade-offs considered.
+- Risks / open questions.
+- Test plan.
+- Commit shape.
+- Confirmation questions.
+
+Wait for approval before coding. This isn't ceremony — most
+mistakes are caught at the plan step.
+
+### 4. Implement
+
+Follow the plan. Deviations go back through plan → approval.
+
+### 5. Verify
+
+```bash
+just verify
+# or, on macOS:
+cargo zigbuild --target x86_64-unknown-linux-gnu --workspace --tests
+cargo clippy --workspace --all-targets -- -D warnings
+cargo fmt --check
+```
+
+### 6. Commit
+
+One commit per sub-task. Commit subject:
+
+```
+<type>(<scope>): <NN.MM> — <summary>
+```
+
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`,
+`perf`.
+
+**Never** add a `Co-Authored-By: Claude` trailer. The user is
+the sole author of these commits.
+
+## Code conventions
+
+- Edition: Rust 2021. MSRV: stable latest minus one.
+- Errors: `thiserror` for libs; `anyhow` for binaries. Stable
+  error taxonomy per spec §03/10.
+- No `unwrap()` outside tests. Use `expect("invariant:
+  <reason>")` for unreachable.
+- Public APIs: rustdoc + at least one example for non-trivial.
+- No `unsafe` outside `crates/brain-storage`. That crate needs
+  it for mmap. Every `unsafe` block: `// SAFETY:` comment,
+  smallest scope.
+- Formatting: rustfmt defaults.
+- Lints: clippy default warnings as errors in CI. Pedantic is
+  aspirational; not enforced on stubs.
+- Naming: snake_case items, CamelCase types — Rust standard.
+
+## Testing
+
+- Unit tests colocated.
+- Integration tests in `tests/` per crate.
+- Property tests with `proptest` for parsers, allocators,
+  recovery.
+- Fuzz with `cargo-fuzz` for the wire protocol.
+- Loom for concurrency-critical paths.
+- Miri for `crates/brain-storage`'s unsafe.
+- Chaos tests for recovery (kill-during-operation).
+- Benchmarks with `criterion` per phase.
+
+New behaviour → new test. Spec change → corresponding test
+change.
+
+## Reporting bugs / security issues
+
+- Functional bugs: open a GitHub issue with a reproducer.
+- Security issues: see [`SECURITY.md`](SECURITY.md).
+
+## License
+
+By contributing, you agree your contribution is licensed under
+the project's [Apache 2.0 license](LICENSE).

README.md

@@ -187,7 +187,7 @@ When a schema is declared, the substrate exposes typed cognition. Three layers,
 | `0x60–0x6F` | Query | QUERY (hybrid), QUERY_EXPLAIN, QUERY_TRACE, RECALL_HYBRID |
 | `0x70–0x7F` | Admin | ADMIN_BACKFILL, ADMIN_LIST_PENDING_RESOLUTIONS, ADMIN_LIST_STALE_STATEMENTS |
 
-**End-to-end** ([`docs/usage/practical-guide.md`](docs/usage/practical-guide.md) walks through this in full):
+**End-to-end** ([`docs/development/usage/practical-guide.md`](docs/development/usage/practical-guide.md) walks through this in full):
 
 ```
 ENCODE "Priya kicked off the billing rewrite today."
@@ -512,9 +512,9 @@ Activates when a schema is declared. Substrate-only deployments are unaffected.
 | 23 | Hybrid query engine (router, RRF fusion, filter chain, EXPLAIN/TRACE) | planned |
 | 24 | Sweepers, knowledge acceptance & `v1.0.0` | planned |
 
-See [`ROADMAP.md`](ROADMAP.md) for the phase index and [`docs/phases/`](docs/phases/) for per-phase sub-task breakdowns. The dependency DAG for the knowledge-layer phases lives in [`docs/phases/README.md`](docs/phases/README.md).
+See [`ROADMAP.md`](ROADMAP.md) for the phase index and [`docs/development/phases/`](docs/development/phases/) for per-phase sub-task breakdowns. The dependency DAG for the knowledge-layer phases lives in [`docs/development/phases/README.md`](docs/development/phases/README.md).
 
-For a hands-on walkthrough of every feature in context (substrate primitives, schema declaration, extractors, hybrid query, FORGET cascade), see [`docs/usage/practical-guide.md`](docs/usage/practical-guide.md).
+For a hands-on walkthrough of every feature in context (substrate primitives, schema declaration, extractors, hybrid query, FORGET cascade), see [`docs/development/usage/practical-guide.md`](docs/development/usage/practical-guide.md).
 
 ## Development environment
 
@@ -597,7 +597,7 @@ cargo +nightly fuzz run protocol_frame -- -max_total_time=60      # nightly + Li
 just shell                                                        # enter the dev container (Docker required)
 ```
 
-A step-by-step setup, CLI tour, SDK tour, and troubleshooting walkthrough lives under [`docs/usage/`](docs/usage/).
+A step-by-step setup, CLI tour, SDK tour, and troubleshooting walkthrough lives under [`docs/development/usage/`](docs/development/usage/).
 
 ### When something doesn't work
 
@@ -616,14 +616,17 @@ brain/
 │   ├── Dockerfile
 │   ├── devcontainer.json
 │   └── post-create.sh
-├── docs/
-│   ├── phases/                   # Per-phase detailed sub-task plans (0–24)
-│   ├── usage/                    # Setup + CLI + SDK + walkthrough + troubleshooting
-│   ├── guides/                   # Operator guides (observability, …)
-│   ├── analytics/                # Reference Grafana dashboards + Alertmanager rules
-│   ├── runbooks/                 # Operational runbooks
-│   ├── spec-audit/               # Per-section spec ↔ impl audit pages
-│   └── spec-deviations.md        # Recorded conscious deviations from the spec
+├── docs/                         # See docs/README.md for navigation
+│   ├── README.md                 # Navigation hub (Diátaxis-shaped)
+│   ├── tutorials/                # Learning-oriented (getting started)
+│   ├── guides/                   # Task-oriented (install, configure, operate, upgrade, observability)
+│   ├── reference/                # Info-oriented (perf targets, error codes)
+│   ├── runbooks/                 # Operator procedures (RB-1 … RB-11)
+│   └── development/              # Contributor-oriented
+│       ├── usage/                # Build + run + debug + test workflow
+│       ├── spec-deviations.md    # Recorded conscious deviations from the spec
+│       └── phases/               # Per-phase plans (0–24); dev history
+├── monitoring/                   # Deployment assets (Grafana dashboards + Alertmanager rules)
 ├── spec/                         # The 32-section specification (read-only)
 │   ├── 00_master_overview/       # Substrate (§00–§16)
 │   ├── 01_system_architecture/