@wirecat/cli-base 0.50.3 → 0.51.0

package/dist/dev/main.js

@@ -11,12 +11,13 @@ import spawn from "cross-spawn";
 import * as v from "valibot";
 import { parseCommandsDocument } from "../commands/document.js";
 import { changelogProblems, docsProblems, JOURNAL_IDS, markdownFiles, packageVersion, structureProblems, versionScript, } from "../release/index.js";
-import { AUDIT_BLOCKS, PARITY_GROUPS, REQUIRED_ROOTS } from "../standards/audit.js";
+import { AUDIT_BLOCKS, defineParityGroups, PARITY_GROUPS, REQUIRED_ROOTS } from "../standards/audit.js";
 import { defineReasons } from "../standards/errors.js";
 import { baselineProblems, baselineSchema, LINT_RULES, OVERRIDE_BUDGET, OVERRIDE_RULE_REVIEW, overridesProblems, overridesSchema, rulesForReview, } from "../standards/lint.js";
 import { issuesOf } from "../standards/registry.js";
 import { VOCABULARY } from "../standards/vocabulary.js";
 import { auditClis, scorecardTable, snakeKeys } from "./audit.js";
+import { readCapabilities } from "./capabilities.js";
 import { changelogChange, landFold, processShell } from "./land.js";
 import { baselineOf, judge, lintCommands } from "./lint.js";
 import { nextVersion } from "./next-version.js";
@@ -48,7 +49,7 @@ const USAGE = `usage: cli-dev <command> [options]
                                        lint/baseline/<rule>.json to today's violations. --schemas
                                        is a JSON object of the CLI's own JSON Schemas by name
   audit (--cli <bin> | --commands <file>)... [--schemas <cli>=<file>]... [--reasons <cli>=<file>]...
-        [--lint <cli>=<dir>]... [--baseline <dir>] [--for <cli>] [--json] [--write-baseline]
+        [--lint <cli>=<dir>]... [--capabilities <file>] [--complete] [--differences <file>] [--baseline <dir>] [--for <cli>] [--json] [--write-baseline]
                                        several CLIs against every lint rule and against each other:
                                        required roots, same path same contract, same flag same
                                        meaning, same entity same schema, same failure same reason.
@@ -186,12 +187,12 @@ const readJson = (path) => {
         throw new Error(`${path}: ${error.message}`);
     }
 };
-const commandsJson = (io, cli, file) => {
+const commandsJson = (io, cli, file, commandArgs = ["commands", "--json"]) => {
     if (file)
         return readJson(isAbsolute(file) ? file : join(io.cwd, file));
     const bin = cli ?? "";
     const script = /\.[cm]?js$/.test(bin);
-    const run = spawn.sync(script ? process.execPath : bin, [...(script ? [bin] : []), "commands", "--json"], {
+    const run = spawn.sync(script ? process.execPath : bin, [...(script ? [bin] : []), ...commandArgs], {
         cwd: io.cwd,
         encoding: "utf8",
         maxBuffer: 64 * 1024 * 1024,
@@ -331,6 +332,9 @@ const auditRun = (args, io) => {
             cli: { type: "string", multiple: true },
             commands: { type: "string", multiple: true },
             schemas: { type: "string", multiple: true },
+            capabilities: { type: "string" },
+            complete: { type: "boolean", default: false },
+            differences: { type: "string" },
             reasons: { type: "string", multiple: true },
             lint: { type: "string", multiple: true },
             baseline: { type: "string", default: "audit/baseline" },
@@ -352,18 +356,60 @@ const auditRun = (args, io) => {
     const reasons = byCli(values.reasons, "--reasons");
     const lintDirs = byCli(values.lint, "--lint");
     const problems = [];
+    const evidence = new Map();
+    if (values.complete) {
+        for (const [index, bin] of (values.cli ?? []).entries()) {
+            const raw = raws[index];
+            const data = commandsJson(io, bin, undefined, ["commands", "info", "--json"]);
+            if (typeof raw.cli === "string")
+                evidence.set(raw.cli, data);
+        }
+    }
     const inputs = raws.map((raw) => {
         const parsed = parseCommandsDocument(snakeKeys(raw));
         if (!parsed.document)
             throw new Error(`a commands document is not the shape cli-base's commandsDocument() writes: ${parsed.problems[0]}`);
         const cli = parsed.document.cli;
