@wirecat/cli-base 0.63.0 → 0.64.0

package/dist/dev/main.js

@@ -66,7 +66,15 @@ const USAGE = `usage: cli-dev <command> [options]
                                        rules by its own lint/ folder; the rest by --baseline
                                        (audit/baseline). --groups replaces PARITY_GROUPS with the
                                        JSON list of parity groups in that file; --differences adds
-                                       to the groups in use`;
+                                       to the groups in use
+  bundle --bin <dist/bin/name.js> [--external <package>]... [--anchor <package>]... [--harmless <path>]...
+                                       bundles the compiled bin with esbuild (a devDependency) into
+                                       dist/bundle/ and turns the bin into its loader. --external keeps
+                                       a package outside (* matches anything); --anchor adds a package
+                                       whose modules keep their installed place, as cli-core's do;
+                                       --harmless names a third-party file whose import.meta or
+                                       __dirname was read and found harmless. Fails when a bundled
+                                       module would look for a file or package in the wrong place`;
 const load = async (cwd, path) => (await import(pathToFileURL(isAbsolute(path) ? path : join(cwd, path)).href));
 const report = (io, problems, ok) => {
     for (const problem of problems)
@@ -604,6 +612,43 @@ const auditRun = (args, io) => {
         io.err(problem);
     return problems.length > 0 ? 1 : 0;
 };
+const bundleCommand = async (args, io) => {
+    const { values } = parseArgs({
+        args,
+        options: {
+            bin: { type: "string" },
+            external: { type: "string", multiple: true },
+            anchor: { type: "string", multiple: true },
+            harmless: { type: "string", multiple: true },
+        },
+    });
+    if (!values.bin) {
+        io.err("bundle needs --bin <dist/bin/name.js>");
+        return 2;
+    }
+    // esbuild is an optional peer: the other commands, and a CLI that does not bundle, never load it.
+    try {
+        await import("esbuild");
+    }
+    catch {
+        io.err("cli-dev bundle needs esbuild: add it as a devDependency, in cli-base's peer range");
+        return 1;
+    }
+    const { bundle } = await import("./bundle.js");
+    const result = await bundle({
+        root: io.cwd,
+        bin: values.bin,
+        external: values.external ?? [],
+        anchored: values.anchor ?? [],
+        harmless: values.harmless ?? [],
+    });
+    if (result.problems.length > 0) {
+        io.err(`the bundle would look for these in the wrong place, or is incomplete:\n${result.problems.join("\n")}`);
+        return 1;
+    }
+    io.out(`bundle: ${values.bin} loads dist/bundle/; a server preloads ${result.chunks.length} chunks`);
+    return 0;
+};
 export const main = async (argv, io) => {
     const [command, ...args] = argv;
     if (args.includes("--help")) {
@@ -649,6 +694,8 @@ export const main = async (argv, io) => {
             return lint(args, io);
         case "audit":
             return audit(args, io);
+        case "bundle":
+            return bundleCommand(args, io);
         case "help":
         case "--help":
         case "-h":

package/dist/skill/index.d.ts

@@ -11,7 +11,7 @@ export interface SkillApp {
 }
 export declare const SKILL_TARGETS: readonly ["claude", "agents"];
 export type SkillTarget = (typeof SKILL_TARGETS)[number];
-/** `~/.claude/skills` is Claude Code's; `~/.agents/skills` is read by Codex and Gemini CLI. */
+/** `~/.claude/skills` is Claude Code's; `~/.agents/skills` is read by Codex, Gemini CLI and OpenClaw. */
 export declare const skillPath: (target: SkillTarget, appName: string, env: Env) => string;
 /**
  * `metadata.version` from the frontmatter — where the Agent Skills specification keeps fields of its

package/dist/skill/index.js

@@ -16,7 +16,7 @@ import { executableEnvironment, executableOnPath } from "../executable.js";
 import { CHECK_EVERY_MS, isNewer, readNoticeState, writeUpdateState } from "../update/index.js";
 export const SKILL_TARGETS = ["claude", "agents"];
 const homeOf = (env) => env.HOME || env.USERPROFILE || homedir();
-/** `~/.claude/skills` is Claude Code's; `~/.agents/skills` is read by Codex and Gemini CLI. */
+/** `~/.claude/skills` is Claude Code's; `~/.agents/skills` is read by Codex, Gemini CLI and OpenClaw. */
 export const skillPath = (target, appName, env) => join(homeOf(env), target === "claude" ? ".claude" : ".agents", "skills", appName, "SKILL.md");
 const FRONTMATTER = /^---(\r?\n)([\s\S]*?\r?\n)?---(\r?\n|$)/;
 const scalar = (key, indent) => new RegExp(`^${indent}${key}:[ \\t]*["']?([^"'\\r\\n]*?)["']?[ \\t]*\\r?\\n?$`);
@@ -234,7 +234,7 @@ export const skillCommand = (app, skill, environment, more = {}) => {
     const named = Object.keys(more);
     const show = annotate(command.command("show"), { effects: { remote: "none", local: "read" } })
         .summary("print the tool's instructions for AI agents")
-        .description(`print SKILL.md — \`${app.command} skill install\` puts it where Claude Code, Codex and Gemini CLI look for it; --for prints the copy already there`);
+        .description(`print SKILL.md — \`${app.command} skill install\` puts it where Claude Code, Codex, Gemini CLI and OpenClaw look for it, and where Hermes does on request; --for prints the copy already there`);
     if (named.length > 0)
         show.argument("[name]", `one of the skills shipped for a task: ${named.join(", ")}`);
     show.addOption(new Option("--for <agents>", "print the copy installed for these agents instead of this version's").choices(SKILL_TARGETS));

