# REPORT: docs standards pass — READMEs and docs/ across ukrrs repos

Date: 2026-08-28
Operator: docs-standards turn (TASK-20260828-2100-docs-standards)
Status: COMPLETE — 4 repos committed and pushed; verification-first throughout

## Method

Read code/help/config before writing a word. Ran every documented command:
build/vet/test inside the Docker builder (golang:1.26-bookworm, pulled,
pre-authorized), `./bin/harness help`, `./bin/harness once --dry-run --demo`,
and the no-key live-demo error path (exit 1, clean message). Gitea anchor
slugs for the DESIGN.md TOC were taken from the rendered page, not guessed.

## Per-repo summary

### ukrrs/MOPAC (harness) — commit c6da05f, pushed to main

- README.md: full rewrite from the 16-line skeleton. H1 + purpose paragraph +
  Status line; verified quickstart (Docker builder, cp harness.toml.example,
  dry-run with real output, live-demo bar incl. verified no-key failure
  output); mermaid conductor flowchart (INTAKE -> ROUTING -> bounded TURN ->
  REPORT, chaining by re-invocation) + prose; reference tables for CLI
  (subcommands, flags, exit codes 0/1/2/4 from actual help), config (every
  harness.toml section + defaults from internal/config), model routing
  (tier table + class -> tier -> model table); Status table (Works/Stubbed/
  Next) sourced from REPORT.md; docs/link section; AGPLv3. Stale
  `reachableceo/MOPAC` path replaced with git.knownelement.com/ukrrs/MOPAC.
- docs/: all three PORTING-NOTES-*.md got Status front-matter lines
  (crush/maki: complete, drift possible; secrets: complete, 7 open questions
  pending Charles, feeds mopac-bitwarden-go). PORTING-NOTES-secrets.md was
  untracked in the working tree (pre-existing) — now committed.
- DESIGN.md: Contents section (19 anchor links, verified against Gitea's
  rendered ids) after the intro. No sections rewritten, reordered, or added
  beyond the TOC.

### ukrrs/mopac-keyproxy — commit 325a36c, pushed to master

- Cloned fresh from Gitea. README upgraded, purpose prose kept: Status line
  (spec seed, no code yet); Scope (mpk_ placeholders, BW Secrets Manager
  REST + Vault KV v2/AppRole backends, HTTP hop + `keyproxy get` CLI);
  Non-goals (no admin UI ever, not a secrets manager, no disk persistence,
  no org assumptions); Today-vs-planned table; Design references linking
  into ukrrs/MOPAC DESIGN.md key-proxy + FLOSS-repos sections (anchors
  verified) and the sibling repos; AGPLv3.

### ukrrs/mopac-bitwarden-go — commit d8c781d, pushed to main

- Cloned fresh from Gitea. README upgraded, purpose prose kept: Status line
  (spec seed, reference study complete, open questions pending Charles);
  Scope (stdlib REST, no SDK, machine-account auth, porcelain/plumbing,
  memory-only session handling); Non-goals (no admin UI, not a vault server,
  no disk cache of values); Today-vs-planned table naming the
  KNELSecretsManager ADR-002 wrapper as the production interim; Design
  references into PORTING-NOTES-secrets.md (incl. its 7 open questions),
  DESIGN.md toolchain-policy + key-proxy anchors, keyproxy sibling; AGPLv3.

### ukrrs/KNEL-AIMiddleware — commit 6476304, pushed to main

- Audit-only pass (working clone: projects/meta/MOPAC/siblings/
  KNEL-AIMiddleware; the task's ~/projects/siblings path does not exist).
  Fixed only wrong/stale facts:
  - License badge + footer said MIT; LICENSE is AGPLv3. Corrected both.
  - Production numbers said 31/42 (MCP 27/38); PRODUCTION-READY.md says
    33/42 (MCP 29/38). Badge + summary table corrected.
  - Clone URL was github.com/KNEL/...; corrected to
    git.knownelement.com/ukrrs/KNEL-AIMiddleware.git.
  - Project structure tree predated tooling-cli/ (redmine, discourse, dns,
    KNELCredsManager), the 40+ mcp-/lsp-wrapper scripts, run.sh,
    maintenance.sh, PRODUCTION-READY.md, LSP_SETUP.md — all added.
  - scripts/ section missing validate-mcp.sh / validate-all.sh — added.
  - Status front-matter line added (org standard) without restructuring.

## Checklist applied

- Front matter (H1, purpose paragraph, Status line): all 4 repos.
- Quickstart verified by running: MOPAC (build/vet/test in Docker builder,
  help, dry-run, no-key live path; with-key path proven live 2026-08-28
  19:29 per log + reports/REPORT-latest.md). Seeds have no runnable code —
  quickstarts intentionally absent until commands exist (standard: never
  document an unverified command).
- Architecture mermaid + prose: MOPAC (conductor loop).
- Reference tables (CLI/flags/exit codes, config sections, routing map):
  MOPAC.
- Status table from REPORT.md: MOPAC.
- Terminology (harness/conductor/turn/REPORT), fenced code with language
  tags, no heading-level skips, no ownerless TODOs: all 4.
- Links checked: relative files exist; Gitea anchors verified against
  rendered HTML; no dead links introduced.
- Correct repo URLs (git.knownelement.com/ukrrs/...): all 4.

## Doc rot found, NOT fixed in this pass (follow-up list)

1. **go.mod module path stale**: `git.knownelement.com/reachableceo/MOPAC/
   harness` (and all internal import paths) predate the ukrrs transfer.
   Source change — excluded from a docs-only pass. Fix in a code turn,
   then drop the parenthetical note in the harness README quickstart.
2. **DESIGN.md line ~154** still lists mopac-bitwarden-go as "later" — it
   is created and seeded now. DESIGN edits were out of scope (TOC only);
   fold into the next DESIGN append turn.
3. **Duplicate KNEL-AIMiddleware clone**: ~/projects/KNEL-AIMiddleware
   (older location) is now one commit behind the siblings/ clone I pushed.
   Someone should `git pull` it or remove it (MIGRATION-projects.md
   territory).
4. **KNEL-AIMiddleware STATUS.md / PRODUCTION-READY.md / LSP_SETUP.md /
   JOURNAL.md**: not audited this pass (scope was the README); README now
   trusts PRODUCTION-READY.md's 33/42, which matched its own internal
   tables. A deeper docs pass could reconcile STATUS.md the same way.
5. **golang:1.26-alpine builder breaks the harness test suite** (no bash in
   the image; internal/tools tests fail). Bookworm image works and is what
   the README documents. Worth pinning digest + documenting image choice
   when the builder container is formalized (DESIGN all-dev-in-docker rule).
6. **Harness bin/ is gitignored but README quickstart builds into it** —
   correct as designed; noting only so nobody "fixes" it away.