@wirecat/cli-template 0.0.0-stage → 0.1.0

package/docs/commands.md

@@ -0,0 +1,227 @@
+<!-- Generated from the command tree by pnpm generate. Do not edit. -->
+
+# Commands
+
+Every command, option and exit code, generated from the program itself. For the same list as JSON, run
+`app commands --json`.
+
+**The first word is the profile**, a name you choose: `app personal doctor`. `APP_PROFILE`
+does the same for a whole shell session. No profile is assumed: a command that uses an account stops without one and
+lists the profiles on this computer.
+
+## Options for every command
+
+| Option | What it does |
+|---|---|
+| `-V, --version` | output the version number. |
+| `-v, --verbose` | more detail in what is shown: -v ids, -vv everything we know. Default: `0`. |
+| `--json` | machine-readable output: one JSON value on stdout; --json=id,text keeps only those fields. |
+| `--jsonl` | machine-readable output: one JSON object per line, for streaming and jq. |
+| `--quiet` | diagnostics off; a failure is still said. |
+| `--trace` | the connection's own log lines on stderr — never message content. |
+| `--debug` | on a failure, its whole record — cause and stack — in place of the short line. |
+| `--timeout <duration>` | give up on the whole command after this — 30s, 2m, 500ms. |
+| `--offline` | answer from what was recorded and never connect; fails if nothing was. |
+| `--no-input` | never prompt or open interactive login; piped input remains available. |
+| `--max-input-bytes <bytes>` | maximum buffered input bytes (default: 16777216). |
+| `--max-output-bytes <bytes>` | maximum machine output bytes (default: 4194304; 0 disables). |
+| `--brief` | found messages as reference, title, time, sender and excerpt only. |
+| `--full` | found messages with their whole text and every provider field. |
+| `--dry-run` | preview parsed arguments and permissions before running the action. |
+| `--yes` | go ahead without the question an ask level puts before a write. |
+| `--record` | keep this run — ids and timings, never message content. |
+| `--no-record` | do not keep it, whatever the configuration says. |
+
+## `app commands`
+
+every command by section; --json prints its contract, one path per call
+
+### `app commands info`
+
+one command contract, or all schemas, error reasons and explicit overrides
+
+```sh
+app commands info [path]
+```
+
+| Argument | | What it is |
+|---|---|---|
+| `path` | optional | one command path; without one, export schemas, error reasons and explicit overrides. |
+
+**Returns:** one command contract, or all schemas, error reasons and explicit overrides
+
+**Example:** `app commands info messages list`
+
+## `app doctor`
+
+check this installation: version, paths, config, profiles; no keyring or network
+
+```sh
+app doctor
+```
+
+**Returns:** check this installation: version, paths, config, profiles; no keyring or network
+
+**Example:** `app personal doctor`, `app personal doctor --json`
+
+## `app skill`
+
+the instructions an agent is given for this tool
+
+### `app skill show`
+
+print SKILL.md — `app skill install` puts it where Claude Code, Codex and Gemini CLI look for it
+
+```sh
+app skill show [name]
+```
+
+| Argument | | What it is |
+|---|---|---|
+| `name` | optional | one of the skills shipped for a task: follow-ups, link-conversations. |
+
+**Returns:** print the tool's instructions for AI agents
+
+**Example:** `app skill show`, `app skill show follow-ups`
+
+### `app skill install`
+
+write SKILL.md to \~/.claude/skills/app-cli/ (Claude Code) and \~/.agents/skills/app-cli/ (Codex, Gemini CLI)
+
+**Changes something on this computer only.**
+
+```sh
+app skill install [options]
+```
+
+| Option | What it does |
+|---|---|
+| `--for <agents>` | which agents to install for. One of: `claude`, `agents`, `all`. Default: `all`. |
+
+**Returns:** install the tool's instructions for AI agents
+
+**Example:** `app skill install --for agents`
+
+## `app mcp`
+
+serve this profile's commands to an agent over MCP, on stdin and stdout, writes included; the profile's permissions decide — `claude mcp add app -- app personal mcp`
+
+**Changes something in the service.**
+
+```sh
+app mcp
+```
+
+**Returns:** serve this profile's commands to an AI agent
+
+**Example:** `app personal mcp`
+
+## `app upgrade`
+
+upgrade app with the package manager that installed it; --check only looks
+
+**Changes something on this computer only.**
+
+```sh
+app upgrade [options]
+```
+
+| Option | What it does |
+|---|---|
+| `--check` | say whether a newer version exists, and install nothing. |
+
+**Returns:** upgrade app with the package manager that installed it; --check only looks
+
+**Example:** `app upgrade --check`, `app upgrade`
+
+## `app config`
+
+the settings in force, and where each one came from
+
+### `app config show`
+
+the profile, the profiles that exist, and each setting with where it came from
+
+```sh
+app config show [options]
+```
+
+| Option | What it does |
+|---|---|
+| `--bot` | the settings a bot command on this profile gets, rather than the personal account's. |
+
+**Returns:** the profile, the profiles that exist, and each setting with where it came from
+
+**Example:** `app personal config show`
+
+### `app config set`
+
+save a setting to the configuration file
+
+**Changes something on this computer only.**
+
+```sh
+app config set <setting> <value> [options]
+```
+
+| Argument | | What it is |
+|---|---|---|
+| `setting` | required | one of: limit, timeout_ms, color, sender_colors, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, read_other_bots, update_check, skill_hint, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories.<name>, task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups.<name>. |
+| `value` | required | a number, true or false, or for allow a list like send,reaction; for a group tg:work,max:Alice,email:me@x. |
+
+| Option | What it does |
+|---|---|
+| `--defaults` | change what every profile gets, rather than this profile. |
+| `--personal` | only for personal accounts — the personal section of the file. |
+| `--bot` | only for bots — the bot section of the file. |
+
+**Returns:** save a setting to the configuration file
+
+**Example:** `app personal config set limit 20`
+
+### `app config unset`
+
+remove a setting from the configuration file
+
+**Changes something on this computer only.**
+
+```sh
+app config unset <setting> [options]
+```
+
+| Argument | | What it is |
+|---|---|---|
+| `setting` | required | one of: limit, timeout_ms, color, sender_colors, record, keep_runs_for_days, permissions, sends_per_hour, requests_per_minute, transcribe_with, speech_model, search_catch_up, picture_search, embedding_provider, embedding_model, embedding_base_url, embedding_dims, analysis_provider, analysis_model, analysis_base_url, models, read_other_bots, update_check, skill_hint, default_profile, search_stemmers.cyrillic, search_stemmers.latin, phone_countries, task_categories.<name>, task_agent_close, task_agent_close_min, task_first_pass_per_chat, account_groups.<name>. |
+
+| Option | What it does |
+|---|---|
+| `--defaults` | change what every profile gets, rather than this profile. |
+| `--personal` | only for personal accounts — the personal section of the file. |
+| `--bot` | only for bots — the bot section of the file. |
+
+**Returns:** remove a setting from the configuration file
+
+**Example:** `app personal config unset limit`
+
+## Exit codes
+
+Branch on the code, not on the text: the text can change, the code does not.
+
+| Code | When |
+|---|---|
+| `0` | it worked |
+| `2` | `validation_error` |
+| `3` | `configuration_error` |
+| `4` | `authentication_error` |
+| `5` | `permission_error` |
+| `6` | `not_found` |
+| `7` | `confirmation_required` |
+| `8` | `rate_limited` |
+| `9` | `timeout` |
+| `10` | `network_error` |
+| `11` | `provider_error` |
+| `12` | `provider_unavailable` |
+| `13` | `invalid_response` |
+| `14` | `outcome_unknown` |
+| `130` | `cancelled` |
+| `1` | anything else |

