Skip to content

docs: the README shows the product before the philosophy - #218

Merged
vicenteliu merged 1 commit into
mainfrom
docs/readme-scannable-highlights
Sep 1, 2026
Merged

docs: the README shows the product before the philosophy#218
vicenteliu merged 1 commit into
mainfrom
docs/readme-scannable-highlights

Conversation

@vicenteliu

Copy link
Copy Markdown
Owner

What

Both READMEs restructured for first-visit scanability, with every factual claim preserved:

  • Visuals first — "A quick look" (web UI screenshot + the TUI gif regenerated in fix: the TUI tour gif stops racing its own workers #213/fix: ingest stops reading the fixture format's own metadata as knowledge #217) moves up right under the intro paragraph.
  • One-line TOC after the intro.
  • Highlights condensed — the six essay-length bullets (Memory, Consultation, Asset inventory, Runtime Skills, Proposed actions, Knowledge bundles) become 2–4 line summaries with [details](#…) anchors.
  • New "Design notes" section after Quick start carries the six essays verbatim — the reasoning stays in the README, it just no longer stands between a visitor and Quick start.
  • zh-CN mirrors the structure exactly; CJK anchors verified against github-slugger semantics.

Review

Ran /code-review high on the diff before this PR. It found 8 real condensation losses, all fixed in both languages:

  1. Intake bullet had lost "(no public endpoint)" and "(no field is ever touched)" — restored.
  2. Multi-user bullet had lost "never the database" — restored.
  3. Multi-provider had lost "when a provider errors" and "remove or upgrade models" — restored; an accidental "declare"→"pin" drift reverted.
  4. WeCom had lost the group-robot vs self-built-app distinction — restored.
  5. Memory bullet's "anchored to an Asset or site" mis-stated the model — back to "up to two anchors (an Asset, a site)".
  6. Stale adjacency: Asset inventory read "the one domain OpsPilot owns" a screen away from Memory's "second owned domain" — now "the first domain OpsPilot came to own".
  7. TOC omitted License — added.
  8. (One pure-style candidate was dropped by the reviewer as no-effect.)

The reviewer also verified: all 28 new anchor links resolve (including CJK slugs), the six moved essays are word-for-word, no external file links into README anchors, and CONTEXT.md terminology is respected.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KXrF6HMB12V1hC9xFtooDE

Restructure both READMEs for scanability without losing a claim:

- "A quick look" (web UI shot + the freshly regenerated TUI gif) moves
  up under the intro, so a visitor sees the product before 100 lines of
  text; a one-line Contents strip follows the intro.
- Highlights condenses the six long-form bullets (Memory, Consultation,
  Asset inventory, Runtime Skills, Proposed actions, Knowledge bundles)
  to 2-4 line summaries with [details] anchors.
- A new "Design notes" section after Quick start keeps the six essays
  verbatim — the reasoning is a selling point, it just no longer blocks
  the path to Quick start.

A high-effort prose review of the diff surfaced eight condensation
losses — dropped guarantees ("no public endpoint", "no field is ever
touched", "never the database", "when a provider errors", group robot
vs self-built app), one altered claim ("up to two anchors" had become
"an Asset or site"), one stale adjacency (inventory as "the one domain
OpsPilot owns" beside Memory as "second owned domain" — now "the first
domain"), and a TOC omission — all fixed in both languages.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KXrF6HMB12V1hC9xFtooDE
@vicenteliu
vicenteliu merged commit 40925ae into main Sep 1, 2026
4 checks passed
@vicenteliu
vicenteliu deleted the docs/readme-scannable-highlights branch September 1, 2026 10:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant