diffmode 0.1.0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "diffmode",
+  "version": "0.1.0",
+  "description": "Agent-drivable CLI for the Diffmode growth pipeline",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentic-builders/diffmode-cli.git"
+  },
+  "homepage": "https://github.com/agentic-builders/diffmode-cli#readme",
+  "bugs": "https://github.com/agentic-builders/diffmode-cli/issues",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "diffmode": "dist/bin.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "esbuild src/bin.ts --bundle --platform=node --target=node20 --format=cjs --external:keytar --outfile=dist/bin.js --banner:js='#!/usr/bin/env node' && chmod +x dist/bin.js",
+    "dev": "tsx src/bin.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "typecheck": "tsc --noEmit",
+    "sync:companions": "tsx scripts/sync-companions.ts",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test && npm run build"
+  },
+  "dependencies": {
+    "commander": "^14.0.0"
+  },
+  "optionalDependencies": {
+    "keytar": "^7.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "esbuild": "^0.28.0",
+    "eslint": "^9.0.0",
+    "msw": "^2.14.0",
+    "tsx": "^4.22.0",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.0"
+  }
+}

package/skills/diffmode/.cursor/rules/diffmode.mdc

@@ -0,0 +1,32 @@
+---
+description: Operate the diffmode CLI to generate growth plans, personas, and focus-group simulations against the hosted Diffmode API.
+alwaysApply: false
+---
+# diffmode CLI
+
+<!-- DO NOT EDIT — generated by scripts/sync-companions.ts from SKILL.md -->
+
+Use the `diffmode` CLI to operate the hosted growth-strategy API.
+
+## When to invoke
+- User asks for a growth plan, personas, focus group, or names diffmode.
+- Confirm: `diffmode --version` and `diffmode whoami --json`.
+
+## Default flow
+1. `diffmode limits --json` — credits.
+2. `diffmode run <product> --input founder.json --idempotency-key <uuid> --json`
+3. `diffmode jobs watch <job_id> --json --wait 4h`
+4. `diffmode results <product> --json` then `--summary --json`.
+5. `diffmode unlock <product>` (optional, 15 cr).
+
+## Contract
+- Always pass `--json`. Stdout = data; stderr = progress/errors.
+- Generate your own UUIDv4 for `--idempotency-key` (CLI never auto-generates).
+- `--input founder.json` required for `run`/`workflow`/`smoke-test`.
+- On exit 8, redirect user to https://diffmode.app/app/billing. No CLI top-up command exists.
+- Exit codes: `4` auth · `5` conflict (job_id in stderr) · `7` rate-limited ·
+  `8` insufficient-credits · `10` interrupted-resumable.
+
+## Reference
+- https://github.com/agentic-builders/diffmode-cli
+- https://diffmode.app

package/skills/diffmode/AGENTS.md

@@ -0,0 +1,35 @@
+# diffmode — agent contract
+
+<!-- DO NOT EDIT — generated by scripts/sync-companions.ts from SKILL.md -->
+
+Agent-drivable CLI for the Diffmode growth pipeline.
+
+## When to use
+- User asks for a growth plan, personas, focus group, or any task using `diffmode`.
+- Verify: `diffmode --version` and `diffmode whoami --json` (exit 4 → `diffmode login`).
+
+## Default flow
+1. `diffmode limits --json` — confirm credits (1 run / 5 idea-eval / 15 unlock).
+2. `diffmode run <product> --input founder.json --idempotency-key <uuid> --json`
+3. `diffmode jobs watch <job_id> --json --wait 4h` (stderr = progress).
+4. `diffmode results <product> --json` — manifest first; never dump full bundle.
+5. `diffmode results <product> --summary --json` — keyFinding sections (~3 k tok).
+6. `diffmode unlock <product> --idempotency-key <uuid> --json` (optional, 15 cr).
+
+## Contract
+- `--json` on every call. Stdout = data; stderr = progress/errors.
+- **Idempotency is yours.** Generate a UUIDv4 per submit; CLI does NOT auto-generate.
+- **Founder input** is required for `run`, `workflow`, `smoke-test`. Use `--input` or
+  `--from-url`. `unlock` reuses the prior free-tier's input.
+- `idea-eval` takes a JSON array (not strings) — see `references/idea-input-schema.md`.
+- **Billing is browser-only.** On exit 8, redirect user to https://diffmode.app/app/billing.
+
+## Exit codes (spec §8)
+`0` ok · `1` generic · `2` usage · `3` network · `4` auth ·
+`5` conflict · `6` not-found · `7` rate-limited · `8` insufficient-credits ·
+`9` server · `10` interrupted-resumable · `130` SIGINT.
+Full recovery: `references/error-codes.md`.
+
+## See also
+- https://github.com/agentic-builders/diffmode-cli
+- https://diffmode.app

