[randomm]

Fixes #225
Fixes #226
Fixes #227

Docs-only. This addresses every MEDIUM-and-above finding from the 2026-10-13 README/docs accessibility audit. All three /work driver cycles stopped at commit-pr because of the integration-worktree defect, so their commits are combined here with conflicts resolved. Every claim was checked against the code, the built binary in temp dirs, the live v0.10.0 release assets, or pi's own docs.

#226 — README first screen

• Single # oo H1. The ASCII-art logo is removed. Badges have descriptive alt text.
• The first screen has: one sentence on what oo does and for whom (pi, Claude Code, other agents), cargo install double-o (noting that the crate installs the oo binary), oo init --agent pi|claude-code, a ✓/✗/● legend, and a before/after with the real label ✓ cargo (47 passed, 2.1s) [saved …].
• "Why oo?" and "The Problem" are merged. The tiers are renamed, and the categories are defined before first use. Quick Start includes agent setup. The joke subtitle is removed.

#225 — agent integration guide

• New docs/agents.md is the canonical guide. For pi and Claude Code it covers install (project vs --global, the exact file written), a verify step (oo rewrite pytest -q → oo pytest -q; oo rewrite git status exits 1 silently), scope (only pattern-matched commands are rewritten; everything else runs unchanged), OO_DISABLE per agent, uninstall, the failure mode when oo is not on the agent's PATH, pi's project-trust gate, a recall instruction to add to CLAUDE.md/AGENTS.md, what to commit, other agents (--format generic), and legacy plain oo init (non-rewriting).
• The README agent section is reduced to the two commands, the scope line and a link. The commands table shows oo init --agent <pi|claude-code>.
• docs/README.md is regrouped by audience and links every doc, including oo-rewrite.md.

#227 — false and stale facts corrected

• Installer URL: oo-installer.sh (404) → double-o-installer.sh (200).
• Removed the false --prefix=/usr/local instruction (the installer rejects --prefix).
• Platforms: pre-built binaries are for Apple Silicon macOS and Linux x86_64/ARM64 with glibc 2.39+ (installer gate; readelf -V on both released binaries shows a max of GLIBC_2.39). Intel macOS, Windows and older glibc → cargo install double-o or source.
• Indicator labels are the binary name only: ✓ cargo (…), ● git (…) (README, cli-reference, CONTRIBUTING). The indexed example is host-independent with the >4 KiB condition stated.
• "No agent modification required" is replaced with the actual setup.
• oo learn disclosure wherever it is mentioned: it sends the command (first 100 bytes), up to the first 4,000 bytes of output, the exit code and any --hint to Anthropic, and needs ANTHROPIC_API_KEY. Links security-model.
• The 7-day default retention and lazy per-project purge are stated next to recall (README, cli-reference).
• docs/configuration.md documents OO_DISABLE, OO_PI_EXTENSIONS_DIR and OO_CLAUDE_DIR.
• The oo rewrite "(experimental)" label is consistent.
• "Output of 4 KiB or less passes through" is qualified to successful output; failures are always filtered.

Verification

• Built binary in temp HOME/OO_DATA_DIR/OO_CONFIG_DIR and a temp git repo: init paths, messages and idempotency for both agents, env overrides and empty-value errors, oo rewrite/oo hook claude output, the OO_DISABLE code paths, success/failure/indexed/truncated/NOT-indexed indicator lines, and the [saved] suffix threshold.
• Live installer script (asset names, glibc gate, options) and readelf on the released Linux binaries.
• All relative links and anchors resolve. Each file has one H1 and no skipped heading levels.
• Adversarial review: 3 passes, no open issues.

Gates

cargo fmt --check ✓ · cargo clippy -- -D warnings ✓ · cargo test ✓ (528 unit tests plus all integration suites)

Notes

• No README/doc tests exist; verification is manual, as decided in Bug: Fix false and stale facts in oo user docs #227.
• Pre-existing and out of scope: learn::tests::test_patterns_dir_is_under_config_dir fails if OO_CONFIG_DIR is set in the environment.

[randomm]

Six-pass review — residual findings (round disclosure)

The lens review verdict is ISSUES_FOUND; nothing listed here has been fixed.
None is CRITICAL and the adversarial gate passed the diff, so a round-capped
review may carry these forward — but they are recorded here so a merge is never
silent about them. Decide them before merging.

• [MEDIUM] docs/agents.md:41 — Existing differing oo.ts install exits 0, hiding a failed install (ERROR_HANDLING)
• [MEDIUM] docs/agents.md:150 — Claude Code hook failure when oo is missing is undocumented (ERROR_HANDLING)
• [MEDIUM] docs/security-model.md:0 — Disclosed payload for oo learn is inconsistent across docs (SECURITY)
• [MEDIUM] README.md:0 — oo learn secret warning omits command-line exposure (SECURITY)
• [MEDIUM] README.md:0 — oo learn data-disclosure text duplicated in six places and already drifting (SIMPLICITY)
• [MEDIUM] README.md:105 — oo learn data-disclosure text duplicated in six places (ARCHITECTURE)
• [LOW] CONTRIBUTING.md:65 — Example command has an unhandled failure path on minimal hosts (ERROR_HANDLING)
• [LOW] docs/agents.md:0 — Pi trust mechanics packed into one table cell (SIMPLICITY)
• [LOW] docs/README.md:0 — agents.md listed under two headings with overlapping descriptions (ARCHITECTURE)
• [LOW] docs/README.md:0 — Agent Integration listed under two headings in the index (SIMPLICITY)
• [LOW] README.md:0 — Indexed-output retention is overstated and secret risk is unstated (SECURITY)
• [LOW] README.md:0 — Retention rule repeated in README paragraph, command table, and docs (SIMPLICITY)