-        const input = { document: parsed.document, raw };
+        const input = { document: parsed.document, raw, ...evidence.get(cli) };
         const schemaFile = schemas.get(cli);
         if (schemaFile)
             input.schemas = readJson(at(schemaFile));
         const reasonFile = reasons.get(cli);
         if (reasonFile)
             input.reasons = defineReasons(readJson(at(reasonFile)));
+        if (values.complete) {
+            if (!input.contracts ||
+                typeof input.contracts !== "object" ||
+                Array.isArray(input.contracts) ||
+                Object.keys(input.contracts).length === 0)
+                problems.push(`${cli}: complete audit needs core contract references from commands info`);
+            for (const root of REQUIRED_ROOTS) {
+                const path = root.path.join(" ");
+                if (!input.contracts?.[path])
+                    problems.push(`${cli}: complete audit needs an inherited contract reference for ${path}`);
+            }
+            if (!input.schemas ||
+                typeof input.schemas !== "object" ||
+                Array.isArray(input.schemas) ||
+                Object.keys(input.schemas).length === 0)
+                problems.push(`${cli}: complete audit needs nonempty entity schemas from commands info or --schemas`);
+            if (!Array.isArray(input.reasons) || input.reasons.length === 0)
+                problems.push(`${cli}: complete audit needs declared error reasons from commands info or --reasons`);
+            if (input.reasons)
+                input.reasons = defineReasons(input.reasons);
+            if (input.schemas) {
+                const visit = (commands) => {
+                    for (const command of commands) {
+                        const names = [command.output?.entity, command.query?.entity].filter((name) => name !== undefined);
+                        for (const name of names)
+                            if (input.schemas?.[name] === undefined)
+                                problems.push(`${cli}: complete audit has no schema for ${name} (${command.path.join(" ")})`);
+                        visit(command.commands);
+                    }
+                };
+                visit(input.document.commands);
+            }
+        }
         const dir = lintDirs.get(cli);
         if (dir) {
             const overridesPath = join(at(dir), "overrides.json");
@@ -398,8 +444,32 @@ const auditRun = (args, io) => {
         problems.push(`--for names ${values.for}, which is not audited`);
     const baselineDir = at(values.baseline);
     const baseline = readBaseline(baselineDir, values.baseline, problems);
+    let groups = PARITY_GROUPS;
+    if (values.differences) {
+        const schema = v.array(v.strictObject({
+            group: v.string(),
+            rule: v.string(),
+            target: v.string(),
+            expected: v.string(),
+            reason: v.string(),
+        }));
+        const parsed = v.safeParse(schema, readJson(at(values.differences)));
+        if (!parsed.success)
+            throw new Error(`${values.differences}: ${issuesOf(parsed.issues).join("; ")}`);
+        for (const entry of parsed.output)
+            if (!groups.some((group) => group.name === entry.group))
+                throw new Error(`${values.differences}: unknown group ${entry.group}`);
+        groups = defineParityGroups(groups.map((group) => ({
+            ...group,
+            differences: [
+                ...group.differences,
+                ...parsed.output.filter((entry) => entry.group === group.name).map(({ group: _, ...entry }) => entry),
+            ],
+        })));
+    }
     const result = auditClis(inputs, {
-        groups: PARITY_GROUPS,
+        ...(values.capabilities ? { capabilities: readCapabilities(readJson(at(values.capabilities))) } : {}),
+        groups,
         roots: REQUIRED_ROOTS,
         vocabulary: VOCABULARY,
         baseline,

package/dist/dev/shared-contracts.d.ts

@@ -0,0 +1,13 @@
+import type { CommandInfo } from "../commands/index.js";
+export interface ContractEdit {
+    command: readonly string[];
+    field: string;
+    before: unknown;
+    after: unknown;
+    reason: string;
+}
+/** A baseline cannot replace a core definition: only an exact, reasoned edit changes its effective value. */
+export declare const sharedContractProblems: (commands: readonly CommandInfo[], references: Readonly<Record<string, Readonly<Record<string, unknown>>>>, edits?: readonly ContractEdit[]) => {
+    path: string;
+    message: string;
+}[];

package/dist/dev/shared-contracts.js

@@ -0,0 +1,85 @@
+const stable = (value) => {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, child]) => [key, stable(child)]));
+    return value;
+};
+const same = (left, right) => JSON.stringify(stable(left ?? null)) === JSON.stringify(stable(right ?? null));
+const FIELDS = new Set([
+    "name",
+    "summary",
+    "description",
+    "origin",
+    "api_operation",
+    "effects",
+    "state",
+    "partial",
+    "lifetime",
+    "reaches",
+    "mcp",
+    "offline",
+    "cooperative",
+    "examples",
+    "output",
+    "query",
+    "runnable",
+    "arguments",
+    "options",
+    "aliases",
+    "children",
+]);
+/** A baseline cannot replace a core definition: only an exact, reasoned edit changes its effective value. */
+export const sharedContractProblems = (commands, references, edits = []) => {
+    const effective = new Map(Object.entries(references).map(([path, contract]) => [path, structuredClone(contract)]));
+    const problems = [];
+    for (const edit of edits) {
+        const path = edit.command.join(" ");
+        const contract = effective.get(path);
+        if (!contract ||
+            !FIELDS.has(edit.field) ||
+            edit.reason.trim().length < 10 ||
+            !same(contract[edit.field], edit.before) ||
+            same(edit.before, edit.after)) {
+            problems.push({ path, message: `invalid or stale explicit override for ${edit.field}` });
+            continue;
+        }
+        if (edit.after === null)
+            delete contract[edit.field];
+        else
+            contract[edit.field] = structuredClone(edit.after);
+    }
+    const walk = (items, inherited) => {
+        for (const command of items) {
+            const path = command.path.join(" ");
+            const expected = effective.get(path);
+            if (expected) {
+                const { path: _, usage: __, commands: nested, ...fields } = command;
+                const original = references[path]?.children;
+                const actual = {
+                    ...fields,
+                    ...(Array.isArray(original)
+                        ? { children: nested.filter((child) => original.includes(child.name)).map((child) => child.name) }
+                        : {}),
+                };
+                const wanted = { ...expected, ...inherited };
+                const changed = [...new Set([...Object.keys(actual), ...Object.keys(wanted)])].filter((field) => field !== "aliases" &&
+                    field !== "availability" &&
+                    !same(actual[field], wanted[field]));
+                if (changed.length)
+                    problems.push({ path, message: `core contract differs without an exact override: ${changed.join(", ")}` });
+                effective.delete(path);
+            }
+            walk(command.commands, {
+                ...(inherited.mcp === false || expected?.mcp === false ? { mcp: false } : {}),
+                ...(inherited.offline === false || expected?.offline === false ? { offline: false } : {}),
+            });
+        }
+    };
+    walk(commands, {});
+    for (const path of effective.keys())
+        problems.push({ path, message: "core contract names a command absent from discovery" });
+    return problems;
+};

