@jevitate/cli 0.1.0 → 0.2.0

package/skills/jevitate-getting-started/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: jevitate-getting-started
+description: Start here for any jevitate task, or when unsure which jevitate skill applies — checks setup (keys, .jevitate/, MCP), gets a first useful result against the user's app URL, routes to the right skill (explore, run-journey, record, demo, verify-fix, ci-check, ux-review, load-test, sources, mission-scope), and says when to use the jevitate MCP tools vs the CLI, what the exit codes mean, and which approvals only a human may give.
+---
+
+Jevitate tests a web app in a real browser and returns evidence: typed outcomes, exit codes,
+Recordings, replayable Journeys, videos and screenshots. You never drive the browser yourself.
+You pick the command, pass it the user's intent, and report what came back honestly.
+
+## 1. Check the setup (once per session)
+
+- `jevitate ai status --json` shows which AI features have their keys, by name only, never a value.
+  Goal runs, authoring, demos and UX reviews need `generation` and `judgment` (`--real`). Without
+  them, use a key-free command (see step 2), or ask the human to run `jevitate ai setup generation`
+  and `jevitate ai setup judgment` themselves. Setup is interactive. Never ask for a key in chat.
+- The repo has a `.jevitate/` directory (Journeys, regressions, baselines, logs and
+  `environments.json`). If it's missing, the human runs `jevitate init` (it also installs these
+  skills and registers the MCP server). `jevitate init --dry-run` changes nothing.
+- The app must be running and the human must have authorized its URL. Jevitate only acts on an
+  authorized origin (`--url`'s own origin, or an explicit `--allow` list). It refuses a production
+  target for authoring runs and demos. Never widen the allowlist on your own.
+
+## 2. A first useful result
+
+| The user has | Run |
+| --- | --- |
+| keys, and a task a user does | `jevitate explore --url <app-url> --goal "<task>" --success "urlIncludes:/<done-path>" --real --json` |
+| keys, and a question about the app | `jevitate explore --url <app-url> --goal "find out <question>; report the answer" --real --json` (read-only by default) |
+| no keys | `jevitate explore --strategy adversarial --url <app-url> --fake-ai --json`: misuse is planned in code, and the findings (HTTP 5xx, uncaught errors, hangs, invariant violations) come from hard signals, not a model |
+| no keys, one feature | `jevitate explore --feature <name> --route "/<area>/**" --url <app-url> --json` (model-free) |
+
+Then pick the matching skill:
+
+| The user wants to | Skill |
+| --- | --- |
+| explore, find bugs, or check that a goal is reachable | `jevitate-explore` |
+| know what to test after a diff or PR | `jevitate-mission-scope` |
+| replay a known flow (a saved Journey) | `jevitate-run-journey` |
+| record a flow they click through | `jevitate-record` |
+| get a narrated demo video or a step-by-step guide | `jevitate-demo` |
+| reproduce a finding, prove a fix, attach evidence to a PR, or lock a bug in as a regression | `jevitate-verify-fix` |
+| gate CI (JUnit, SARIF, baselines, a defect report) | `jevitate-ci-check` |
+| get a usability critique | `jevitate-ux-review` |
+| run a load test | `jevitate-load-test` |
+| share or run third-party Journeys | `jevitate-sources` |
+
+## 3. MCP tools or the CLI
+
+- If the jevitate MCP tools are in your tool list (`init` registers `jevitate mcp` for Claude
+  Code, Cursor and Codex), use them. They take typed arguments named after the CLI flags
+  (`--storage-state` becomes `storageState`), run the same command in process, and return
+  `{exitCode, data}`. Exit 2 (proved nothing) and every refusal come back as MCP errors
+  (`invalid_args` or `refused`, with the `E_…` code), never as a pass.
+- Otherwise use the CLI with `--json`: one line on stdout, `{v, ok, data}` or
+  `{v, ok: false, error: {code, message}}`. Read the exit code as well.
+- Common pairs: `run_exploration` = `explore`, `queue_exploration` + `run_queued_missions` +
+  `get_mission_result` = `mission queue` + `mission run` + `mission result`,
+  `find_capabilities`/`run_journey` = `journey find`/`journey run`, `author_journey` =
+  `explore-author-journey`, `create_demo`/`demo_journey` = `demo`/`journey demo`, `verify_fix` =
+  `verify-fix`, `regressions` = `regression capture|run`, `ledger` = `ledger …`, `run_check` =
+  `check`, `get_report` = `report`, `ux_review` = `ux`. The full table is in the jevitate repo's
+  `docs/agents.md`.
+- These are never available over MCP: `record` (a person clicks), `init`, `ai setup` (secret entry),
+  `ui`, `source trust` and `source add --accept-tou`. Operator settings are never tool arguments
+  either: shell hooks, browser binaries, which environment variable a secret comes from, and
+  log-command sources. Tell the human the CLI command instead.
+- Raw browser tools (click, fill, evaluate, get DOM or cookies) don't exist on purpose. Never
+  swap in another browser-automation tool to get around a refusal.
+
+## 4. Decisions that belong to the human
+
+Only do these when the human has asked for that specific action in this conversation. Before
+you do, show them what they are approving:
+
+- promoting a Journey: `jevitate journey promote <id>` / `promote_journey`
+- applying drafted annotations: `jevitate journey annotate <id> --approve` / `annotate_journey` with `approve: true`
+- approving a demo, which promotes its Journey: `jevitate demo approve <id>` / `approve_demo`
+- promoting a mission target: `jevitate mission target promote <id>`
+- trusting a third-party Journey or accepting a source's Terms of Use (CLI only)
+- approving or cancelling an inbox item: only in `jevitate ui`. The MCP tools `approve_action` and `cancel_command` always refuse.
+
+## 5. Exit codes (every command)
+
+`0` clean / passed / fixed · `1` defects found, a gating finding, or still reproduces · `2`
+inconclusive: the run proved nothing, so never report it as a pass · `3` the app hung (reproduced) ·
+`4` intermittent · `64` usage error, nothing ran (bad flag, unknown id, missing keys
+`E_AI_SETUP_REQUIRED`, target not allowed) · `130`/`143` interrupted, but the partial result was
+written. Report the outcome the tool gave you. Never round it up.

package/skills/jevitate-load-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevitate-load-test
-description: Runs a seeded, human-paced concurrent load test of a promoted Journey via `jevitate load run`, against an explicitly authorized target only. Use when a user wants a capacity/throughput measurement, not a single functional run.
+description: Run a seeded, human-paced concurrent load test of a promoted jevitate Journey (`jevitate load run`, MCP `run_load_test`) against an origin the human explicitly authorized, optionally on a named environment (`--env`). Use when the user wants capacity, throughput or latency numbers. For a single functional run, use jevitate-run-journey.
 ---
 
 You scope and run a throughput/capacity measurement, never a single functional
@@ -19,12 +19,21 @@ check (use `jevitate-run-journey` for that instead).
 
 - `jevitate load run <journeyId> --authorized-origin <origin> [--authorized-origin
   <origin2> ...] --param k=v --concurrency <n> --iterations <n> --seed <n>
-  --json`.
+  [--storage-state <file>] --json`.
 - `<journeyId>` must be a promoted Journey id (same discovery flow as
   `jevitate-run-journey`: `jevitate journey find`/`find_capabilities` first).
+- `--env <name>` / `--base-url <origin>` runs it against a named environment
+  (`.jevitate/environments.json`) instead of the recorded site; the
+  `--authorized-origin` must still name that origin explicitly.
+- MCP: `run_load_test` takes the same arguments (`authorizedOrigin`,
+  `concurrency`, `iterations`, `seed`, …).
 - `--seed` makes the run reproducible — if the human wants to compare two
   configurations, keep the seed fixed and vary only `--concurrency`/
   `--iterations`.
+- `--storage-state <file>` seeds EVERY pool member's session from the same
+  Playwright storageState file (the same authenticated pre-step as `jevitate
+  journey run` — see `jevitate-run-journey`), for load-testing a Journey that
+  needs an authenticated session.
 
 ## Reading the result
 

package/skills/jevitate-mission-scope/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevitate-mission-scope
-description: Reads a diff, pull request, changelog, or user story and scopes change-driven testing — identifies at-risk routes/features, maps them to existing promoted Journeys, runs the most relevant ones, and recommends which newly-discovered repros to promote. Use when a user wants to know "what should I test" after a code change, rather than testing everything or picking targets blindly.
+description: Turn a diff, pull request, changelog or user story into targeted jevitate testing. Finds at-risk routes and features, maps them to promoted Journeys (`journey find` / `find_capabilities`) and runs those, scopes bounded missions where nothing covers a gap (including queued missions on promoted targets), and recommends which new repros to promote or capture as regressions. Use when the user asks "what should I test?" after a code change, or wants a change-scoped check.
 ---
 
 You scope testing to what actually changed. You never drive a browser yourself —
@@ -54,6 +54,8 @@ tool to scope a **bounded** mission at the specific at-risk area:
   --url <authorized-url>` (bounded misuse + a trusted hard-signal defect oracle).
 - For state coverage of the changed area: `jevitate explore --strategy coverage
   --url <authorized-url>`.
+- In CI, the same scoping is `jevitate check --suite <file> --changed-routes '<glob>'`: only the
+  Journeys and goals touching those routes run (see `jevitate-ci-check`).
 - Only if you cannot reach an authorized target at all (or `jevitate explore`
   is genuinely absent from your environment) do you stop and report the gap —
   never fall back to a generic browser-automation tool; that would bypass every
@@ -86,22 +88,28 @@ quantity.
 
 `queue_exploration` runs against a PROMOTED mission target, never a raw URL.
 When you want to queue a scoped mission at an at-risk area via MCP:
-- `jevitate mission target add <id> --url <authorized-url> [--goal ...] [--route
-  <glob> ...] --json` registers the target (unpromoted).
+- `jevitate mission target add <id> --name <name> --authorized-origin
+  <authorized-origin> --base-url <url> [--description <text>] --json`
+  registers the target (unpromoted). Note the target's own registration takes
+  NO `--goal`/`--route` — those are `queue_exploration` call arguments
+  (`target`, `goal`, `feature`, `route`, ...), supplied per-enqueue, not baked
+  into the target itself.
 - `jevitate mission target list --json` shows registered targets and their
   promoted/unpromoted state.
 - `jevitate mission target promote <id> --json` promotes it — a human-gated act,
-  same as Journey promotion. Only a promoted target is enqueueable.
+  same as Journey promotion (`jevitate journey promote <id>`). Only a promoted
+  target is enqueueable.
 
 Then `queue_exploration({ target: "<id>", ... })` (via the `jevitate mcp`
 server, registered with `jevitate mcp --print-config ...` or `jevitate init`)
 enqueues a bounded mission and returns a `missionId`.
 
-## Known gaps
+An app whose API lives on another origin declares it on the target:
+`--authorized-origin <app-origin> --api-origin <api-origin>` (repeatable; each a
+bare http(s) origin). A queued mission can reach only those origins.
 
-- The MCP inbox/command-queue tools (`queue_retrieval`, `queue_action`,
-  `get_command`, `list_incoming`, `get_thread`, `approve_action`,
-  `cancel_command`, `get_site_health`) are registered on the `jevitate mcp`
-  server but return a typed `not_implemented` error today — the wired tools are
-  `find_capabilities`, `run_journey`, `queue_exploration`, and
-  `ai_generate_text`. Scoping and running work fully through those four.
+Queued missions run when the queue is drained: `run_queued_missions` over MCP (it drains once),
+or `jevitate mission run --once --real --json` (`--watch` keeps draining).
+`get_mission_result({ id: missionId })` reports `queued`/`running` (`pending: true`), the typed
+result once done, or `failed`. `queue_exploration` only enqueues — treat the returned `missionId`
+as "accepted," not "finished," until the result says otherwise.

package/skills/jevitate-record/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevitate-record
-description: Capture a demonstrated browser flow into a Recording (`jevitate record --url`) and post-process it — diff multiple takes, review/classify fill steps (postdoc), fit a timing policy, promote a value to a variable — via the jevitate CLI. Use to record human-demonstrated takes and turn them into a parameterized, replayable artifact.
+description: Record a flow the human clicks through (`jevitate record --url`, CLI only, headed), then post-process the takes: diff them, classify values as constants, variables or hand-backs (postdoc), fit a timing policy, and promote a value to a variable (`jevitate recording ...`, MCP `recordings`). Use when the user wants to demonstrate a flow themselves. If they want jevitate to find and save the flow for them, use `explore-author-journey` (jevitate-explore).
 ---
 
 You drive Jevitate's human-driven authoring mode (RxD): capturing a take from a
@@ -13,16 +13,27 @@ headed browser demonstration a human performs — you launch it and they drive.
 - `jevitate record --url <authorized-url> [--intent "<framing>"] [--retro
   "<note>"] [--allow <origin>] [--out <dir>] --json` opens a headed browser at
   an authorized origin and records the human's demonstrated flow into a
-  `Recording` JSON file (default `~/.jevitate/recordings`). The session is
+  `Recording` JSON file (default `.jevitate/logs/<date>/` in the repo, else
+  `~/.jevitate/logs/<date>/`). The session is
   headed by design — a record session IS a live human demonstration; add
   `--headless` only when a caller explicitly asks. The target must be
-  authorized (defaults to `--url`'s own origin; widen only with explicit
-  `--allow`), and an unauthorized target is refused
-  (`E_UNAUTHORIZED_EXPLORE_TARGET`).
+  authorized (`--allow` REPLACES the default allowlist when given at all —
+  it defaults to `--url`'s own origin only when `--allow` is omitted
+  entirely; include that origin explicitly in `--allow` if you still need
+  it), and an unauthorized target is refused (`E_UNAUTHORIZED_EXPLORE_TARGET`).
+- **Ending a take**: press Enter on stdin, or send SIGINT (Ctrl-C) — both end
+  the take the SAME way (the demonstrated steps are stopped and written to
+  disk). This matters most for `--headless`, where there is no visible
+  window to interact with: Ctrl-C is the way to end a headless take, and it
+  saves the take rather than killing the process and losing it.
 - The emitted `recordingPath` is the take you then feed into the diff/postdoc
   flow below. Capture two or more takes of the same flow (varying the data each
   time) when you want `diff` to classify which values are variables.
 
+- `record` is never an MCP tool (a person does the clicking). As an agent, give the human the
+  command to run, and wait for the `recordingPath` it prints. `diff`/`fit`/`postdoc`/`promote`
+  are available over MCP as the `recordings` tool (`action`).
+
 ## Diff multiple takes
 
 - `jevitate recording diff <takeA.json> <takeB.json> [more.json...] --json` —
@@ -30,6 +41,13 @@ headed browser demonstration a human performs — you launch it and they drive.
   (constant vs. likely-variable) with a confidence score. Read the confidences;
   do not treat a low-confidence classification as settled — surface it to the
   human via `postdoc` instead of deciding for them.
+- **Input shape**: `diff`/`postdoc` accept ONLY a `jevitate record`-produced
+  take file — `{ "recording": <Recording>, "values": {...} }`. A raw
+  `Recording` (what `explore`, `explore-author-journey`, or a usability run
+  write directly — `{version, site, pages, ...}` with no `recording`/`values`
+  wrapper) is refused with a clear `E_INVALID_TAKE` message naming the
+  mismatch, not a zod dump. Wrap a raw Recording as `{ "recording": <it>,
+  "values": {} }` first if you need to diff/postdoc one.
 
 ## Review and classify (postdoc)
 

package/skills/jevitate-run-journey/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevitate-run-journey
-description: Find and run a promoted Jevitate Journey by id, with typed params, via the jevitate CLI or the find_capabilities/run_journey MCP tools. Use when a user wants to execute a known, already-recorded browser automation (a login, a checkout, a form submission) rather than explore or record a new one.
+description: Find and replay a promoted jevitate Journey (a saved, deterministic browser flow such as a login, checkout or form submission) by id with typed params, on any named environment (`--env`/`--base-url`), optionally with video and screenshots and self-heal. Runs via `jevitate journey find|run` or MCP `find_capabilities`/`run_journey`. Also covers promoting (human-only). Use when a known flow should be re-run or regression-checked, not explored or recorded fresh.
 ---
 
 You drive already-published, promoted Jevitate Journeys. You never write or invent
@@ -25,13 +25,43 @@ artifact; your job is to find the right one and run it with the right params.
   Every param the `find`/`find_capabilities` result listed under `params` is
   required; passing an unknown param key is a refusal (`E_INVALID_PARAMS`), not
   a silent ignore. An unknown id is `E_UNKNOWN_JOURNEY`.
-- MCP: `run_journey(id, params)` — same param-schema validation, same refusal on
-  an unknown id or params. It NEVER accepts inline steps or a raw recording —
-  a published id only.
+- MCP: `run_journey({ id, params, storageState? })` — same param-schema
+  validation, same refusal on an unknown id or params. It NEVER accepts inline
+  steps or a raw recording — a published id only.
 - Read the JSON envelope's `outcome` field. `"ok"` and `"healed"` (a run that
-  recovered via self-heal) are both successes; `"quarantined"` (and any other
-  value, including a secret-handback pause) means it did not complete — report
-  that honestly, do not summarize a non-success outcome as success.
+  recovered via self-heal) are both successes (exit 0); `"quarantined"` (exit 1)
+  and any other value, including a secret-handback pause, mean it did not
+  complete — report that honestly, with the step it stopped at. Exit 64 is a
+  refusal before anything ran (unknown id, bad params, a step off the allowlist).
+
+## Where it runs (`--env`) and what it records
+
+- `--env <name>` replays on a named environment from the repo's
+  `.jevitate/environments.json` (its `baseUrl` plus `allow`); `--base-url <origin>`
+  is an ad-hoc one (e.g. a preview deploy). Without either, the Journey runs on
+  the site it was recorded on. A step on an origin the environment doesn't allow
+  is refused (64) before any browser opens. MCP: `run_journey`'s `env`/`baseUrl`.
+- Evidence: `--record-video` (listed as `videoPaths`), `--screenshots
+  [screens|steps]` (`screenshotPaths` + an `index.md`), `--headed`/`--slow-mo <ms>`
+  to watch it. `--viewport 375x812` / `--device "iPhone 13"` for mobile.
+- For a narrated demo video or a step-by-step guide of a Journey, use
+  `jevitate-demo` (`journey demo`, `journey annotate`).
+
+## Authenticated Journeys (#118)
+
+- A Journey authored behind a login needs a deterministic authenticated
+  pre-step to replay: `--storage-state <file>` (a Playwright storageState JSON
+  path — cookies + origin storage) on `jevitate journey run`, `jevitate load
+  run`, and `jevitate source run`; over MCP, `run_journey`'s optional
+  `storageState` argument is the SAME thing — a file PATH on the machine
+  running the MCP server, never raw cookie/session content in the call itself.
+  The file's contents are read only by the browser session; never logged,
+  never echoed back.
+- A Journey CAN declare `metadata.requiresAuth: true` if it only reaches its
+  steps from an authenticated session. A run given no `storageState` then
+  fails fast — before any browser opens — with `E_JOURNEY_REQUIRES_AUTH`
+  naming the actual problem, instead of a confusing deep
+  `replay-target-not-found` partway through the steps.
 
 ## Self-heal (optional, additive)
 