package/skills/diffmode/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: diffmode
+description: Use this skill whenever the user asks to generate, run, retrieve, or apply a growth plan, marketing strategy, persona research, or focus group simulation with the Diffmode CLI. Triggers on phrases like "growth plan", "diffmode run", "personas", "focus group", "growth strategy", and any instruction to operate the `diffmode` CLI. The skill orchestrates the `diffmode` CLI end-to-end against the hosted growth-pipeline API — authenticate, pre-flight credits, submit a run, watch the job, retrieve manifest-shaped results, and apply tactics. Use this any time the user mentions Diffmode or asks for a bootstrapped-SaaS growth plan, even if they don't explicitly name the CLI.
+---
+
+# Diffmode
+
+You are operating the `diffmode` CLI on behalf of the user. It is a thin HTTP
+client to a hosted growth-strategy API. A full plan run can take 10 minutes to
+several hours and produces dozens of markdown files. **Never dump full outputs
+into your context** — always work through the manifest emitted by
+`diffmode results`.
+
+## When to use this skill
+
+- User says "use diffmode", "generate a growth plan", "run diffmode for
+  <product>", "show the personas", or asks to apply a plan produced by
+  Diffmode.
+- User has installed the CLI (verify with `diffmode --version`) and
+  authenticated (verify with `diffmode whoami --json`).
+
+## When NOT to use this skill
+
+- For generic marketing advice not tied to a Diffmode product.
+- If the user wants to top up credits — Diffmode billing is **browser-only**.
+  On exit 8, redirect them to `https://diffmode.app/app/billing` (or the
+  resolver URL in the error payload). There is no `diffmode billing topup`
+  command.
+- If `diffmode` is not installed — instruct the user to run
+  `npx diffmode@latest login` once, then resume.
+
+## Operating contract
+
+- The CLI is **non-interactive** when stdout is not a TTY. Always pass
+  `--json` and parse the schema-versioned envelope.
+- **Stdout is data; stderr is progress/errors.** Both carry valid JSON when
+  `--json` is set.
+- **Exit codes** are part of the public contract:
+  - `0` ok · `1` generic · `2` usage · `3` network · `4` auth ·
+    `5` conflict (409) · `6` not-found · `7` rate-limited ·
+    `8` insufficient-credits (402) · `9` server ·
+    `10` interrupted-resumable · `130` SIGINT
+  - Full recovery guidance: `references/error-codes.md`.
+- **Idempotency is the agent's responsibility.** The CLI does NOT
+  auto-generate an `Idempotency-Key` header. Generate a UUIDv4 yourself and
+  pass `--idempotency-key <uuid>` on every submit (`run`, `unlock`,
+  `workflow`, `idea-eval`, `smoke-test`). Same key + same user → same
+  `job_id` (no double-charge). Matches `gh`/`stripe` UX.
+- **Founder input is required** for `run`, `workflow`, and `smoke-test`. Use
+  `--input founder.json` (canonical) or `--from-url <url>` (CLI calls
+  `/public/v1/analyze-website` to pre-fill). Schema:
+  `references/founder-input-schema.md`. `unlock` reuses the prior
+  free-tier's stored input — do not re-supply.
+- **Idea-eval** takes a structured JSON array, not strings — see
+  `references/idea-input-schema.md`.
+
+## Default workflow
+
+1. **Authenticate (one-time per machine).**
+   `diffmode whoami --json` → on exit 4, stop and tell the user
+   `npx diffmode@latest login` (or `diffmode login --token dm_pat_…`) in
+   their terminal, then resume.
+2. **Pre-flight credits.**
+   `diffmode limits --json` → if `credits_available < N` (1 for `run`/
+   `smoke-test`, 5 for `idea-eval`, 15 for `unlock`/`workflow`), echo the
+   `billing_url` and stop. The CLI's submit also does this pre-flight by
+   default; `--no-preflight` skips it.
+3. **Submit a run (default = free-tier, 1 credit).**
+   Generate a UUIDv4 and run
+   `diffmode run <product> --input founder.json --idempotency-key <uuid> --json`.
+   On exit 5 (CONFLICT), parse `error.job_id` from stderr and resume at
+   step 4 with that id.
+4. **Watch.**
+   `diffmode jobs watch <job_id> --json --wait 4h`. This blocks; the CLI
+   handles `next_poll_ms` backoff and prints progress to stderr.
+   - exit 10 (RESUMABLE) → run `diffmode jobs resume <job_id>` once, then
+     re-watch.
+   - exit 7 (rate-limited) → respect `error.retry_after`; sleep then retry.
+   - exit 9 twice in a row → stop, surface to the user.
+   - Ctrl-C never cancels the server job — print "resume with
+     `diffmode jobs watch <job_id>`" and exit 130.
+5. **Retrieve results (manifest-first; never read the full bundle).**
+   `diffmode results <product> --json` → read the manifest only. Then read
+   `report.json` keyFinding sections via
+   `diffmode results <product> --summary --json` (~3 k tokens).
+6. **Drill down deliberately.**
+   - Buyer personas (free-tier report sections are: `landscape`,
+     `advantages`, `buyers`, `blockers`, `growthPlan`):
+     `diffmode results <product> --stage buyers --summary --json`, then
+     `--pull` once and `--show <relative-path>.md` for any persona file
+     listed in the manifest.
+   - A tactic: `diffmode results <product> --tactic <id-or-name>` (look up
+     valid tactic ids/names via `--stage growthPlan --summary --json`).
+   - Always page large files with `--max-tokens 4000` unless the user asks
+     for the full file.
+7. **Optional unlock (15 credits).**
+   `diffmode unlock <product> --idempotency-key <uuid> --json`. Requires a
+   completed `diffmode run` for the same product first — on 422, prompt the
+   user to run free-tier first.
+8. **Apply the plan.** Present the executive summary and proposed actions.
+   **Stop and confirm** before making any code/copy/config changes. Treat
+   each tactic as its own edit-review-commit loop.
+
+## Human-checkpoint policy
+
+- Submit a run only after confirming product name AND that the user
+  understands it costs credits.
+- Apply changes to files only after presenting a diff and getting explicit
+  user approval.
+- Never re-run the pipeline against the same product within 30 minutes
+  without asking.
+
+## Failure recovery (cheat sheet)
+
+| Exit | Meaning | Action |
+| --- | --- | --- |
+| 4 | Auth | Ask the user to `diffmode login`. |
+| 5 | Conflict (in-flight job) | Parse `error.job_id`; jump to step 4 (watch). |
+| 7 | Rate limited | Sleep `error.retry_after` (or surface if > 5 min). |
+| 8 | Insufficient credits | Print `billing_url` from the error; stop. |
+| 10 | Interrupted (resumable) | `diffmode jobs resume <id>` once, re-watch. |
+| 130 | SIGINT | Confirm whether to re-watch — do NOT auto-cancel. |
+
+See `references/error-codes.md` for every code + per-command coverage.
+
+## See also
+
+- `references/commands.md` — full command catalog with endpoints, credit
+  costs, flags, and example invocations.
+- `references/error-codes.md` — exit codes + per-code recovery script.
+- `references/founder-input-schema.md` — `FounderDiagnostics` shape for
+  `--input`.
+- `references/idea-input-schema.md` — `IdeaInput` array shape for
+  `--ideas-file`.
+- `https://github.com/agentic-builders/diffmode-cli` — repo + issue tracker.
+- `https://diffmode.app` — top-up + dashboard (browser-only billing).

