@jevitate/cli 0.1.0

package/skills/jevitate-record/SKILL.md

@@ -0,0 +1,78 @@
+---
+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.
+---
+
+You drive Jevitate's human-driven authoring mode (RxD): capturing a take from a
+live demonstration, then post-processing one or more takes into a clean,
+parameterized `Recording` a Journey can be built from. Capture is a live,
+headed browser demonstration a human performs — you launch it and they drive.
+
+## Capture a take (live demonstration)
+
+- `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
+  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`).
+- 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.
+
+## Diff multiple takes
+
+- `jevitate recording diff <takeA.json> <takeB.json> [more.json...] --json` —
+  compares fill/select steps across takes and classifies each varying value
+  (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.
+
+## Review and classify (postdoc)
+
+- `jevitate recording postdoc <take1.json> [more.json...] --decisions <decisions.json> --out <result.json> --json`
+  applies a `PostdocDecision[]` (one decision per varying fill/select step:
+  `classify: "constant" | "variable" | "handback"`, with a `name` for
+  `"variable"` or a `prompt` for `"handback"`) non-interactively. Build the
+  decisions file yourself from the `diff` output and the user's stated intent
+  (e.g. "the quantity should be a variable, everything else is fixed") — do not
+  ask the human to run the interactive prompt flow when you already know the
+  answer from context.
+- Without `--decisions`, `postdoc` is interactive (prompts a human at the
+  terminal) — only omit `--decisions` when you are explicitly handing control
+  to a human, not when driving autonomously.
+
+## Fit a timing policy
+
+- `jevitate recording fit <recording.json> --json` derives a `SitePolicy`
+  (interaction timing) from a recording's captured pacing. Hand the result to
+  `jevitate site policy set <site> --file <policy.json>` if the user wants it
+  applied.
+
+## Promote a value to a variable directly (single-take shortcut)
+
+- `jevitate recording promote <file.json> --page <n> --step <n> --var <name>` —
+  for the simple case of a single take with one known value to parameterize,
+  skipping the full diff/postdoc review flow.
+
+## Publishing the result
+
+- The output of `postdoc`/`promote` is a `Recording` JSON file — one authoring
+  artifact short of a runnable Journey. Two autonomous authoring paths write a
+  Journey directly from a goal-based exploration: `jevitate
+  explore-author-journey` (see `jevitate-explore`) emits an UNPROMOTED,
+  parameterized Journey a human must still promote. To share a promoted local
+  Journey to a distributed source, use `jevitate journey publish <id> --to
+  <source>` (see `jevitate-sources`).
+
+## Known gaps
+
+- There is no single-command "postdoc result -> promoted local Journey" verb: a
+  `Recording` produced here still becomes a Journey through the authoring paths
+  above (`explore-author-journey`) or the `JourneyRegistry` API, and promotion
+  stays a deliberate human gate. `jevitate explore-author-journey` is a
+  separate, Jev-driving authoring path (not human capture) that may be what a
+  user who wants a Journey "recorded for them" actually needs.

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

@@ -0,0 +1,72 @@
+---
+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.
+---
+
+You drive already-published, promoted Jevitate Journeys. You never write or invent
+automation steps yourself — a Journey is a deterministic, pre-recorded, reviewed
+artifact; your job is to find the right one and run it with the right params.
+
+## Discover
+
+- CLI: `jevitate journey find "<query>" --json` — searches promoted Journeys by
+  name/description. Returns `{ id, name, description, params }[]`.
+- MCP: `find_capabilities(query)` returns the same shape. Prefer this when you are
+  already inside an MCP-connected session — it is scoped to the same
+  promoted-only allowlist.
+- `jevitate journey list --json` shows ALL Journeys including unpromoted ones —
+  use this only for authoring/debugging with a human present, never to find
+  something to run autonomously (an unpromoted Journey is unpromoted for a
+  reason and `journey run`/`run_journey` will refuse it anyway).
+
+## Run
+
+- CLI: `jevitate journey run <id> --param key=value --param key2=value2 --json`.
+  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.
+- 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.
+
+## Self-heal (optional, additive)
+
+- `jevitate journey run <id> --self-heal <fail-closed|hybrid|full>` opts a run
+  into scoped self-healing when a selector drifts. The default `fail-closed`
+  preserves the plain, unhealed behavior. `hybrid`/`full` need an AI gateway
+  (`--real` after `jevitate ai setup`, or `--fake-ai` for a pipeline smoke);
+  requesting a heal mode without one fails closed rather than running unhealed.
+- A write/irreversible step NEVER auto-heals in any mode — that floor is
+  enforced by the runtime, not something you can override from a flag.
+
+## What you must never do
+
+- Never pass inline steps, a raw URL, or a selector anywhere in this flow — you
+  only ever pass an `id` that came from `find`/`find_capabilities`.
+- Never guess a param value that looks like a secret (a password, an API key) —
+  if a Journey's params include something secret-shaped, tell the user it needs
+  to be supplied by them or via the configured secret manager, never invent one.
+- Never try to run an id you have not first seen in a `find`/`find_capabilities`
+  result in this same session — a promoted id can be revoked; don't rely on a
+  memorized id from an earlier conversation.
+
+## 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.

package/skills/jevitate-sources/SKILL.md

@@ -0,0 +1,88 @@
+---
+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.
+---
+
+You add, trust, run, and publish federated Journeys across git-backed sources.
+`@jevitate/sources` (git-backed remote sources, a local source,
+trust/acknowledgement tracking, a lockfile pinning each source at a commit, a
+publish flow, and a risk-classifying run-gate) is fully wired to the
+`jevitate source ...` and `jevitate journey publish` commands — this is a real,
+invokable surface, not a programmatic-only capability.
+
+## The model
+
+- A `JourneySource` (local or remote/git) exposes a promoted-only
+  `list()`/`find()` just like a local `JourneyRegistry`. Each result carries a
+  `source`, an optional `pin` (a locked commit), a `riskClass` (`"read-only" |
+  "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.
+
+## Add and manage sources
+
+- `jevitate source add <name> <gitUrl> [--accept-tou] --json` clones and pins a
+  source at its current commit and prints its declared Terms of Use per origin.
+  A source's Journeys cannot RUN until its ToU is acknowledged — pass
+  `--accept-tou` (an explicit human act) to acknowledge at add time, or re-run
+  later. `add` never trusts any Journey implicitly.
+- `jevitate source list --json` — registered sources, their pinned commit, and
+  the set of trusted Journey ids.
+- `jevitate source pull <name> --json` fetches without moving the pin;
+  `jevitate source update <name> --json` advances the pin to the fetched head.
+- `jevitate source remove <name> --json` — deregister a source.
+
+## Trust an individual Journey
+
+- `jevitate source trust <name> <journeyId> --json` explicitly trusts ONE
+  Journey in a source, bound to its current content hash. This is the gate a
+  `risky`-classified Journey must pass before it can run. Trust never comes from
+  `add`/`pull`/`update` — only from this explicit act, and it emits only the
+  address + bound hash, never the Journey's content.
+
+## 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:
+  - `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.
+  - `E_SOURCE_RUN_ORIGIN` — a navigate target outside the Journey's declared
+    origins.
+  - `E_SOURCE_RUN_TOU` — the source's Terms of Use were never acknowledged.
+  - `E_SOURCE_RUN_SECRET` — an embedded secret (Journeys carry secret
+    references, never values).
+- `source run` is the REMOTE trust boundary; `jevitate journey run` stays the
+  LOCAL `FsJourneyStore` path. Keep them separate — a remote run never bypasses
+  the gate.
+
+## Publish a local Journey up to a source
+
+- `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
+  (`E_JOURNEY_PUBLISH_SECRET`).
+
+## What you must never do
+
+- Never acknowledge a source's ToU (`--accept-tou`) or trust a Journey
+  (`source trust`) on the user's behalf without their explicit say-so — both are
+  human-consent gates, not conveniences to auto-satisfy.
+- Never treat an untrusted or `risky`-classified federated Journey as safe to
+  run — the run-gate exists precisely to stop that, and a refusal is the correct
+  outcome to surface, not an obstacle to work around.
+- Never widen a Journey's declared origins on publish beyond what the human
+  authorized just to make coverage pass.
+
+## Known gaps
+
+- 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.

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

@@ -0,0 +1,68 @@
+---
+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.
+---
+
+You produce a UX review: ranked, cited, evidence-anchored usability findings for
+a flow. This is advisory analysis, not a functional gate — a UX finding never
+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.
+
+## 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
+  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.
+- 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
+  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.
+
+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.
+
+## Choosing inputs
+
+- `--app-class` is the single most important calibration input — state the real
+  class of the app under review; do not default to `consumer` to be lenient or
+  `internal` to be harsh. If you don't know it, ask.
+- For the live mode, write `--goal` as the JOB the user is trying to accomplish
+  in plain language ("sign up and reach the dashboard"), the same as a goal-based
+  exploration — the review is calibrated against how well the flow serves that
+  job.
+- Live mode is authoring/test-plane only and refuses an unauthorized target
+  (`E_UNAUTHORIZED_EXPLORE_TARGET`). Never widen `--allow` beyond what the human
+  authorized. Pass real secrets/PII via `--secret` so they stay out of every
+  model call.
+
+## 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).
+- 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.
+
+## What you must never do
+
+- Never present UX findings as pass/fail gates — they are advisory by design.
+- Never emit or paraphrase a finding without its rubric citation.
+- Never run the live mode against a production or unauthorized target — UX review
+  is authoring/test-plane only.
+- Never fabricate a clean report from a failed or empty analysis.