deliberate-cli 0.2.0-beta.1.1

package/roles/skills/product-readout.md

@@ -0,0 +1,98 @@
+# Product readout — method
+
+> Use this for a periodic, project-scoped readout of product performance and customer evidence. The readout answers what materially changed, what the configured evidence supports, and what deserves action. It is not team-status reporting, a dashboard dump, or causal attribution by intuition.
+
+## 1. Establish coverage before drawing conclusions
+
+Read every relevant attached source the harness can access: product analytics, warehouses or exports, billing and commercial data, customer feedback, research, release and experiment logs, incidents, and the repo. For each expected source, establish:
+
+- whether it was accessible;
+- how fresh it is relative to the reporting period;
+- what part of the product picture it covers;
+- whether missing or partial coverage materially limits a conclusion.
+
+State material coverage limits in the report. Never turn an inaccessible source into "no change" or silently substitute general knowledge for project evidence.
+
+## 2. Use one completed reporting period
+
+One completed reporting period grounds the entire readout: metrics, customer feedback, releases, experiments, incidents, takeaways, insights, and actions. The project's durable readout contract defines its cadence, calendar alignment, and timezone; the default is the previous completed Monday–Sunday calendar week. A user may override the period for one run with a completed natural-language range such as "for June" or "for Q2."
+
+- Use only evidence dated inside the reporting period for the report's findings. Do not mix in events or metric observations from the period currently in progress.
+- Calculate every metric over the reporting period using its durable definition, source/query, aggregation, and segment. The period is stated once at report level; do not repeat it in every metric row.
+- Compare every metric with the immediately preceding equivalent completed period. For a calendar override, preserve its natural alignment: July compares with June, Q2 with Q1, and a calendar year with the prior year. An arbitrary date range compares with the immediately preceding range of equal duration.
+- Preserve units, aggregation, period duration, alignment, timezone, segments, and metric definitions across readouts.
+- For counts and amounts, show absolute and relative change. For rates, lead with percentage-point change; a relative change may follow when useful.
+- Never compare against the previous readout artifact, the elapsed time since it ran, or an incomplete period.
+- On the first readout, use the same immediately preceding equivalent period when the source has sufficient history. Otherwise show the reporting-period value and surface the missing comparator under Data gaps.
+
+## 3. Calculate; do not eyeball
+
+Use deterministic queries, exports, scripts, or calculator/tool results for arithmetic. The language model synthesizes meaning; it does not invent or visually estimate values.
+
+Every reported number must carry a source link or traceable local-source reference. If two sources disagree, surface the disagreement rather than choosing the more convenient value.
+
+## 4. Show material trends without turning the readout into a dashboard
+
+Add a trend chart only when a decision-relevant key metric has at least four comparable completed observations; prefer six to twelve periods so the shape is more informative than two-point period-over-period change. Include no more than three charts.
+
+- Generate charts deterministically from the normalized values used in the analysis; never ask a language model to draw SVG or infer points from a screenshot.
+- Keep the table canonical: it carries the exact reporting-period and comparison values, while the chart reveals the longer trajectory.
+- Use the readout's configured cadence, alignment, timezone, and the metric's stable aggregation and segment for every point.
+- Preserve missing periods as gaps. Never smooth, interpolate, forecast, or add a target line.
+- Use a zero-based quantitative axis so small movements are not visually exaggerated.
+- Embed the generated SVG beneath Key metrics with descriptive alt text and a relative `charts/<metric>.svg` path.
+- Skip charts when the source exposes only current/comparable values, the history is not consistently defined, or the series would disclose data that should not be committed.
+
+## 5. Distill only decision-relevant signal
+
+Prioritize:
+
+- movement relevant to the current Objective;
+- the North Star, its strongest inputs, material funnel changes, retention, revenue or efficiency where relevant, and guardrails;
+- meaningful segment differences;
+- notable changes that cross a configured business threshold;
+- customer-feedback themes whose prevalence, specificity, or change matters;
+- releases, experiments, campaigns, or incidents that provide context.
+
+Do not force positive and negative symmetry. Call a movement an **anomaly** only when sufficient history and a defined statistical or business threshold support that term; otherwise call it a notable movement.
+
+## 6. Keep observation, context, hypothesis, and causality separate
+
+- **Observation:** what the evidence directly shows.
+- **Context:** a release, experiment, incident, campaign, or environmental event in the same period.
+- **Hypothesis:** a plausible explanation worth testing.
+- **Causal finding:** only when an experiment or equivalent evidence supports attribution.
+
+Temporal proximity is not causality. Never claim that a launch, campaign, or incident caused a metric change merely because the dates overlap.
+
+## 7. Combine feedback prevalence with customer voice
+
+Summarize meaningful feedback themes with the reviewed volume or denominator, source coverage, affected segment when known, and direction versus the comparison period when supported.
+
+Use a short quotation when it adds specificity, language, or emotional texture:
+
+- quote the source exactly; never create synthetic or composite quotations;
+- choose a representative quotation, not merely the most dramatic;
+- include a date and source link or traceable record reference;
+- redact unnecessary identifying information without changing meaning;
+- never let one quotation imply prevalence — report volume alongside it.
+
+## 8. Turn findings into bounded action
+
+Recommend only actions or decisions warranted by the findings. Each action states why it matters now and, when the evidence permits, the owner or decision-maker, timing, and success signal. "No immediate action warranted" is a valid conclusion.
+
+## Anti-patterns
+
+- A polished report built from inaccessible or stale core sources.
+- Changes without reporting-period and comparable values and a named comparison.
+- Conclusions influenced by a week, month, quarter, or other reporting period that has not fully closed.
+- A reporting or comparison period that changes because the readout ran early, late, or after a gap.
+- Relative percent change used as the primary movement for a rate where percentage points are clearer.
+- A universal "health score" that hides mixed evidence.
+- Raw metric dumps, vanity metrics, or exhaustive source summaries.
+- Decorative charts, two-point charts, charts with inconsistent period grains, or more than three charts.
+- Smoothed, interpolated, forecast, or target lines not present in the normalized source series.
+- Generic recommendations that could appear in any project's report.
+- Root-cause claims without causal evidence.
+- Feedback sentiment without volume, coverage, or representative evidence.
+- Repeating the previous readout without a material update.

package/roles/skills/tech-constraints.md

@@ -0,0 +1,27 @@
+# Technical Constraints — pipeline output
+
+> How agents must **emit artifacts**. These are constraints of the Deliberate pipeline
+> itself, independent of whatever product the operator is running it on. (The *operator
+> project's* stack, personas, and strategy come from the auto-derived project context,
+> not from here.)
+
+## Prototype constraints
+- A single self-contained `index.html`: inline CSS/JS, hardcoded data, no build step,
+  no external network calls. It must open by double-clicking the file.
+- **One prototype per PRIMARY surface** (init marks them): the single default surface is
+  `prototype/index.html`; additional surfaces nest at `prototype/<surface>/index.html`.
+  The `index.html` is always the openable container, but its **medium follows the surface**
+  — a clickable GUI, a CLI terminal replay, an API request/response explorer, an
+  agent-session replay, a storyboard. **Never fabricate a GUI for a non-GUI product.**
+
+## Build Packet (the handoff artifact)
+- Markdown + YAML only, never JSON files. `spec.md` (acceptance criteria as YAML
+  frontmatter), `context.md`, `evidence.yaml`, `prototype/index.html`.
+- Delegated to the repo's coding agent via an installed **skill file**
+  (AGENTS.md / .github/skills) — Deliberate never pushes code itself.
+
+## Integration
+- Prefer official **MCP** servers (GitHub, LaunchDarkly); thin adapters for the rest.
+- Read repo access is optional + scoped (read-only).
+- Inference is model-agnostic (Copilot CLI by default, including the cross-vendor
+  critic) — never hard-wire one model.

