Skip to content

docs(readme): open with what you build, a code sample and who builds on it - #3073

Merged
leemour merged 1 commit into
mainfrom
docs/library-readme
Nov 17, 2026
Merged

leemour merged 1 commit into
mainfrom
docs/library-readme

Conversation

@leemour

@leemour leemour commented Nov 17, 2026

Copy link
Copy Markdown
Member

Why

The README opened with a banner that said cli-core under cli-base's tagline, a 15-row documents table and the rename history. A newcomer could not tell from the first screen what they would build with cli-core. The README research (2026-11-17) proposed a library opening: one sentence naming the stack, one proof, "Built on it". The owner chose a code sample, not a GIF, as the proof.

What

  • README. Hero sentence, then a short program where an adapter gets the local store, search and the MCP server, and three commands with their real output (run with the kit's fakeAdapter in place of a service, isolated store, keyring unreachable). "Built on it" names tg-cli, max-cli, gcal-cli and the 12 other WireCat CLIs that depend on cli-core on main. Install, links, badges, then the same "which package" diagram as cli-base's README. Features as gains with one checked number each (54 ms search median over 100,341 synthetic messages from cli-testing, 3 MCP tools, 30 sends an hour, 29 contract cases). The stale "26 entry points" is gone (there are 46). The architecture diagram moves to "How it works". Key documents and the rename history move to the end. Every link target of the old page is still on it.
  • Banner. docs/images/src/banner.html plus docs/images/src/render.ts (pnpm docs:images). Same file name, so npm's page of the current release keeps working.
  • TESTING.md gets the macOS and Windows paragraph that left the README. cspell.json learns gcal and whatsapp.

No changelog fragment: nothing changes for a caller.

Testing

pnpm docs:check, pnpm docs:lint, pnpm docs:spell, pnpm standards:check, biome on the changed files. The README program was typechecked against the built package with strict settings and run.

🤖 Generated with Claude Code

…on it

The README now opens the way a library page should: one sentence that says what
you build with cli-core and on which stack, then a short program where an
adapter gets the local store, search and the MCP server, with three commands
and their real output (run with the kit's fakeAdapter in place of a service).
"Built on it" names tg-cli, max-cli, gcal-cli and the 12 other WireCat CLIs
whose package.json on main depends on cli-core. Install, the links row and the
badges follow, then the same small diagram as cli-base that says which package
to install.

Features are written as gains with one checked number each: 54 ms median search
over 100,341 synthetic messages (cli-testing), 3 MCP tools (`mcp check`), 30
sends an hour by default, 29 contract cases. The stale "26 entry points" (there
are 46) is gone. The documents table and the rename history move to the end,
and every link target of the old page is still on it.

The banner said cli-core with cli-base's tagline. It is now rendered from
docs/images/src/banner.html by `pnpm docs:images` with cli-core's own promise.
The paragraph on which CI runs on macOS and Windows moves to TESTING.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit 6f60690 into main Nov 17, 2026
49 checks passed
@leemour
leemour deleted the docs/library-readme branch November 17, 2026 09:58
leemour added a commit that referenced this pull request Nov 17, 2026
#3073 overwrote `docs/images/cli-core-banner.png`. The owner prefers the
earlier image ("The foundation for agent-ready CLIs"), which is also the
repository's social preview. Restored from 4ab1191; `banner.html`
renders the same text; the README alt matches. Images and one alt only.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
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