[randomm]

Six-pass review — residual findings (round disclosure)

The lens review verdict is ISSUES_FOUND; nothing listed here has been fixed.
None is CRITICAL and the adversarial gate passed the diff, so a round-capped
review may carry these forward — but they are recorded here so a merge is never
silent about them. Decide them before merging.

• [LOW] CONTRIBUTING.md:0 — Expected-output parenthetical is harder to follow than the example (SIMPLICITY)
• [LOW] docs/agents.md:0 — Stale oo.ts remedy is documented twice in the pi section (SIMPLICITY)
• [LOW] docs/agents.md:45 — Agent doc restates installer and extension internals, creating drift coupling (ARCHITECTURE)
• [LOW] docs/security-model.md:0 — Hint-length refusal has no documented error surface (ERROR_HANDLING)
• [LOW] docs/security-model.md:0 — Disclosure section carries implementation internals that will drift (SIMPLICITY)
• [MEDIUM] docs/agents.md:41 — Existing differing oo.ts install exits 0, hiding a failed install (ERROR_HANDLING)
• [MEDIUM] docs/agents.md:150 — Claude Code hook failure when oo is missing is undocumented (ERROR_HANDLING)
• [MEDIUM] docs/security-model.md:? — Disclosed payload for oo learn is inconsistent across docs (SECURITY)
• [MEDIUM] README.md:? — oo learn secret warning omits command-line exposure (SECURITY)
• [MEDIUM] README.md:105 — oo learn data-disclosure text duplicated in six places and already drifting (SIMPLICITY)
• [LOW] CONTRIBUTING.md:65 — Example command has an unhandled failure path on minimal hosts (ERROR_HANDLING)
• [LOW] docs/agents.md:? — Pi trust mechanics packed into one table cell (SIMPLICITY)
• [LOW] docs/README.md:? — agents.md listed under two headings with overlapping descriptions (ARCHITECTURE)
• [LOW] docs/README.md:? — Agent Integration listed under two headings in the index (SIMPLICITY)
• [LOW] README.md:? — Indexed-output retention is overstated and secret risk is unstated (SECURITY)
• [LOW] README.md:? — Retention rule repeated in README paragraph, command table, and docs (SIMPLICITY)

[randomm]

Non-blocking adversarial observations carried forward:

1. A >1000-byte --hint refusal is surfaced asynchronously via learn-status.log on a later oo run. The docs say it is refused before any request but do not say where it is shown.
2. docs/security-model.md, the pre-existing line 'Command output … Sent to Anthropic only when you run oo learn', could link to #llm-learning-oo-learn.
3. The README Quick Start comment path to the disclosure is plain text inside a code block.

[randomm]

Six-pass review — residual findings (round disclosure)

The lens review verdict is ISSUES_FOUND; nothing listed here has been fixed.
None is CRITICAL and the adversarial gate passed the diff, so a round-capped
review may carry these forward — but they are recorded here so a merge is never
silent about them. Decide them before merging.

• [MEDIUM] docs/security-model.md:0 — Learn retry section omits the terminal failure outcome (ERROR_HANDLING)
• [LOW] docs/agents.md:0 — Legacy plain oo init section adds a non-rewriting path to a new page (SIMPLICITY)
• [LOW] docs/agents.md:5 — New page depends on deep anchors in other docs (ARCHITECTURE)
• [LOW] docs/security-model.md:0 — Retries codified to reuse the initial reply, discarding latest error (ERROR_HANDLING)
• [LOW] docs/security-model.md:0 — Hint limit documented in bytes but quoted error says "chars" (TYPE_SAFETY)
• [LOW] docs/security-model.md:0 — Experiment transcript embedded in the oo learn disclosure spec (SIMPLICITY)
• [MEDIUM] docs/agents.md:41 — Existing differing oo.ts install exits 0, hiding a failed install (ERROR_HANDLING)
• [MEDIUM] docs/agents.md:150 — Claude Code hook failure when oo is missing is undocumented (ERROR_HANDLING)
• [MEDIUM] docs/security-model.md:? — Disclosed payload for oo learn is inconsistent across docs (SECURITY)
• [MEDIUM] README.md:? — oo learn secret warning omits command-line exposure (SECURITY)
• [MEDIUM] README.md:105 — oo learn data-disclosure text duplicated in six places and already drifting (SIMPLICITY)
• [LOW] CONTRIBUTING.md:65 — Example command has an unhandled failure path on minimal hosts (ERROR_HANDLING)
• [LOW] docs/agents.md:? — Pi trust mechanics packed into one table cell (SIMPLICITY)
• [LOW] docs/README.md:? — agents.md listed under two headings with overlapping descriptions (ARCHITECTURE)
• [LOW] docs/README.md:? — Agent Integration listed under two headings in the index (SIMPLICITY)
• [LOW] README.md:? — Indexed-output retention is overstated and secret risk is unstated (SECURITY)
• [LOW] README.md:? — Retention rule repeated in README paragraph, command table, and docs (SIMPLICITY)
• [LOW] CONTRIBUTING.md:? — Expected-output parenthetical is harder to follow than the example (SIMPLICITY)
• [LOW] docs/agents.md:? — Stale oo.ts remedy is documented twice in the pi section (SIMPLICITY)
• [LOW] docs/agents.md:45 — Agent doc restates installer and extension internals, creating drift coupling (ARCHITECTURE)
• [LOW] docs/security-model.md:? — Hint-length refusal has no documented error surface (ERROR_HANDLING)
• [LOW] docs/security-model.md:? — Disclosure section carries implementation internals that will drift (SIMPLICITY)