@@ -54,19 +84,33 @@ artifact; your job is to find the right one and run it with the right params.
   result in this same session — a promoted id can be revoked; don't rely on a
   memorized id from an earlier conversation.
 
+## Promoting a Journey
+
+- `jevitate journey promote <id> --json` promotes a local Journey — a
+  deliberate human-approval gate (mirrors `mission target promote`'s
+  semantics), never automatic — run it (or MCP `promote_journey`) only when
+  the human tells you to. Every authored/recorded Journey starts
+  `metadata.promoted: false` (`explore-author-journey`, `jevitate record` +
+  `recording postdoc`); only a promoted Journey is discoverable via `journey
+  find`/`find_capabilities` and runnable via `journey run`/`run_journey`.
+  There is still no "raw Recording -> promoted Journey in one step" command —
+  a Recording becomes a Journey first (through an authoring path, or the
+  `JourneyRegistry` API), then `journey promote <id>` promotes it.
+
+## Step intent (annotations)
+
+- `journey run` reports `intent.withoutObjective` (steps with no stated objective). It is
+  informational and never a failure. Drafting and approving objectives is `journey annotate`
+  (see `jevitate-demo`); `--approve` is the human's call, like promote.
+
 ## Publishing to a distributed source
 
 - `jevitate journey publish <id> --to <source>` pushes a PROMOTED local Journey
   up to a registered distributed source (see `jevitate-sources`). It preserves
   every publish-side guard: promoted-only, secret-references-only, and
   declared-origin coverage; it writes onto a new `publish/<id>` branch and,
