@whisperr/wizard 0.5.3 → 0.6.0

package/README.md

@@ -1,80 +1,85 @@
 # @whisperr/wizard
 
-Generate and integrate a Whisperr intervention model from your actual codebase.
+Integrate [Whisperr](https://whisperr.net) into your app with one command.
 
 ```bash
 npx @whisperr/wizard
 ```
 
-Run the command in the customer-facing frontend first. The wizard detects the stack, authenticates the app, inspects concrete product behavior, writes the generated model to Whisperr as it works, installs the SDK, and instruments the generated events.
+Run it in your project's root. The wizard detects your stack, signs you in,
+**maps your codebase, plans every event placement, shows you the plan, and
+wires it in** — then verifies the build, watches for your first event, and
+hands you a clean diff to review and commit.
 
-## How It Works
+## How it works
 
-1. A read-only Terra agent maps repository structure, end-user paths, and concrete event call sites.
-2. The Sol primary creates only intervention groups, interventions, events, and direct intervention-event links.
-3. Each accepted item is written to runtime immediately with a stable idempotency key, so the dashboard can show live progress.
-4. Sol installs and configures the stack-specific SDK, then instruments events owned by this project.
-5. The host runs the stack's deterministic build or lint verifier when one is defined, before runtime accepts completion.
-6. An interrupted run resumes from the runtime snapshot and its OpenAI conversation. Missing conversations restart from the same server snapshot without duplicating rows.
+The wizard is an agentic integrator with a planner/editor split:
 
-For split repositories, finish the frontend run before running the wizard in backend repositories. A full-stack repository is one project.
+1. **Plan** — one read-only pass charts your repo (entry points, end-user vs
+   admin auth flows, billing surfaces, existing analytics wrappers) and
+   decides, per event, exactly where it belongs (`file @ anchor`) with the
+   properties available in scope — or says honestly that it doesn't exist on
+   this surface. It also notes churn-relevant moments your plan is missing.
+2. **See the plan** — every placement is printed before a single line
+   changes. The run then proceeds on its own; pass `--review-plan` if you'd
+   rather confirm placements first, or `--propose-only` to keep new
+   events/interventions behind dashboard approval instead of adding them.
+3. **Wire** — a fast editor model executes the plan mechanically.
+4. **Review** — the agent re-reads its own diff and fixes wrong subjects,
+   wrong lifecycle moments, and missing discriminators.
+5. **Verify** — placements are scanned back out of the diff, your build/lint
+   command runs, and failures get one automatic repair pass. Every event ends
+   the run as `✓ wired @ file` or `○ skipped — reason`.
 
-## Supported Stacks
+Multi-surface aware: run it in your web app, then your mobile app, then your
+backend — the wizard knows what each surface already covers and never
+re-proposes what another run wired.
 
-Next.js, Web (JavaScript/TypeScript), React Native, Flutter, Swift, Node, Python, and PHP.
+## Supported stacks
 
-## Requirements
+Next.js · Web (JS/TS) · React Native · Flutter · Swift · Node · Python · PHP
 
-- Node.js 22+
-- A completed Whisperr onboarding session
-- A Git repository with a clean working tree for a new run
+## Requirements
 
-An incomplete run may resume with its existing wizard edits still in the working tree. `--force` permits other uncommitted changes; invocation-scoped restore preserves the state that existed before that invocation.
+- Node.js 18.17+
+- A Whisperr account with onboarding completed (or use `--offline` to demo)
 
 ## Usage
 
 ```bash
+# in your project root
 npx @whisperr/wizard
+
+# or point it somewhere
 npx @whisperr/wizard path/to/app
 ```
 
 Options:
 
-```text
---force         Proceed without a clean Git tree
---api <url>     Override the Whisperr API base URL
---model <id>    Override the primary Sol model
+```
+--offline       Demo run with a mock manifest — no account or browser needed
+--force         Proceed without a clean git tree (disables the safe undo)
+--api <url>     Point at a specific Whisperr API (advanced)
+--model <id>    Override the editor model (WHISPERR_WIZARD_MODEL)
 -h, --help      Show help
 -v, --version   Show version
 ```
 
-Model defaults are `gpt-5.6-sol` with `high` reasoning and the `priority` service tier, plus `gpt-5.6-terra` with `xhigh` reasoning for read-only exploration.
-
-Development overrides:
-
-- `WHISPERR_WIZARD_API_BASE`
-- `WHISPERR_WIZARD_OPENAI_BASE`
-- `WHISPERR_WIZARD_PRIMARY_MODEL`
-- `WHISPERR_WIZARD_PRIMARY_EFFORT`
-- `WHISPERR_WIZARD_SERVICE_TIER`
-- `WHISPERR_WIZARD_EXPLORER_MODEL`
-- `WHISPERR_WIZARD_EXPLORER_EFFORT`
-- `WHISPERR_WIZARD_DIRECT_OPENAI_KEY`
-- `WHISPERR_WIZARD_LOG_DIR` to place private diagnostic logs in a specific directory outside the target repository
-
-## Diagnostics
-
-Each wizard invocation prints the path to one private JSONL diagnostic file. By default it is stored under the wizard state directory's `logs` folder, outside the target repository. The directory is mode `0700` and each file is mode `0600`. Filenames contain only a timestamp and random invocation ID.
-
-Diagnostics contain bounded lifecycle, progress, Git-safety, coverage, first-event, and HTTP timing/status metadata. They do not contain request or response bodies or headers, prompts, repository source, model output or reasoning, subprocess output, environment contents, authorization codes or URLs, or credentials. Known credentials are registered for exact redaction as they become available, and common token/key formats are also scrubbed.
+Environment knobs: `WHISPERR_WIZARD_PLANNER_MODEL`,
+`WHISPERR_WIZARD_BUDGET_USD` (default 25), `WHISPERR_WIZARD_EFFORT`.
 
 ## Safety
 
-- Repository tools are host-owned and restricted to the selected repository.
-- Secret files are blocked. The host writes ingestion credentials only to local environment files and redacts them from model-visible reads and command output.
-- Terra receives only read, list, and search tools.
-- Repository commands use parsed arguments without a shell and are limited to approved SDK package installation plus metadata-only Git commands.
-- Git and CI configuration writes are blocked.
-- The wizard never commits or pushes changes.
+- **Clean-tree contract** — the wizard requires a clean git working tree and
+  gives you a one-command revert; your code is never uncommitted-mixed with
+  its changes.
+- **Restricted agent sandbox** — the agent cannot read secret material
+  (`.env*`, keys, credentials) and can only run an allowlisted set of package
+  -manager commands. Details in [SECURITY.md](./SECURITY.md).
+- **Nothing merges itself** — the wizard's output is a working-tree diff for
+  you to review and commit.
+
+---
 
-See [SECURITY.md](./SECURITY.md) for the complete boundary and residual risks.
+Whisperr — predict churn, automate interventions, recover revenue.
+[whisperr.net](https://whisperr.net)