docs: rewrite README to house standard

[steipete]

Summary

Before, the 403-line README mixed first-time setup with an exhaustive flag matrix, provider notes, browser recovery details, and many examples that duplicated the docs site. After, the 136-line README follows the house front-door structure: pitch, dynamic flat-square badges, install, a credential-free quick start, progressively deeper workflows, development, and license.

The existing banner and project credits remain. The banner is visually unchanged at 1600×770 and compressed from 1.0 MB to 307 KB.

Documentation changes

No new docs file was needed. Detailed material removed from the README already lives in the linked installation, quickstart, browser, provider, configuration, CLI, session, follow-up, multi-model, MCP, and agent guides.

No unique maintained content was dropped as obsolete. Volatile model and flag enumerations now defer to the CLI help and dedicated docs, and the old unqualified browser stability wording was not carried forward.

Verification

• pnpm install, pnpm check, pnpm build, pnpm docs:check, and pnpm docs:site pass.
• pnpm test passes: 1,670 tests passed and 43 skipped across 169 files.
• pnpm test:packed-cli passes, including the packed help smoke.
• The published npx -y @steipete/oracle --help path passes from a neutral temporary directory.
• The README's --render, --dry-run summary --files-report, status --hours 72, and doctor --providers examples were run against the built CLI. The answer-producing path requires credentials or a signed-in browser, so its flags were checked against real --help output without sending a paid request or controlling Chrome.
• All 20 relative links resolve. All 14 external URLs return HTTP 200. All five Shields badges return HTTP 200 and contain no invalid or not found card.
• npm, Homebrew formula, GitHub release, Node 24 runtime floor, ci.yml, and main distribution/workflow claims were checked against the registry, tap, release metadata, manifest, and workflow.
• /Users/steipete/Projects/agent-skills/skills/autoreview/scripts/autoreview --mode local reports no accepted/actionable findings. The helper cannot ingest binary diffs; the text diff was reviewed while the compressed PNG was checked separately for dimensions, size, and visual integrity.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 2, 2026, 8:15 PM ET / August 3, 2026, 00:15 UTC.

ClawSweeper review

What this changes

The branch replaces the long README with a verified install and credential-free quick start, links detailed workflows to existing guides, refreshes badges, recompresses the header image, and adds a Docs changelog entry.

Merge readiness

⚠️ Ready for maintainer review - 1 item remains

Keep this owner-authored PR open for normal merge review. The README now gives a concise, accurate entry path into Oracle and delegates detailed setup and workflow guidance to existing maintained docs; no actionable defect or security concern was found in the proposed patch.