package/roles/skills/ux-principles.md

@@ -0,0 +1,24 @@
+# Experience Principles
+
+> Guides **Shape** and **Prototype** so solutions feel native to the product they're designed for —
+> whatever its **primary surface** is (a GUI, a CLI or agent skill, an API/SDK, an MCP/agent tool, a
+> physical device, …). The principles are surface-neutral; apply them to whatever the surface is.
+
+## Principles
+- **Design around the job, not the features.** Start from the Frame JTBD: the experience should
+  meet the user in their situation and support the steps of getting the job done. A feature
+  list is not a design.
+- **Explain every automated decision.** Show the evidence behind anything the system decides
+  or recommends — never a black box. This is how trust is earned.
+- **Fewest steps to the point.** The core action should take as few steps as possible — clicks,
+  commands, or calls — so the user spends attention on judgment, not navigation or boilerplate.
+- **Reduce anxiety, amplify pull.** Make progress obvious and make the new way feel safe —
+  preview, undo/dry-run, and visible evidence lower the fear of switching.
+- **Delight is a feature.** A tangible, shareable, screenshot-able moment is worth designing
+  for — polish the one thing users will remember and tell others about. Simplicity and ease of use are essential; less is more from user perspective - complexity needs to be abstracted with a simple interface.
+- **Match the product's surface.** Reuse the product's real conventions so a new surface looks
+  native, not bolted on — a GUI's layout / navigation / components / voice, a CLI's command
+  grammar / flags / output, an API's resource shapes / naming / error envelopes, an agent tool's
+  schema and idioms.
+- **Tool-neutral & honest.** Don't assume a specific stack; never use dark patterns or
+  manufacture urgency — trust compounds, tricks don't.

package/roles/skills/win-conditions.md