-  when `gh` is present, opens a PR. It never publishes an unpromoted Journey.
-
-## Known gaps
-
-- There is no single "raw Recording -> promoted Journey" command: a Recording
-  becomes a Journey through the authoring paths (`jevitate
-  explore-author-journey`, which writes an UNPROMOTED Journey a human still
-  promotes) or the `JourneyRegistry` API, and promotion stays a deliberate
-  human gate. If a user asks you to "promote this recording," recommend those
-  paths rather than guessing at a promote command — do not invent one.
+  when `gh` is present, opens a PR. When `gh` is absent, or a PR can't be
+  opened (e.g. the remote isn't GitHub), the branch is still pushed and the
+  command still reports success (`pushed: true`, no PR) with instructions to
+  open one manually — pushing the branch is never reported as a failure. It
+  never publishes an unpromoted Journey.

package/skills/jevitate-sources/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevitate-sources
-description: Manage Jevitate's distributed Journey sources — add/list/pull/update/remove git-backed sources, trust individual Journeys (content-hash-bound), run a trusted remote Journey through the run-gate, and publish a local promoted Journey up to a source — via `jevitate source ...` and `jevitate journey publish`. Use when sharing Journeys across repos or trusting/running a third-party Journey; use jevitate-run-journey for an already-local Journey.
+description: Share Journeys across repos and teams with jevitate's git-backed sources. Covers add/list/pull/update/remove (`jevitate source ...`, MCP `sources`), human-only trust of a single Journey (content-hash-bound), running a trusted remote Journey through the run-gate (`source run`), and publishing a promoted local Journey (`journey publish`, MCP `publish_journey`). Use for third-party or shared Journeys. For a Journey already in this repo, use jevitate-run-journey.
 ---
 
 You add, trust, run, and publish federated Journeys across git-backed sources.
@@ -18,6 +18,41 @@ invokable surface, not a programmatic-only capability.
   "risky"`), and `trusted` (whether this project has acknowledged that exact
   content). Trust is LOCAL and per-user; it is bound to a content hash, so any
   change to a Journey's content invalidates its trust until re-approved.
+- `riskClass` is engine-derived, not author-declared: a Journey is
+  `"read-only"` iff every step is a `navigate`/`waitFor`/`extract`/`assert`, or
+  a `click` whose target has ARIA role `link` (following a link reads a page,
+  it does not mutate anything), AND every absolute `navigate` stays within
+  `declaredOrigins`. Anything else — a non-link `click` (e.g. a button),
+  `fill`/`select`/`press`/`handback`, or a navigate that could leave
+  `declaredOrigins` — is conservatively `"risky"` and needs `source trust`
+  before it can run.
+
+- Simpler, for Journeys your own team shares: mount a Journeys repo as a git submodule under
+  `.jevitate/journeys/<name>/`. Its Journeys appear as `<name>/<id>` in `journey list`/`find`/`run`,
+  `check` and the MCP tools, and the submodule pin is reviewed like code. Use sources (below) for
+  third-party Journeys that need Terms of Use and per-Journey trust.
+
+## The source manifest shape
+
+A source repo (what `source add <name> <gitUrl>` clones) needs exactly this at
+its root, or `source add`/`source update` refuse with `E_SOURCE_INVALID_MANIFEST`:
+
+- `jevitate.json` — `{ "version": 1, "source": "<name>", "sites": [{ "origin":
+  "<https://...>", "automationPolicy": "allowed", "touBasis": "<free text>" }, ...] }`.
+  `sites` declares every origin this source's Journeys are authorized to touch
+  and the Terms-of-Use basis for each; `source add --accept-tou` acknowledges
+  ALL of them together.
+- `journeys/*.journey.json` — one file per shared Journey: an ordinary
+  `Journey` (`{ metadata, recording }`, same shape `jevitate journey list`
+  reads) PLUS a top-level `declaredOrigins: string[]` (at least one absolute
+  URL) — the origins THIS Journey is authorized to touch, which must all
+  appear in the manifest's `sites`. `jevitate journey publish` writes this
+  file for you (deriving `declaredOrigins` from the Journey's absolute
+  `navigate` steps, or from `recording.site` when its navigates are relative —
+  e.g. an `explore-author-journey`-authored Journey — or from an explicit
+  `--declare-origin`); a hand-authored source repo must match this shape
+  exactly, `.strict()` — unknown/missing keys fail the whole load, one bad
+  file at a time (never a silent partial list).
 
 ## Add and manage sources
 
@@ -42,10 +77,12 @@ invokable surface, not a programmatic-only capability.
 
 ## Run a trusted remote Journey (through the run-gate)
 
-- `jevitate source run <name> <journeyId> --param k=v ... --json` runs a
-  remote-source Journey THROUGH `@jevitate/sources`' `resolveForRun` gate. Every
-  refusal is a typed error thrown BEFORE any browser launches, each with its own
-  code so a caller knows WHY:
+- `jevitate source run <name> <journeyId> --param k=v ... [--storage-state
+  <file>] --json` runs a remote-source Journey THROUGH `@jevitate/sources`'
+  `resolveForRun` gate. `--storage-state` is the same authenticated pre-step
+  as `jevitate journey run` (see `jevitate-run-journey`), for a source Journey
+  that needs one. Every refusal is a typed error thrown BEFORE any browser
+  launches, each with its own code so a caller knows WHY:
   - `E_SOURCE_RUN_HASH_MISMATCH` — the pinned content no longer matches what was
     trusted.
   - `E_SOURCE_RUN_UNTRUSTED` — a `risky` Journey that was never trusted.
@@ -63,10 +100,16 @@ invokable surface, not a programmatic-only capability.
 - `jevitate journey publish <id> --to <source> [--declare-origin <origin> ...]
   [--as <newId>] --json` pushes a PROMOTED local Journey up to a registered
   source. It preserves every publish-side guard (promoted-only,
-  secret-references-only, declared-origin coverage), writes onto a new
-  `publish/<id>` branch, and opens a PR when `gh` is present (degrading to
-  printed instructions when it is not). It refuses an unpromoted Journey
-  (`E_JOURNEY_PUBLISH_NOT_PROMOTED`) and an embedded secret
+  secret-references-only, declared-origin coverage — derived from the
+  Journey's absolute `navigate` steps, or from `recording.site` when they are
+  relative), writes onto a new `publish/<id>` branch, and opens a PR when `gh`
+  is present. The branch push is reported as `pushed: true` regardless of
+  whether a PR could be opened: when `gh` is absent, OR `gh` is present but
+  `gh pr create` fails (e.g. the remote isn't GitHub), the result still comes
+  back `ok: true` with `pushed: true` and no `prUrl`, plus printed
+  instructions to open the PR manually — the push already happened by that
+  point, so a PR failure is never reported as a publish failure. It refuses an
+  unpromoted Journey (`E_JOURNEY_PUBLISH_NOT_PROMOTED`) and an embedded secret
   (`E_JOURNEY_PUBLISH_SECRET`).
 
 ## What you must never do
@@ -80,9 +123,9 @@ invokable surface, not a programmatic-only capability.
 - Never widen a Journey's declared origins on publish beyond what the human
   authorized just to make coverage pass.
 
-## Known gaps
+## MCP
 
-- There is no MCP-tool surface over federated sources yet — the
-  `find_capabilities`/`run_journey` MCP tools operate over the LOCAL promoted
-  store, not remote sources. Federated add/trust/run/publish are CLI-only today;
-  drive the `jevitate source ...` commands directly.
+- The `sources` tool takes `add`/`list`/`pull`/`update`/`remove`/`run` as its `action` (the same
+  gate and refusals as the CLI), and `publish_journey` mirrors `journey publish`. Accepting a
+  source's Terms of Use (`source add --accept-tou`) and `source trust` are CLI-only on purpose:
+  they are the human's consent, so tell the human the command instead of looking for a tool.

package/skills/jevitate-ux-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: jevitate-ux-review
-description: Produce ranked, cited, advisory usability findings for a flow — offline over a saved Recording (`jevitate ux <recording> --app-class`) or live over an authorized target (`jevitate explore --strategy usability --goal --app-class`). Use when a human wants a UX/usability critique of a journey, not a pass/fail functional test. Findings are advisory and never gate a run.
+description: Produce ranked, cited, advisory usability findings (preview) for a flow — offline over a saved Recording (`jevitate ux <recording> --app-class`, MCP `ux_review`) or live on an authorized target (`jevitate explore --strategy usability --goal --app-class`, MCP `run_exploration`). Use when the user wants a UX or usability critique, not a pass/fail test. Findings are advisory and never gate a run.
 ---
 
 You produce a UX review: ranked, cited, evidence-anchored usability findings for
@@ -9,22 +9,40 @@ fails a run or a build. Every finding is calibrated to an app class (a consumer
 signup and an internal admin tool are held to different bars) and cites a rubric
 item; the platform structurally cannot emit an uncited finding.
 
+PREVIEW (0.2.0): these findings are a preview feature. The independent quality
+grader is not yet calibrated across apps, and how findings are grouped/deduped
+is still being redesigned (issues #133, #198). `report.preview` is `true` and
+`report.headline` says so; tell the human this is a preview, not a finished
+verdict.
+
 ## Two modes — pick by what you have
 
 - OFFLINE, over a saved Recording — `jevitate ux <recording.json> --app-class
-  <class> [--persona <p>] [--job "<text>"] [--out <dir>] --json`. Analyzes a
+  <class> [--persona <p>] [--job "<text>"] [--out <dir>] [--min-confidence <n>]
+  [--show <labels>] --real --json`. Analyzes a
   Recording you already captured (e.g. from `jevitate-record` or a successful
   `jevitate explore`). It launches no browser. `--app-class` is REQUIRED
-  (e.g. `consumer`, `admin`, `internal`); `--job` sharpens relevance.
+  (e.g. `consumer`, `admin`, `internal`); `--job` sharpens relevance. It reads
+  the artifacts next to `<stem>.recording.json` automatically: the live
+  usability run's evidence sidecar `<stem>.evidence.json` (the screens as
+  analyzed plus the run signals), `<stem>.result.json` or
+  `<stem>.transcript.json`, and `<stem>.screens/`. With the sidecar, offline
+  review reproduces the live run's findings. Without it, `report.evidenceCaveats`
+  names what could not be checked. `--evidence` and `--result` override the
+  discovered files.
 - LIVE, against an authorized target — `jevitate explore --strategy usability
   --url <authorized-url> --goal "<the job>" --app-class <class> [--allow
-  <origin>] [--secret <value>] [--max-actions <n>] --real --json`. Drives the
+  <origin>] [--secret <value>] [--max-actions <n>] [--min-confidence <n>]
+  [--show <labels>] --real --json`. Drives the
   exploration loop toward the job (Jev makes the browsing decisions, not you)
   and reviews each observed screen against the rubric as it goes. Needs a
   gateway: `--real` (live, after `jevitate ai setup`) or `--fake-ai` (a
   deterministic pipeline smoke that will NOT produce a real review). No
   selection fails closed.
 
+Over MCP: `ux_review` is the offline mode (`recording`, `appClass`, …); `run_exploration`
+with `strategy: "usability"` is the live mode. Usability is not a queueable mission strategy.
+
 Prefer OFFLINE when a Recording already exists — it is cheaper, deterministic,
 and touches no live site. Use LIVE only when there is no Recording and the human
 authorized the target.
@@ -43,21 +61,93 @@ authorized the target.
   authorized. Pass real secrets/PII via `--secret` so they stay out of every
   model call.
 
+## Filtering what is shown
+
+- `--min-confidence <0..1>` (also `JEVITATE_UX_MIN_CONFIDENCE`, or `ux.minConfidence` in
+  `~/.jevitate/config.json`; default 0.3): findings below it are suppressed.
+- `--show <labels>` (also `JEVITATE_UX_SHOW`, or `ux.show` in the config): an
+  opt-in filter on the quality grade. The grades are `actionable`,
+  `relevant-minor`, `generic` and `wrong`. The default shows ALL grades. The
+  grader is not calibrated (no held-out, multi-rater kappa ≥ 0.4 off its tuning
+  app), so it labels findings and does not hide them. Each finding carries its
+  grade in `quality`, and `report.qualityFiltered` says whether a filter was
+  applied. `--show actionable,relevant-minor` restores the old filter.
+- `--max-findings-per-page <n>` (also `JEVITATE_UX_MAX_FINDINGS_PER_PAGE`, or
+  `ux.maxFindingsPerPage` in the config; default 5): caps findings per route,
+  highest-confidence first (0.2.0, issue #198 interim — a full redesign is
+  tracked there). The rest are counted in `report.suppressed` as
+  `per-page-cap`, never dropped silently.
+- Nothing is dropped silently: every suppressed candidate is counted in
+  `report.suppressed`. Change a filter only when the human asks, and say which
+  filter you changed.
+
 ## Reading the result
 
-- The report is a set of findings, each with a `severity` (`info` | `minor` |
-  `major`), a rubric `citation` (`source` + `ref`), and redacted evidence refs
-  pointing at the screen/control it is about. Rank your summary by severity and
-  lead with the `major` findings.
-- Report findings as ADVISORY recommendations, with their citations — never as
-  defects that block shipping, and never restate a finding without the rubric
-  citation the tool attached (the citation is what makes it more than an
-  opinion).
+- Lead with `report.headline`. It gives the findings grounded in observed run
+  behavior, the heuristic-only count in the appendix, and "N suppressed (by
+  rubric item: …)".
+- `report.findings` holds only findings with behavioral evidence:
+  - run signals (tier `signal`): a hung request, a stuck job still offered
+    again, a duplicate write or create, a failed submit with no or only generic
+    error copy, a repeated assistant reply, an inert control, an internal id,
+    or a URL whose page shows another route's content. Each cites its steps,
+    requests, text and screenshot in `signal`.
+  - rubric findings grounded in the friction the run hit on that screen: a
+    backtrack, a retry, a dead end, a long wait, an error, an abandoned field,
+    or the goal not reached. `journeyEvidence` gives the kind and step range.
+  - Their `severity` and `impact` come from the observed impact on the job:
+    `blocked` > `slowed` > `confused`. Findings on the same friction point are
+    collapsed into one, with the others listed in `contributing`.
+- `report.heuristicAppendix` holds rubric findings with no observed friction.
+  They are screen-level heuristics only, capped at `info`. Mention them as an
+  appendix, never as the review's findings.
+- Each finding is specific and grounded:
+  - `observation`: what is wrong, naming the control, label or text, relative to
+    the job.
+  - `userImpact`: what it costs the user.
+  - `recommendation`: a concrete change to that control or text.
+  - `controls` and `quotes`: the implicated controls and verbatim on-screen text.
+    Independent code checked that both exist on the screen.
+  - `evidenceRefs`: only those controls, not every control on the page.
+  - `route`, `screenId`, `occurrences` and `screenIds`: where it was seen. The
+    same item on the same route and controls is one finding with a count.
+  - `severity` (`info` | `minor` | `major`) and a rubric `citation` (`source` +
+    `ref`).
+  - `quality`: the independent grader's label and its confidence.
+  - `confidence` with its `confidenceBasis`: violation × applicability ×
+    grounding × agreement. Quote the observation and recommendation; don't
+    paraphrase them into generic heuristic advice.
+  - `contributing` (0.2.0, issue #198 interim): DIFFERENT rubric items that
+    fired on the SAME control on the SAME route are collapsed into one
+    finding — the highest-confidence one leads, the rest are listed here with
+    their own `rubricItemId`, `citation`, `observation` and `occurrences`. Read
+    it as "these principles all flagged the same thing", not as noise to
+    ignore — mention the other principles when it matters.
+- Rank your summary the way the report does: by `impact`, then severity. Lead
+  with what blocked the job.
+- `report.suppressed` counts what was not shown: `byReason`, `byRubricItem` and
+  `byRubricItemRoute`. The reasons are:
+  - `ungrounded`: named no control or text.
+  - `rejected-evidence`: cited a control or text that is not on the screen.
+  - `not-confirmed`: the specifics step found no concrete violation.
+  - `below-min-confidence`
+  - `quality-policy`: a grade outside an explicit `--show` filter.
+  - `per-page-cap` (0.2.0, issue #198 interim): the route already has
+    `--max-findings-per-page` findings shown; this one ranked lower.
+  Say how many were suppressed. `clean: true` only happens with zero findings
+  AND zero suppressed, so never describe a report with suppressions as "no
+  issues".
+- `coverage.notApplicable` lists items whose rubric precondition did not hold,
+  for example choice overload on a 2-control screen. Those items are evaluated,
+  not skipped.
+- Report findings as ADVISORY recommendations, with their citations. They are
+  never defects that block shipping. Never restate a finding without the rubric
+  citation the tool attached; the citation is what makes it more than an opinion.
 - An analysis that FAILED (`E_UX_ANALYSIS`) is a real failure to surface
-  honestly — never fabricate a clean "no issues found" report from a failed run.
-  Offline review over a bare Recording is coverage-limited (it sees only what
-  the Recording captured — no live a11y tree, no runtime contrast); say so when
-  the Recording is thin, rather than implying the flow is fully vetted.
+  honestly. Never fabricate a clean "no issues found" report from a failed run.
+  Offline review over a bare Recording is coverage-limited: it sees only what
+  the Recording captured, with no live a11y tree and no runtime contrast. When
+  the Recording is thin, say so rather than implying the flow is fully vetted.
 
 ## What you must never do