diffmode 0.1.0

package/skills/diffmode/references/error-codes.md

@@ -0,0 +1,118 @@
+# Exit codes reference
+
+`diffmode`'s exit codes are part of the public contract — agents and shell
+scripts branch on them. The table below is verbatim from spec §8.
+
+| Code | Name | Trigger | Recovery |
+| --- | --- | --- | --- |
+| `0` | OK | Command succeeded. | None. |
+| `1` | GENERIC | Unclassified failure. | Surface stderr `error.message` to the user. |
+| `2` | USAGE | Wrong flags, missing args, schema violations, "module not resumable", "no prior free-tier", … | Read stderr; fix the invocation. |
+| `3` | NETWORK | DNS, TLS, connection-reset, response-body parse failure. | Check connectivity; retry with backoff (≤ 3 attempts). |
+| `4` | AUTH | No token, expired/revoked PAT, or 401 from server. | Ask the user to run `diffmode login`, then retry. |
+| `5` | CONFLICT (409) | A job is already running for this product. | Parse stderr `error.job_id`; switch to `diffmode jobs watch <id>`. |
+| `6` | NOT_FOUND | 404 from server (unknown job id, missing product). | Verify the id/product slug. |
+| `7` | RATE_LIMITED (429) | Free-tier limit (3 submits / 24 h) or `Retry-After` set. | Honor `error.retry_after` (seconds); sleep and retry. |
+| `8` | INSUFFICIENT_CREDITS (402) | Pre-flight or server rejected the submit. | Print `error.billing_url`; instruct the user to top up at `https://diffmode.app/app/billing`. **Do not retry.** |
+| `9` | SERVER | 5xx. | If `error.retryable === true`, retry with backoff. Otherwise stop and surface. |
+| `10` | INTERRUPTED_RESUMABLE | Server marked the job interrupted (deploy/rotation). | Run `diffmode jobs resume <id>` once, then `diffmode jobs watch <id>` again. |
+| `130` | SIGINT | User hit Ctrl-C. | Print resume hint (the server job is still running); do NOT auto-cancel. |
+
+## Per-code recovery scripts
+
+### Exit 4 (AUTH)
+
+```bash
+diffmode whoami --json
+# exit 4 → prompt user
+echo "Please authenticate, then re-run."
+echo "  npx diffmode@latest login   (paste PAT from https://diffmode.app/app/tokens)"
+exit 4
+```
+
+### Exit 5 (CONFLICT — in-flight job)
+
+The error envelope on stderr carries the running `job_id`:
+
+```json
+{"error": {"code": "conflict", "message": "...", "retryable": false, "job_id": "<id>", "product_id": "<p>"}}
+```
+
+Pivot to watching that job:
+
+```bash
+diffmode run "$PRODUCT" --input founder.json --idempotency-key "$UUID" --json
+# if exit 5:
+JOB_ID=$(jq -r '.error.job_id' /tmp/stderr.json)
+diffmode jobs watch "$JOB_ID" --json --wait 4h
+```
+
+### Exit 7 (RATE_LIMITED)
+
+Read `error.retry_after` (seconds). If ≤ 300, sleep and retry once. If
+larger, surface to the user — don't loop silently.
+
+### Exit 8 (INSUFFICIENT_CREDITS)
+
+Browser-only top-up. The CLI **never** calls `POST /billing/checkout`. The
+error payload includes the billing URL the CLI resolves at runtime:
+
+```json
+{"error": {"code": "insufficient_credits", "message": "...", "retryable": false, "billing_url": "https://diffmode.app/app/billing"}}
+```
+
+Tell the user, do not retry:
+
+```
+You're out of credits. Top up at https://diffmode.app/app/billing,
+then re-run `diffmode run <product>`.
+```
+
+### Exit 10 (INTERRUPTED_RESUMABLE)
+
+Workflow + free-tier are resumable; idea-eval, smoke-test, and unlock are
+not. `diffmode jobs resume` handles the module branching for you:
+
+```bash
+diffmode jobs resume "$JOB_ID" --json
+diffmode jobs watch "$JOB_ID" --json --wait 4h
+```
+
+If `jobs resume` itself exits 2 with "module not resumable", resubmit:
+
+```bash
+diffmode "$MODULE" "$PRODUCT" --input founder.json --idempotency-key "$NEW_UUID"
+```
+
+### Exit 130 (SIGINT)
+
+The server-side job keeps running. Confirm with the user; if they want to
+keep going:
+
+```bash
+diffmode jobs watch "$JOB_ID" --json --wait 4h
+```
+
+Do NOT issue `DELETE /jobs/{id}` on Ctrl-C — the CLI deliberately skips
+that to keep jobs durable across watch interruptions.
+
+## Coverage per command
+
+The exact exit-code set per command is in `commands.md` (and emitted by
+`diffmode commands --json` under each entry's `exits` field). This file
+documents the codes themselves; that file documents which commands can emit
+which codes.
+
+## Drift policy
+
+This table mirrors `src/lib/exit-codes.ts` (constants) and spec §8 (the
+authoritative source). If you change a code's number or name:
+
+1. Update `src/lib/exit-codes.ts`.
+2. Update the constant test in `test/exit-codes.test.ts`.
+3. Update this file + `commands.md`.
+4. Bump `schema_version` if the JSON envelope's `error.code` strings
+   change semantically.
+
+The CI matrix in `test/exit-codes.test.ts` enforces constants vs. spec
+parity; this doc is for humans + agents.

package/skills/diffmode/references/founder-input-schema.md

@@ -0,0 +1,113 @@
+# Founder input schema (`FounderDiagnostics`)
+
+`diffmode run`, `diffmode workflow`, and `diffmode smoke-test` all accept a
+founder-input JSON object via `--input <file|->`. The schema mirrors the
+backend Pydantic class `FounderDiagnostics` in the upstream Diffmode API
+(`src/api/models.py`).
+
+> **Drift policy:** regenerate this file whenever
+> `models.py:FounderDiagnostics` changes. Treat the Pydantic class as the
+> source of truth; this document is a developer-facing mirror. The CLI
+> parser intentionally tolerates unknown keys (`extra="allow"`) so adding
+> a field to the backend never breaks an existing client.
+
+## Required
+
+- **`product_description`** *(string, non-empty)* — what the product does.
+  This is the only hard-required field. Missing it → CLI exits 2 with a
+  pointer to this file.
+
+## Recommended (warn if missing)
+
+These fields meaningfully sharpen the generated plan; the CLI prints a
+non-fatal stderr warning when they're absent.
+
+- `target_audience` *(string)* — current or target customers.
+- `trigger_events` *(string)* — moments customers need the solution.
+- `pricing` *(string)* — business model and pricing.
+- `acquisition_sources` *(string)* — where customers come from today.
+- `current_growth` *(object|null)* — last-30-days traffic + conversion.
+
+## Optional — diagnostics (v2.2)
+
+- `alternatives_used` *(string)*
+- `marketing_experiments` *(string)*
+- `tactics_ruled_out` *(string)*
+- `goals` *(string)*
+- `budget` *(string)* — monthly budget shorthand.
+- `product_complexity` *(object|null)* — `{ type, details }`. `from-url`
+  pre-fill populates this when the analysis returns a complexity hint.
+- `resource_constraints` *(object|null)*
+- `problem_urgency` *(object|null)*
+- `challenges` *(object|null)*
+
+## Optional — business / team context
+
+- `business_model` *(string)*
+- `current_mrr` *(string)*
+- `funding_stage` *(string)*
+- `team_size` *(string)*
+- `your_role` *(string)*
+- `marketing_team_size` *(string)*
+- `resource_profile` *(string)* — `"solo"` / `"small_team"` / `"dedicated"`.
+
+## Optional — persona & customer mix
+
+- `persona_type` *(string)* — founder vs marketing-hire framing.
+- `observed_customers` *(string)*
+- `customer_mix` *(string)*
+- `top_competitors` *(string)*
+- `what_makes_you_different` *(string)*
+- `channels_tried_raw` *(string | string[])*
+
+## Optional — growth & retention signals
+
+- `retention_signal` *(string)*
+- `emotional_signals` *(string)*
+- `blind_spots` *(string)*
+- `comprehension_friction` *(string)*
+- `comfortable_with_outreach` *(`""` | `"yes"` | `"no"`)*
+- `trigger_events_source` *(string)*
+
+## Extra keys
+
+The backend accepts arbitrary additional keys (`extra="allow"`). The
+parent diagnostics formatter renders them under an "Additional Context"
+section. **Reserved keys** (`user_id`, `created_at`, `updated_at`, `id`,
+`job_id`, `product_id`) are server-managed and rejected by the CLI before
+submit.
+
+## Example
+
+```json
+{
+  "product_description": "Drop-in fraud-detection API for fintech apps.",
+  "pricing": "Usage-based — $0.002/request after a 10k-request free tier.",
+  "target_audience": "Series-A fintechs adding their first underwriting team.",
+  "trigger_events": "First fraud incident or compliance review.",
+  "acquisition_sources": "Founder outbound + a small founder-led community.",
+  "current_growth": { "traffic_30d": 12000, "conversion_rate": 0.018 },
+  "goals": "$50k MRR in 6 months."
+}
+```
+
+## Pre-fill from a URL
+
+`diffmode diagnostics from-url https://your-site.example` calls
+`POST /public/v1/analyze-website` and emits a draft `FounderDiagnostics`
+JSON. Field mapping:
+
+| Response field                            | FounderDiagnostics field          |
+|-------------------------------------------|-----------------------------------|
+| `company_description`                     | `product_description`             |
+| `analysis_pricing`                        | `pricing`                         |
+| `target_customer`                         | `target_audience`                 |
+| `analysis_trigger_events`                 | `trigger_events`                  |
+| `how_customers_find_you_today`            | `acquisition_sources`             |
+| `top_competitors`                         | `top_competitors`                 |
+| `what_makes_you_different`                | `what_makes_you_different`        |
+| `analysis_product_complexity_type` + `_details` | `product_complexity` *(object)* |
+
+`auto_filled_fields` / `draft_fields` from the response are logged to
+stderr (not part of the diagnostics object) so you can tell which fields
+are confident vs. best-guess. Always review draft fields before submit.

package/skills/diffmode/references/idea-input-schema.md

@@ -0,0 +1,82 @@
+# IdeaInput schema
+
+The `diffmode idea-eval` command accepts a structured JSON list of `IdeaInput`
+objects, not free-text strings. This file mirrors the canonical Pydantic
+shape declared in the upstream Diffmode API (`IdeaInput` in `src/api/models.py`,
+~lines 43–83) — regenerate this doc when that class changes.
+
+## Top-level shape
+
+The ideas file passed via `--ideas-file <path>` MUST be a JSON array of
+`IdeaInput` objects:
+
+```json
+[
+  { "name": "…", "description": "…", … },
+  { "name": "…", "description": "…", … }
+]
+```
+
+A single-object file (`{"ideas": [...]}`) is **not** accepted — the array
+must be the top-level value.
+
+## Required fields
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `name` | string (non-empty) | Idea name |
+| `description` | string (non-empty) | One-sentence description |
+
+## Optional fields
+
+All optional fields default to `""` server-side and are forwarded into the
+"Additional Context" section of the formatted prompt.
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `target_customer` | string | Target segment, B2B/B2C, ideal first 10 customers |
+| `problem` | string | Pain point being solved, urgency, consequence of inaction |
+| `solution` | string | Solution approach, how it solves, differentiation |
+| `revenue_model` | string | Subscription, one-time, marketplace, etc. |
+| `price_point` | string | Price point |
+| `revenue_goal_min` | string | Minimum viable MRR + timeline |
+| `revenue_goal_ambitious` | string | Ambitious revenue goal |
+| `validation` | string | Existing validation: conversations, signups, prototypes |
+
+## Extras
+
+`IdeaInput` uses Pydantic `extra="allow"` — any additional fields you include
+will be preserved and rendered in the formatted output under "Additional
+Context". Use this to carry domain-specific metadata you want the model to
+see.
+
+## Example
+
+```json
+[
+  {
+    "name": "founder-mode-onboarding",
+    "description": "Concierge onboarding videos recorded by the founder",
+    "target_customer": "B2B SaaS solopreneurs $0–$10k MRR",
+    "problem": "Activation drops 60% on day 2 of a free trial",
+    "solution": "Loom-style 90s personalized welcome per signup",
+    "revenue_model": "subscription, $79/mo add-on",
+    "price_point": "$79/mo",
+    "revenue_goal_min": "$2k MRR in 90 days",
+    "validation": "12 founders agreed to pilot"
+  }
+]
+```
+
+## Companion flags
+
+- `--intuition "<text>"` — founder's qualitative gut feel about the list
+- `--target-idea "<slug>"` — evaluate a single idea (slug = name in
+  kebab-case, e.g. `founder-mode-onboarding`)
+
+## See also
+
+- [`founder-input-schema.md`](./founder-input-schema.md) — diagnostics that
+  `run` / `workflow` / `smoke-test` consume
+- [`commands.md`](./commands.md) — endpoint + credit cost per command
+- [`error-codes.md`](./error-codes.md) — exit-code recovery guide