package/docs/configuration.md

@@ -0,0 +1,18 @@
+# Settings
+
+Settings live in one file, `config.json`, in the folder `app personal doctor` shows. Each profile has its own part,
+and `defaults` apply to every profile. This page lists how to see and change them.
+
+```sh
+app personal config show
+app personal config set limit 50
+app personal config unset limit
+```
+
+`config show` lists each setting and where it came from: the file, a variable or the default.
+
+## Permissions
+
+`permissions` decides what a command may do for this profile: `allow`, `ask`, `readonly` or `deny`, per permission
+key. Over MCP there is no one to ask, so `ask` lets the command run. `APP_READ_ONLY=1` refuses every write, whatever
+the permissions say.

package/docs/dev/DESIGN.md

@@ -0,0 +1,13 @@
+# Design
+
+`npx @wirecat/cli-template new` writes this page from the answers to the
+[design interview](skills/design-interview/SKILL.md). It is empty in the template: ask the interview and write the
+answers here before building anything.
+
+## Answers
+
+Not answered yet.
+
+## Open questions for the owner
+
+None yet.

package/docs/dev/TESTING.md

@@ -0,0 +1,16 @@
+# Testing
+
+How the tests run, and what they never touch. The rules are the handbook's
+[Testing page](../../node_modules/@wirecat/cli-base/docs/standards/testing.md).
+
+- `pnpm test` runs vitest. `@wirecat/cli-base/testing/setup` gives each test file its own temporary home folder, a
+  keyring that throws and no network; `src/testing/sandbox.ts` points this CLI's config, state, cache and the shared
+  store into that folder.
+- `pnpm test:coverage` adds the coverage floor in `vitest.config.ts`.
+- Each run logs the command lines the tests drove (`coverage/argv.jsonl`). `pnpm test:matrix` turns that log into
+  [test-matrix.md](test-matrix.md); a command or option no test drives needs a reason in
+  `scripts/test-matrix-untested.ts`.
+- `pnpm contracts:check` runs the built CLI against `contracts/plan.json`: help, discovery, errors and the MCP tool
+  list. `cli-contract contracts/plan.json --update` rewrites the snapshots; review the diff.
+- `pnpm smoke` installs the packed package into a temporary folder and runs it offline.
+- `pnpm audit:commands` audits the command tree beside the latest published WireCat CLIs.

