SESSION: API Doc System 2026-04-06

Here is Claude’s plan: ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ Plan: domus-api — REST API for the Documentation System

Context
domus-captures has 2,954 .adoc files, 20 standards, 10 skills, and 74 projects — but
it's only accessible via the terminal and the Antora site. The user wants to interact
 with all of this through APIs: query documents, create incidents, scaffold projects,
 search content. This turns the documentation system from a static site into a
programmable platform.
Reference implementation exists: Doctrina (Principia's API) — FastAPI, 32 endpoints,
Pydantic, full-text search. Template for domus-api. Difference: filesystem instead of
 Postgres.
Architecture
domus-api (FastAPI on localhost:8080, Tailscale accessible)
├── Reads: ~/atelier/_bibliotheca/domus-captures/docs/modules/ROOT/
├── Reads: ~/.claude/skills/*/SKILL.md
├── Reads: docs/antora.yml (attributes)
├── Writes: pages/case-studies/ (incidents, CRs, RCAs)
├── Writes: partials/projects/ + pages/projects/ (project scaffolds)
└── No database — filesystem + in-memory cache
Stack
FastAPI, Pydantic v2, uvicorn, PyYAML, python-frontmatter, watchfiles (dev reload).
No database. No ORM. Filesystem IS the database.
Endpoints (Phase 1 MVP — Read + Search)
GET  /                           → health + counts
GET  /pages                      → list pages (?type=standard&category=operations)
GET  /pages/{path}               → page content + metadata
GET  /search?q={query}           → full-text search (?scope=standards)
GET  /standards                  → all 20 standards
GET  /standards/{id}             → single standard (STD-005)
GET  /projects                   → all projects with compliance
GET  /skills                     → all skills from ~/.claude/skills/
GET  /attributes                 → antora.yml attributes
GET  /stats                      → repository metrics
Endpoints (Phase 2 — Write)
POST  /case-studies/incidents    → create INC- per STD-011
POST  /case-studies/changes      → create CR- per STD-005
POST  /case-studies/rcas         → create RCA per STD-010
POST  /projects                  → scaffold STD-001 project
PATCH /projects/{slug}/status    → update status
Project Structure
~/atelier/_projects/personal/domus-api/
├── pyproject.toml
├── src/domus_api/
│   ├── main.py                  # FastAPI app, lifespan, CORS
│   ├── config.py                # Settings: docs root, cache TTL
│   ├── models/                  # Pydantic: page, case_study, project, search
│   ├── routes/                  # pages, search, case_studies, projects, standards, skills
│   ├── services/                # filesystem, parser, search, scaffolder, attributes
│   └── exceptions.py
└── tests/
Implementation order
. uv init + pyproject.toml + dependencies
. config.py — docs root path, antora.yml path
. services/parser.py — extract AsciiDoc metadata from header (regex on first 20 lines)
. services/filesystem.py — load all .adoc paths, cache metadata in memory
. services/search.py — full-text grep across cached files
. models/page.py — PageSummary, PageDetail, PageMetadata (Pydantic)
. routes/pages.py — GET /pages, GET /pages/{path}
. routes/search.py — GET /search
. routes/stats.py — GET /stats
. main.py — FastAPI app with lifespan (load cache on startup)
. Test: uv run uvicorn domus_api.main:app --reload
Verification
. curl localhost:8080/ → health
. curl localhost:8080/pages → lists documents
. curl localhost:8080/search?q=mandiant → matches
. curl localhost:8080/standards → 20 standards
. /docs → Swagger UI
. uv run pytest passes
Current state
Each spoke has:
- partials/projects/<slug>/ with 5 files: metadata, summary, purpose, scope, status
- pages/projects/`{personal,chla}`/PRJ-domus-<name>.adoc — flat file with includes
What each project needs
For each of the 14 repos:
. Create pages/projects/`{personal,chla}`/domus-<slug>/index.adoc — shell including
summary + purpose + scope + status + metadata (same includes as current PRJ file)
. Create partials/projects/<slug>/appendix-issues.adoc — "No issues documented yet."
. Create partials/projects/<slug>/appendix-todos.adoc — seeded with relevant TODOs
. Create pages/projects/`{personal,chla}`/domus-<slug>/appendix-issues.adoc — shell
. Create pages/projects/`{personal,chla}`/domus-<slug>/appendix-todos.adoc — shell
. Replace old PRJ-*.adoc with redirect note
. Update nav from flat xref to directory with appendices
The 14 repos to convert
Personal (12 repos)
┌─────────────┬────────────────────────────┬─────────────────────────────────────┐
│    Slug     │        Partial Dir         │            New Page Dir             │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ infra-ops   │ partials/projects/infra-op │ pages/projects/personal/domus-infra │
│             │ s/                         │ -ops/                               │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ domus-docs  │ partials/projects/domus-do │ pages/projects/personal/domus-docs/ │
│             │ cs/                        │                                     │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ netapi-docs │ partials/projects/netapi-d │ pages/projects/personal/domus-netap │
│             │ ocs/                       │ i-docs/                             │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ linux-ops   │ partials/projects/linux-op │ pages/projects/personal/domus-linux │
│             │ s/                         │ -ops/                               │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ secrets-ops │ partials/projects/secrets- │ pages/projects/personal/domus-secre │
│             │ ops/                       │ ts-ops/                             │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ windows-ops │ partials/projects/windows- │ pages/projects/personal/domus-windo │
│             │ ops/                       │ ws-ops/                             │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ automation- │ partials/projects/automati │ pages/projects/personal/domus-autom │
│ ops         │ on-ops/                    │ ation-ops/                          │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ identity-op │ partials/projects/identity │ pages/projects/personal/domus-ident │
│ s           │ -ops/                      │ ity-ops/                            │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ o11y-ops    │ partials/projects/o11y-ops │ pages/projects/personal/domus-o11y- │
│             │ /                          │ ops/                                │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ domus-pytho │ partials/projects/domus-py │ pages/projects/personal/domus-pytho │
│ n           │ thon/                      │ n/                                  │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ ollama-loca │ partials/projects/ollama-l │ pages/projects/personal/ollama-loca │
│ l           │ ocal/                      │ l/                                  │
├─────────────┼────────────────────────────┼─────────────────────────────────────┤
│ domus-music │ partials/projects/domus-mu │ pages/projects/personal/domus-music │
│ a           │ sica/                      │ a/                                  │
└─────────────┴────────────────────────────┴─────────────────────────────────────┘
CHLA (2 repos — work spoke repos)
┌───────────┬──────────────────────────────┬──────────────────────────────────────┐
│   Slug    │         Partial Dir          │             New Page Dir             │
├───────────┼──────────────────────────────┼──────────────────────────────────────┤
│ ise-linux │ partials/projects/ise-linux/ │ pages/projects/chla/domus-ise-linux/ │
├───────────┼──────────────────────────────┼──────────────────────────────────────┤
│ ise-ops   │ partials/projects/ise-ops/   │ pages/projects/chla/domus-ise-ops/   │
└───────────┴──────────────────────────────┴──────────────────────────────────────┘
Note: domus-ise-windows and domus-siem-ops are also flat PRJ files in chla/ but may
not have partials. Check and include if they do.
Implementation
Phase 1: Create all directories + shell pages (batch script)
For each repo: mkdir page dir, create index.adoc, appendix-issues.adoc,
appendix-todos.adoc shells
Phase 2: Create appendix partials (agent)
For each repo: create appendix-issues.adoc and appendix-todos.adoc in the existing
partials dir
Phase 3: Replace old PRJ-*.adoc files with redirects
Phase 4: Update nav.adoc
Convert flat xrefs to directory structure with appendices
Verification

  1. make 2>&1 | grep -E 'WARN|ERROR' — clean build

  2. All 14 new directories exist in pages/

  3. All 14 partials dirs have appendix-issues + appendix-todos

  4. Nav shows directory structure for all spoke repos

  5. Old PRJ files redirect to new locations ╌╌