wicked-crew-api-types 0.25.0 → 0.28.0

package/index.d.ts

@@ -1156,8 +1156,15 @@ export interface ConformanceRule {
   excludes?: string[];
   /** Ordering within a severity band + gate priority. Engine default: 1.0. */
   weight?: number;
-  /** Enforcement half (from the retired policy model). Absent ⇒ the rule is recall-only. */
-  effect?: 'deny' | 'allow_with_conditions' | 'allow';
+  /**
+   * Enforcement half (from the retired policy model). Absent ⇒ the rule is RECALL-ONLY: it is
+   * surfaced to workers but never enters decide()/select(), so it can neither block a gate nor
+   * `catch` an eval sample — which is why a store of effect-less rules evals to "every bad
+   * sample is a gap" (api-types 0.27.0, the #394/#395 companion). `deny` blocks (the only effect
+   * the evals credit as a catch); `warn` surfaces without blocking (the operator-authorable
+   * middle band); `allow_with_conditions` permits with obligations; `allow` permits outright.
+   */
+  effect?: 'deny' | 'warn' | 'allow_with_conditions' | 'allow';
   trigger?: { contains?: string };
   obligations?: string[];
   /** The frozen acceptance-criteria text (becomes a claim's `criteria` when the rule decides a gate). */
@@ -1319,6 +1326,371 @@ export interface SteeringLandingResult {
   error?: string;
 }
 
+// ── Skills — the daemon-owned garden plugin root, published as immutable snapshots (api-types 0.28.0) ──
+//
+// Skills are files (skills keystone, design v3 + amendments v3.1/v3.2). The daemon owns ONE
+// effective `wicked-garden`-shaped plugin root — `<state home>/skills/effective/`, the dependency
+// closure of the installed plugin: `.claude-plugin/{plugin.json,archetypes.json,components.json}`,
+// `skills/**` (nested layout verbatim), `scripts/**` minus CI + dev tools, `schemas/`,
+// `docs/examples/`, `pyproject.toml`, `uv.lock` — seeded from the LIVE installed plugin into a
+// content-addressed `baseline/<contentHash>/`. The operator edits files in place, replaces a
+// skill, adds one, disables one (manifest state — the files stay), resets one (content from the
+// baseline; never enablement). Nothing a worker runs is read from `effective/`: PUBLISHING
+// validates the whole tree and writes an IMMUTABLE, read-only `snapshots/<gen>/` (enabled skills
+// only, closure included, `snapshot.json`, and the generated delivery views —
+// `views/copilot/.github/skills/<name>/` holding the enabled PORTABLE skills, part of the content
+// hash), then flips `current -> snapshots/<gen>`; the engine receives the resolved snapshot path
+// as `WICKED_SKILLS_SNAPSHOT`. The daemon NEVER writes into the user's own CLI directories
+// (`~/.codex`, `~/.pi`, `~/.copilot`, `~/.config/opencode`, `~/.claude`): skills reach non-Claude
+// workers only through per-launch, wicked-owned delivery core performs from the snapshot (v3.2) —
+// a CLI without a lever (codex today) runs without wicked skills, and a unit on such a seat that
+// requires one is REFUSED at launch (no proceed-with-disclosure setting exists).
+// `/skills` is a file manager whose EVERY mutation is CAS-guarded (`expectedRevision`) and
+// answers 2xx `{verdict, findings[], revision}` — a `blocked` verdict is a normal response,
+// including a publish refused because one is in flight (`publish-in-flight`) or aborted because the
+// root changed under it (`root-changed`), neither of which wrote anything. 409 (`{error, revision}`)
+// is EXCLUSIVELY a stale `expectedRevision` (a CAS conflict).
+
+/** What a skill IS, from its frontmatter — fork-first: `context: fork` → fork worker (a subagent
+ *  body); else `user-invocable: true` → router (an operator-facing entry point); else module (a
+ *  nested reference skill routers/workers pull in). */
+export type SkillKind = 'router' | 'fork-worker' | 'module';
+
+/** `shipped` = every own file byte-identical to the baseline; `override` = a shipped skill with
+ *  edited/replaced files; `user-added` = no baseline (added through the API, or upstream dropped
+ *  it while the operator's edits were kept). */
+export type SkillProvenance = 'shipped' | 'override' | 'user-added';
+
+/** Where a baseline was captured from. `claude-plugin-cache` covers the marketplace cache AND the
+ *  hand-installed `plugins/wicked-garden` copy (both are "the installed plugin"); `checkout` is a
+ *  git working tree; `directory` any other explicit plugin-shaped directory. */
+export type SkillSourceKind = 'claude-plugin-cache' | 'checkout' | 'directory';
+
+/** The per-baseline `uv sync` state (`<baseline>/.venv`, provisioned once per content hash — the
+ *  publish that needs it AWAITS it — and shared read-only by every snapshot that links it):
+ *  `pending` until a successful publish records it, `synced` on success (the snapshot carries a
+ *  `.venv` link), `skipped` when the bundle carries no `pyproject.toml` (nothing to provision; no
+ *  link). `failed` (uv missing or a sync error) is BLOCKING for the publish (`venv-failed`) and is
+ *  therefore never the recorded state of a published baseline — the record keeps its previous
+ *  value; a later publish retries. */
+export type SkillVenvState = 'pending' | 'synced' | 'failed' | 'skipped';
+
+/** One captured baseline — keyed in `SkillManifest.baselines` by the content hash of its bundle
+ *  (sorted relative paths + sha256 digests), never by the version string alone: two installs of
+ *  "12.32.0" with different bytes are two baselines. */
+export interface SkillBaselineRecord {
+  /** `version` from the source's `.claude-plugin/plugin.json`. */
+  plugin_version: string;
+  source: { kind: SkillSourceKind; path: string };
+  /** HEAD sha for a `checkout` source; `null` otherwise (or when git could not answer). */
+  git_sha: string | null;
+  /** ISO-8601 instant the baseline was captured. */
+  captured_at: string;
+  venv: SkillVenvState;
+}
+
+export interface SkillEntry {
+  /** Plugin-relative directory, nested layout preserved (`skills/engineering/frontend`). Never
+   *  renamed — sibling `../` links depend on it. */
+  dir: string;
+  kind: SkillKind;
+  /** Core-by-reference: in the registered-reference closure — a `skill_ref` of a workflow the
+   *  daemon knows (core drop-ins, crew-generated, user-registered) or a skill one of those names in
+   *  its SKILL.md (repo-learn → search, mem). Disabling or renaming it is blocking. */
+  core: boolean;
+  /** `false` when the skill's files resolve `${CLAUDE_PLUGIN_ROOT}`, invoke a script relative to
+   *  the cwd (`python3 -u scripts/x.py`, `./scripts/x`, …), or link `../` — Claude-only by nature:
+   *  excluded from the snapshot's `views/copilot/` and from the per-launch skill lists core builds
+   *  for the other CLIs. `portable` is the admission key for every non-Claude view (design v3.2). */
+  portable: boolean;
+  /** Manifest state, orthogonal to content: a disabled skill's files stay in `effective/` and are
+   *  excluded from the next published snapshot. Reset never flips it. */
+  enabled: boolean;
+  provenance: SkillProvenance;
+  /** ISO-8601 instant of the last edit/replace/add through the API; `null` when untouched. */
+  editedAt: string | null;
+  /** A refreshed baseline changed a file this skill overrides — the new side is readable as
+   *  `?side=baseline` for diffing; the operator's content is kept. */
+  upgradeAvailable: boolean;
+  /** `upgradeAvailable`, or the last refresh found a name collision (upstream now ships a skill
+   *  under this user-added name at another dir). Cleared by reset / a later refresh. */
+  conflict: boolean;
+  /** The held-back UPSTREAM skill's directory in the current baseline when the last refresh found a
+   *  name collision (upstream ships this name at another dir than the operator's skill); `null`
+   *  otherwise. `GET /skills/:name/files/*path?side=baseline` reads THIS directory for such a skill,
+   *  so the two sides of the collision are comparable — the answer's `path` names the file actually
+   *  read (api-types 0.28.0). Re-derived by every refresh. */
+  upstreamDir: string | null;
+}
+
+/** One managed file (plugin-relative path → hashes). `baselineHash` `null` = user-added file;
+ *  `effectiveHash` `null` = a baseline file absent from `effective/` (removed by a direct
+ *  filesystem edit — reset restores it; the skill reads `override` until then). */
+export interface SkillFileRecord {
+  baselineHash: string | null;
+  effectiveHash: string | null;
+  /** The hash this file had in the most recent published snapshot; `null` = never published. */
+  lastPublishedHash: string | null;
+  /** The last refresh saw BOTH sides change (kept the effective side). */
+  conflict: boolean;
+}
+
+/** The most recent publish. */
+export interface SkillPublishedRecord {
+  gen: number;
+  /** Hash over the snapshot's files (sorted relative paths + sha256 digests), `snapshot.json` excluded. */
+  contentHash: string;
+  /** ISO-8601 instant. */
+  at: string;
+  /** sha256 of the exact `snapshot.json` bytes publish wrote. `snapshot.json` is excluded from the
+   *  content hash, so the crew-owned manifest AUTHENTICATES it: `current` verifies only the
+   *  generation this record names, with metadata hashing to this value (api-types 0.28.0). */
+  snapshotHash: string;
+}
+
+/** `<skills root>/manifest.json` — the state of the daemon-owned root. (The v3 mirror ledger is
+ *  withdrawn with the mirror — design v3.2 §1: the daemon never writes into the user's CLI dirs.) */
+export interface SkillManifest {
+  version: 2;
+  /** Monotonic; bumped by EVERY mutation. Every mutating request carries it as `expectedRevision`. */
+  revision: number;
+  /** Content hash of the current baseline (`baseline/<hash>/`). */
+  baseline: string;
+  baselines: Record<string, SkillBaselineRecord>;
+  /** Keyed by frontmatter `name` (`wicked-garden-<dir segments joined by '-'>`). */
+  skills: Record<string, SkillEntry>;
+  /** Every managed file under `effective/`, plugin-relative. */
+  files: Record<string, SkillFileRecord>;
+  published: SkillPublishedRecord | null;
+}
+
+/** `GET /skills` 200 body. 503 when the root is not seeded (no installed plugin was found) or when
+ *  `current` exists but fails verification (realpath outside `snapshots/`, malformed
+ *  `snapshot.json`, content hash mismatch) — a corrupt root is a loud error, never an empty catalog. */
+export interface SkillsManifestResponse {
+  manifest: SkillManifest;
+  revision: number;
+  /** The resolved skills root on the daemon host (`<state home>/skills` by default). */
+  root: string;
+  /** The VERIFIED published snapshot `current` resolves to, or `null` before the first publish.
+   *  `path` is the absolute REAL path of `snapshots/<gen>` — byte-identical to the one input the
+   *  engine is handed (`WICKED_SKILLS_SNAPSHOT`; design v3.1 §2). */
+  current: { gen: number; path: string } | null;
+}
+
+export interface SkillFileEntry {
+  /** POSIX path relative to the skill dir. */
+  path: string;
+  size: number;
+  sha256: string;
+  /** This file's manifest record (`null` for a file present on disk but not yet recorded). */
+  record: SkillFileRecord | null;
+}
+
+/** `GET /skills/:name/files` 200 body — the skill's OWN files (a nested skill's files are its own). */
+export interface SkillFileTree {
+  name: string;
+  dir: string;
+  enabled: boolean;
+  files: SkillFileEntry[];
+}
+
+/** `GET /skills/:name/files/*path` and `GET /skills/support/*path` 200 body — a typed, capped read.
+ *  Save is disabled on `truncated` or `binary`. `?side=baseline` reads the baseline copy instead
+ *  (the "new side" of a refresh conflict). */
+export interface SkillReadResult {
+  /** Plugin-relative path served. */
+  path: string;
+  /** UTF-8 text — the first 512 KB when `truncated`; `null` when `binary` (there is no text to show). */
+  content: string | null;
+  /** The file's FULL size in bytes. */
+  size: number;
+  truncated: boolean;
+  binary: boolean;
+}
+
+export type SkillFindingKind =
+  | 'name-invalid'
+  | 'name-collision'
+  | 'name-mismatch'
+  | 'frontmatter-invalid'
+  | 'missing-skill-md'
+  | 'unregistered-skill'
+  | 'nested-skill-create'
+  | 'core-disable'
+  | 'core-rename'
+  | 'core-missing'
+  | 'support-file-edit'
+  | 'non-portable'
+  /** A `${CLAUDE_PLUGIN_ROOT}/<p>` or `../<p>` reference in an enabled skill's files that does not
+   *  resolve inside the would-be snapshot. Severity follows the TARGET (design v3.4 §1): a reference
+   *  that ESCAPES the plugin root (`..` climbing out — it reaches whatever lies beside the snapshot on
+   *  the worker host) is `blocking`; one whose target is MISSING (it normalizes inside the root but
+   *  the snapshot does not carry it — a file the bundle omits, or a skill that is disabled) is a
+   *  `warning`: a content bug the skill's author owns, published as found — a publish with only
+   *  warnings answers `verdict: 'warnings'` with the findings AND a written snapshot (api-types
+   *  0.28.0). */
+  | 'unresolved-ref'
+  /** A path the store refuses BY NAME rather than reads through: a shape that could leave its root
+   *  (`..`, an absolute piece), a component that crosses a symlink, or — under `effective/`, where
+   *  every entry is classified — a symlink or a special node (socket, fifo, device) anywhere,
+   *  the contents of a pruned directory (`.venv`, `node_modules`, `__pycache__`) INCLUDED: such a
+   *  directory is never copied or hashed, but what it holds is still judged, and a link inside one
+   *  blocks with the reason (a provisioned environment lives under `baseline/`, not the editable
+   *  root). Blocking; `file` names the entry, `skill` its owning skill when it has one. */
+  | 'path-invalid'
+  | 'unknown-skill'
+  | 'no-baseline'
+  | 'fs-drift'
+  | 'refresh-conflict'
+  | 'empty-snapshot'
+  /** `.claude-plugin/plugin.json`, `archetypes.json` or `components.json` is absent from `effective/`
+   *  — the plugin manifest + the runtime catalogs are REQUIRED snapshot members (blocking at
+   *  publish; api-types 0.28.0). */
+  | 'missing-plugin-manifest'
+  /** The plugin manifest or a runtime catalog is present but not what its reader expects — does
+   *  not parse as JSON, is not a JSON object, or `archetypes.json` lacks its `archetypes`
+   *  collection (blocking at publish; api-types 0.28.0). A manifest without `name` is
+   *  `name-mismatch`. */
+  | 'catalog-invalid'
+  /** The baseline's shared read-only Python env could not be provisioned (uv missing, `uv sync`
+   *  failed, or the env could not be locked) while the bundle carries a `pyproject.toml` — the env
+   *  is REQUIRED, so the publish is blocked and nothing (the provisioning state included) is
+   *  persisted (api-types 0.28.0). */
+  | 'venv-failed'
+  /** A publish was refused because one is already running (one at a time) — nothing was written, so
+   *  it is a 2xx `blocked` envelope, not a 409 (409 is only a stale `expectedRevision`; api-types
+   *  0.28.0). Re-read `GET /skills` and retry against the revision it answers. */
+  | 'publish-in-flight'
+  /** A publish was aborted because the skills root changed under it — nothing was written to either
+   *  root; a 2xx `blocked` envelope (api-types 0.28.0). Re-read `GET /skills` and retry. */
+  | 'root-changed'
+  /** A path outside the bundle closure — the ONE allowlist of what the seed copies, what the support
+   *  API may address, and what a snapshot may carry: the five runtime catalogs under `.claude-plugin`
+   *  BY NAME (`plugin.json`, `archetypes.json`, `components.json`, `specialist.json`,
+   *  `stack-registry.json` — `marketplace.json`, a publish-time listing, is outside), everything under
+   *  `skills`, `schemas` and `docs/examples`, everything under `scripts` except the `ci` and `wg`
+   *  directories and any `wg-`-prefixed dev tooling, plus `pyproject.toml` and `uv.lock`. A support
+   *  add/PUT there is a 2xx `blocked` envelope (nothing written); a file found there under
+   *  `effective/` at publish/analyze (a direct filesystem edit) is a BLOCKING finding naming the path
+   *  — a snapshot never ships it (api-types 0.28.0). */
+  | 'outside-closure'
+  /** A content-addressed `baseline/<hash>` whose tree does not hash to its name (a bundle file
+   *  modified, planted or removed, or a symlink inside), or a baseline file whose bytes do not match
+   *  the hash the manifest recorded for it. Baselines are re-verified before EVERY reuse: a refresh
+   *  refuses to reuse it (2xx `blocked`, nothing copied), reset refuses to restore from it (nothing
+   *  written), publish/analyze report it blocking (before AND after the env was provisioned in it).
+   *  Read-only mode bits on the baseline are a guard, never the integrity boundary — the hash is
+   *  (api-types 0.28.0). */
+  | 'baseline-corrupt';
+
+export type SkillFindingSeverity = 'warning' | 'blocking';
+
+/** `blocked` = at least one blocking finding (nothing was written / published); `warnings` =
+ *  proceeded with warnings; `clear` = nothing to say. */
+export type SkillVerdict = 'clear' | 'warnings' | 'blocked';
+
+export interface SkillConflictFinding {
+  kind: SkillFindingKind;
+  severity: SkillFindingSeverity;
+  /** The skill this finding is about, or `null` for a catalog / support-file finding. */
+  skill: string | null;
+  /** Plugin-relative file the finding names, or `null`. */
+  file: string | null;
+  /** 1-based line in `file`, when the finding is anchored to one. */
+  line: number | null;
+  /** The OTHER catalog skill this finding is against (a collision, a core guard), or `null`. */
+  againstSkill: string | null;
+  againstIsCore: boolean;
+  /** The concrete fact (names, paths, the parse error). */
+  evidence: string;
+  /** Why it matters. */
+  explanation: string;
+}
+
+/** `POST /skills/analyze` 200 body (a PURE dry run of the publish validation: nothing persisted,
+ *  `revision` unchanged — drift it observes is reported, and recorded only by the publish that
+ *  ships it) — and the base of every mutation result. */
+export interface SkillAnalyzeResult {
+  verdict: SkillVerdict;
+  findings: SkillConflictFinding[];
+  revision: number;
+}
+
+/** Every `/skills` mutation's 200 body. `blocked` ⇒ nothing was written and `revision` is unchanged. */
+export interface SkillMutationResult extends SkillAnalyzeResult {
+  skill?: SkillEntry & { name: string };
+}
+
+/** `POST /skills/publish` 200 body. `snapshot` is `null` when the verdict is `blocked` — and then
+ *  `revision` is unchanged (a blocked publish persists nothing — not the drift it observed, not the
+ *  baseline's provisioning state). `path` is the absolute REAL path of the locked, read-only
+ *  generation; its `snapshot.json` carries the skill rows and the `views` block (`views.copilot`:
+ *  the `views/copilot` dir + the portable skills laid out in it). One publish runs at a time — a
+ *  concurrent one wrote nothing and answers a 2xx `blocked` `publish-in-flight` envelope
+ *  (`snapshot: null`), not a 409. */
+export interface SkillPublishResult extends SkillAnalyzeResult {
+  snapshot: { gen: number; path: string; contentHash: string; skills: number } | null;
+}
+
+/** `POST /skills/refresh-baseline` 200 body — the three-way merge per FILE (baseline_old /
+ *  baseline_new / effective): unchanged → take new; user-modified & upstream-unchanged → keep;
+ *  both changed → keep + `conflict` (new side readable as `?side=baseline`); user-DELETED &
+ *  upstream-changed → the deletion is kept + `conflict` (a deletion is a modification; reset
+ *  restores upstream); upstream-deleted & user-unmodified → remove; upstream-deleted &
+ *  user-modified → keep as user-added; a new upstream skill whose path-derived name is a
+ *  user-added skill's → conflict. 502 when no plugin is installed. */
+export interface SkillRefreshResult extends SkillAnalyzeResult {
+  previous_baseline: string;
+  baseline: string;
+  plugin_version: string;
+  /** Skills whose files were replaced from the new baseline. */
+  taken: string[];
+  /** Skills that kept operator content (upstream unchanged, or a flagged conflict). */
+  kept: string[];
+  added: string[];
+  removed: string[];
+  /** Skills flagged `conflict` by this refresh. */
+  conflicts: string[];
+}
+
+/** The 409 body of a `/skills` mutation whose `expectedRevision` is stale — a CAS conflict, the
+ *  ONLY thing that answers 409. A publish refused because another is in flight, or aborted because
+ *  the skills root changed under it, wrote nothing and instead answers a 2xx `blocked` findings
+ *  envelope (`publish-in-flight` / `root-changed`; api-types 0.28.0), never a 409. */
+export interface SkillRevisionConflict {
+  error: string;
+  /** The current revision — re-read `GET /skills` (or use this) and retry. */
+  revision: number;
+}
+
+/** The body of `POST /skills/:name/{enable,disable,reset}`, `POST /skills/publish` and
+ *  `POST /skills/refresh-baseline`. */
+export interface SkillRevisionBody {
+  expectedRevision: number;
+}
+
+/** `PUT /skills/:name/files/*path` and `PUT /skills/support/*path` body. `content` is UTF-8 text,
+ *  at most 512 KB. */
+export interface PutSkillFileBody {
+  content: string;
+  expectedRevision: number;
+}
+
+/** `POST /skills` body — add a user skill. `files` maps skill-relative POSIX paths to UTF-8 text
+ *  and must include `SKILL.md`; the skill lands at `skills/<name minus "wicked-garden-">`. */
+export interface AddSkillBody {
+  name: string;
+  files: Record<string, string>;
+  expectedRevision: number;
+}
+
+/** `POST /skills/:name/replace` body — replace the skill's OWN files wholesale (nested skills untouched). */
+export interface ReplaceSkillBody {
+  files: Record<string, string>;
+  expectedRevision: number;
+}
+
 // ── Governance wiki management (scoreboard + meta) ─────────────────────────────
 
 /**
@@ -1465,7 +1837,17 @@ export interface GovernanceEvalNearestRule {
  * remediation pointer for "which rule needs sharpening".
  */
 export interface GovernanceEvalResult {
-  sample: Pick<GovernanceEvalSample, 'id' | 'description' | 'kind' | 'steering_type'>;
+  sample: Pick<GovernanceEvalSample, 'id' | 'description' | 'kind' | 'steering_type'> & {
+    /**
+     * The sample's PAYLOAD identity — `sha256:` over the canonical JSON of its full payload (id,
+     * description, kind, steering_type, signals). The engine echoes only the four fields above
+     * (input `signals` never ride a result row), so this is stamped by a PRODUCER that held the
+     * samples it staged (the internal-corpus `run`); a row without it cannot be proven to be the
+     * same action as a row with the same id in another run, and the offline comparison reports
+     * such a pair as unverified rather than comparable.
+     */
+    payload_hash?: string;
+  };
   expected: 'deny' | 'allow';
   fired: string[];
   verdict: 'caught' | 'gap' | 'false_positive';
@@ -1480,15 +1862,73 @@ export interface GovernanceEvalSummary {
   false_positives: number;
 }
 
+/**
+ * One steering rule in the judged store that NO sample of the run exercised — the inverse blind
+ * spot of `summary.gaps` (core #394): a gap is a sample nothing caught, but a rule with zero
+ * exercising samples produces no result row at all and so is invisible to the summary. Each
+ * entry names the rule and the Steering sub-page it belongs to, so the corpus can grow a sample
+ * for it (or the rule can be retired as untestable).
+ */
+export interface GovernanceEvalUnexercisedRule {
+  rule_id: string;
+  steering_type: SteeringType;
+}
+
+/**
+ * One steering type's row of {@link GovernanceEvalRuleCoverage.per_type} (evals.rs `TypeCoverage`):
+ * how many of the run's eligible decide-lane rules OF THAT TYPE fired for at least one sample, and
+ * how many fired for none. `unexercised` here is a COUNT — the ids are the parent's `unexercised`
+ * list, whose rows each carry their `steering_type`, so the two reconcile per type.
+ */
+export interface GovernanceEvalTypeCoverage {
+  exercised: number;
+  unexercised: number;
+}
+
+/**
+ * Rule-side coverage of an eval run (core #394/#395 — evals.rs `RuleCoverage`): the decide-lane
+ * rules ELIGIBLE for the run (every active effect-bearing rule, narrowed to the run's `--type`
+ * slice when one was given) partitioned into `exercised` (fired — blocking or not — for at least
+ * one sample; a COUNT) and `unexercised` (fired for none; the ids, each with its steering type).
+ * Together with `summary` it separates "the corpus lacks a behavior" from "the store lacks a rule"
+ * — the two readings a bare gap count conflates. `recall_only` counts the active rules in the slice
+ * carrying NO effect — outside the partition because the gate never fires them (core #395).
+ * `per_type` is the same partition per steering type — all seven keys, zeros included (the engine
+ * pins the shape).
+ *
+ * Every engine that emits `rule_coverage` at all (core #394 onward) serializes all four fields on
+ * every report (serde, no skip). `recall_only` and `per_type` are declared optional on the CONTRACT
+ * only because the daemon persists a run's coverage VERBATIM and validates none of its fields, so a
+ * stored record is exactly as complete as its producer made it and the contract never promises what
+ * was never checked: a consumer reads an absent `per_type` as "the engine reports no per-type
+ * coverage" (the offline comparison says exactly that), never as zeros. `exercised` and
+ * `unexercised` are required — no engine ever emitted one without the other.
+ *
+ * A run's `results[].fired` is NOT this partition's evidence: `fired` is the BLOCKING subset of the
+ * firings, and under a type filter it may name rules of OTHER types — the filter slices the samples
+ * and this denominator, never the gate (evals.rs `run_evals` / `evaluate_sample`).
+ */
+export interface GovernanceEvalRuleCoverage {
+  exercised: number;
+  unexercised: GovernanceEvalUnexercisedRule[];
+  recall_only?: number;
+  per_type?: Record<SteeringType, GovernanceEvalTypeCoverage>;
+}
+
 /**
  * The `POST /testing/evals/run` 200 body — the engine's serde report passed through VERBATIM
  * (snake_case field names, `degraded` spelled `null` when the run was full-fidelity;
- * `'facet-only'` when the embedding side was unavailable and only facet matching ran).
+ * `'facet-only'` when the gap-hint embedder was unavailable and hints fell back to lexical
+ * matching — the verdicts are the same either way, only `nearest_rules` degrades).
+ *
+ * `rule_coverage` is OPTIONAL on purpose: an engine that predates core #394 emits a report
+ * without it, and that report still validates — the daemon never fabricates the field.
  */
 export interface GovernanceEvalReport {
   results: GovernanceEvalResult[];
   summary: GovernanceEvalSummary;
   degraded: 'facet-only' | null;
+  rule_coverage?: GovernanceEvalRuleCoverage;
 }
 
 /** The `POST /testing/corpora/import` request body — a named eval corpus for later runs. */
@@ -1553,6 +1993,12 @@ export interface EvalRunSummary {
   per_type: Partial<Record<SteeringType, EvalRunPerTypeCount>>;
   /** `'facet-only'` when the run degraded to facet matching; null when it ran full-fidelity. */
   degraded: 'facet-only' | null;
+  /**
+   * The report's {@link GovernanceEvalReport.rule_coverage}, persisted VERBATIM (like `degraded`,
+   * never recomputed daemon-side). ABSENT — not null — when the engine that ran the eval predates
+   * core #394 and emitted no coverage, so a history row honestly shows which runs measured it.
+   */
+  rule_coverage?: GovernanceEvalRuleCoverage;
 }
 
 /**
@@ -1963,6 +2409,15 @@ export interface SystemSettings {
    * the engine default `~/.wicked-worker`.
    */
   worker_config_root?: string;
+  /*
+   * There is NO skills setting (skills keystone, api-types 0.28.0). The daemon-owned skills root is
+   * `<state home>/skills` — the directory holding `manifest.json`, `baseline/<hash>/`, `effective/`,
+   * `snapshots/<gen>/` and the `current` symlink — full stop: not configurable (a `skills_root` a
+   * client sends is dropped and named in the audit entry's `ignored`; design v3.1 §1 one storage
+   * root, v3.2 §1 never a user CLI directory), and there is no mirror knob either (the daemon never
+   * writes into the user's own CLI directories). `GET /skills` → `root` and `GET /diagnostics` →
+   * `skills.root` report where it is.
+   */
   /**
    * The repo-scoped launch delivery DEFAULT (crew#393; api-types 0.18.0, additive). What a
    * `POST /runs` with `repoRef` + a CODE-WORK `workflow` (a def with at least one
@@ -2246,6 +2701,32 @@ export interface InteractiveDocDeleteResponse {
   ledger: InteractiveDocDeleteLedgerReport;
 }
 
+/**
+ * One row of `GET /projects/:projectId/interactive/api/docs` (crew#472) — the bridge's own
+ * `GET /api/docs` row (interactive's `listDocs` shape, relayed field-for-field) stamped with the
+ * project whose mount it was listed under. Docs roots are partitioned per project (the `default`
+ * project keeps the legacy shared root), so `projectId` is the attribution a client rendering
+ * docs from several projects at once cannot otherwise recover.
+ */
+export interface InteractiveDocSummary {
+  /** The doc name (slug). */
+  name: string;
+  /** Manifest `kind`; a manifest without one lists as `doc`. */
+  kind: 'doc' | 'html' | 'source' | 'demo';
+  /** Head version. */
+  head: number;
+  /** Lineage size. */
+  versions: number;
+  /** ISO-8601 timestamp of the head version, or null when the lineage is empty. */
+  updated_at: string | null;
+  /** Present only on a retired (tombstoned) row, which lists only with `?includeRetired=1`. */
+  retired?: true;
+  /** ISO-8601 retirement timestamp; present with `retired`. */
+  retired_at?: string;
+  /** The crew project this row was listed under — the mount's `:projectId`. */
+  projectId: string;
+}
+
 /**
  * One normalized entry of the merged project activity feed
  * (`GET /projects/:id/activity`, ADR §5.2): core events of member runs/chats
@@ -2881,6 +3362,50 @@ export interface DiagnosticsResponse {
   /** Bounded tail of the daemon's own error-level log lines, newest first. */
   recentErrors: DiagnosticsRecentError[];
   acp: AcpDiagnostics;
+  /** The skills seam's last outcome (api-types 0.28.0) — see `DiagnosticsSkills`. */
+  skills: DiagnosticsSkills;
+}
+
+/** The skills seam's state as `GET /diagnostics` reports it (skills keystone, api-types 0.28.0). */
+export type DiagnosticsSkillsState = 'published' | 'fallback' | 'blocked' | 'config-error' | 'disabled';
+
+/** One finding the skills degradation ladder produced (design v3 §3). */
+export interface DiagnosticsSkillsFinding {
+  /** `skills.fallback` = no wicked-garden installed (engine input left unset / restored to the boot
+   *  value — the engine resolves the live cache itself); `skills.blocked` = the first publish is
+   *  blocked (engine input points at a non-existent refusal path — launches fail loudly until the
+   *  catalog is fixed); `skills.config` = the configured root is corrupt/unusable (same refusal;
+   *  `error`), or — as a `warning` on the `published` state — the root lies OUTSIDE the daemon
+   *  state home, so core's fence cross-check (`WICKED_CREW_STATE_HOME`) refuses every launch. */
+  kind: 'skills.fallback' | 'skills.blocked' | 'skills.config';
+  severity: 'warning' | 'error';
+  message: string;
+}
+
+/**
+ * `GET /diagnostics` → `skills`: whether the engine is being handed a verified snapshot, and if not,
+ * why — the one read-only answer to "why do launches refuse the skills snapshot". `disabled` is a
+ * daemon booted without the seam (the manifest collector, some tests).
+ */
+export interface DiagnosticsSkills {
+  state: DiagnosticsSkillsState;
+  /** The resolved skills root on the daemon host; `null` when `disabled`. */
+  root: string | null;
+  /** The VERIFIED published snapshot (`current` realpath-contained, `snapshot.json` + content hash
+   *  checked), or `null`. `path` is the absolute REAL path of `snapshots/<gen>`. */
+  current: { gen: number; path: string } | null;
+  /** What `WICKED_SKILLS_SNAPSHOT` — the engine's ONE skills input (v3.1 §2, v3.4 §2;
+   *  `WICKED_SKILLS_CURRENT` is never set, `WICKED_CREW_STATE_HOME` is not exported) — is exported as
+   *  right now: the real snapshot path, a `<root>/refused/…` refusal path, `""` when the process
+   *  booted with an explicitly EMPTY value (preserved — a configuration error core refuses, state
+   *  `config-error`; design v3.5 §4), or `null` = unset. */
+  engineInput: string | null;
+  /** DIAGNOSTICS-ONLY: the canonical realpath of the daemon state home, reported for humans. It is
+   *  NOT an engine input — `WICKED_CREW_STATE_HOME` is retired (v3.4 §2): core reads only
+   *  `WICKED_SKILLS_SNAPSHOT` and derives the state home from its `<state home>/skills/snapshots/<gen>`
+   *  layout. `null` only when `disabled`. */
+  stateHome: string | null;
+  findings: DiagnosticsSkillsFinding[];
 }
 
 // ── Memory proposal queue (DES-MEM-FACETED-001 §5.0, api-types 0.21.0) ─────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.25.0",
+  "version": "0.28.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",