TASK: Docs standards pass — READMEs and docs/ across ukrrs repos

Context

Charles decreed (2026-08-28 ~21:00): ALL project docs must be informative, well-formatted, beautiful, and useful. Current MOPAC harness README is 16 skeleton lines with a stale Gitea path (says reachableceo/MOPAC; org moved to ukrrs/MOPAC). This standard applies to every repo we own from now on.

Scope (in priority order)

~/projects/meta/MOPAC/harness/ — README.md full rewrite; docs/ polish.
~/projects/meta/MOPAC/harness/ siblings cloned from Gitea: clone https://git.knownelement.com/ukrrs/mopac-keyproxy and https://git.knownelement.com/ukrrs/mopac-bitwarden-go under ~/projects/meta/MOPAC/ and upgrade their READMEs (they are spec seeds).
~/projects/siblings/KNEL-AIMiddleware (if present) — README audit: fix only what is wrong/stale; do not rewrite working docs wholesale.

The doc standard (apply to every README; checklist)

Front matter: H1 title, one-paragraph purpose (what/why/who-for, no throat-clearing), then a Status: line — date + one-word state (e.g. Status: 2026-08-28 — skeleton, MVP demo path live).
Quickstart: copy-paste commands that actually work, each block followed by a short expected-output snippet. Verify every command by RUNNING it (e.g. ./bin/harness once --dry-run --demo, ./bin/harness help). Never document an unverified command.
Architecture: a mermaid flowchart of the conductor loop (intake -> routing -> bounded turn -> REPORT) plus one paragraph of prose.
Reference tables (not prose walls):
- CLI: subcommands, flags, exit codes (0/1/2/4) — from actual help output.
- Config: every harness.toml section with one-line meaning (from harness.toml.example + internal/config).
- Model routing: the [models] tier map as a table (class -> model).
Status table: Works / Stubbed / Next — sourced from REPORT.md, kept honest.
Formatting: fenced code with language tags; headings never skip levels; consistent terminology (harness, conductor, turn, REPORT capitalized as shown); no dead links; no TODO markers without an owner; correct repo URLs (git.knownelement.com/ukrrs/...).
For keyproxy/bitwarden-go seeds: purpose, scope, non-goals (no admin UI, memory-only), license (AGPLv3), status line, and what exists today vs planned — the spec READMEs already carry the design; make them navigable.

docs/ polish (MOPAC only)

Each PORTING-NOTES-*.md gets the Status front-matter line.
DESIGN.md gets a short table of contents after its intro (section list, anchor links). Do NOT rewrite or reorder existing sections.

Constraints

DOCS ONLY. No source code changes. No new sections in DESIGN.md.
This turn runs AFTER pmo-ops and events-receiver complete (dispatch is gated); the repo working tree will be clean and pushed when you start.
Verify-then-write: read the code/help/config you are documenting.
Commit per repo with clear messages; push to ukrrs remotes.

Deliverables

Commits + pushes: MOPAC (README + docs/), mopac-keyproxy, mopac-bitwarden-go, (KNEL-AIMiddleware if touched).
REPORT-20260828-docs-standards.md in ~/.coordinate/inbox-pmo/: per-repo summary of changes, the checklist items applied, any doc rot found that you could NOT fix in this pass (list for follow-up).

3.3 KiB Raw Permalink Blame History