package/skills/diffmode/llms.txt

@@ -0,0 +1,20 @@
+# diffmode
+
+<!-- DO NOT EDIT — generated by scripts/sync-companions.ts from SKILL.md -->
+
+> Agent-drivable CLI for the Diffmode growth pipeline. Generate growth plans,
+> personas, and focus-group simulations against the hosted Diffmode API. PAT
+> auth, JSON-on-non-TTY, durable jobs, browser-only billing.
+
+## Docs
+
+- [Repository](https://github.com/agentic-builders/diffmode-cli): source, README, exit codes, CHANGELOG.
+- [SKILL.md](https://github.com/agentic-builders/diffmode-cli/blob/main/skills/diffmode/SKILL.md): canonical agent skill.
+- [Commands reference](https://github.com/agentic-builders/diffmode-cli/blob/main/skills/diffmode/references/commands.md): endpoint, credit cost, flags, examples per command.
+- [Exit codes](https://github.com/agentic-builders/diffmode-cli/blob/main/skills/diffmode/references/error-codes.md): exit-code contract + per-code recovery scripts.
+- [Founder input schema](https://github.com/agentic-builders/diffmode-cli/blob/main/skills/diffmode/references/founder-input-schema.md): `FounderDiagnostics` shape for `--input`.
+- [Idea-eval input schema](https://github.com/agentic-builders/diffmode-cli/blob/main/skills/diffmode/references/idea-input-schema.md): `IdeaInput` array for `--ideas-file`.
+
+## Optional
+
+- [Dashboard](https://diffmode.app): mint PATs at `/app/tokens`, top up credits at `/app/billing`.

package/skills/diffmode/references/commands.md

@@ -0,0 +1,295 @@
+# Commands reference
+
+Complete catalog of `diffmode` commands. Each entry lists: the backend
+endpoint it calls, credit cost (where applicable), required + optional
+flags, exit codes, and example invocations (TTY + `--json` forms). For a
+machine-readable version of this table, run `diffmode commands --json`.
+
+> **Drift policy.** The CLI emits its commander tree as a manifest; the
+> test `test/commands-reference-drift.test.ts` asserts every command listed
+> here also appears in `diffmode commands --json`. Don't add a new command
+> without updating this file.
+
+## Globals (apply to every command)
+
+| Flag | Description |
+| --- | --- |
+| `--json` | Emit machine-readable JSON (forces JSON even on a TTY). |
+| `--no-color` | Disable ANSI colors. |
+| `--quiet` | Suppress stderr progress. |
+| `--verbose` | Verbose stderr output. |
+| `--yes` | Auto-confirm interactive prompts. |
+| `--token <pat>` | PAT override (precedence: `--token` > `DIFFMODE_TOKEN` env > stored). |
+| `--profile <name>` | Configuration profile (default `default`). |
+| `--timeout <s>` | Per-HTTP-request timeout in seconds (default 60). |
+
+`--idempotency-key <uuid>` is **subcommand-scoped** (on submit commands
+only) and **not** a global flag.
+
+## Auth
+
+### `diffmode login`
+
+- **Endpoint:** `GET /public/v1/access-tokens` (validates PAT)
+- Reads a PAT from stdin or `--token`. Stores it via OS keyring (or 0600
+  file fallback with a one-time stderr warning).
+- **Exits:** 0, 1, 2, 3, 4, 9
+- Examples:
+  ```bash
+  diffmode login --token dm_pat_…
+  echo "$DIFFMODE_TOKEN" | diffmode login
+  ```
+
+### `diffmode logout`
+
+- Clears stored credentials for the active profile. Idempotent.
+- **Exits:** 0
+
+### `diffmode whoami`
+
+- **Endpoint:** `GET /public/v1/access-tokens`
+- Verifies the active token; prints identity metadata.
+- **Exits:** 0, 1, 3, 4, 9
+- Example: `diffmode whoami --json`
+
+## Submit (job-creating)
+
+All submit commands accept `--idempotency-key <uuid>` (optional, no
+auto-generation). The CLI does a pre-flight `GET /billing/balance` before
+posting unless `--no-preflight` is set.
+
+### `diffmode run <product>` (default, **1 credit**)
+
+- **Endpoint:** `POST /public/v1/free-tier`
+- **Required input:** `--input <file|->` or `--from-url <url>` (founder
+  diagnostics; see `founder-input-schema.md`).
+- **Flags:** `--input`, `--from-url`, `--save-input`, `--idempotency-key`,
+  `--no-preflight`
+- **Exits:** 0, 1, 2, 3, 4, 5, 7, 8, 9
+- Examples:
+  ```bash
+  diffmode run myproduct --input founder.json --idempotency-key "$(uuidgen)"
+  diffmode run myproduct --from-url https://example.com --json
+  ```
+
+### `diffmode workflow <product>` (**15 credits**)
+
+- **Endpoint:** `POST /public/v1/workflow`
+- Cold-start full plan. Power-user verb.
+- **Flags:** identical surface to `run`.
+- **Exits:** 0, 1, 2, 3, 4, 5, 7, 8, 9
+
+### `diffmode unlock <product>` (**15 credits**)
+
+- **Endpoint:** `POST /public/v1/products/{id}/unlock`
+- Server reuses the founder input from the prior completed free-tier run;
+  no `--input` accepted here. On 422 → CLI exits 2 with
+  `Run \`diffmode run <p>\` first.`
+- **Flags:** `--idempotency-key`, `--no-preflight`
+- **Exits:** 0, 1, 2, 3, 4, 5, 7, 8, 9
+
+### `diffmode idea-eval <product>` (**5 credits**)
+
+- **Endpoint:** `POST /public/v1/idea-eval`
+- **Required input:** `--ideas-file <path>` — JSON array of `IdeaInput`
+  objects (see `idea-input-schema.md`). Not resumable.
+- **Flags:** `--ideas-file`, `--intuition`, `--target-idea`,
+  `--idempotency-key`, `--no-preflight`
+- **Exits:** 0, 1, 2, 3, 4, 5, 7, 8, 9
+- Example:
+  ```bash
+  diffmode idea-eval myproduct --ideas-file ideas.json \
+    --intuition "founder-mode onboarding is the highest-leverage" \
+    --json
+  ```
+
+### `diffmode smoke-test <product>` (**1 credit**)
+
+- **Endpoint:** `POST /public/v1/smoke-test`
+- Always pass `--input` (CLI does NOT rely on the server-side disk
+  fallback used by local-CLI mode). Not resumable.
+- **Flags:** `--input`, `--from-url`, `--save-input`, `--idempotency-key`,
+  `--no-preflight`
+- **Exits:** 0, 1, 2, 3, 4, 5, 7, 8, 9
+
+## Jobs
+
+### `diffmode jobs list`
+
+- **Endpoint:** `GET /public/v1/jobs?limit=&cursor=&product_id=&status=`
+- Keyset pagination (max `--limit 200`).
+- **Flags:** `--product`, `--status`, `--limit`, `--cursor`
+- **Exits:** 0, 1, 3, 4, 9
+- Examples:
+  ```bash
+  diffmode jobs list --product myproduct --json
+  diffmode jobs list --cursor "$NEXT_CURSOR"
+  ```
+
+### `diffmode jobs status <job_id>`
+
+- **Endpoint:** `GET /public/v1/jobs/{job_id}`
+- **Exits:** 0, 1, 3, 4, 6, 9
+
+### `diffmode jobs watch <job_id>`
+
+- Repeated `GET /public/v1/jobs/{job_id}`; honors `next_poll_ms` with
+  ±20 % jitter clamped to `[3 s, 30 s]`.
+- **Flags:** `--wait <duration>` (e.g. `4h`, `30m`, `300s`; this is the
+  **total polling wait**, distinct from the global per-request
+  `--timeout`). The deadline is enforced at the start of every poll
+  iteration AND retry sleeps (429 `Retry-After`, transient backoff) are
+  clamped to the remaining budget, so a single long `Retry-After` cannot
+  push the watch past `--wait`.
+- **Exits:** 0, 1, 3, 4, 6, 7, 9, 10, 130
+- Persistent `429` responses (≥5 in a row) surface as exit 7 with code
+  `rate_limited` and the server's `Retry-After` echoed in the envelope.
+- `--wait` deadline exhaustion exits **1** with `code: "generic"` (the
+  server-side job keeps running; re-watch to resume). This is distinct
+  from exit 7 — the CLI has no `retry_after` to promise on a client-side
+  timeout, so it deliberately does NOT pose as back-pressure.
+- Ctrl-C: prints `Resume with: diffmode jobs watch <id>` to stderr; never
+  calls `DELETE /jobs/{id}`.
+
+### `diffmode jobs resume <job_id>`
+
+- Two-step:
+  1. `GET /public/v1/jobs/{job_id}` to fetch `module_type` + `product_id`.
+  2. Branch:
+     - `free-tier` → `POST /public/v1/free-tier/{product_id}/retry`
+     - `workflow` → `POST /public/v1/workflow/resume`
+     - other modules → exit 2 with "module is not resumable" hint.
+- **Flags:** `--idempotency-key`
+- **Exits:** 0, 1, 2, 3, 4, 6, 9
+
+### `diffmode jobs cancel <job_id>`
+
+- **Endpoint:** `DELETE /public/v1/jobs/{job_id}`
+- Idempotent; on TTY prompts unless global `--yes` is set.
+- **Exits:** 0, 1, 2, 3, 4, 6, 9
+- Declining the interactive `y/N` confirmation exits 2 with code `usage`
+  (no `DELETE` issued) — same envelope agents already handle for malformed
+  flags, so the path is predictable from `diffmode commands --json`.
+
+## Results
+
+### `diffmode results <product>`
+
+- Resolves the latest completed job (or `--job-id <id>`), downloads
+  `/products/{id}/outputs`, and emits a manifest:
+  ```json
+  {
+    "schema_version": "1",
+    "product": "<p>",
+    "job_id": "<id>",
+    "module_type": "free-tier",
+    "out_dir": ".diffmode/<p>/<id>/",
+    "total_files": 14,
+    "total_bytes_est": 184323,
+    "report_sections": ["meta", "landscape", "advantages", "growthPlan", ...]
+  }
+  ```
+- **Flags:** `--job-id`, `--out`, `--summary`, `--show <path>`,
+  `--max-tokens <n>`, `--pull`, `--stage <s>`, `--tactic <t>`
+- **Exits:** 0, 1, 2, 3, 4, 6, 9
+- `--summary` returns `report.json` keyFinding sections for free-tier
+  jobs; for workflow/unlock it prints a Phase-2 stub.
+- **Phase-1 `--job-id` caveat:** `/products/{id}/outputs` returns the
+  current product workspace; the API does not yet serve per-job artifact
+  snapshots. `--job-id` pins the manifest's `job_id` field, but downloaded
+  files always reflect the latest run. If the pinned job is not the latest
+  completed run, the manifest JSON carries `latest_completed_job_id`
+  (always emitted, not silenced by `--quiet`), the CLI redirects the local
+  snapshot dir to `<latest-job>/` so any prior `<pinned>/` snapshot stays
+  intact, and a stderr note describes the redirect for humans. If the
+  advisory drift lookup itself fails (transient 429/5xx/network), the
+  manifest sets `drift_lookup_failed: true` and the CLI warns on stderr
+  that drift status could not be verified. Per-job snapshots ship with the
+  Phase-2 manifest endpoint.
+
+## Billing (read-only)
+
+### `diffmode account`
+
+- **Endpoint:** `GET /public/v1/billing/balance`
+- Pretty table on TTY; full `CreditBalance` JSON on `--json`.
+- **Exits:** 0, 1, 3, 4, 9
+
+### `diffmode billing balance`
+
+- Terse `{balance, has_purchased}` (or pretty on TTY).
+- **Exits:** 0, 1, 3, 4, 9
+
+### `diffmode billing history`
+
+- **Endpoint:** `GET /public/v1/billing/history?limit=&offset=`
+- **Offset-based** pagination (not B5 keyset). NDJSON output on non-TTY.
+- **Flags:** `--limit`, `--offset`
+- **Exits:** 0, 1, 3, 4, 9
+
+### `diffmode limits`
+
+- Derives credit availability from `/billing/balance` plus the documented
+  rate-limit policy (3 submissions / 24 h for non-paying).
+- **Exits:** 0, 1, 3, 4, 9
+- Does NOT estimate `free_submits_remaining` — the backend doesn't expose
+  remaining slots and a CLI-local guess would lie across devices.
+
+### NO `diffmode billing topup`
+
+Top-up is **browser-only by design**. On exit 8 from any submit, the CLI
+prints `Insufficient credits. Top up at <DIFFMODE_BILLING_URL or default>`
+and exits. Override the redirect with `DIFFMODE_BILLING_URL`.
+
+## Diagnostics helpers
+
+### `diffmode diagnostics from-url <url>`
+
+- **Endpoint:** `POST /public/v1/analyze-website`
+- Prints a draft `FounderDiagnostics` JSON; `--save <path>` writes to
+  disk instead.
+- **Exits:** 0, 1, 2, 3, 4, 9
+
+### `diffmode diagnostics validate <path>`
+
+- Validates a founder-input JSON file against the documented schema. Exits
+  0 if valid, 2 with field-level errors otherwise.
+- **Exits:** 0, 1, 2
+
+## Self-describing
+
+### `diffmode commands`
+
+- Emits the full commander tree as a manifest. Always JSON (no `--json`
+  required). Stable schema; use it for agent discovery.
+- **Exits:** 0
+
+### `diffmode --version --json`
+
+- Emits `{schema_version, version, node, platform}`. Plain text without
+  `--json`.
+
+## Agent integration
+
+### `diffmode skill show`
+
+- Prints the bundled `SKILL.md` to stdout (`{path, contents}` on `--json`).
+  Useful for agents that want to inspect the skill without installing it.
+- **Exits:** 0, 1
+
+### `diffmode skill install`
+
+- Copies the bundled skill into per-tool agent dirs.
+- **Flags:**
+  - `--target <claude|codex|cursor|all>` (default `all`)
+  - `--yes` overwrites a divergent existing file (without it, the command
+    reports `needs-confirm` and writes nothing)
+  - `--dry-run` reports the action without writing
+  - `--print-paths` prints the resolved target paths and exits
+- **Default paths** (override with `DIFFMODE_SKILL_{CLAUDE,CODEX,CURSOR}_PATH`):
+  - Claude: `~/.claude/skills/diffmode/SKILL.md`
+  - Codex: `~/.codex/skills/diffmode/SKILL.md`
+  - Cursor: `~/.cursor/rules/diffmode.mdc`
+- Skips a target gracefully when the parent tool's home dir is missing
+  (e.g., Claude Code not installed) — non-fatal.
+- **Exits:** 0, 1, 2