Priority: P3
Reviewed head: 660d751985986d1904eefad15cdfdc5b32c97384
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦞 diamond lobster (5/6)	A focused, well-supported documentation patch with accurate current-code claims and no actionable review findings.
Proof confidence	🌊 off-meta tidepool	Not applicable: This owner-authored documentation PR is outside the external-contributor real-behavior-proof gate; its body nonetheless records concrete CLI, link, docs-site, and package-smoke validation.
Patch quality	🦞 diamond lobster (5/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This owner-authored documentation PR is outside the external-contributor real-behavior-proof gate; its body nonetheless records concrete CLI, link, docs-site, and package-smoke validation.
Evidence reviewed	5 items	README claims match current CLI contracts: The revised README describes --render, API/browser engine selection, --dry-run, --files-report, --models, doctor --providers, and session follow-ups; current CLI option definitions support those descriptions, including API selection when OPENAI_API_KEY is set and browser fallback otherwise. README links point to maintained documentation: All repository-relative documentation links in the proposed README resolve at the PR head, including install, quickstart, engine, provider, session, configuration, agent, MCP, and bridge guides. Quick-start path is concrete and non-empty: The README's example source glob currently selects 29 TypeScript files under src/oracle, while its test exclusion does not hide the selected production files.
Findings	None	None.
Security	None	None.

How this fits together

Oracle is a CLI and MCP server that packages selected project files with a prompt, routes the request through API or browser engines, and persists the result as a session. The README is the public front door that directs new users from installation and local rendering to the detailed engine, provider, session, and integration guides.

flowchart LR
  A[Developer or coding agent] --> B[README front door]
  B --> C[Install Oracle]
  B --> D[Credential-free render quick start]
  D --> E[CLI bundles prompt and files]
  E --> F[API or browser engine]
  F --> G[Saved Oracle session]
  B --> H[Detailed workflow guides]

Loading

Decision needed

Question	Recommendation
Should this owner-authored README consolidation merge once the pending macOS and Windows build checks complete?	Merge after platform checks: Accept the concise README as the public entry point once the pending platform matrix confirms the documented distribution remains healthy.

Why: The patch is documentation-focused and appears correct, but the review policy requires explicit maintainer judgment rather than automated cleanup for owner-authored items.

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	3 files affected; 76 added, 339 removed	The patch is tightly limited to the README, its header image, and one release-note entry.
README reduction	403 lines to 136 lines	The change deliberately moves detailed operational material to existing linked guides rather than adding a parallel documentation system.

Technical review

Best possible solution:

Land the focused README front-door structure after ordinary owner review and the remaining platform checks complete, keeping detailed and volatile setup material in the linked guides and CLI help.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a documentation restructuring PR rather than a report of broken runtime behavior. Static inspection confirms the central README examples, linked guides, source glob, and CLI-option claims align with the current implementation.

Is this the best way to solve the issue?

Yes. A short front-door README with links to the maintained installation, quickstart, engine, provider, session, and integration guides is a more maintainable solution than duplicating volatile flags and model details in the repository landing page.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 3be9329b4ca5.

Labels

Label changes:

• add P3: This is low-risk documentation and onboarding polish with no demonstrated runtime regression or user-facing outage.
• add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This owner-authored documentation PR is outside the external-contributor real-behavior-proof gate; its body nonetheless records concrete CLI, link, docs-site, and package-smoke validation.

Label justifications:

• P3: This is low-risk documentation and onboarding polish with no demonstrated runtime regression or user-facing outage.
• rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🌊 off-meta tidepool and patch quality is 🦞 diamond lobster.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This owner-authored documentation PR is outside the external-contributor real-behavior-proof gate; its body nonetheless records concrete CLI, link, docs-site, and package-smoke validation.

Evidence

What I checked:

• README claims match current CLI contracts: The revised README describes --render, API/browser engine selection, --dry-run, --files-report, --models, doctor --providers, and session follow-ups; current CLI option definitions support those descriptions, including API selection when OPENAI_API_KEY is set and browser fallback otherwise. (bin/oracle-cli.ts:471, 3be9329b4ca5)
• README links point to maintained documentation: All repository-relative documentation links in the proposed README resolve at the PR head, including install, quickstart, engine, provider, session, configuration, agent, MCP, and bridge guides. (README.md:39, 660d75198598)
• Quick-start path is concrete and non-empty: The README's example source glob currently selects 29 TypeScript files under src/oracle, while its test exclusion does not hide the selected production files. (README.md:56, 660d75198598)
• Banner claim is consistent with the actual binary: The checked PR image remains a 1600×770 PNG; the patch changes no executable code, dependencies, workflows, or package metadata. (README-header.png, 660d75198598)
• Documentation ownership history: README history is predominantly Peter Steinberger's work, with recent Oracle README changes also from Paul Bohm; Peter also recently maintained docs and changelog surfaces on current main. (README.md:1, ec9546d34e57)

Likely related people:

• steipete: Peter Steinberger dominates the README history and recently maintained the README, documentation, and changelog surfaces on current main; the current owner-authored PR also follows the repository's README and changelog guidance. (role: recent documentation and release contributor; confidence: high; commits: f1576525341f, 739d0be2bb6a, 5daa6ce8c352; files: README.md, CHANGELOG.md, docs/quickstart.md)
• Paul Bohm: The latest current-main README feature update in the inspected history is Paul Bohm's GPT-5.6 Pro reasoning-mode change, which this consolidation intentionally moves out of the front-door overview. (role: recent README contributor; confidence: medium; commits: ec9546d34e57; files: README.md)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.