package/dist/standards/audit.d.ts

@@ -23,6 +23,7 @@ declare const parityGroupSchema: v.StrictObjectSchema<{
     readonly differences: v.ArraySchema<v.StrictObjectSchema<{
         readonly rule: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a lower-case word, words joined by -">]>;
         readonly target: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>;
+        readonly expected: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, undefined>;
         readonly reason: v.SchemaWithPipe<readonly [v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "must not be empty">]>, v.MinLengthAction<string, 10, "say why, in a sentence">]>;
     }, undefined>, undefined>;
 }, undefined>;

package/dist/standards/audit.js

@@ -10,6 +10,11 @@ const auditRuleSchema = v.strictObject({ id: word, severity: v.picklist(LINT_SEV
 export const defineAuditRules = (input) => parseRegistry("audit rules", v.array(auditRuleSchema), input, (rules) => duplicates(rules.map((rule) => rule.id)).map((id) => `"${id}" is listed twice`));
 /** The rules that compare CLIs; each CLI is also judged alone by every lint rule. */
 export const AUDIT_RULES = defineAuditRules([
+    {
+        id: "shared-command-contract",
+        severity: "high",
+        summary: "core-owned command definitions change only through exact, reasoned overrides",
+    },
     {
         id: "required-root",
         severity: "high",
@@ -44,7 +49,12 @@ const parityGroupSchema = v.strictObject({
     /** `tree` compares every path; otherwise the root words whose paths are compared. */
     covers: v.union([v.literal("tree"), v.pipe(v.array(segment), v.minLength(1))]),
     /** Permanent differences, each with its reason; they count against the override budget of the group. */
-    differences: v.array(v.strictObject({ rule: word, target: text, reason: v.pipe(text, v.minLength(10, "say why, in a sentence")) })),
+    differences: v.array(v.strictObject({
+        rule: word,
+        target: text,
+        expected: v.optional(text),
+        reason: v.pipe(text, v.minLength(10, "say why, in a sentence")),
+    })),
 });
 export const defineParityGroups = (input) => parseRegistry("parity groups", v.array(parityGroupSchema), input, (groups) => [
     ...duplicates(groups.map((group) => group.name)).map((name) => `"${name}" is listed twice`),

package/dist/standards/flags-how.js

@@ -448,6 +448,12 @@ export const HOW_FLAGS = [
         meaning: "override one permission for this run; repeat it for more",
     },
     { name: "--read-only", role: "mode", type: "switch", meaning: "refuse every write, local and remote" },
+    {
+        name: "--append",
+        role: "mode",
+        type: "switch",
+        meaning: "keep existing entries and add the explicitly named one beside them",
+    },
     { name: "--replace", role: "mode", type: "switch", meaning: "overwrite an existing one of the same name" },
     {
         name: "--rescan",

package/dist/standards/flags-what.js

@@ -323,6 +323,34 @@ export const WHAT_FLAGS = [
         meaning: "look again at this many recent days, for what arrived late",
         unit: "days",
     },
+    {
+        name: "--meeting-id",
+        value: "<id>",
+        role: "target",
+        type: "id",
+        meaning: "one stored meeting selected for transcript search",
+    },
+    {
+        name: "--identity-id",
+        value: "<id>",
+        role: "target",
+        type: "id",
+        meaning: "a stored participant identity whose meetings are selected; does not identify the speaker of a hit",
+    },
+    {
+        name: "--person-id",
+        value: "<id>",
+        role: "target",
+        type: "id",
+        meaning: "a stored person whose linked participant identities select meetings",
+    },
+    {
+        name: "--series-id",
+        value: "<id>",
+        role: "target",
+        type: "id",
+        meaning: "one stored recurring series selected for meeting search",
+    },
     { name: "--meeting", value: "<id>", role: "target", type: "id", meaning: "a meeting, by its store id" },
     {
         name: "--message",
@@ -408,6 +436,13 @@ export const WHAT_FLAGS = [
     },
     { name: "--task", value: "<id>", role: "target", type: "id", meaning: "a task, by id" },
     { name: "--to", value: "<chat>", role: "target", type: "id", meaning: "the chat it goes to" },
+    {
+        name: "--topic-name",
+        value: "<name>",
+        role: "target",
+        type: "string",
+        meaning: "a stored meeting topic label, by name or alias",
+    },
     { name: "--topic", value: "<id>", role: "target", type: "id", meaning: "the forum topic, in a chat that has topics" },
     { name: "--transcript-id", value: "<id>", role: "target", type: "id", meaning: "one transcript version, by id" },
     { name: "--until-id", value: "<id>", role: "target", type: "id", meaning: "up to and including this message id" },

package/dist/standards/vocabulary.js

@@ -120,7 +120,7 @@ const verbs = [
     ["cancel", "stop a job or a pending thing"],
     [
         "sync",
-        "bring the local store up to date from the source: only what changed, or the whole list where the source cannot say",
+        "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"],
     ["export", "write from the store to a file"],
@@ -169,6 +169,10 @@ const verbs = [
     ["unarchive", "bring an archived chat back to the main chat list"],
     ["reset", "replace a thing; the old one stops working"],
     ["moderate", "apply a chat's rules: delete what breaks them, act on who broke them"],
+    ["assign", "name the person responsible for work, with their task role"],
+    ["reverse", "record that an accepted decision no longer holds, without replacing it"],
+    ["invalidate", "mark a derived record whose supporting evidence no longer holds"],
+    ["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"],
     ["move", "move a file in the source"],
@@ -239,6 +243,10 @@ const collections = [
     ["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"],
+    ["agents", "the agents whose actions are recorded in the shared store"],
+    ["reminders", "scheduled notices about stored work, claimed and acknowledged with delivery receipts"],
+    ["key-documents", "selected source documents that a project keeps as its starting references"],
+    ["answers", "evidence-grounded answers assembled from selected stored sources"],
     ["aliases", "other names of one thing"],
     ["mentions", "phones, e-mail addresses, links and documents found in stored text, each where it was written"],
     ["images", "pictures in stored messages, searched by what they show"],
@@ -264,6 +272,7 @@ const collections = [
 const singulars = [
     ["session", "this tool's login"],
     ["account", "the messenger or mail account behind a profile"],
+    ["mail", "the local email archive and its mailbox import, rules and cleanup operations"],
     ["config", "a profile's settings"],
     ["server", "the long-running process of a profile"],
     ["store", "the local SQLite database the tools share"],

package/docs/standards/README.md

@@ -38,6 +38,7 @@ rules it keeps. A new CLI is ready for its first release when every check under
 | [Testing](testing.md) | `TEST` | 17 | Sandbox, no network, no real waits, leak tests, coverage, contracts, test matrix, parity |
 | [Security](security.md) | `SECR` | 20 | Secrets, logs, keyring, argv, error text, untrusted text, scanners, workflow hardening, reporting |
 | [Documents](docs.md) | `DOC` | 20 | User pages and developer pages, generated pages, current facts, changelog |
+| [Comparisons](comparisons.md) | `CMP` | 11 | Which tools a comparison page lists, rows as user tasks, agents and safety, where others are better, proof of marks |
 | [Releases](releases.md) | `REL` | 16 | `bin/release`, the release lock, versions, release reports, trusted publishing |
 | [CI](ci.md) | `CI` | 12 | Hooks, the pull request budget, full validation, monthly runs |
 | [Time](time.md) | `TIME` | 6 | UTC in the store and in answers, the zone at input and display edges, date-only filters, tests in another zone |

package/docs/standards/accounts.md

@@ -13,8 +13,7 @@ Rule ids on this page are `WC-ACCT-<n>`. How to read a rule, how ids work and wh
 
 ### Who follows these rules today
 
-cli-core resolves the profile for tg, max and wa. WC-ACCT-1 needs cli-core 0.319.0 or newer, and all three pin
-0.321.0. memo has no messenger profile: its shared commands run without one, and they pick accounts with `--provider`
+cli-core resolves the profile for tg, max and wa. WC-ACCT-1 needs cli-core 0.319.0 or newer. memo has no messenger profile: its shared commands run without one, and they pick accounts with `--provider`
 and `--account` (WC-ACCT-7). zoom resolves its own profile word by the same rules (`zm <profile> …`, `ZM_PROFILE`,
 `ZM_PROFILE_LOCK`) from zoom-cli 0.35.0, with cli-core's `liftProfile` and `usableProfileName`. drive still has its own
 profile code: it registers its own profiles. That is a known gap, not an exception.

package/docs/standards/ci.md

@@ -96,7 +96,7 @@ cli-testing, cli-docs, plus community itself.
   cli-docs validates its site before each deployment instead, and community has no build. Third-party security apps
   may post their own checks.
 - **Applies to:** the CLIs, cli-base, cli-core and cli-testing. cli-base, whatsapp-cli, tg-cli, max-cli, cli-core
-  cli-memo and zoom-cli have `pr.yml`; drive-cli and cli-testing do not have it yet. **Since:**
+  cli-memo, zoom-cli and drive-cli have `pr.yml`; cli-testing does not have it yet. **Since:**
   cli-base 0.41.0 (pull request validation since cli-base 0.44.6). **Rulings:** none.
 
 ### WC-CI-6 · Run the changelog guard on every pull request
@@ -168,9 +168,10 @@ cli-testing, cli-docs, plus community itself.
 - **Why:** a red merge breaks `main` for every parallel branch, and an admin merge skips the only gate there is.
 - **Enforced by:** `whatsapp-cli: main ruleset required checks` · `cli-core: main ruleset required checks` ·
   `tg-cli: main ruleset required checks` · `max-cli: main ruleset required checks` ·
-  `cli-memo: main ruleset required checks`, plus the main ruleset of cli-base itself. In each repository with pr.yml,
-  the ruleset requires the pull request validation jobs besides the standards job. drive-cli, cli-testing and cli-docs
-  have no pr.yml, so their rulesets require only the standards job, and review covers the rest. zoom-cli has pr.yml,
+  `cli-memo: main ruleset required checks` · `drive-cli: main ruleset required checks`, plus the main ruleset of
+  cli-base itself. In each repository with pr.yml, the ruleset requires the pull request validation jobs besides the
+  standards job. cli-testing and cli-docs have no pr.yml, so their rulesets require only the standards job, and
+  review covers the rest. zoom-cli has pr.yml,
   but its ruleset still requires only the standards job.
 - **Example:** `gh pr checks <number>` shows every line as pass before `gh pr merge`. Never merge with `--admin`. A
   release changes `main` the same way

package/docs/standards/commands.md

@@ -287,10 +287,10 @@ Each of these is set with `annotate(command, { … })` from `@wirecat/cli-base/c
 ### WC-CMD-27 · Refuse a command path that arrived as one word
 
 - **Why:** a shell loop that quotes `"projects add"` would otherwise get the root help and no reason.
-- **Enforced by:** `src/commands/commands.test.ts` · `cli-memo: src/program.test.ts`.
+- **Enforced by:** `src/commands/commands.test.ts` · `cli-memo: src/program.test.ts` · `cli-core: src/cli/program.ts`.
 - **Example:** call `refuseJoinedPath(program, args)` before `parseAsync`. It throws a `validation_error` that names
   the words to type.
-- **Exceptions:** none. Only memo calls `refuseJoinedPath` today; cli-core and the other CLIs do not yet.
+- **Exceptions:** none. memo and cli-core call `refuseJoinedPath` before parsing.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ## External references

package/docs/standards/comparisons.md

@@ -0,0 +1,133 @@
+# Comparisons
+
+## Scope
+
+How a CLI's comparison page is written: which tools it compares, which rows it has, how a mark is proven, and what it
+says about the places where another tool is better. The page is read by someone choosing a tool for a job, not by
+someone reviewing our code.
+
+The page lives in the site repository (`cli-docs`, published on wirecat.dev), not in the CLI repository, because a
+comparison changes when the other tools change, not when we release. The CLI repository keeps a short
+`docs/compare.md` that links to the site page, and its other docs link there too.
+
+Rule ids on this page are `WC-CMP-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). The general rules for user pages are in [Documents](docs.md).
+
+## Rules
+
+### WC-CMP-1 · Compare with the tools a reader would pick instead, for the same job
+
+- **Why:** a table against products in another category answers a question nobody asked and makes us look either
+  better or worse than we are.
+- **Enforced by:** review only.
+- **Example:** zm is compared with other command lines and MCP servers for a Zoom account. Meeting assistants that
+  join calls (Otter, Fireflies) are a different job; that comparison stays private until zm does that job too.
+- **Exceptions:** one column may be the official app or the official API, when readers would otherwise use it.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-2 · A row is a task the user wants done, grouped by how people use the tool
+
+- **Why:** people choose a tool by what they can do with it: read and send messages, send photos, find a chat, find a
+  file, keep a draft, see who is active in a group. How login works or where data is stored is rarely the reason.
+- **Enforced by:** review only.
+- **Example:** groups such as "Catch up", "Reply and send", "Find", "Files and media", "Organise", "Overview and
+  analytics", "Agents and safety", "Setup". Rows such as "Send several photos as one album", "Find a file someone sent
+  in any chat". Not rows such as "QR login and two-step password" or "Works without a local copy".
+- **Exceptions:** an implementation detail gets a row only when it changes what the user can do, such as "Search
+  without internet".
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-3 · A missing feature gets a row only if users would choose a tool by it
+
+- **Why:** a row we fail reads as a gap to fix. A rare account setting listed as missing makes the product look
+  incomplete for no reason.
+- **Enforced by:** review only.
+- **Example:** "Set or remove the cloud password" is not a row on max's page. "Drafts" is.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-4 · Write each row so that ❌ cannot be misread
+
+- **Why:** a short noun can name a bigger thing than the row means; with ❌ beside it the reader concludes the tool
+  cannot do the bigger thing.
+- **Enforced by:** review only.
+- **Example:** "Show the other person that you are typing", not "Typing". ❌ beside "Typing" reads as "cannot send
+  messages".
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-5 · Every page has an "Agents and safety" group, and it may be the largest
+
+- **Why:** it is what the WireCat tools are built for, and what a reader cannot learn from a feature list: what an
+  agent may do without asking, how a wrong send is stopped, what the agent sees.
+- **Enforced by:** review only.
+- **Example:** rows such as "An agent can read but not send unless you allow it", "Ask before each send", "Limit sends
+  to a list of chats", "A send is never made twice after a retry", "Every command reachable through MCP", "Works with
+  an agent without a browser".
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-6 · Keep technical rows few, and only where they help a choice
+
+- **Why:** a reader who wants protocol details reads the docs; a comparison full of them hides the answer.
+- **Enforced by:** review only.
+- **Example:** one "Setup" group: install command, platforms, licence, price, MCP over stdio or HTTP, and how the tool
+  compares with a browser agent driving the web app (speed, cost, reliability).
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-7 · Say plainly where another tool is better
+
+- **Why:** a table that only shows our wins is not believed, and a reader who finds the gap later stops trusting the
+  rest.
+- **Enforced by:** review only.
+- **Example:** a section "Where another tool fits better" with two to four scenarios, each one sentence: the job, the
+  tool that does it better, why. Only gaps a reader would care about (WC-CMP-3).
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-8 · No "better" or "faster" without a published measurement
+
+- **Why:** a quality claim against another tool is the claim a reader is most likely to test.
+- **Enforced by:** review only.
+- **Example:** "memo finds better answers than Hindsight" needs a result in cli-testing `performance/` and a link to
+  it. Without one, the row says what each tool does ("search by words and by meaning"), not which does it better.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** none.
+
+### WC-CMP-9 · Every mark is proven, and the page says when it was checked
+
+- **Why:** a comparison goes stale faster than any other page, and a wrong mark about another project is unfair to
+  it.
+- **Enforced by:** review only.
+- **Example:** our marks are checked against the code on `main` or by running the tool. A competitor mark links to
+  its own documentation or source. A mark that cannot be proven is ➖ ("not in its documentation"). The intro names the
+  check date. The legend is ✅ yes · 🟡 partly · ❌ no · ➖ not in its documentation, plus "n/a" where
+  a row cannot apply to a tool (an MCP row for a connector that is itself the agent).
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** none.
+
+### WC-CMP-10 · Keep the table short enough to read
+
+- **Why:** past about 25 rows the reader stops scanning, and the rows that matter are lost.
+- **Enforced by:** review only.
+- **Example:** one feature table, with each group as a bold row inside it; 15 to 25 rows and 3 to 6 tools. A row
+  where every tool has the same mark is dropped.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.4. **Rulings:** owner, 2026-10-24.
+
+### WC-CMP-11 · Our marks are re-checked at each release
+
+- **Why:** our own marks go stale with every release, and a mark that says we lack something we have shipped, or the
+  reverse, is the error a reader finds first.
+- **Enforced by:** review only.
+- **Example:** the release report lists the compare page as checked. Before a release, each ✅, 🟡 and ❌ for the CLI is re-proven against the release build, the check date
+  and version in the intro are updated in the site repository, and the release report names the page.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.50.5. **Rulings:** owner, 2026-10-24.
+
+## Sources
+
+- Owner review of the max, zm and memo comparison pages, 2026-10-24.
+- The tg comparison page, the first page written this way.
+- Owner decision, 2026-10-24: comparison pages live in `cli-docs`; each CLI's docs link to them.