@@ -0,0 +1,68 @@
+# Win-conditions
+
+> The forces that decide whether a product succeeds in the **AI era (the next 5–15 years)**,
+> when building software is nearly free. These are **principles to build toward** — not
+> only criteria to judge by. When anyone (or any agent) can ship the software, the product
+> *existing* is worth almost nothing; value accrues to what stays **scarce and
+> compounding** around it. Apply these to **this** project (from the derived context),
+> grounded in the real evidence — never import another product's story.
+
+## The thesis: build for what's scarce and compounding
+Features reach parity instantly, so don't compete on the code — compete on the layers that
+compound and can't be copied:
+- **Building is commoditized; taste, trust, and judgment aren't** (Dorsey: AI does ~80%,
+  the human "final 20%" is the edge).
+- **The moat is the flywheel, not the feature** (Nadella & Huang's "virtuous cycle";
+  Amodei on proprietary high-signal data; Karpathy's Software 2.0).
+- **Distribution is AI-mediated** (Thiel: distribution decides winners; Nadella: copilots
+  disintermediate discovery) — you must be found and *chosen* by humans **and** AI agents.
+- **Trust is premium amid infinite synthetic output** (Dorsey on authenticity/open
+  protocols/resilience; Amodei on safe + trusted; Huang on grounded, verifiable answers).
+- **Agents are users and buyers** (Karpathy/Huang: AI as counterparties) — composable,
+  agent-readable products get reach and stickiness humans-only ones won't.
+
+## The essentials — a winning product must earn **all** of these
+1. **Durable, AI-proof demand** — a real, important job whose value ubiquitous AI makes
+   *more* valuable, not obsolete. If a generic assistant erases the need next year, it's dead.
+2. **Compounding flywheel** — usage builds a proprietary, self-reinforcing asset (data,
+   learning, network, community, trust) that makes the product better and harder to copy
+   over time.
+3. **AI-era distribution** — a credible, compounding way to be found and *chosen* — by
+   humans **and** AI agents / answer engines / workflows (embeddedness, word-of-mouth,
+   agent-of-mouth).
+4. **Trust & authenticity** — clear sourcing (where results and data come from), reliability/grounding, safety, privacy / user
+   ownership, credible neutrality — the things that earn durable trust when output is
+   infinite and synthetic.
+
+## The amplifiers — multiply a product that already has the essentials
+- **Taste & delight** — human craft and judgment in the "final 20%," delight strong enough
+  to turn users into evangelists.
+- **Agent-readiness & composability** — clean APIs, tool/function exposure, MCP; a building
+  block others compose on.
+- **Personalization & adaptivity** — gets more tailored to each user/context the more it's used.
+- **Openness & resilience** — open protocols, local-first / user-owned data, resistance to
+  platform capture, resilience to shocks.
+- **"Why now" & strategic fit** — a real tech/economic/societal shift that makes this newly
+  possible, and alignment with this project's strategy and first target segment.
+
+## How each stage applies these
+- **Shape** — design the concept *toward* the essentials: the primary journey should serve
+  durable demand, **case a flywheel**, fit AI-era distribution, and **earn trust**; make it
+  **delightful**, not just functional. The go-to-market half should exploit **AI-era
+  distribution and compounding loops** (word-of-mouth, agent-of-mouth, being the answer/tool
+  AIs surface), preferring channels that build trust and repeat use over one-shot spikes.
+  Keep all of this as internal design intent — don't name the win-conditions in the output.
+- **Prototype** — the mock should *feel* trustworthy and delightful and **show** the
+  flywheel / distribution moments (e.g. the moment a user invites others, or sees where a result came from),
+  not a bare CRUD screen. Reduce anxiety (show evidence, explain automated decisions) to build trust.
+- **Score (Evaluator)** — these **are** the factors it scores; see the `prioritization` skill
+  for the gates + weakest-link method (essentials are kill-gates; amplifiers refine). As the
+  independent reviewer, it also flags analysis that ignores demand-durability, the flywheel,
+  distribution, or trust, or that trades trust for short-term metrics.
+
+## Anti-patterns (across stages)
+- Building something a generic AI assistant makes obsolete.
+- A one-shot funnel with no compounding loop; "build it and they'll come" (ignoring distribution).
+- Dark patterns / engagement-hacking that spend **trust** for short-term metrics.
+- Treating "it can be built" as the win — that's table stakes now.
+- Optimizing an amplifier (delight, openness) while a **required essential** is absent.

package/skill/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: deliberate
+description: 'Use Deliberate for files-first product work inside a coding agent: grounded product analysis and go/no-go scoring, concept shaping, launch planning, optional prototypes, competitive and market briefs, product readouts from configured metrics and customer evidence, competitor matchups and battlecards, and repo product context. For product managers, founders, business development, marketing, and adjacent roles. Outputs are reviewable Markdown in the current repo. Triggers: product strategy or decision, validate or prioritize an idea, PRD, roadmap, product metrics, product health, customer feedback, data analysis, executive readout, competitive analysis, competitor teardown, battlecard, market brief, positioning, go-to-market, or deciding what to build.'
+version: '0.1.0'
+user-invocable: true
+argument-hint: '[help | init | case <idea> | brief | readout | matchup <competitor> | score | prototype | address | case list | brief list | readout list | matchup list | source | feedback] [idea, a URL, or a file path]'
+license: Apache-2.0
+---
+
+# Deliberate — a product toolkit inside your coding agent
+
+**Deliberate is a suite of essential, files-first product tools that run inside your coding agent** — for product managers, founders, business development, marketing, and any adjacent role. It is not just a go/no-go pipeline: it frames and scores ideas, shapes concepts and their go-to-market, builds interactive prototypes, monitors the competitive and market landscape, turns configured metrics and customer evidence into product readouts, and produces deep single-competitor teardowns — each a grounded, reviewable Markdown document you can hand to a team, drop into a deck, or give to your own coding agent to build. Everything is plain Markdown/JSON in the user's repo, all under `deliberate/`; there is no database and no cloud, and the records are versioned by the user's own git. **The project is simply the repo the harness is running in.**
+
+**The toolkit at a glance:** `init` grounds a project once (the product context every tool reads); `case` turns a raw problem into a scored, prototyped decision record; `brief` tracks what changed in the competitive + market landscape; `readout` reports what product data and customers are saying; `matchup` tears down one named rival head-to-head into a battlecard; `source` curates the grounding sources; `address` works through a reader's in-record comments. Each has its own section below.
+
+**Deliberate vs. Sonorance.** *Sonorance* is the stable local app/platform Deliberate runs on: an agent-review workbench over Markdown for reading agent output, inspecting git diffs, leaving anchored comments, and editing when needed. *Deliberate* is the product toolkit that adds product-management capabilities per project without replacing Sonorance's engine or identity. Meet Deliberate primarily inside the coding agent through `/deliberate`, and optionally open the same files in Sonorance with `LAUNCHER serve --open`. Existing editor/file features are enabling mechanics; use mature libraries for commodity Markdown/file-management work and do not expand generic editor parity without telemetry-backed demand.
+
+**What a `case` leaves on disk.** The deliverable is one combined decision record — `deliberate/cases/<YYYY-MM-DD-slug>/analysis.md` (the case's **title** is that record's `# H1`; a 1–2 sentence **case summary** sits just under it; then a section per stage, in funnel order). The go/no-go **score** is a recomputable companion — `score.md` beside the record, linked from a `## Score` section — re-run any time without touching the analysis. The interactive **prototype** is another recomputable companion — `prototype/index.html` (one per primary surface) beside the record, built on request, linked from a `## Prototype` section. A `case` also writes an internal **reverse PR-FAQ** — `one-pager.md` beside the record — a concise narrative + FAQ in the customer's own voice, for the team deciding. **A Case is just a prompt** — it is *not* saved as its own file; the workflow condenses it to the summary and keeps only that. The project context that grounds all of this lives in `deliberate/context/product.md` (+ `competitors.md` + `ecosystem.md`).
+
+## Setup (do this first, every invocation)
+
+The engine is driven through a launcher. Define it once for this session:
+
+```
+LAUNCHER = node .github/skills/deliberate/scripts/deliberate.mjs
+```
+
+Run everything below as `LAUNCHER <args>`. It needs Node ≥ 22. The stage reasoning runs in this session; the LLM-free engine builds prompts, validates configuration, persists artifacts, and extracts structured values. If a command prints "engine not found", tell the user to run `npx deliberate-cli install`, or set `DELIBERATE_ENGINE`.
+
+## Commands
+
+| Command | What you do |
+|---|---|
+| `help` | Show the current `/deliberate` command grammar, generated directly from the command registry. |
+| `init` | Set up the current repo as a Deliberate project: **you** read the repo + sources and write the grounded context in `deliberate/context/` (`product.md` + `competitors.md` + `ecosystem.md`); the root README points agents to it. |
+| `case <idea>` | Create a case, complete frame → shape → launch, score the finished analysis with recorded evaluator provenance, and write an internal reverse-PR-FAQ; report the verdict, then offer to prototype. |
+| `case [id] score` | (Re)compute the go/no-go after the full analysis; prefer an isolated cross-vendor Evaluator, record the actual model and independence status in `score.md`, and visibly label any same-session fallback. |
+| `case [id] prototype` | Build (or rebuild) the prototype(s) for a completed case — one per primary surface, each in its surface's native medium; a recomputable companion, built on request. |
+| `brief` | Produce a landscape **brief** — the competitive + market changes since the last brief (≤ 3 months). `brief list` lists them. |
+| `readout [period]` | Produce a **product readout** grounded in one completed reporting period: the previous calendar week by default, or a natural-language override such as `for June` or `for Q2`. `readout list` lists them. |
+| `matchup <competitor>` | Produce a competitive **matchup** — a grounded, point-in-time head-to-head against one named rival (one canonical doc per rival, refreshed in place). `matchup list` lists them. |
+| `case list` | List cases + scores. Change a case's state/title by editing its `analysis.md` (state in frontmatter, title in the `# H1`); delete one by removing its folder — no sub-commands. |
+| `source` | `source list` lists context sources; `source add <location> ["<description>"] [--section <section>]` and `source remove <location>` manage them (recorded by category in `.sonorance/sources.md`; you read each in-harness). |
+| `feedback` | Send the user's feedback to the makers — a bug (with repro), an idea (framed as the problem), or praise. You **structure, never rewrite**; their words go verbatim. See the `feedback` section. |
+| `address` | Work through the reader's in-record comments in the open Sonorance app — answer or edit, then resolve (optional; only when the app is open). |
+
+Routing: if the first word is one of these, follow its section. A bare `/deliberate <idea>` (no command) = `case <idea>`. If there's no project yet (no `deliberate/context/product.md`), do `init` first for every command except `help`. **A `case` runs the entire funnel in one pass** — there are no per-stage verbs to re-trigger; to change a finished record the user leaves in-record comments in the app and you `address` them (edit the file as a whole). After you produce or update any record, point the user at its file path (and, if the app is running, they read it there).
+
+**Every substantive workflow ends with one clear next-step question, using the harness's native confirmation or multiple-choice UI.** The CTA must name what will happen and why it is useful, not merely ask whether to "continue": `init` → run the first brief (default yes); `brief` → run the recommended Cases (default yes); `case` → build the prototype (default yes); `prototype` → open it for review in Sonorance (default yes); `readout` → run the recommended Cases for case-worthy actions (default yes); `matchup` → run a fresh brief (default yes); `source add|remove` → refresh affected project context (default yes); `address` → review the resolved changes in Diff mode (default yes). Listing and feedback commands may end transactionally when no responsible next action exists.
+
+---
+
+## `help` — show the current command grammar
+
+Run `LAUNCHER help --skill` and present its output verbatim. The engine renders this list directly from the same `SKILL_COMMANDS` registry that defines the user-facing grammar, so never reconstruct, summarize, or maintain a second command list. This command works before project initialization and ends after showing the grammar.
+
+## `init` — set up the project context (the Initiator)
+
+A grounded `deliberate/context/` grounds every Case, brief, product readout, and matchup. **You (the Initiator) derive it yourself** in this session (read the repo, fetch URLs) — the engine runs no model. Keep the exchange concise: group related choices at each confirmation gate and never interrogate the user one source at a time. The full method is a role you fetch with `init prompt`; this is the orchestration.
+
+1. **Scaffold and expose the context.** Run `LAUNCHER init` → creates `deliberate/` with three markdown scaffolds (`context/product.md` + `context/competitors.md` + `context/ecosystem.md`) and makes this current repo the project. It idempotently creates or updates the root README (case-insensitive README variants are respected) with a **Product context for agents** section linking `deliberate/context/` and telling agent harnesses to read it before product, strategy, market, positioning, or implementation work. It also creates the shared platform config in `.sonorance/`; only `.sonorance/local/` and hidden `deliberate/` runtime subfolders are added to an existing `.gitignore`.
+2. **Collect the project's grounding sources — manual first, then propose more.** These describe the product and live in `.sonorance/sources.md`, shared grounding any skill on the project can read.
+   - **Ask.** *"Point me at anything that describes your product — docs, a landing page, an API reference, a git repo, a metrics dashboard/query, or customer research (URLs, local paths, or a repo). Paste any you have, or say 'none'."* For **each**, run `LAUNCHER source add "<location>" ["<description>"] --section <section>`, choosing `product-strategy`, `code-delivery`, `metrics-data`, `customer-voice`, `go-to-market`, or `other`, then read it yourself in-harness.
+   - **Discover by section, not as one undifferentiated pile.** For each standard section (`product-strategy`, `code-delivery`, `metrics-data`, `customer-voice`, `go-to-market`), deliberately seek the few sources that best ground that section. Prefer at least three distinct, high-signal sources per section when they genuinely exist, but accept fewer when they are more authoritative; never pad a quota with weak, duplicate, stale, or incidental links. Read the repo (README links, manifest homepage/repository/docs fields, `docs/`, website/status badges) and use your knowledge to find the product's own first-party landing page, docs, changelog/releases, public GitHub, product blog, API reference, status page, metrics, research, and commercial sources. Verify every candidate before showing it; never fabricate a URL. Assign each accepted location to its strongest primary section and mention secondary relevance in its description.
+   - **Public GitHub Issues are customer voice.** For every product-owned GitHub repository among the manual or discovered sources, verify whether it is publicly accessible and Issues are enabled. If so, propose its `/issues` page under `customer-voice`, read the issue signal where accessible, and include it in `product.md` → **Customer voice**. Never infer accessibility from a URL alone and never treat a private or disabled Issues page as evidence.
+   - **Confirm before adding (default: accept).** Show **every auto-discovered candidate**, grouped by section, as a bullet in this exact readable shape: `- <location> - <source description>`. Do not collapse the list into counts or prose. Ask whether to *add them alongside the manual sources* (**the default**), *keep only the ones they gave*, or *change the list*. Then run `LAUNCHER source add "<location>" "<description>" --section <section>` for each accepted source — **never drop or overwrite manually provided ones** — and read each in-harness. Manual-only → add nothing further.
+3. **Get the method, then fill the files.** Run `LAUNCHER init prompt` → a `MODEL:` line, a `===== SYSTEM =====` block (AGENTS.md + the **Initiator instructions**) and a `===== TASK =====` block (the attached sources + the three current scaffolds). **Follow it:** read the repo + each source, then **edit `deliberate/context/product.md`, `competitors.md`, and `ecosystem.md` directly**, replacing every section's guidance with real, grounded markdown. Guardrails the method insists on:
+   - **Competitors are research, not fabrication.** Deduce the **real, named** field ordered by relevance (typically 5–10; non-competitor players go under **Ecosystem**). Never leave Competitors empty, never invent one.
+   - **Ecosystem is strategic, grounded, and quiet.** Catalogue only named players whose news could materially change the product or business outlook — classified by position (**dependency / complement / channel / mover**) and status (**current / potential**). For dependencies, manifests are evidence, not a roster: include only critical platforms, services, runtimes, protocols, or embedded components whose availability, roadmap, security, licensing, pricing, policy, or distribution can create an actionable decision. Exclude ordinary implementation-detail libraries and transitive components. Their monitoring sources go in `ecosystem.md`.
+   - **Missing info → never guess.** If the sources don't cover a section, ask the user to add a source or provide the details; if still unavailable, mark it `Not covered by the provided sources — add a source or fill in manually.` — never "unknown", never fabricated.
+4. **Confirm the risky bits.** Show the user the **personas**, the **deduced competitors**, the **deduced ecosystem players**, and the **readout cadence/alignment/timezone**, and ask them to confirm/correct just those; update to match.
+5. **Recommend the hero next step.** Report that context is saved to `deliberate/context/` and linked from the root README, briefly explain that the first brief establishes a current market/competitive baseline and surfaces grounded opportunities worth analyzing, then ask with the harness's native confirmation: *"Run the first landscape brief now?"* with **Run brief** (default) and **Not now**. On approval, run the `brief` workflow below; do not steer directly to a Case after init.
+
+---
+
+## `case <idea>` — create a case and run the funnel
+
+**You (the host agent) run the pipeline in THIS session** with three roles:
+
+- **Analyst — YOU, in this session** (not a sub-agent). One context-rich author writes `frame` (the problem + competitive landscape), `shape` (concept + step-level, surface-native journeys) and `launch` (the pitch, first users, how it spreads, metrics). **Keep this reasoning in your own context** so refining a result reuses *why* you wrote it, instead of a fresh agent rediscovering everything.
+- **Evaluator — preferably an isolated sub-agent** on the score's cross-vendor `MODEL:` target. It judges the complete analysis and flags ungrounded claims. If the harness cannot isolate it, an inline fallback is allowed only with honest provenance: the save omits `--independent`, and `score.md` visibly says it is not an independent second opinion.
+- **Prototyper — YOU** (or a sub-agent), building the `prototype` (one per primary surface, in each surface's native medium) on request once the analysis is complete.
+
+`<idea>` may be free text, a URL, or a file path; if it's a URL/file describing *product/market* context, add it as a source first (`LAUNCHER source add "<location>"`), else fold its gist into the idea text.
+
+1. **Create the case** (no pipeline runs yet — it becomes the case you work): `LAUNCHER case "<one-line idea>"`. It prints the Case id, a provisional slug, and the ordered funnel stages. The raw idea is held only as a transient input; you will condense it to a summary and the verbatim prompt is then dropped.
+2. **Give it a concise title** (there is no title agent — you do it): edit the record's `# H1` in `deliberate/cases/<YYYY-MM-DD-slug>/analysis.md` to a short, specific title — **≤ ~10 words, < 50 chars**. The title is that `# H1` (there is no title field and no retitle command — you just edit the file). The folder slug keeps its provisional value; that's fine (folders sort by date, and the title lives in the body).
+3. **Summarize the case** (1–2 short sentences): condense the original idea into a plain-English summary a reader sees directly under the title — what the case is about, grounded in what the user actually wrote. **Write it directly into `analysis.md` as the lede** — the prose line(s) between the `# H1` and the first `##` section (no command; it's a plain file edit, kept on one logical line, not hard-wrapped). Once that lede exists the engine **drops the raw prompt** on the next save (a case is "just a prompt"): from here on the record keeps only the summary, and later stages ground on the summary + the frame. *(Do this right after producing `frame` below, so the frame still grounds on the verbatim prompt — or immediately if you've already captured the idea faithfully.)*
+4. **Run the analyst funnel** — repeat until the analysis is **complete**, walking `frame → shape → launch`:
+   1. **Get the prompt:** `LAUNCHER case analysis prompt` (auto-targets the next stage for the active case) → a `MODEL:` line, a `===== SYSTEM =====` block (AGENTS.md + project context + the stage's skills + instructions) and a `===== TASK =====` block (the accumulated per-case context + the output template).
+   2. **Produce the artifact yourself, in this session** (the Analyst) — the reasoning must persist for later refinement (don't spawn a throwaway sub-agent). Ground strictly in the SYSTEM/TASK content; never invent demand or evidence.
+   3. **Persist:** write the artifact to a file → `LAUNCHER case analysis save --file <path>` (or pipe via stdin). It appends the stage's section to the single combined `analysis.md` (headings are normalized into one clean hierarchy — don't add your own summaries or attribution) and advances the case; after `launch` it prints **`analysis complete`** — the funnel is done.
+5. **Score the complete analysis with honest provenance.** The go/no-go is a recomputable `score.md` companion, not a funnel stage:
+   1. **Get the prompt:** `LAUNCHER case score prompt` → the target `MODEL:` line and SYSTEM/TASK blocks with the finished record.
+   2. **Prefer an ISOLATED sub-agent** on that cross-vendor model. Record the model that actually produced the artifact, not merely the requested target. If no isolation tool exists, do a fresh inline pass and treat it explicitly as a same-session fallback.
+   3. **Persist an isolated result:** `LAUNCHER case score save --model <actual-model-id> --independent --file <path>`.
+   4. **Persist an inline fallback:** `LAUNCHER case score save --model <actual-model-id> --file <path>` (no `--independent`). The generated `score.md` visibly labels the fallback as non-independent. Both forms stamp the number and link the companion from `analysis.md`.
+6. **The analysis is done — write the Key highlights.** In ≤ 3 **short, concrete** bullets (an executive summary of the decision — no fluff), capture what a reader must know: the verdict + why, the single biggest risk or gap, and the strongest lever. **Add them directly to `analysis.md`** as a `## Key highlights` section placed at the top — right after the summary lede, before the first stage section (no command; a plain file edit). Keep **each bullet on one logical line — never hard-wrap prose across several source lines** (the same rule as the summary lede). The engine recognizes that heading and keeps it above the stages.
+7. **Write the one-pager** (always, as part of a `case`) — an **internal reverse PR-FAQ**. Distil the finished record into a single page in the **customer's own voice** — a narrative + short FAQ (PR/FAQ lineage, no jargon), leading with the customer's world and outcome:
+   1. **Get the prompt:** `LAUNCHER case one-pager prompt` (acts on this case) → a `MODEL:` line, a `===== SYSTEM =====` block (AGENTS.md + project context + the customer-lens skills + the One-pager instructions) and a `===== TASK =====` block (the finished record to distil + the output template).
+   2. **Produce it yourself** (the Analyst — keep it in your own context; don't spawn a throwaway). Distil **only** the record — invent no new capability, customer, price, or metric; be honest about what it does **not** do yet. Customer voice first; keep it to ~one page.
+   3. **Persist:** `LAUNCHER case one-pager save --file <path>` (or pipe via stdin). It writes `deliberate/cases/<YYYY-MM-DD-slug>/one-pager.md` beside `analysis.md` and links it from the record (a `## One-pager` section). Don't hand-edit that link — the engine regenerates it.
+8. **When the analysis is complete, report the decision and ASK.** From the artifacts you just produced (the `score`, `shape`, and `launch` sections now in the record), present a compact **decision card**, grounded only in those artifacts:
+   - the **score** and verdict (advance / shelve / reject),
+   - the one or two **reasons** the score landed there, and the **evidence** each rests on,
+   - where the record is on disk (`deliberate/cases/<YYYY-MM-DD-slug>/analysis.md`, with the `score.md` (the recomputable go/no-go) and `one-pager.md` (the internal reverse PR-FAQ) beside it).
+
+   **Point the user at the record** on disk; if they want to read it in the UI and the app isn't running, start it with `LAUNCHER serve --open` (they navigate to the case via the Explorer).
+
+   Then **ask for approval using the harness's native confirmation / multiple-choice prompt** (not prose) — *"Build the prototype now?"* with **Yes** (default), **No**, and **Other** (a freeform reply, e.g. a refinement). **Wait for the choice.** Don't print raw shell commands; don't proceed on your own.
+   - **Yes:** build the prototype for this case now — the `prototype` flow below.
+   - **No:** stop; the analysis is complete and the case waits — the user can `prototype` it later.
+   - **Other:** read the reply, refine (below), then re-ask.
+
+   This confirmation is a **host behavior**, not an engine gate: the analysis is already complete (the case is `done`); the prototype is a recomputable companion built only when the user asks. Don't oversell or kill the idea — the Evaluator already scored it; present the evidence and let the user decide.
+
+## Refining a finished record — comment, don't re-run
+
+There are **no per-stage verbs**. A `case` runs frame → shape → launch in one pass and is scored separately with recorded evaluator provenance. The record is then edited as a whole, not by re-triggering stages. When the user wants changes, they leave in-record comments in the app and you `address` them. When an edit changes the analysis, re-run `LAUNCHER case score prompt`, produce the evaluation, and save it with the actual model/provenance flags.
+
+## `prototype [id]` — build the prototype(s) (a recomputable companion, one per primary surface)
+
+Produced **in-harness** (the Prototyper) — right after the analysis is complete, or any time later. Never auto-built; it's a companion built only on request. A case gets **one prototype per PRIMARY surface** (the surfaces `product.md` → **Interfaces** marks `primary`): the single default surface lives at `prototype/index.html`; each additional primary surface at `prototype/<surface>/index.html`. Each prototype's **medium follows its surface** — a clickable GUI page, a CLI terminal replay, an API request/response explorer, an agent-session replay, or a storyboard — **never a fabricated GUI for a non-GUI product**.
+
+1. **Pick the case.**
+   - If the user named one (`/deliberate case 3 prototype`), use it; else the case you were just discussing.
+   - If neither is clear, **ask** with the harness's native multiple-choice, each option labelled `id` · title · score:
+     - **Default** — the case you were just discussing; else the **latest completed** case that has no prototype yet (`LAUNCHER case list --state done`, newest first).
+     - **Second** — the latest such case that **scored well** (score verdict *advance*), if ≠ default.
+     - **Third** — the latest case overall, **even if it already has a prototype**, if ≠ the above.
+     - **Other** — the user names a case.
+2. **Build one per primary surface, in-harness.** Read `product.md` → **Interfaces** for the `primary` surfaces. For the single default surface: `LAUNCHER case prototype prompt` → produce a self-contained `index.html` in that surface's native medium, grounded in the product's real conventions → `LAUNCHER case prototype save --file <path>`. For **each additional** primary surface, pass its slug: `LAUNCHER case prototype prompt --surface <slug>` → produce → `LAUNCHER case prototype save --surface <slug> --file <path>` (e.g. `--surface cli`, `--surface api`). Most products have a single primary surface — build just the default then.
+3. **Report** the built prototype(s) (`LAUNCHER case prototype list`) — `deliberate/cases/<YYYY-MM-DD-slug>/prototype/[<surface>/]index.html` (the combined `analysis.md` links each one under `## Prototype`). The prototype is a recomputable companion — rebuild any surface any time to refine it.
+4. **Offer review.** Ask with the harness's native confirmation: *"Open the prototype in Sonorance to review it against the Case?"* with **Open for review** (default) and **Not now**. On approval, run `LAUNCHER serve --open` and point the user to the prototype and its Case record.
+
+---
+
+## `brief` — the periodic landscape brief (the Briefer)
+
+A **Brief** is a project-scoped landscape report (not a case): the **competitive + market changes since the last brief**, capped at 3 months. You (the host) are the **Briefer** — you do the research yourself in this session (fetch changelogs, blogs, release notes, GitHub activity, roadmaps; scan the market), then distil it to only what a founder / PM / manager would act on, every finding grounded in a linked source. There is no evaluator and no gate — a brief just surfaces signal.
+
+1. **Get the prompt:** `LAUNCHER brief prompt`. It prints a `MODEL:` line (produce in THIS session), a `===== SYSTEM =====` block (AGENTS.md + project context + `competitors.md` + `ecosystem.md` monitoring sources + the `landscape-scan` skill + Briefer instructions) and a `===== TASK =====` block with the **reporting window** (`period_start → period_end`), the **previous brief** (read-only prior context, when one exists — so you report only what changed *after* it and never re-report it), and the output template. **The window is the hard boundary** — *since the last brief*, at most 3 months back (a first-ever or stale brief → a full 3-month window; a later brief is told so explicitly and carries the prior brief).
+2. **Research the window, yourself.** For **each named competitor** (from `product.md` / `competitors.md`), scan their **first-party** signals *inside the window* — announcements, product blog, release notes / changelog, roadmap changes, public codebase activity (notable commits / merged PRs), pricing moves. Capture **≤ 3** meaningful highlights each, **every one with a working source link**; a competitor that was quiet gets exactly **"No meaningful updates."**. Then scan the wider **market & ecosystem** — the named ecosystem players (from `product.md` → Ecosystem / `ecosystem.md`: dependency / complement / channel / mover moves), protocol / standard releases, new entrants or adjacent players, M&A / funding / partnerships / pivots, new technologies — and keep the **≤ 3** most important, actionable developments, each with a source.
+3. **Distil the decision.** Pick the **top three (fewer is better)** findings across both lenses for **Key highlights**. Each must name the actor/product, the concrete change and date/evidence, and why it matters specifically to this product; never replace specifics with a vague category trend. Then reason the **Action items** — what decision or investigation this project should undertake and which finding warrants it. Filter hard: cut anything not worth a manager's time; empty sections are fine when the window was quiet. Keep every bullet **≤ 3 sentences (ideally 1–2)**.
+4. **Persist:** write the brief to a file → `LAUNCHER brief save --file <path>` (or pipe via stdin). It records the window and writes `deliberate/briefs/<YYYY-MM-DD>/brief.md`, printing its id.
+5. **Report a decision-ready brief, not a headline list.** State the reporting period and file path. For each Key highlight, summarize the named actor/product, what concretely changed, the dated/source-backed evidence, and why it matters to this product. Then summarize each warranted Action item and the decision it would unlock. Finally propose the **recommended Case candidates**: for each, give a concise problem/opportunity title, the triggering signal and evidence, why analyzing it is valuable now, and the decision a Case would help make. Do not make the user open the file just to understand the recommendation. `LAUNCHER brief list` lists prior briefs; use `LAUNCHER serve --open` when the user wants the full report in Sonorance.
+6. **Run the relevant Cases by default.** Ask with the harness's native multiple-choice prompt: *"Run the recommended Cases from this brief?"* with **Run recommended Cases** (default), **Pick Cases**, and **Not now**. On approval, run one full Case per chosen candidate, phrased around the underlying problem/opportunity rather than a predetermined solution: complete frame → shape → launch, evaluate with recorded provenance, then offer its prototype. Do not propose a Case for an action that is purely operational or already decided.
+
+Ground everything: no source link, no highlight; never fabricate funding, partnerships, competitors, or releases; never re-report a change a prior brief already covered.
+
+## `readout [period]` — the periodic product readout (the Reporter)
+
+A **product readout** is a project-scoped evidence synthesis (not a case and not a landscape brief): what the configured metrics and customers are saying, what materially changed, and what deserves action. You (the host) are the **Reporter** — inspect and query the project's configured evidence yourself in this session, then produce a concise executive read with enough detail to audit every conclusion. One completed reporting period grounds the entire report. Read `product.md` → **Metrics & traction** for the durable readout cadence, calendar alignment, and timezone; init defaults it to the previous completed Monday–Sunday calendar week. If the user adds a natural-language override such as `/deliberate readout for June`, `/deliberate readout for Q2`, or an explicit completed date range, use that completed calendar period for this run. If the requested period is ambiguous or still in progress, ask for clarification or explain that only completed periods can be analyzed.
+
+1. **Resolve one completed period.** Convert the configured default or user override to inclusive ISO dates in the project's timezone. Run `LAUNCHER readout prompt --period-start <YYYY-MM-DD> --period-end <YYYY-MM-DD> --timezone <IANA timezone>`. The engine rejects a range whose end date is today or later in that timezone. Use the exact same dates and timezone on `readout save`. The prompt includes the immediately preceding equivalent completed comparison period; a calendar month compares with the prior calendar month, a quarter with the prior quarter, and an arbitrary range with the immediately preceding equal-duration range.
+2. **Check evidence coverage before interpreting it.** Read every relevant configured source you can access, prioritizing **Metrics & data** and **Customer voice**, then product/strategy, delivery, and go-to-market context. A source can be a URL, local file, dashboard, query, warehouse, support export, CRM, transcript, or another harness-accessible location. Never imply a source was inspected when it was inaccessible, stale, empty, or outside the requested permissions; carry that limitation to **Data gaps**.
+3. **Use the reporting period for everything.** Metrics, customer evidence, releases, experiments, incidents, Key takeaways, Insights, and Actions must use only evidence inside the report-level period. Calculate every metric over that period using its durable definition, source/query, aggregation, and segment; compare it with the supplied immediately preceding equivalent period. The period appears once at the top of the report, so the metric table needs only **Metric · Value · Comparison · Read**. Never mix in the period currently in progress, project or annualize partial data, use the previous readout artifact as the comparator, or add a target.
+4. **Render material trends when history supports them.** Add no more than three charts, only for decision-relevant metrics with at least four comparable completed periods (prefer six to twelve) at the readout's configured cadence. The table remains canonical; charts reveal the longer trajectory. Never smooth, interpolate, forecast, add target lines, mix period grains, or chart sensitive detail that should not be committed. Create a temporary bundle containing `readout.md` and `charts/`. For each chart, write a JSON spec shaped as `{"title":"Weekly active teams","unit":"teams","comparison":"WoW","source":"<traceable source>","series":[{"period_start":"YYYY-MM-DD","period_end":"YYYY-MM-DD","value":123}]}` with four to sixty strictly ordered points, then run `LAUNCHER readout chart --spec <json> --output <bundle>/charts/<safe-metric-name>.svg`. Embed it directly below Key metrics as `![descriptive metric trend](charts/<safe-metric-name>.svg)`. If no series qualifies, generate no chart and keep the report Markdown-only.
+5. **Synthesize the read.** Lead with at most three Key takeaways. Keep Key metrics compact but complete; put cross-metric and customer interpretation under Insights; use exact representative customer quotes only when they are verifiable, relevant, dated/source-linked, prevalence-backed, and privacy-safe. Distinguish observation, context, hypothesis, and causal evidence. Turn only decision-relevant findings into Actions with an owner/decision, timing, and success signal; do not force positive/negative symmetry, invent a health score, dump raw metrics, or prescribe work unsupported by the evidence.
+6. **Persist:** when charts exist, run `LAUNCHER readout save --bundle <bundle> --period-start <YYYY-MM-DD> --period-end <YYYY-MM-DD> --timezone <IANA timezone>` so `readout.md` and every referenced SVG are stored atomically. Without charts, use `LAUNCHER readout save --file <path> --period-start <YYYY-MM-DD> --period-end <YYYY-MM-DD> --timezone <IANA timezone>` (or pipe via stdin). Use the exact same dates and timezone as `prompt`; save rejects a mismatched `Period:` line. Each run writes a new `deliberate/readouts/<YYYY-MM-DD[-N]>/readout.md`; same-day runs remain separate artifacts.
+7. **Report** the Key takeaways, Actions, material Data gaps, and the file path. `LAUNCHER readout list` lists the project's readouts. If the user wants the UI and it is not running, start `LAUNCHER serve --open`; readouts appear in the Inbox and Explorer and support anchored comments.
+8. **Offer case-worthy follow-through.** For each Action that represents an unresolved product opportunity or decision, propose a Case with the signal, why analysis is valuable, and the decision it would unlock. Ask *"Run the recommended Cases from this readout?"* with **Run recommended Cases** (default), **Pick Cases**, and **Not now**. Do not turn routine operations, instrumentation fixes, or already-decided work into Cases.
+
+Reliability is explicit: incomplete evidence yields a useful bounded readout plus visible gaps, never a confident fiction. If there is no accessible metric or customer evidence, do not pad the template; explain that a grounded readout cannot yet be produced, identify the minimum sources/definitions needed, and do not save a success-shaped artifact. Chart rendering is deterministic and optional; a chart is never evidence by itself and never compensates for missing or inconsistent source data.
+
+## `matchup` — the single-competitor head-to-head (the Scout)
+
+A **Matchup** is a project-scoped, single-rival **head-to-head** (not a case, not a brief): a full, honest, sourced read of **one named competitor** against us across every dimension — strengths, weaknesses, gaps, journeys, JTBD coverage, positioning, reuse/interop, and the "why we win / why we lose" a competing deck is built from. You (the host) are the **Scout** — you research the rival yourself in this session, then write the definitive current read, grounded in linked sources and true **as of** the run date. There is no evaluator and no gate. Where `brief` is *breadth of change over time*, `matchup` is *depth on one rival at a point in time*.
+
+**Keyed by the rival, refreshed in place:** there is exactly one canonical `matchup.md` per competitor (`deliberate/matchups/<slug>/matchup.md`). Re-running the same rival **updates that doc**, keeping its id and creation date and restamping the as-of date (git carries the history) — it never spawns a dated copy.
+
+1. **Get the prompt:** `LAUNCHER matchup prompt "<competitor>"` (a name, product, or URL). It prints a `MODEL:` line (produce in THIS session), a `===== SYSTEM =====` block (AGENTS.md + project context + `competitors.md` + the `head-to-head` / `jtbd` / `positioning` / `prioritization` / `tech-constraints` / `landscape-scan` skills + Scout instructions) and a `===== TASK =====` block naming **the rival**, **the as-of date**, the **existing matchup** (read-only prior read, when one exists — so you refresh it in place), and the output template.
+2. **Research the rival, yourself.** Fetch their site, docs, changelog, repo, pricing, positioning. **Steelman them first** — establish honestly what they do better and why a smart buyer picks them — *before* finding the openings; a home-team read loses the deck in Q&A. **If the rival isn't already in the competitors roster** (`deliberate/context/product.md` + `competitors.md`), research it first-party from scratch, then **ask the user whether to add it to the project context — default yes.** On yes, add the rival to the **Competitors** list in `product.md` and its official monitoring sources to `competitors.md` (the same edits `init` makes), so `brief` starts tracking it; on no, proceed without touching context.
+3. **Read across every dimension** — user journey, UX, functional, supported scenarios, strategic, marketing & positioning, pricing & business model, distribution & GTM, implementation, ecosystem & interop, maturity & momentum — ending each with an honest **Edge: us / them / even — because…** ("even" is valid; don't manufacture contrast). Then **synthesize**: SWOT the pair (name our real weaknesses), a JTBD coverage grid, and the strategy-canvas value curve.
+4. **Turn it into a decision** — a **battlecard** (why we win / why we lose / landmines / objection handling, ≤3 each with proof), **positioning against them** (the frame + the do-not-compete), and prioritized **opportunities** (Borrow by value ÷ effort — learn, don't copy, respect their license — Partner/interop, Respond). Keep every bullet **≤ 3 sentences (ideally 1–2)**.
+5. **Persist:** write the matchup to a file → `LAUNCHER matchup save "<competitor>" --file <path>` (or pipe via stdin). It cleans the artifact, stamps the as-of date, and upserts `deliberate/matchups/<slug>/matchup.md`, printing its id.
+6. **Report** where it landed and the Bottom line. `LAUNCHER matchup list` lists the project's matchups (one per rival); if the user wants to read this one in the UI and the app isn't running, start it with `LAUNCHER serve --open` (matchups appear under the **Matchups** tab beside Cases and Briefs).
+7. **Offer a fresh brief.** Once the matchup is saved, **ask the user whether to run a landscape brief now — default yes** — capturing the latest market moves including this competitor (especially valuable when you just added them to tracking, so the field is complete). On yes, run `brief` (see the `brief` playbook above); on no, stop here.
+
+Ground everything: every factual claim links to a first-party source dated on or before the as-of date; mark confidence (fact ▪ inferred ▪ assumption); steelman the rival and name our real weaknesses; never fabricate features, pricing, funding, or adoption; and never bolt on a slide outline — the substance already seeds a competing deck.
+
+## `case list` · `source` · reading in the app
+
+- **`case list`** — `LAUNCHER case list` lists cases + scores (the active case is marked `*`). There are **no case sub-commands** and **no shelve/dismiss states** — a case is simply kept or deleted: to **rename** one edit its `analysis.md` `# H1`, and to **remove** one delete its folder (both plain file operations).
+- **`source`** — `LAUNCHER source list` lists sources by section; `source add <location> ["<description>"] [--section <section>]` adds one and `source remove <location>` drops it. Standard sections are `product-strategy`, `code-delivery`, `metrics-data`, `customer-voice`, `go-to-market`, and `other`; users may also create custom `##` headings in `.sonorance/sources.md`. A `<location>` is a URL or local path. Nothing is cloned or fetched. After adding or removing a source, explain which context sections it can affect and ask *"Refresh the affected project context now?"* with **Refresh context** (default) and **Not now**; on approval, read the source in-harness and update `product.md`, `competitors.md`, or `ecosystem.md` as needed.
+- **Reading records in the UI** — we operate on **files**, not ids: point the user at the file path. If they want the web UI, `LAUNCHER serve --open` starts the Sonorance app (over the repo); they navigate to the record via the Explorer. There is no open-by-id command.
+
+The **project context** is a markdown file you author (`deliberate/context/product.md` + `competitors.md` + `ecosystem.md`) and the user reads/edits directly — there is no `context` command; just open the files.
+
+---
+
+## `address` — work through the reader's in-record comments (when the app is open)
+
+The optional Sonorance app (`deliberate serve`) lets the user **select any span of any file in the project — a case's decision record, a landscape brief, a product readout, a matchup, or any other file — and leave a comment** (a question or a change request), GitHub-PR-review style. When the user has finished annotating they run `/deliberate address` (or ask you to); you then **work through the open comments** and resolve each. The port is auto-resolved from the app's `serve.json`.
+
+1. **Fetch.** Run `LAUNCHER comment list` — it returns `{ comments:[ { id, file, anchor:{quote,heading}, body } ], count }`, the batch of every **open** comment across the project. Each comment names the **`file`** it annotates (a project-root-relative path). If the command exits nonzero, stop and surface its app/transport error; never treat that as an empty review queue. If `count` is 0, there are no open comments.
+2. **Address each comment.** Open the comment's `file`, find the quoted span (`anchor.quote`) in its section (`anchor.heading`), then:
+   - **A question** → answer it **here, in this conversation** (grounded in the file/context — the user reads your answer in this agent interface). No file change.
+   - **A change request** ("drop this competitor", "tighten the urgency claim") → **before editing, confirm with the user** using the harness's native confirmation / multiple-choice prompt when the change is material or ambiguous (*"Apply this edit to `<file>`?"*). On yes, **edit that `file`** to make the change (a case's `analysis.md` round-trips through the app's diff view, reviewable before the user commits — the propose-and-commit ethos: you propose, their git commits).
+   - **Keep the case's two documents consistent.** A case has both `analysis.md` and its reverse-PR-FAQ `one-pager.md`. When a change to one invalidates the other, revise both in the same pass. The one-pager is downstream: after a material analysis edit, regenerate it (`LAUNCHER case one-pager prompt` → produce → `LAUNCHER case one-pager save`) and refresh Score with `LAUNCHER case score prompt` followed by a provenance-aware `case score save`. A cosmetic one-pager wording fix needs no analysis change.
+3. **Resolve.** `LAUNCHER comment <commentId> resolve` (add `--revised` if you edited a file; add `--note "<what you did>"` to record a short note in the durable `comments.jsonl`). The comment disappears from the app the moment it's resolved.
+4. **Loop** through the remaining comments, then tell the user what you answered / changed. If you edited a record, point the user at its file path.
+5. **Offer review.** When files changed, ask *"Review the resolved changes in Sonorance Diff mode?"* with **Review changes** (default) and **Not now**. The app is already open for addressing; point the user to the revised files rather than starting another server.
+
+Addressing is **optional and non-blocking** — only do it when the app is plausibly open. Never invent answers: an in-record answer is held to the same grounding bar as any stage artifact.
+
+---
+
+## `feedback` — send the user's feedback to the makers (structure, never rewrite)
+
+When the user wants to report a bug, request something, or share praise, run `LAUNCHER feedback "<their message>" [--category bug|idea|praise|question|other] [--rating <1-5|up|down>]` — or pass a structured record with `--file <json>` (or pipe the JSON on stdin) when you've collected more than one field. The message is sent **exactly as the user framed it**; your job is to help them structure it, not to reword it.
+
+**Your role is to STRUCTURE, never to REWRITE.** Preserve the user's own words verbatim (the founder distils the JTBD later, on their side — not you, not now). Do two light things before sending:
+- **For an idea / feature request — steer them to the PROBLEM, not a solution.** Nudge the user to say *what they're trying to achieve and why* rather than prescribing the feature. If their message is only a proposed solution, ask one short question ("What are you trying to do, and what's getting in the way?") and put their answer in `--context`. If it still reads as solution-only, pass `--needs-framing` so the record is flagged — but **send their words unchanged**.
+- **For a bug — get repro completeness.** Encourage steps-to-reproduce, expected vs. actual, and how often it happens; put these in the `bug` fields of a `--file` record. A pasted log or stack can go in `bug.diagnostics` — it is **scrubbed** (paths/secrets/emails stripped) before it leaves the machine.
+
+**Privacy is absolute — this channel carries only what the user typed.** Never send prompts, model completions, file contents, or full logs. The one field that carries free text is the user's own `message` (and their `--context` answer), because they explicitly authored it to send. Optionally you may attach a short, safe **agent-drafted context summary** via `--agent-context` — a one-or-two-sentence recap of what the user was trying to do and the gap they hit — but only after you've **shown it to the user to approve, edit, or skip**, and it must never quote file contents, secrets, or anything session-specific that would reveal more than the user intends. Default: offer it for bugs (previewed), ask first for ideas.
+
+After sending, confirm to the user that their feedback went through (the CLI prints a short id). The CLI sends **one** consented feedback record (never a duplicate telemetry event), correlated with product usage by the same anonymous install id, and writes a durable local mirror in the project's `.sonorance/local/`.
+
+**A note on telemetry (be transparent when asked).** Deliberate and Sonorance emit content-free OpenTelemetry product usage and error signals to help improve the product — never prompts, completions, file contents, paths, or file/folder names. It is controlled from Sonorance Settings, the `sonorance` binary, `SONORANCE_TELEMETRY`, and a committed `.sonorance/config.json` `"telemetry": false` team policy. Telemetry is not a `/deliberate` command.
+
+---
+
+## Rules
+
+- **The prototype is asked for, never automatic.** After the analysis is complete, the prototype is an explicit, asked-for step. *Ask* "Build the prototype now?" (default Yes) and wait; only build on the user's yes (or an explicit `/deliberate case <id> prototype`), and always **in-harness** (`case prototype prompt` → `case prototype save`). Never dump a raw command; never auto-build. This confirmation is a **host behavior**, not an engine state — the analysis is already `done`; the prototype is a recomputable companion built only on request.
+- **Evaluator provenance is honest.** Prefer an isolated cross-vendor evaluator after the complete analysis. Save with `--independent` only when isolation actually occurred; otherwise omit it so `score.md` visibly labels the same-session fallback. Always pass the actual evaluator model with `--model`.
+- **Ground everything.** Every claim traces to `deliberate/context/product.md`, the case's artifacts, or the repo. Never invent demand, personas, or competitors.
+- **Files are the deliverable.** The records live in the repo (`deliberate/context/product.md`, `deliberate/…`), versioned by the user's own git. Point the user at those files; the Sonorance app is an optional reader, never required.
+- **Be concise.** A run header, a streamed sense of progress, and a tight decision card — not a wall of text.

package/skill/scripts/deliberate.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * deliberate.mjs — launcher the skill shells into. Resolves the Deliberate engine
+ * and forwards all args + stdio to it, so the SKILL.md never hard-codes an engine
+ * path. Resolution order:
+ *   1. $DELIBERATE_ENGINE (explicit override)
+ *   2. ./engine.json  { "engine": "/abs/path/to/src/cli/deliberate.mjs" }  (written by `deliberate install`)
+ *   3. ../../src/cli/deliberate.mjs  (in-repo dev: skill/scripts → repo root)
+ * The spawned engine inherits cwd, so `init`/`case` act on the folder the user is in.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function enginePath() {
+  const env = process.env.DELIBERATE_ENGINE;
+  if (env && existsSync(env)) return env;
+  const cfg = join(here, 'engine.json');
+  if (existsSync(cfg)) { try { const e = JSON.parse(readFileSync(cfg, 'utf8')).engine; if (e && existsSync(e)) return e; } catch { /* ignore */ } }
+  return resolve(here, '../../src/cli/deliberate.mjs');
+}
+
+function launchTarget() {
+  const engine = enginePath();
+  if (existsSync(engine)) return { command: process.execPath, args: [engine] };
+  const cfg = join(here, 'engine.json');
+  if (existsSync(cfg)) {
+    try {
+      const { package: name, version } = JSON.parse(readFileSync(cfg, 'utf8'));
+      if (name === 'deliberate-cli' && version) {
+        return { command: process.platform === 'win32' ? 'npx.cmd' : 'npx', args: ['-y', `${name}@${version}`] };
+      }
+    } catch { /* handled by the error below */ }
+  }
+  console.error(`deliberate: engine not found at ${engine}. Set DELIBERATE_ENGINE or re-run \`npx deliberate-cli install\`.`);
+  process.exit(1);
+}
+
+const target = launchTarget();
+const r = spawnSync(target.command, [...target.args, ...process.argv.slice(2)], { stdio: 'inherit' });
+process.exit(r.status ?? 1);