package/docs/dev/design-questions.md

@@ -0,0 +1,24 @@
+# Further design questions
+
+Ask these only when the reference CLI does not already answer them, after the seven questions of the
+[design interview](skills/design-interview/SKILL.md). Write each answer into [DESIGN.md](DESIGN.md).
+
+## Storing, indexing, syncing and deleting
+
+1. Which of the service's records are kept locally, and which core entity does each become (people, events,
+   documents, files, messages, meetings)? (WC-DATA-1, WC-DATA-2)
+2. How does it sync: everything each time, from a cursor, or by change token? On demand, on a schedule, or kept
+   running?
+3. When the service deletes something, what happens here? Proposed: mark it deleted, keep it, never wipe. (WC-DATA-7)
+4. Can the person delete local data themselves, and how much: one record, one account, everything?
+
+## Search
+
+1. What should a search find: titles only, the full text, names of people?
+2. Should `search all` and `memo context <person>` show its records?
+3. What must work without a network?
+
+## Security
+
+1. Where are the secrets kept? Proposed: the system keyring. (WC-SECR)
+2. Which writes need a permission, and which are never allowed whatever the permissions? (WC-PERM)

package/docs/dev/reference-clis.md

@@ -0,0 +1,15 @@
+# Reference CLIs
+
+The template has no sample code. The agent that builds a new CLI learns from the WireCat CLI closest to it, picked by
+the first question of the [design interview](skills/design-interview/SKILL.md):
+
+| Category | Learn from |
+| --- | --- |
+| messenger | [whatsapp-cli](https://github.com/WireCatLabs/whatsapp-cli), the handbook's worked example; then [tg-cli](https://github.com/WireCatLabs/tg-cli) and [max-cli](https://github.com/WireCatLabs/max-cli) |
+| files and documents | [drive-cli](https://github.com/WireCatLabs/drive-cli) |
+| meetings | [zoom-cli](https://github.com/WireCatLabs/zoom-cli) |
+| notes | [cli-memo](https://github.com/WireCatLabs/cli-memo) |
+| mail, calendar, other | none yet: pick the nearest one with the owner |
+
+Until cli-core has a provider registry, a CLI made from this template is not listed as a provider of its own, and
+`search` finds its records as messages.

package/docs/dev/skills/design-interview/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: design-interview
+description: Ask the owner the seven design questions for a new WireCat CLI before building anything, then the further questions the reference CLI does not answer, and write the answers to docs/dev/DESIGN.md. Use when DESIGN.md has no answers, when asked to design or start the CLI, «спроектировать», «начать CLI».
+---
+
+# Design interview
+
+Ask before you build. Each question is multiple choice, and every one also takes "Other", typed by hand. Ask them in
+this order, one at a time, and write each answer down as it comes. `npx @wirecat/cli-template new` asks the same
+questions in a terminal and takes them as flags without one; when `DESIGN.md` already has the answers, read them and
+go to the further questions.
+
+1. **What kind of tool is it?** messenger · mail · notes · files and documents · calendar · meetings · other. It
+   picks the reference CLI (see [Reference CLIs](../../reference-clis.md)).
+2. **Which languages is the content in?** Any languages, several allowed: the messages, documents or transcripts the
+   CLI handles. The answer picks the language-dependent parts: search stemming, the embedding and speech models.
+3. **How does a person sign in?** OAuth in the browser · an API token or key · a session (phone code, QR) · none ·
+   other.
+4. **What does the service offer to build on?** an official API with an official client library · official API
+   documentation only · nothing official · other.
+5. **How do people filter what they find?** by time · by person · by container (chat, folder, calendar) · by words in
+   the text · by status or label · other; several allowed.
+6. **What must never reach the store, a log or the output?** tokens and passwords · one-time codes and passcodes ·
+   links that carry a secret · the full content, keep only metadata · other; several allowed.
+7. **What untrusted input arrives?** messages from other people · files and attachments · links · names and titles set
+   by others · none · other; several allowed.
+
+Then read the reference CLI and ask the [further questions](../../design-questions.md) it does not answer.
+
+## What to write
+
+`docs/dev/DESIGN.md`: the seven answers, the reference CLI, the further answers, and a list of open questions for
+the owner. Name the reference CLI in `AGENTS.md`, between the `cli-template:reference-cli` markers. Start building
+only after the owner has read `DESIGN.md`.

package/docs/dev/skills/release/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: release
+description: Prepare a release of this CLI for the owner to publish — run release:check, write the changelog under the handbook's headings, check the docs against what changed, raise the version in a pull request; the owner runs bin/release. Use when asked to release, prepare a release, cut a version, «выпуск», «выпустить версию».
+---
+
+# Release
+
+The rules are the handbook's [Releases page](../../../../node_modules/@wirecat/cli-base/docs/standards/releases.md)
+(`WC-REL-<n>`), which wins over this skill. An agent prepares the release; the owner merges the release pull request
+and runs `bin/release`.
+
+1. **What changed.** In a worktree off `origin/main`: `git log --oneline v<last version>..origin/main`. The
+   `docs/commands.md` diff shows what a cli-core or cli-base release changed in the commands.
+2. **The checks.** `pnpm release:check`. Before the version is raised, only the changelog's `## Unreleased` may be
+   left; report anything else and fix it in the release pull request.
+3. **The changelog.** Write `## Unreleased` under the handbook's headings, each at most once: `Added`,
+   `Changed — may break callers`, `Fixed`, `Security`, `Removed` (`WC-DOC-14` to `WC-DOC-18`). No internal ids.
+4. **The docs.** `README.md`, `docs/*.md` and `skills/app-cli/SKILL.md` state what the code does now (`WC-DOC-3`).
+   `pnpm generate` and `pnpm test:matrix` rewrite the generated pages (`WC-DOC-4`).
+5. **The version.** `npm view @wirecat/app-cli version` is what is published. Set the next version in
+   `package.json`, run `pnpm version:sync`, date the section as `## <version> — DD.MM.YYYY`, run
+   `pnpm release:check` again, and open the pull request `chore(release): <version>`.
+6. **The owner** merges it and runs `bin/release` on a clean `main`. `bin/release --local` publishes from this
+   computer when GitHub Actions cannot, with the owner's own npm login or `NPM_TOKEN`.

package/docs/dev/test-matrix.md

@@ -0,0 +1,52 @@
+<!-- Generated by cli-dev test-matrix from the command tree and a test run. Do not edit; `pnpm test:matrix`. -->
+
+# Test matrix
+
+Every command and option of `app`, and whether an offline test drives it through the CLI. ✅ a test
+ran it · ⛔ not tested offline, with the reason and where it is checked instead · ❌ nothing.
+Measured from the test run (`coverage/argv.jsonl`), not searched for — see
+[TESTING.md](TESTING.md) for how, and for the states and failures that cut across commands.
+
+**37 ✅ · 2 ⛔ · 0 ❌** — 11 commands, 28 options.
+
+| Command | Option | | Note |
+|---|---|---|---|
+| `commands` |  | ✅ |  |
+| `commands info` |  | ✅ |  |
+| `doctor` |  | ✅ |  |
+| `skill show` |  | ✅ |  |
+| `skill install` |  | ✅ |  |
+| `skill install` | `--for` | ✅ |  |
+| `mcp` |  | ✅ |  |
+| `upgrade` |  | ✅ |  |
+| `upgrade` | `--check` | ✅ |  |
+| `config show` |  | ✅ |  |
+| `config show` | `--bot` | ✅ |  |
+| `config set` |  | ✅ |  |
+| `config set` | `--defaults` | ✅ |  |
+| `config set` | `--personal` | ✅ |  |
+| `config set` | `--bot` | ✅ |  |
+| `config unset` |  | ✅ |  |
+| `config unset` | `--defaults` | ✅ |  |
+| `config unset` | `--personal` | ✅ |  |
+| `config unset` | `--bot` | ✅ |  |
+| `help` |  | ✅ |  |
+| *global* | `--version` | ⛔ | Commander answers before any command runs, so the trace never sees it; `pnpm version:check` checks it |
+| *global* | `--verbose` | ✅ |  |
+| *global* | `--json` | ✅ |  |
+| *global* | `--jsonl` | ✅ |  |
+| *global* | `--quiet` | ✅ |  |
+| *global* | `--trace` | ✅ |  |
+| *global* | `--debug` | ✅ |  |
+| *global* | `--timeout` | ✅ |  |
+| *global* | `--offline` | ✅ |  |
+| *global* | `--no-input` | ✅ |  |
+| *global* | `--max-input-bytes` | ✅ |  |
+| *global* | `--max-output-bytes` | ✅ |  |
+| *global* | `--brief` | ✅ |  |
+| *global* | `--full` | ✅ |  |
+| *global* | `--dry-run` | ✅ |  |
+| *global* | `--yes` | ✅ |  |
+| *global* | `--record` | ✅ |  |
+| *global* | `--no-record` | ✅ |  |
+| *global* | `--help-all` | ⛔ | Commander answers before any command runs, so the trace never sees it; contracts/help.snap covers help |

package/docs/index.md

@@ -0,0 +1,7 @@
+# app
+
+`app` brings a service to the terminal, to scripts and to AI agents. This page is where a reader starts: say what
+the tool does, who it is for, and the first command to run. It will say that once the tool connects to its service.
+
+Today it has the commands every WireCat CLI shares: `doctor`, `commands`, `config`, `skill`, `mcp` and `upgrade`.
+Start with [installation](installation.md), then [usage](usage.md).

package/docs/installation.md

@@ -0,0 +1,17 @@
+# Install
+
+Install `app` once on each computer where you or an agent use it. You need Node.js 22.16 or later, or 24.
+
+```sh
+npm install -g @wirecat/app-cli
+app --version
+```
+
+Check the installation, then pick a profile name for your account, such as `personal`:
+
+```sh
+app personal doctor
+```
+
+`doctor` needs no network and opens no keyring. It shows the version, where settings live and the profiles that
+exist. Next: [use it](usage.md).

package/docs/meta.json

@@ -0,0 +1,18 @@
+{
+  "title": "app",
+  "pages": [
+    "---Start---",
+    "index",
+    "installation",
+    "---Guides---",
+    "usage",
+    "---Reference---",
+    "commands",
+    "configuration",
+    "---When something goes wrong---",
+    "troubleshooting",
+    "security",
+    "---Project---",
+    "changelog"
+  ]
+}

package/docs/security.md

@@ -0,0 +1,8 @@
+# Security
+
+What WireCat CLIs share — the keyring, permissions, MCP and what never reaches a log — is on the
+[shared security page](https://wirecat.dev/en/docs/security). This page keeps only what is particular to `app`.
+
+`app` keeps its settings in `config.json` and its state in the folders `app personal doctor` shows. It sends nothing
+to any service yet. Report a vulnerability as [SECURITY.md](https://github.com/WireCatLabs/app-cli/blob/main/SECURITY.md)
+says.

package/docs/troubleshooting.md

@@ -0,0 +1,14 @@
+# When something goes wrong
+
+Start with the symptom, run the check, then retry the command. Keep the error code and the profile name for a
+support request.
+
+| Symptom | What to do |
+| --- | --- |
+| Not sure what is set up | Run `app personal doctor`. It reads no keyring and uses no network. |
+| `app` is not found | Open a new terminal, and check that npm's global folder is on `PATH`. |
+| "name a profile" | Put the profile first, as in `app personal config show`, or set `APP_PROFILE`. |
+| The settings file does not read | `doctor` names the file and the error. Fix it, or move it away and set the values again. |
+| A write is refused | The profile's permissions or `APP_READ_ONLY` stop it; see [settings](configuration.md#permissions). |
+
+Never paste a token, a password or private content into a support request.

package/docs/usage.md

@@ -0,0 +1,31 @@
+# Use it
+
+This page explains how a command is built, and how an agent uses the tool. Read it before your first command.
+
+## The profile comes first
+
+A profile is a name you choose for one account. It is the first word of every command that uses an account:
+
+```sh
+app personal config show
+```
+
+`APP_PROFILE=personal` does the same for one shell session. No profile is ever assumed, not even the only one: a
+command without one stops with exit code 2 and lists the profiles on this computer.
+
+## Output for scripts
+
+Every command takes `--json`, and prints one JSON value on stdout. Errors are JSON on stderr, with a code to branch
+on. The [command reference](commands.md) lists the codes.
+
+## Agents
+
+`app skill install` puts the tool's skill where Claude Code, Codex and Gemini CLI look for it. `app personal mcp`
+serves the profile's commands over MCP, on stdin and stdout:
+
+```sh
+claude mcp add app -- app personal mcp
+```
+
+The server offers every command, the ones that write included. The profile's permissions decide what runs; see
+[settings](configuration.md#permissions).

package/kit/README.md

@@ -0,0 +1,123 @@
+# kit — `new` and `upgrade`
+
+The copy tool behind `npx @wirecat/cli-template`. It is the package's `cli-template` bin
+(`kit/dist/main.js`, built from `kit/src` by `tsc -p kit`). It is never copied into a new CLI.
+
+```sh
+npx @wirecat/cli-template new cal-cli --command cal --package @wirecat/cal-cli --owner WireCatLabs \
+  --category notes --content-lang en,ru --sign-in token --api official-docs --filters time,person \
+  --never-store tokens --untrusted messages,links
+npx @wirecat/cli-template upgrade --dry-run
+```
+
+## `new <name>`
+
+`new` copies the files of its own package version into `./<name>`. It renames the placeholders, rewrites
+`package.json`, runs `git init` and writes `template.json`, `docs/dev/DESIGN.md` and the reference CLI into
+`AGENTS.md`. It then prints the four steps that need a person. It does not install packages, commit or push.
+
+In a terminal it asks for every missing answer. Without a terminal, a missing answer is an error that lists the
+choices. Nothing is guessed.
+
+| Flag | Answers (several are comma-separated) |
+|---|---|
+| `<name>` | the folder and repository name |
+| `--command` | the command word |
+| `--package` | the npm package name |
+| `--owner` | the GitHub owner |
+| `--category` | `messenger`, `mail`, `notes`, `files`, `calendar`, `meetings` |
+| `--content-lang` | language codes, several: `en,ru` |
+| `--sign-in` | `oauth`, `token`, `session`, `none` |
+| `--api` | `official-client`, `official-docs`, `unofficial` |
+| `--filters` | several of `time`, `person`, `container`, `text`, `status` |
+| `--never-store` | several of `tokens`, `codes`, `secret-links`, `content` |
+| `--untrusted` | several of `messages`, `files`, `links`, `names`, or `none` alone |
+
+Every question except the names and `--content-lang` also takes `other:<your answer>`.
+
+The content languages go only into `DESIGN.md`. The file also holds the speech-model order a messenger definition
+should use, and the warnings for languages that have no stemmer or speech model in cli-core. `new` writes no search
+or model setting.
+
+## `upgrade`
+
+Run it in a CLI made from the template, with a clean git working tree. For each template-owned file that the
+template changed since the recorded version, it asks one of four things:
+
+- **apply** merges the change with `git merge-file`. The base is the recorded version, downloaded with `npm pack`.
+  "Ours" is the CLI's file and "theirs" is this version. Both template versions are renamed first, so the command
+  word never conflicts.
+- **replace** takes the template's file as it is.
+- **skip** keeps the CLI's file. It is asked again only when the template changes that file again.
+- **diff** shows the template's change.
+
+Without a terminal, `--apply`, `--replace` or `--skip` sets the answer for every file. `--dry-run` lists what each
+file would get and writes nothing. Seeds and `package.json` are never touched.
+
+A conflict leaves git markers, and `template.json` keeps the new state under `pending`. Resolve the markers and run
+`upgrade` again: it checks that the markers are gone and then moves to the new version.
+
+## `template.json` in this repository
+
+```json
+{
+  "files": [".github/", "bin/release", "AGENTS.md", "docs/meta.json"],
+  "seeds": ["src/", "README.md", "docs/", "config/wirecat/"],
+  "placeholders": {
+    "command": "app", "name": "app-cli", "package": "@wirecat/app-cli", "repository": "WireCatLabs/app-cli"
+  }
+}
+```
+
+- `files` lists the template-owned files that `upgrade` replays. `seeds` lists the files copied once and never
+  touched again; `config/wirecat/` goes there, because community's installer owns it. An entry ending in `/` is a
+  folder. The most specific entry wins: an exact path beats a folder, a deeper folder beats a shallower one, and a
+  seed wins a tie. Only listed files are copied. A listed file missing from the package stops `new`.
+- `template.json` and `kit/` are never copied, whatever the lists say. The kit's tests run inside `pnpm test`, so
+  the configs name `kit/`: `new` and `upgrade` drop every `"kit/…"` entry from `vitest.config.ts`, `biome.json`,
+  `cspell.json`, `tsconfig*.json` and `.markdownlint-cli2.jsonc`. Do not add a kit-only workflow: `.github/` is
+  template-owned and would carry it into every new CLI.
+- `README.md` and `CHANGELOG.md` describe the template, so `new` writes short ones for the new CLI.
+- `docs/dev/DESIGN.md` is always a seed: it holds the CLI's interview answers.
+- `package.json` is always a seed. `new` rewrites it: `name` becomes `--package`, `version` becomes `0.0.0`, and
+  `repository`, `homepage` and `bugs` point at `<owner>/<name>`. It also drops every `bin`, `files` entry and script
+  that points into `kit/`, and the `&& pnpm kit:…` parts of other scripts. `src/version.ts` gets `VERSION = "0.0.0"`.
+- `placeholders` is optional; the defaults are shown above. The command word is replaced as a whole word, so `app`
+  changes but `application` does not. Its upper-case form changes too: `APP_HOME` becomes `CAL_HOME`. Followed by a
+  colon and a space it is a key and stays, so cli-core's `app: APP` becomes `app: CAL`. `name` (`app-cli`) is the repository
+  name: `skills/app-cli/` becomes `skills/cal-cli/`. The word `app` cannot appear in prose for any other meaning.
+  Paths are renamed the same way: `src/bin/app.ts` becomes `src/bin/cal.ts`.
+- The version is `package.json`'s, never a second copy.
+- `AGENTS.md` can hold the block that `new` fills with the reference CLI:
+
+  ```md
+  <!-- cli-template:reference-cli:start -->
+  <!-- cli-template:reference-cli:end -->
+  ```
+
+  Without the block, `new` appends one.
+
+## `template.json` in a CLI made from it
+
+`new` writes this shape and `upgrade` keeps it current:
+
+```json
+{
+  "template": "@wirecat/cli-template",
+  "version": "0.1.0",
+  "names": { "name": "cal-cli", "command": "cal", "package": "@wirecat/cal-cli", "owner": "WireCatLabs" },
+  "files": { ".github/workflows/ci.yml": "<sha256 of the renamed template file at this version>" },
+  "seeds": ["src/", "README.md", "docs/", "config/wirecat/"]
+}
+```
+
+## What the package needs from the repository
+
+- `"bin": { "cli-template": "kit/dist/main.js" }`, and `kit/dist` in `files`. No ignore file inside `kit/`: npm
+  applies it and drops `kit/dist` from the package. npm also never packs `pnpm-lock.yaml`, so it is not a seed; the
+  new CLI makes its own on `pnpm install`.
+- Every template-owned file and seed in `files`. npm drops a nested `.gitignore` and any `.npmrc`; the test in
+  `kit/test/package.test.ts` runs the bin from a real tarball to catch that.
+- `kit:build` (`tsc -p kit`) run by `build`, because `bin/release` publishes with `--ignore-scripts`. Node does not
+  strip types under `node_modules`, so the bin must be JavaScript.
+- `kit/test/**/*.test.ts` in vitest's `include`; `kit/dist` is ignored by the root `**/dist` rules of Biome and git.