# 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)
1. `~/projects/meta/MOPAC/harness/` — README.md full rewrite; docs/ polish.
2. `~/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).
3. `~/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).