Claude/repo tidy rsr taxonomy

.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/agent_instructions/methodology.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/servers/menu.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)

0-AI-MANIFEST.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
     ;

CHANGELOG.md

@@ -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

Containerfile

@@ -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 .

Intentfile

@@ -65,7 +65,7 @@ ai_agent_capabilities:
       - Must not scrape sensitive data.
       - Must respect rate limits.
     example_actions:
-      - "Read README.md"
+      - "Read README.adoc"
       - "View logs: `kubectl logs <pod_name>`"
       - "Query BoJ API: `curl http://localhost:4000/api/cartridges`"
 

Justfile

@@ -1389,7 +1389,7 @@ tour:
     echo "  Umoja   — unity (federation, gossip protocol)"
     echo "  Ayo     — joy (the BoJ philosophy)"
     echo ""
-    echo "Read more: docs/ARCHITECTURE.md, QUICKSTART-USER.adoc"
+    echo "Read more: docs/architecture/README.adoc, docs/quickstarts/USER.adoc"
 
 # Show help for common workflows, build commands, test commands, and doc links
 help-me:
@@ -1453,10 +1453,10 @@ help-me:
     echo ""
     echo "DOCUMENTATION:"
     echo "  README.adoc                      Project overview"
-    echo "  EXPLAINME.adoc                   Detailed claims and evidence"
+    echo "  docs/EXPLAINME.adoc              Detailed claims and evidence"
     echo "  docs/AI_INSTALLATION_GUIDE.adoc  AI-assisted setup guide"
-    echo "  docs/ARCHITECTURE.md             Architecture overview"
-    echo "  QUICKSTART-USER.adoc             Quick start for users"
+    echo "  docs/architecture/README.adoc             Architecture overview"
+    echo "  docs/quickstarts/USER.adoc       Quick start for users"
     echo "  .machine_readable/STATE.a2ml     Current project state"
 
 

Mustfile

@@ -45,7 +45,7 @@ check-core-invariants:
 
 check-strong-invariants:
 	@echo "Checking strong invariants..."
-	@test -f docs/QUICKSTART.md && echo "✓ Documentation exists." || echo "⚠ Documentation missing."
+	@test -f docs/quickstarts/DEV.adoc && echo "✓ Documentation exists." || echo "⚠ Documentation missing."
 	@test -d examples && echo "✓ Example cartridges exist." || echo "⚠ Examples missing."
 	@echo "✓ Strong invariants verified."