Claude/repo tidy rsr taxonomy (#149)

## Summary

Repo-health tidy aligning boj-server's documentation taxonomy with
`hyperpolymath/rsr-template-repo`. The root went from 17 .md/.adoc docs
to **9** (all of which are either GitHub-required, load-bearing, or
known high-coupling items deferred for separate work); `docs/` now has
audience-targeted subdirectories matching the template (`quickstarts/`,
`wikis/`, `architecture/`, `status/`, `developer/`); and every
non-GitHub-required `.md` doc in the moved set is now `.adoc` per the
hyperpolymath language policy.

## Changes — six logical commits

**1. `docs(taxonomy): move root .adoc docs under docs/<category>/`** — 8
root `.adoc` files relocated:
- `EXPLAINME.adoc` → `docs/EXPLAINME.adoc`
- `BOJ_LOGIC.adoc`, `NeSy_SERVERS.adoc` → `docs/architecture/`
- `FUTURE_PLANS.adoc`, `ROADMAP.adoc` → `docs/status/`
- `QUICKSTART-{USER,DEV,MAINTAINER}.adoc` →
`docs/quickstarts/{USER,DEV,MAINTAINER}.adoc`

Cross-refs updated in `0-AI-MANIFEST.a2ml`, `Justfile`,
`elixir/boj-rest.service`,
`.machine_readable/agent_instructions/methodology.a2ml`,
`docs/README.adoc`, `docs/accessibility/README.adoc`, and the two
`outreach/` drafts.

**2. `docs(readme): merge README.md into README.adoc, drop the .md
duplicate`** — the substantive 518-line `README.md` (11-client install
matrix, collapsible cartridge tables, AAA section) converted to AsciiDoc
and merged with the unique sections from the shorter `.adoc` (Features
bullets, Formal verification). `README.md` deleted. Refs in `jsr.json`,
`mcp-bridge/lib/resources.js`, `.github/SECURITY.md`, and `Intentfile`
repointed at `README.adoc`.

**3. `docs(taxonomy): convert wiki/llm-warmup/Phase-3B docs to .adoc and
re-home them`** — five wiki pages converted and moved from `docs/wiki/`
to `docs/wikis/` (template's spelling); `llm-warmup-{dev,user}.md` moved
into `docs/developer/`; `CARTRIDGE-PHASE-3B-COMPLETION.md` moved into
`docs/status/`. Also drift-fixed `STATE.a2ml`'s stale cartridge counts
(`112 → 125`, derived from actual directory count).

**4. `docs(taxonomy): convert docs/*.md to .adoc, relocate
ARCHITECTURE+DEVELOPERS, add subdir READMEs`** — 8 `docs/*.md` files
converted to `.adoc`; `docs/ARCHITECTURE.md` →
`docs/architecture/README.adoc`; `docs/DEVELOPERS.md` →
`docs/developer/README.adoc`. **99 files cross-rewritten** (55 cartridge
READMEs + governance/wiki/dev/architecture refs + `Justfile`,
`.github/copilot-instructions.md`, `SECURITY.md`,
`src/abi/Boj/Catalogue.idr`, `k8s/service.yaml`,
`mcp-bridge/lib/api-clients.js`, etc.). New subdir orientation READMEs
in `docs/quickstarts/`, `docs/status/`, `docs/wikis/`.

**5. `docs(quickstarts): replace stub DEV/MAINTAINER with the
substantial docs/*.md content`** — the substantive `docs/QUICKSTART.md`
(72 lines), `docs/GETTING-STARTED.md` (198 lines), and
`docs/OPERATOR-QUICKSTART.md` (296 lines) replace the 39/40-line stubs
that had moved over from root in commit 1. Result:
`docs/quickstarts/{USER, DEV, BUILD-FROM-SOURCE, MAINTAINER}.adoc`.

**6. `docs(index): comprehensive docs/README.adoc rewrite + final
TYPED-WASM-MCP-BRIDGE conversion`** — `docs/README.adoc` rewritten in
full (four sections: "Reading order by audience", "Directory taxonomy",
"Standalone `docs/` root files", "Related root-level files"). Last lone
`.md` in `docs/architecture/` converted.

## Known-deferred (not in this PR — high coupling)

These four root-level files are intentionally left in place because
moving them would ripple across 5–16+ files including CI workflows,
Idris2 proofs, and Elixir test fixtures:

- `PROOF-NEEDS.md` (16 cross-refs, incl.
`.github/workflows/backend-assurance.yml`,
`src/abi/Boj/SafetyLemmas.idr`, 4 Elixir test files)
- `TOPOLOGY.md` (11 cross-refs, incl. a CI workflow)
- `TEST-NEEDS.md` (5 cross-refs)
- `GEMINI.md` — *not* deferred; it's load-bearing
(`gemini-extension.json` references it as `contextFileName`)

A follow-up PR can address the first three with a careful bulk-rewrite
once these moves are accepted.

## Issues + PRs

Verified all 6 open issues (#135, #111, #101, #100, #87, #67) are
current — most recently updated 2026-05-20. No stale issues require
closing.

## Cartridge-count drift

`.machine_readable/6a2/STATE.a2ml` had `cartridges-total = 112` but the
actual count is **125** (every cartridge directory has
`cartridge.json`). Bumped: `cartridges-total 112 → 125`,
`cartridges-with-zig-ffi 111 → 115` (manifest-counted),
`cartridges-with-js-mod 111 → 113`, and the prose in
`[project-context].purpose`.

## Test plan

- [x] All cross-references rewritten in the same commits as the file
moves (no dangling links). Verified via `git grep -l <old-path>`
returning 0 for every moved file.
- [x] CHANGELOG.md and historical log entries inside
`.machine_readable/6a2/STATE.a2ml` deliberately left intact (rewriting
history obscures the audit trail).
- [ ] CI is freshly running (26 checks queued from this push).
- [ ] Reviewer spot-check: `docs/README.adoc` index accurately reflects
the on-disk taxonomy.
- [ ] Reviewer spot-check: at least one cartridge README (e.g.
`cartridges/aerie-mcp/README.adoc`) still links cleanly to
`docs/READINESS.adoc`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

.github/DISCUSSION_TEMPLATE/cartridge-proposal.yml

@@ -6,7 +6,7 @@ body:
       value: |
         Proposing a new cartridge for the Ayo (community) menu? Tell us about it!
         Cartridges follow the stack: Idris2 ABI + Zig FFI, served by the Elixir adapter.
-        See docs/DEVELOPERS.md for the full guide.
+        See docs/developer/README.adoc for the full guide.
   - type: input
     attributes:
       label: Cartridge name

.github/SECURITY.md

@@ -364,7 +364,7 @@ When using boj-server, we recommend:
 |---------|---------|
 | **Security issues** | [Report via GitHub](https://github.com/hyperpolymath/boj-server/security/advisories/new) or j.d.a.jewell@open.ac.uk |
 | **General questions** | [GitHub Discussions](https://github.com/hyperpolymath/boj-server/discussions) |
-| **Other enquiries** | See [README](README.md) for contact information |
+| **Other enquiries** | See [README](../README.adoc) for contact information |
 
 ---
 

.github/copilot-instructions.md

@@ -1,6 +1,6 @@
 <!-- SPDX-License-Identifier: MPL-2.0 -->
 <!-- Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> -->
-<!-- Authoritative source: docs/AI-CONVENTIONS.md -->
+<!-- Authoritative source: docs/AI-CONVENTIONS.adoc -->
 
 # Copilot Instructions
 

.machine_readable/6a2/STATE.a2ml

@@ -104,4 +104,4 @@ constraints = [
 reject-if-contains = ["{{PLACEHOLDER}}", "{{PROJECT}}", "rsr-template-repo"]
 reject-if-project-name-mismatch = true
 staleness-threshold-days = 90
-fallback-files = ["TODO.md", "TODO.adoc", "ROADMAP.adoc", "README.adoc"]
+fallback-files = ["TODO.md", "TODO.adoc", "docs/status/ROADMAP.adoc", "README.adoc"]

.machine_readable/agent_instructions/methodology.a2ml

@@ -299,7 +299,7 @@
 @section(id="ayo", label="The Ayo Selection"):
 
 # No community cartridges yet — the door is open.
-# See docs/DEVELOPERS.md for how to contribute a cartridge.
+# See docs/developer/README.adoc for how to contribute a cartridge.
 
 # ═══════════════════════════════════════════════════════════════════════════
 # Umoja Network (Community Nodes)

.machine_readable/servers/menu.a2ml

@@ -28,7 +28,7 @@
 
   (context-tiers
     ; Tier 0 (always load): This file + .claude/CLAUDE.md — orientation only
-    ; Tier 1 (load if working on code): README.adoc, EXPLAINME.adoc, Justfile
+    ; Tier 1 (load if working on code): README.adoc, docs/EXPLAINME.adoc, Justfile
     ; Tier 2 (load on demand): .machine_readable/*.a2ml, docs/
     ; Tier 3 (never load unless asked): tests/, generated/, CI configs
     ;

0-AI-MANIFEST.a2ml

@@ -27,6 +27,45 @@ All notable changes to Bundle of Joy Server are documented here.
 
 ## [Unreleased]
 
+### Documentation
+
+- **Repository documentation reorganised to match rsr-template-repo taxonomy.**
+  Root-level `.adoc` clutter eliminated; all docs now live under `docs/`
+  subdirectories clustered by purpose (`quickstarts/`, `wikis/`, `architecture/`,
+  `status/`, `developer/`, `governance/`, `decisions/`, `specification/`,
+  `integration/`, `backend-assurance/`, `compliance/`, `practice/`,
+  `proposals/`, `attribution/`, `accessibility/`, `papers/`, `examples/`,
+  `glama/`, `outreach/`, `handover/`, `maintenance/`). Each subdirectory has
+  its own `README.adoc` index. High-coupling root files (`PROOF-NEEDS.md`,
+  `TOPOLOGY.md`, `TEST-NEEDS.md`) stay at root pending follow-up PR to update
+  their 16/11/5 cross-references.
+
+- **`README.md` merged into `README.adoc` and dropped.** Single canonical
+  root README in AsciiDoc. Preserves the full 11-client MCP install matrix
+  (Claude Code, Claude Desktop, Gemini CLI, Copilot, Cursor, Cline, Windsurf,
+  Continue.dev, Zed, generic stdio) and collapsible cartridge tables via
+  `[%collapsible]` blocks.
+
+- **All `docs/*.md` files converted to `.adoc`** (format only; content
+  preserved). Affected files: `ARCHITECTURE.md` → `docs/architecture/README.adoc`,
+  `DEVELOPERS.md` → `docs/developer/README.adoc`, `OPERATOR-QUICKSTART.md` →
+  `docs/quickstarts/MAINTAINER.adoc`, `DEVELOPER-QUICKSTART.md` →
+  `docs/quickstarts/DEV.adoc`, and 8 others. `docs/wikis/` sources fully
+  converted and expanded (Home, User-Guide, Operator-Guide, Developer-Guide,
+  FAQ all in `.adoc`).
+
+- **`docs/README.adoc` rewritten** with reading-order-by-audience table,
+  full directory taxonomy, standalone-docs table, and rationale for the three
+  high-coupling deferred moves.
+
+- **New subdir index files**: `docs/quickstarts/README.adoc`,
+  `docs/wikis/README.adoc`, `docs/status/README.adoc` — each explains its
+  subdirectory's scope and contents.
+
+- **STATE.a2ml cartridge count corrected**: was 112, actual is 125 (verified
+  by `find cartridges -name cartridge.json | wc -l`). Session log entry added
+  documenting all 2026-05-26 work.
+
 ### Changed
 
 - **Cowboy listener now binds to `127.0.0.1` by default** (was: all

CARTRIDGE-PHASE-3B-COMPLETION.md

@@ -5,7 +5,7 @@
 # cartridge tool manifest.
 #
 # TRANSITIONAL: this image will be replaced by a Zig→WASM bridge once
-# typed-wasm-mcp lands. See docs/architecture/TYPED-WASM-MCP-BRIDGE.md.
+# typed-wasm-mcp lands. See docs/architecture/TYPED-WASM-MCP-BRIDGE.adoc.
 #
 # For the full production image (Zig FFI + adapter), use:
 #   podman build -f container/Containerfile .