Skip to content

docs(readme): say why, what and how, with two quick-start paths - #188

Merged
leemour merged 2 commits into
mainfrom
docs/readme-why-what-how
Nov 17, 2026
Merged

leemour merged 2 commits into
mainfrom
docs/readme-why-what-how

Conversation

@leemour

@leemour leemour commented Nov 17, 2026

Copy link
Copy Markdown
Member

Why

The owner likes how HKUDS/CLI-Anything's README explains why, what and how in every section. This takes the best of it and keeps what ours already did well: the banner, the GIF, the links row (Docs · Reference · Discord, WC-DOC-23), the measured 16 s / 12 s and the comparison table from #168, #169, #171, #174 and #175.

What

  • README: three gains under the banner; a quick start with two paths (from an API description, from wirecat.config.ts) and a third row for the agent skill; why a CLI and MCP, with a table of how each agent connects; a pain-to-fix table; what you get (the tree with the config files); how it works (description → config → hooks → cli-dev ready → live check → release); the tests that come with it, with two real fault-case names from cli-core's CRM contract; the nine public CLIs made from the template; design principles; limitations (what stays hand-written, the live check needs a test account, config covers CRM only); a roadmap (GraphQL in new, configs for more categories, OAuth from securitySchemes, RPC services).
  • Numbers: only measured ones (feat(kit): --preset generic, a new CLI's README in tg-cli's order, the api-to-cli skill, and the demo GIF #171) and one estimate, labelled as such, with its whole range (42% to 87%), from the cli-factory plan.
  • A new CLI's README (cliReadme in kit/src/new.ts): says that mcp add needs --allow-writes for a profile whose tools may write. Without it the printed command fails (cli-core mcp-command.js, probeStdio → potentialWrites).
  • Changelog fragment changes/docs-readme-why-what-how.md.

Skipped from their README: news feed, star history, citation, translated READMEs, test-count badges (we have no measured count). The idea list with the reason for each is in cli-private (plans/2026-11-16-cli-factory/readme-ideas.md).

Testing

  • pnpm docs:check (docs rules, fragments, cspell, rumdl, markdownlint, kit docs): passed.
  • pnpm vitest run kit (122 passed), biome and tsc -p kit on kit/src/new.ts: passed.
  • A fresh agent checked every claim against the code, the installed packages, cli-core/cli-base main and the nine repos. Its six false and eight imprecise findings are fixed in the second commit (for example: each operation is not its own MCP tool, ask runs over MCP, GraphQL is not yet in a released cli-core, src/hooks.ts is not generated).

Not released: docs and a one-paragraph seed change, the next release carries it.

🤖 Generated with Claude Code

leemour and others added 2 commits November 17, 2026 23:59
Rework the README with the best ideas from HKUDS/CLI-Anything's README:
three gains under the banner, a quick start from an API description and
from a wirecat.config.ts, why a CLI and MCP with a table of agents, a
pain-to-fix table, how it works from the description to cli-dev ready,
the tests that come with it, the nine CLIs built with it, design
principles, limitations and a roadmap. The banner, the GIF, the links
row and the comparison stay. The only estimate (config coverage) is
labelled as one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- mcp add needs --allow-writes for a profile that may write, in the
  template's quick start and in a new CLI's README
- an operation is a command the MCP server runs, not an MCP tool each
- upgrade merges CI, release and agent files; cli-core brings code fixes
- ask runs over MCP, so the profile served there wants readonly or deny
- the api-to-cli skill runs new --spec-url, not --from-config
- GraphQL: cli-base generates, cli-core's next release sends
- src/hooks.ts is yours to add; the live check binds WireCat's CLIs
- the coverage estimate gives the whole range, 42% to 87%
- Discovery goes through --spec discovery, not --spec-url

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@leemour
leemour merged commit 7b6cb3d into main Nov 17, 2026
16 checks passed
@leemour
leemour deleted the docs/readme-why-what-how branch November 17, 2026 23:03
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