package/dist/standards/audit.js

@@ -64,7 +64,7 @@ export const PARITY_GROUPS = defineParityGroups([
     { name: "messengers", members: ["tg", "max"], covers: "tree", differences: [] },
     {
         name: "all",
-        members: ["tg", "max", "memo", "drive", "zm", "wa"],
+        members: ["tg", "max", "memo", "drive", "zm", "wa", "gcal"],
         covers: ["commands", "doctor", "skill", "mcp", "upgrade", "search", "notes", "meetings"],
         differences: [],
     },

package/dist/standards/flags-calendar.d.ts

@@ -0,0 +1,2 @@
+import type { VocabularyFlag } from "./vocabulary.js";
+export declare const CALENDAR_FLAGS: VocabularyFlag[];

package/dist/standards/flags-calendar.js

@@ -0,0 +1,59 @@
+export const CALENDAR_FLAGS = [
+    { name: "--end-time", value: "<time>", role: "value", type: "time", meaning: "when it ends" },
+    {
+        name: "--start-date",
+        value: "<date>",
+        role: "value",
+        type: "time",
+        meaning: "the first day of something that lasts whole days, such as an all-day event",
+    },
+    {
+        name: "--end-date",
+        value: "<date>",
+        role: "value",
+        type: "time",
+        meaning: "the last day of something that lasts whole days, such as an all-day event",
+    },
+    { name: "--location", value: "<text>", role: "value", type: "string", meaning: "where it takes place" },
+    {
+        name: "--attendee",
+        value: "<email>",
+        role: "value",
+        type: "string",
+        meaning: "a person invited to the event, by email address; repeat it for more",
+    },
+    {
+        name: "--id",
+        value: "<id>",
+        role: "value",
+        type: "id",
+        meaning: "the id to create it with, chosen beforehand, so a retry finds it instead of making a second one",
+    },
+    {
+        name: "--calendar",
+        value: "<id>",
+        role: "target",
+        type: "id",
+        meaning: "the calendar it acts on, when the thing is on more than one",
+    },
+    {
+        name: "--repeat",
+        value: "<rule>",
+        role: "value",
+        type: "string",
+        meaning: "how it repeats, as an RFC 5545 rule such as FREQ=WEEKLY;BYDAY=MO;COUNT=10",
+    },
+    {
+        name: "--hours",
+        value: "<from-to>",
+        role: "target",
+        type: "string",
+        meaning: "the working hours of each day to look in, such as 09:00-17:00, in the owner's time zone",
+    },
+    {
+        name: "--series",
+        role: "target",
+        type: "switch",
+        meaning: "act on the whole repeating event, not only this occurrence",
+    },
+];

package/dist/standards/flags-how.js

@@ -308,7 +308,13 @@ export const HOW_FLAGS = [
         meaning: "do not keep this run, whatever the configuration says",
     },
     { name: "--no-registries", role: "mode", type: "switch", meaning: "do not ask the public ban lists" },
-    { name: "--notify", role: "mode", type: "switch", meaning: "tell the chat's members about it" },
+    {
+        name: "--notify",
+        role: "mode",
+        type: "switch",
+        meaning: "tell the people it concerns about it: the chat's members, or an event's attendees",
+    },
+    { name: "--no-notify", role: "mode", type: "switch", meaning: "tell nobody about it" },
     { name: "--offline", role: "mode", type: "switch", meaning: "answer from what was recorded and never connect" },
     {
         name: "--operation-id",

package/dist/standards/vocabulary.js

@@ -1,4 +1,5 @@
 import * as v from "valibot";
+import { CALENDAR_FLAGS } from "./flags-calendar.js";
 import { HOW_FLAGS } from "./flags-how.js";
 import { WHAT_FLAGS } from "./flags-what.js";
 import { duplicates, parseRegistry, text, word } from "./registry.js";
@@ -123,6 +124,7 @@ const verbs = [
         "bring the local store up to date from the source: only what changed, or the whole list where the source cannot say; a mirror syncs both ways",
     ],
     ["fetch", "one bounded pull of one named thing into the store, not a catch-up"],
+    ["unsync", "stop syncing a thing; what the store already holds stays"],
     ["export", "write from the store to a file"],
     ["import", "bring a file or list the user gives into the store or the messenger, once"],
     ["download", "save a file from the source to this machine"],
@@ -153,6 +155,7 @@ const verbs = [
     ["unstar", "take the owner's star off a message"],
     ["vote", "answer a poll"],
     ["answer", "reply to a button someone pressed under a bot's message"],
+    ["respond", "answer an invitation: accept, tentatively accept or decline it"],
     ["press", "press a button under a bot's message; the bot sees who pressed it"],
     ["action", "show what a bot is doing in a chat, such as typing, for a few seconds"],
     ["watch", "follow new events as they come, and keep them"],
@@ -175,6 +178,8 @@ const verbs = [
     ["acknowledge", "record successful delivery using the exact receipt issued when the item was claimed"],
     ["confirm", "the owner accepts what an agent proposed"],
     ["reject", "the owner refuses what an agent proposed"],
+    ["review", "list what waits for the owner's decision"],
+    ["resolve", "settle one thing that waits for the owner's decision, with the owner's choice"],
     ["move", "move a file in the source"],
     ["copy", "copy a file in the source"],
     ["run", "run a saved job once, now, as its timer would"],
@@ -241,6 +246,9 @@ const collections = [
     ["files", "files in the source, such as Google Drive, read and changed there"],
     ["comments", "comments people left on a thing in the source: a channel post or a file"],
     ["meetings", "stored meetings, from Zoom or another provider"],
+    ["calendars", "calendars of an account, each synced or not"],
+    ["events", "calendar entries: meetings, appointments and other things on a calendar"],
+    ["people", "persons the owner deals with, such as the attendees of events"],
     ["recordings", "the files a provider recorded of a meeting"],
     ["jobs", "work this tool runs in the background or on a timer"],
     ["actions", "what an agent proposes to do; the owner confirms or rejects each"],
@@ -302,6 +310,7 @@ const views = [
     ["evidence", "the stored messages or lines a result or a reference rests on"],
     ["passage", "a cited transcript line with bounded surrounding lines from the same revision"],
     ["agenda", "what needs a look today"],
+    ["busy", "when calendars or people are taken, without what takes them"],
     ["categories", "the categories a thing takes, with what each means"],
     ["domains", "the internet domains links point to, most linked first"],
     ["places", "the street addresses confirmed as places, most mentioned first"],
@@ -348,5 +357,5 @@ export const VOCABULARY = defineVocabulary({
     ],
     views: views.map(([entry, meaning]) => ({ word: entry, meaning })),
     roots: roots.map(([entry, meaning]) => ({ word: entry, meaning })),
-    flags: [...HOW_FLAGS, ...WHAT_FLAGS],
+    flags: [...HOW_FLAGS, ...WHAT_FLAGS, ...CALENDAR_FLAGS],
 });

package/docs/standards/README.md

@@ -28,12 +28,12 @@ the four steps that need a person. A new CLI is ready for its first release when
 | Page | Area id | Rules | What it covers |
 |---|---|---:|---|
 | [Toolchain](toolchain.md) | `TOOL` | 20 | TypeScript, Biome, grit plugins, size caps, import cycles, spelling, Markdown, Go |
-| [Layout](layout.md) | `LAY` | 9 | Repository layout, entry points, exports, file size, one job per file, splitting a unit |
+| [Layout](layout.md) | `LAY` | 10 | Repository layout, entry points, exports, file size, one job per file, splitting a unit, the bundled bin |
 | [Commands](commands.md) | `CMD` | 28 | Paths, vocabulary, flags, arguments, effects, lifetime, query, help, external references |
 | [Output](output.md) | `OUT` | 23 | Data on stdout only, envelopes, errors, exit codes, partial answers, projection |
 | [MCP](mcp.md) | `MCP` | 13 | The MCP tools, how they come from commands, what each permission shows |
 | [Accounts](accounts.md) | `ACCT` | 11 | The explicit profile, reads across accounts, scope flags, linked identities |
-| [Permissions](permissions.md) | `PERM` | 21 | Levels, keys, defaults, hard limits, the write guard and its journal |
+| [Permissions](permissions.md) | `PERM` | 22 | Levels, keys, defaults, hard limits, the write guard and its journal |
 | [Architecture](architecture.md) | `ARCH` | 17 | Layers, dependency direction, vendor types, what goes in which package |
 | [Lifecycle](lifecycle.md) | `LIFE` | 14 | Opening late, who closes, one-shot exits, long-running commands, the `serve` relay, resumable syncs, the run log |
 | [Store](store.md) | `STORE` | 14 | Store areas, account scope, migrations, test isolation |
@@ -84,7 +84,7 @@ Every rule has the same shape. A rule may add a sentence or a short list under i
     CLI's `node_modules`;
   - a check in another repository, as `<repo>: <check>`, such as `cli-core: pnpm parity:check` or
     `cli-core: biome noRestrictedImports`. `<repo>` is the repository's name on GitHub: `cli-core`, `cli-testing`,
-    `cli-docs`, `community`, `tg-cli`, `max-cli`, `cli-memo`, `drive-cli`, `zoom-cli` or `whatsapp-cli`. `<app>`
+    `cli-docs`, `community`, `tg-cli`, `max-cli`, `cli-memo`, `drive-cli`, `zoom-cli`, `whatsapp-cli` or `gcal-cli`. `<app>`
     stands for each CLI the rule applies to, when every one of them runs that check in its own repository.
 - **Since** is the cli-base release whose handbook first carried the rule. A feature can be older than its rule.
 

package/docs/standards/accounts.md

@@ -57,8 +57,8 @@ CLI with a `setup` command suggests it, and any other CLI suggests the command t
 - **Enforced by:** `cli-core: src/cli/settings.test.ts` · `cli-core: src/cli/program.test.ts`.
 - **Example:** ``name a profile: `tg <profile> …` — profiles here: personal, work (or set TG_PROFILE)``. With none,
   tg, which has `setup`, says to ``create one with `tg personal setup` (any name in place of personal)``. A CLI
-  without `setup`, such as one made from cli-template, answers `cal events list` with ``name a profile: there is none
-  on this computer yet — any name works, such as `cal personal events list` (or set CAL_PROFILE)`` (cli-core 0.424.0
+  without `setup`, such as one made from cli-template, answers `gcal events list` with ``name a profile: there is none
+  on this computer yet — any name works, such as `gcal personal events list` (or set GCAL_PROFILE)`` (cli-core 0.424.0
   and later).
 - **Exceptions:** none.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.

package/docs/standards/ci.md

@@ -10,8 +10,9 @@ Rule ids on this page are `WC-CI-<n>`. How to read a rule, how ids work and whic
 [Releases page](releases.md); which scanners must exist and how workflows are hardened is on the
 [Security page](security.md).
 
-"The ten repositories" on this page means the six CLIs (tg, max, memo, drive, zoom, wa), cli-base, cli-core,
-cli-testing, cli-docs, plus community itself. cli-template follows every rule here as a CLI does
+"The WireCat repositories" on this page means every WireCat CLI (today tg, max, memo, drive, zoom, wa and gcal; a
+CLI made with `npx @wirecat/cli-template new` counts from its first commit), cli-base, cli-core, cli-testing, cli-docs,
+plus community itself. cli-template follows every rule here as a CLI does
 ([New CLI](new-cli.md#the-template-repository-itself)).
 
 ## Rules
@@ -24,7 +25,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   `gitleaks git --staged --redact`. A clone without gitleaks gets a warning and can still commit; CI scans anyway.
   The `prepare` script installs the hooks; `LEFTHOOK=0 git commit` skips them for one commit.
 - **Exceptions:** none.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-2 · Add no push hook, and no hook that installs, builds, checks types, generates or tests
 
@@ -34,7 +35,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   does not run `standards:check`, the full lint, spelling, a build or the test suite on each commit or push; it runs a
   targeted check when it needs one.
 - **Exceptions:** none. cli-base `config/lefthook.yml` still has a pre-push typecheck, but no repository extends it.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-3 · Run the fast standards job on every pull request and every push to `main`
 
@@ -45,7 +46,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   commit cancels the run it replaces. The job times out after five minutes, a ceiling for a stalled setup, not an
   expected time.
 - **Exceptions:** none. Runner queues and cold downloads are outside the budget.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-4 · Keep `ci:quick` to early bug checks that finish within two minutes
 
@@ -61,7 +62,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
 - **Exceptions:** never put live-account suites, agent suites or platform jobs here. Full tests and coverage run in
   the pull request validation job ([WC-CI-5](#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out)),
   not in `ci:quick`.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-5 · Run the full Linux validation on every pull request, and keep platform suites out
 
@@ -139,10 +140,13 @@ cannot pass yet; the `skip` input names it.
 
 The shared workflows are not in the npm package, because CI runs the pinned commit, not the installed copy. To see
 what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/…@<commit>` lines in `ci.yml`,
-`release.yml` and `monthly.yml`, and opens each workflow file at that commit in cli-base.
+`release.yml` and `monthly.yml`, and opens each workflow file at that commit in cli-base. The fresh-agent audit on the
+[New CLI](new-cli.md#done-when) page is given these files for this reason, beside the handbook and the repository;
+its prompt in cli-template says so from cli-template 0.8.0. A CLI on an older template takes the prompt with
+`upgrade`.
 
 - **Why:** one shared workflow keeps the full suite the same everywhere, and a pin keeps a cli-base change from
-  breaking ten repositories at once.
+  breaking every repository at once.
 - **Enforced by:** `ci.yml:ci`.
 - **Example:** `uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@<commit> # v0.31.0`, with `cli: true` for
   the CLI steps (WC-CI-7), the project's extra checks in the `checks` input and `bun-run` for the Bun job. A job that only one repository needs stays beside it in
@@ -158,12 +162,29 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
 - **Example:** `monthly.yml`, from the community template, calls the repository's `ci.yml` and the pinned cli-base
   `release-checks.yml`. Each repository has its own minute, between 02:17 and 03:20 UTC, so runs do not overlap. No
   check compares the minutes across repositories; review keeps them apart. A CLI made from cli-template starts with
-  the template's own minute and changes it (see [New CLI](new-cli.md)).
+  the template's own minute and changes it (see [New CLI](new-cli.md)). Taken minutes, from each `monthly.yml` on
+  the default branch:
+
+  | UTC | Repository |
+  |---|---|
+  | 02:17 | cli-base |
+  | 02:24 | whatsapp-cli |
+  | 02:27 | gcal-cli |
+  | 02:31 | cli-memo |
+  | 02:38 | cli-core |
+  | 02:45 | drive-cli |
+  | 02:52 | cli-testing |
+  | 02:59 | max-cli |
+  | 03:02 | cli-template |
+  | 03:06 | tg-cli |
+  | 03:13 | zoom-cli |
+  | 03:20 | cli-docs |
+
 - **Exceptions:** cli-core also builds and probes its native packages in their own workflows, after the window:
   `onnx.yml` at 03:27 and `sqlite.yml` at 03:37 UTC. A scheduled run of either never publishes; only a manual run
   with `publish` does. community has no build, so it runs only the release security checks, at 03:47 UTC. A monthly
   run never publishes a package or deploys the site.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-10 · Run heavy security checks only at release, monthly or on request
 
@@ -177,7 +198,7 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
   job ([WC-CI-5](#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out)); it
   takes seconds. The dependency audit, `zizmor` and CodeQL stay out. Do not add a heavy scanner to an editor hook, a
   stop hook or an ordinary pull request job.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** sc:9.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** sc:9.
 
 ### WC-CI-11 · Moved to [WC-SECR-20](security.md#wc-secr-20--pin-each-third-party-action-to-a-commit-and-give-each-workflow-read-only-defaults)
 
@@ -195,7 +216,7 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
   release changes `main` the same way
   ([WC-REL-2](releases.md#wc-rel-2--main-changes-only-through-a-pull-request-also-during-a-release)).
 - **Exceptions:** none.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** NEED-381.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** NEED-381.
 
 ### WC-CI-13 · Start no live messenger or account test from a workflow
 

package/docs/standards/commands.md

@@ -77,8 +77,9 @@ catalogue and parity manifest stay in cli-core
 - **Example:** ranking is `stats messages top`, not a ranking mode on `search messages`. Options choose the scope,
   measure, order or format of the same action. No command both shows and changes something.
 - **Exceptions:** a documented preparatory fetch such as `--sync-first`. It keeps its own permissions and reports
-  its outcome.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+  its outcome. `mcp --revoke` forgets every login given to a browser app; it stays an option on `mcp` because it
+  belongs with the HTTP server's login state.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1864.
 
 ### WC-CMD-7 · Never let two commands overlap
 

package/docs/standards/kit-surface.md

@@ -18,11 +18,11 @@ nothing from either package.
 | Package and path | Exports |
 |---|---|
 | `@wirecat/cli-base` | `catchCrashes`, `CliError`, `configFilePath`, `mcpErrorResult`, `resolvePaths` |
-| `@wirecat/cli-base/commands` | `annotate`, `CommandInfo`, `describeProgram` |
+| `@wirecat/cli-base/commands` | `annotate`, `CommandInfo`, `COMMANDS_PAGE_LABELS` (in `scripts/`), `commandsPage` (in `scripts/`), `describeOptions` (in `scripts/`), `describeProgram` |
 | `@wirecat/cli-base/codegen` | `writeArtifacts` (in `scripts/`) |
 | `@wirecat/cli-base/release` | `DocsRules`, `JOURNAL_IDS`, `markdownFiles`, `packContents` (in `scripts/`) |
-| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `itemOf`, `LOCAL_READ`, `outputFor`, `privateFiles`, `profileFree`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
-| `@wirecat/cli-core/mcp` | `McpCommand`, `registerCommands`, `runCommandForAgent`, `toolsFromCommands` |
+| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandHelpMarkdown` (in `scripts/`), `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `httpTokenFile`, `itemOf`, `LOCAL_READ`, `MCP_HTTP_DEFAULT_PORT`, `mcpServerCommand`, `outputFor`, `privateFiles`, `profileFree`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `refuseUnderReadOnly`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
+| `@wirecat/cli-core/mcp` | `httpLockFile`, `MCP_PATH`, `McpCommand`, `portOf`, `publicUrlOf`, `registerCommands`, `runCommandForAgent`, `serveOverHttp`, `toolsFromCommands` |
 | `@wirecat/cli-core/sends` | `Level` |
 | `@wirecat/cli-core/update` | `appUpdate` |
 | `@wirecat/cli-core/testing` | `ARGV_LOG`, `argvLogSetup` |

package/docs/standards/layout.md

@@ -122,6 +122,38 @@ Rule ids on this page are `WC-LAY-<n>`. How to read a rule, how ids work and whi
 - **Exceptions:** none.
 - **Applies to:** all CLIs and libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
+### WC-LAY-10 · Ship the bin as a bundle that `cli-dev bundle` builds
+
+A command that imports about a thousand module files spends most of its start resolving and reading them. tg's
+bundle halved `--help` and every other short command
+([measurements](https://github.com/WireCatLabs/cli-testing/blob/main/performance/startup/tg-bundle/README.md)).
+
+- **Why:** one shared build keeps what tg learned in one place: lazy imports stay lazy, files and packages are found
+  where they were installed, and a running server survives an in-place upgrade.
+- **Enforced by:** `<app>: pnpm build` · `<app>: pnpm smoke:node` · `<app>: pnpm smoke:bun`.
+- **Example:** `"build": "tsc --build --force && cli-dev bundle --bin dist/bin/tg.js --external '@mtcute/*' --external undici"`,
+  with `esbuild` as a devDependency in cli-base's peer range. `dist/bundle/` holds the bundle, split so every lazy
+  `import()` stays a chunk of its own; `dist/bin/tg.js` stays the path `"bin"` names and becomes a loader. What it
+  does and checks:
+  - The loader answers `--version` from the version built into it, turns the compile cache on, and imports the
+    bundle. Under `serve`, `watch` and `mcp` it loads every chunk 2 s after start and resolves imports between chunks
+    without looking on disk: an upgrade deletes the old chunks, whose names carry a hash.
+  - In the CLI's own modules and in cli-core's and cli-base's (`--anchor` adds a package), `import.meta.url` is the
+    module's place before bundling, so skills, fonts, scenarios, migrations and child scripts are found. A package
+    they load at run time resolves from that place too (a resolve hook under Node, `Bun.resolveSync` under Bun):
+    pnpm installs cli-core's dependencies beside cli-core.
+  - A dynamic import of CommonJS (`yaml`) keeps its named exports. Names are kept (`keepNames`), so `commands --json`
+    and errors read as before.
+  - Native modules, Bun's SQLite and the packages cli-core loads by name stay outside; `--external` adds the CLI's
+    own (`*` matches anything).
+  - The build fails when a bundled module would look for a file or package from the chunk's place, or when the loader
+    names a chunk that was not built. A third-party file read and found harmless is named with `--harmless`.
+  - The CLI's smoke test runs the built bin under Node and Bun and checks that the store opens and the document
+    readers resolve.
+- **Exceptions:** a CLI moves when its outputs are byte-identical before and after and its start gains 15% or more;
+  until then it ships `tsc`'s output. cli-base, cli-core and cli-testing ship libraries, not a bin.
+- **Applies to:** all CLIs. **Since:** cli-base 0.64.0. **Rulings:** none.
+
 ## Sources
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page

package/docs/standards/new-cli.md

@@ -12,7 +12,7 @@ built on are on the [Kit surface](kit-surface.md) page.
 ## Start with the template
 
 ```sh
-npx @wirecat/cli-template new cal-cli --command cal --package @wirecat/cal-cli --owner WireCatLabs \
+npx @wirecat/cli-template new gcal-cli --command gcal --package @wirecat/gcal-cli --owner WireCatLabs \
   --category calendar --content-lang en,ru --sign-in oauth --api official-client --filters time,person,text \
   --never-store tokens,secret-links --untrusted names,links
 ```
@@ -24,7 +24,7 @@ the choices. Nothing is guessed.
 |---|---|---|
 | `<name>-cli` | the repository folder | any name |
 | `--command` | the command word people type | one word |
-| `--package` | the npm package name | a scoped name, such as `@wirecat/cal-cli` |
+| `--package` | the npm package name | a scoped name, such as `@wirecat/gcal-cli` |
 | `--owner` | the GitHub owner of the repository | an owner |
 | `--category` | what the CLI reads | `messenger`, `mail`, `notes`, `files`, `calendar`, `meetings` |
 | `--content-lang` | the languages of the content | a list, such as `en,ru` |
@@ -42,11 +42,11 @@ a reference CLI for your category in `AGENTS.md`. It does not install packages,
 publish. Then:
 
 ```sh
-cd cal-cli && pnpm install && pnpm ci:quick
+cd gcal-cli && pnpm install && pnpm ci:quick
 git add -A && git commit -m "chore: start from @wirecat/cli-template"
 ```
 
-Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explicitly, such as `cal personal doctor`.
+Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explicitly, such as `gcal personal doctor`.
 The reference CLI is the one to compare with when a step is unclear.
 
 The copy already holds every file this handbook asks for: the required root commands (`commands`, `doctor`,
@@ -61,6 +61,15 @@ The rules they keep are on the area pages: [Commands](commands.md), [MCP](mcp.md
 Later template changes come in with `npx @wirecat/cli-template upgrade`, file by file: apply, replace, skip or diff.
 See [Kit surface](kit-surface.md#how-your-cli-stays-current).
 
+The template's `template.json` splits the copy in two. A **seed** (`DESIGN.md`, `CLAUDE.md`, `README.md`, the user
+pages, `src/`) is the CLI's own from the first commit: rewrite it freely. A **template-owned** file (`AGENTS.md`,
+`docs/dev/TESTING.md`, `docs/dev/reference-clis.md`, the skills under `docs/dev/skills/`, `.github/`) holds only what
+is true for every CLI made from the template. Do not rewrite one to fit this CLI: put the CLI's own facts in a seed.
+A template-owned page that is wrong for this CLI is a gap in cli-template, under
+[WC-DOC-3](docs.md#wc-doc-3--every-document-states-current-facts-rewrite-a-wrong-sentence-in-place) like any other
+wrong sentence: fix it there, and `upgrade` brings the fix. Change it in the CLI only where the CLI must differ for
+good; `upgrade` then asks before it touches the change.
+
 ## Four steps that need a person
 
 `new` prints these at the end.
@@ -69,12 +78,14 @@ See [Kit surface](kit-surface.md#how-your-cli-stays-current).
    changes only through a pull request, required status checks, and no bypass. Add the ruleset after the first
    commit is on `main`, since a pull request rule leaves an empty repository no way to get one, and the required
    check names exist only once CI has run. See [Releases](releases.md).
-2. **Set npm trusted publishing** for the new package, naming `release.yml`, and add any secrets the CI needs. See
+2. **Set npm trusted publishing** for the new package, naming `release.yml`, and add any secrets the CI needs. npm
+   offers this only once the package exists, so the owner publishes the first version with `bin/release --local`
+   and sets it right after. See
    [WC-REL-11](releases.md#wc-rel-11--publish-from-github-actions-with-npm-trusted-publishing).
-3. **Pick a monthly cron minute** between 02:17 and 03:20 UTC that no other repository uses. The copy of
-   `.github/workflows/monthly.yml` keeps the template's own minute, 03:02, and no check compares minutes across
-   repositories, so change it by hand. See
+3. **Pick a monthly cron minute** between 02:17 and 03:20 UTC that is not in the list of taken minutes under
    [WC-CI-9](ci.md#wc-ci-9--run-full-validation-and-release-security-on-the-first-day-of-each-month-without-publishing).
+   The copy of `.github/workflows/monthly.yml` keeps the template's own minute, 03:02, and no check compares minutes
+   across repositories, so change it by hand, and add the new minute to the list in the step 4 pull request.
 4. **WireCat CLIs only: join the shared lists.** A pull request to cli-base's `PARITY_GROUPS` (at least the `all`
    group, which compares the shared root commands), a line in cli-core's `WIRECAT_TOOLS` and a line in cli-docs'
    `tools.json`. A messenger also joins cli-core's `parity.json`. A CLI outside WireCatLabs keeps its parity groups
@@ -89,17 +100,20 @@ All of these pass on `main`, before the first release:
 - `cli-dev lint` against the built CLI. It also makes the CLI fail once in an empty home and checks that
   `runs list` shows the failed run
 - `cli-dev audit --for <cli> --lint <cli>=lint` with no new finding, run with the command trees of the CLIs in
-  the same parity groups. `--lint` judges the CLI's lint rules by its own `lint/` folder. What it shares with the
-  other CLIs is judged by cli-base's `audit/baseline`; the pull request that adds the CLI to a parity group adds its
-  shared findings there
+  the same parity groups (`pnpm audit:commands`). `--lint` judges the CLI's lint rules by its own `lint/` folder.
+  What it shares with the other CLIs has no baseline: `audit/baseline` does not accept a shared-contract finding
+  (cli-base 0.51.0). Fix each one, or, where the CLI must differ for good, the pull request that adds it to a parity
+  group declares the exact difference with its reason in that group's `differences`
 - `pnpm contracts:check`
 - `cli-dev test-matrix --check`
 - `pnpm docs:check`, with `--pages`, and the CLI's `generate:check`
 - the changelog guard on a pull request
 - `pnpm release:check`
 
-The last test is a fresh agent. Give it only this handbook's [index](README.md) and the new repository, and ask it to
-audit the CLI. Every gap it lists is either a gap in the CLI, to fix before the first release, or a hole in the
+The last test is a fresh agent. Give it only this handbook's [index](README.md), the new repository and the cli-base
+workflow files its own workflows pin
+([WC-CI-8](ci.md#wc-ci-8--call-cli-base-node-ciyml-from-ciyml-pinned-to-a-tag-or-commit)), and ask it to audit the
+CLI. Every gap it lists is either a gap in the CLI, to fix before the first release, or a hole in the
 handbook, to fix here.
 
 ## The template repository itself
@@ -118,7 +132,7 @@ upgrade, and no script or agent reads its answers.
 | [WC-DOC-12](docs.md#wc-doc-12--a-runnable-command-in-a-document-has-no-placeholder-in-it) | Exempt only for the placeholder names `clidev`, `clidev-cli`, `@wirecat/clidev-cli` and `WireCatLabs/clidev-cli`, and the upper-case prefix `CLIDEV_` (as in `CLIDEV_PROFILE`). | `new` replaces each of them with the CLI's own name. Any other placeholder is still a gap. |
 | [WC-DOC-17](docs.md#wc-doc-17--each-entry-says-what-changed-for-the-caller-why-and-what-to-watch-for) | A changelog entry may name a file path. | The template's readers are CLI authors, who edit those files or take them with `upgrade`; for them a path is what they see. |
 
-Every other rule that applies to all CLIs, or to the ten repositories, applies to cli-template as it is written,
+Every other rule that applies to all CLIs, or to the WireCat repositories, applies to cli-template as it is written,
 with one limit for the copy tool. It follows the rules for code and the repository: Toolchain, Layout, Style,
 Testing, Security and Documents. It has no profile, no machine mode, no MCP server, no store and no agent reading its
 answers, so the rules for a CLI's commands and runtime do not reach it: Commands, Output, MCP, Accounts, Permissions,

package/docs/standards/permissions.md

@@ -20,8 +20,9 @@ Rule ids on this page are `WC-PERM-<n>`. How to read a rule, how ids work and wh
 tg, max and wa use cli-core's permissions and write guard in full. memo uses them for the shared commands only. drive
 has its own policy and guard, with its own `--read-only` flag. zoom has per-profile `permissions` from zoom-cli 0.35.0,
 read with cli-core's `levelFor`; its writes change Zoom meetings, its built-in default is `remote-meetings: ask`, and
-it has no send journal or recipient list, since it sends no messages. Where this page says "every CLI that writes",
-drive is a known gap.
+it has no send journal or recipient list, since it sends no messages. gcal declares its own keys through cli-core's
+`commandPermissions` and runs its event writes through cli-core's write guard (WC-PERM-22). Where this page says
+"every CLI that writes", drive is a known gap.
 
 WC-PERM-10 and WC-PERM-11 need cli-core 0.321.0, which tg, max and wa pin. WC-PERM-12 as written needs cli-core
 0.337.0; before it, the lock let through some local writes that overwrite what the owner saved. A command other
@@ -114,7 +115,8 @@ A default is never made stricter without the owner's word.
 - **Exceptions:** where the messenger has replies, `replies.send` is `deny`: a reply rule writes to people with nobody
   typing a command, so it waits for the owner's own `allow`. A messenger with no `replies` group, such as wa, has no
   use for the key.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-568.
+- **Applies to:** messenger CLIs. A CLI that is not a messenger sets its own defaults (WC-PERM-22). **Since:** cli-base
+  0.41.0. **Rulings:** NEED-568.
 
 ### WC-PERM-7 · A built-in default only ever tightens
 
@@ -310,6 +312,34 @@ Moderation rules use the same four levels for each kind of action (delete, remov
   looser than the profile's `chats.moderate`; the code does not check that yet.
 - **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-306, NEED-310.
 
+### WC-PERM-22 · A CLI that is not a messenger declares its own keys and defaults with `commandPermissions`
+
+A messenger's keys come from its resources (`messages`, `chats`). Any other CLI names its own with cli-core's
+`commandPermissions({ keyOf, extra, defaults })`, passed as `settingsFor(app, { permissions })` (cli-core 0.450.0):
+
+- **Keys.** Each command is checked against its own path (`events.create`), the default `keyOf`. Housekeeping has no
+  key (WC-PERM-5). `extra` adds the keys a command checks inside itself, such as one per generated API method
+  (`api.calendar.events.insert`). A key that names no command is refused when it is set or saved.
+- **Defaults.** `defaults` holds the CLI's built-in levels, beside cli-core's. They only ever tighten (WC-PERM-7). A
+  CLI picks them for what its writes do, not by WC-PERM-6's messenger list: they ask before a write people other
+  than the owner see or cannot easily undo, and deny what an agent must never do unasked.
+- **Read-only lock and guard.** `<PREFIX>_READ_ONLY` refuses every write to the service, as in WC-PERM-12. Every
+  write runs through cli-core's write guard with `permissionDefaults: configuration.permissions.defaults`
+  (cli-core 0.455.0), so `ask` is a y/N question at a terminal (WC-PERM-9) and every attempt goes into the send journal
+  (WC-PERM-17). A CLI that sends no messages has no recipient list or hourly limit to set.
+
+- **Why:** one permission model for every CLI; a CLI-own layer drifts from the shared one and is audited by nobody.
+- **Enforced by:** `cli-core: src/cli/command-permissions.test.ts` · `cli-core: src/calendar/cli/writes.test.ts`.
+- **Example:** a calendar CLI takes cli-core's `CALENDAR_WRITE_DEFAULTS` and `CALENDAR_WRITE_KEYS`
+  (`@wirecat/cli-core/calendar`, cli-core 0.458.0): `events create`, `update`, `respond` and `delete` ask, since each
+  changes a calendar other people may share or be invited from; `events.delete.series` (a whole repeating series) and
+  `events.notify` (mail the attendees) are `deny` until the owner allows them. gcal adds its own: a generated
+  `api <method>` that writes asks, and one that shares, empties or gives away a calendar is `deny`.
+- **Exceptions:** known gaps: drive keeps its own policy and `--read-only` flag, zoom reads its own
+  `remote-meetings` key with `levelFor`, and memo uses cli-core's permissions for the shared commands only. None of
+  them declares `commandPermissions` yet.
+- **Applies to:** every CLI that writes and is not a messenger. **Since:** cli-base 0.64.0. **Rulings:** none.
+
 ## Sources
 
 These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page