wicked-crew-api-types 0.167.0 → 0.172.0

package/index.d.ts

@@ -359,6 +359,58 @@ export interface HealthCapabilities {
    * the model are on this machine) is {@link VoiceStatus.ready}. ABSENT on an older daemon: read as `false`.
    */
   voice?: boolean;
+  /**
+   * (api-types 0.168.0) `GET /workflows/catalog` is served: the categorised workflow catalog with the
+   * requesting operator's usage ({@link WorkflowCatalogResponse}). ABSENT on an older daemon: read as `false`.
+   */
+  workflowCatalog?: boolean;
+  /**
+   * (api-types 0.169.0, DES-CHAT-ARTIFACTS-001 §14) What a chat can do with artifacts, one flag per operation, each
+   * true only once its slice ships. `context`: `ChatMessageBody.context` is accepted ({@link ChatMessageContext}),
+   * `POST /chats {seedFromArtifact}` is served, and each turn's seats get the open artifact, the runs the person names
+   * and the ids they may use, recorded per turn as a `context` transcript record. `proposals` (api-types 0.170.0,
+   * slice A2): a seat's `wicked-make` block becomes a crew-resolved proposal card answered by a person. The operations
+   * (`create`, `refine`, `theme`, `demo`) are later slices and are `false` until then (all `true` with `stub: true` in
+   * the test configuration). ABSENT on an older daemon: read every flag as `false`, and send no `context` (the message
+   * body is strict there, so the field would be refused).
+   */
+  chatArtifacts?: ChatArtifactsCapabilities;
+  /**
+   * (api-types 0.172.0, DES-APPS-001) PRESENT means the app store is served: `GET|POST /apps`, `GET /apps/:app`, and
+   * the human-only edits, undo, redo and restore. The flags of {@link AppsCapabilities} are about the OTHER routes:
+   * each says whether that route serves for real yet (rather than `501`). A skin shows Apps only when this is
+   * present. ABSENT on an older daemon.
+   */
+  apps?: AppsCapabilities;
+}
+
+/** {@link HealthCapabilities.chatArtifacts} (api-types 0.169.0). */
+export interface ChatArtifactsCapabilities {
+  context: boolean;
+  /**
+   * (api-types 0.170.0, slice A2) A seat's `wicked-make` block becomes a crew-resolved proposal ({@link ArtifactProposal},
+   * transcript kinds `proposal` / `proposal_accepting` / `proposal_decided`, `/ws` {@link ChatProposalFrame}) and
+   * `POST /chats/:id/proposals/:pid` answers it. Seats are told only about the operations below that are `true`, and
+   * the resolver and the accept route refuse the others, so with every operation `false` no card is made.
+   */
+  proposals: boolean;
+  create: boolean;
+  refine: boolean;
+  theme: boolean;
+  demo: boolean;
+  /**
+   * (api-types 0.170.0) The daemon runs the chat-artifacts TEST configuration (DES §13 A2): every operation resolves,
+   * and Go on a proposal of a kind in {@link stubOps} records a stub dispatch and starts NOTHING (a skin says so on that
+   * card). With `stubOps` absent (a daemon before 0.171.0), that is every kind. ABSENT in production.
+   */
+  stub?: true;
+  /**
+   * (api-types 0.171.0, slice A3) The operations whose Go records a stub dispatch and starts nothing under the TEST
+   * configuration; every other advertised operation starts real work (A3: `create` is real, `refine`, `theme` and
+   * `demo` stay stubs until their slices). ABSENT in production. A skin says "starts nothing" only for these kinds;
+   * before this field, `stub: true` meant every kind.
+   */
+  stubOps?: ArtifactProposalKind[];
 }
 
 // ── A run's working document (program DES-POWER-MODE §8.3, §9; api-types 0.148.0) ──────────────────
@@ -1220,6 +1272,22 @@ export interface AgentSession {
    * before the field: check `GET /health.capabilities.runChatId` before grouping runs by chat.
    */
   chat_id?: string;
+  /**
+   * (api-types 0.171.0, DES-CHAT-ARTIFACTS-001 §4.3, slice A3) The chat proposal this run answers
+   * (`<chatId>:<turnId>`, or a crew-made `<chatId>:retry:<runId>`), read back from the `run.launched`
+   * entry after a restart. ABSENT on a run no proposal started.
+   */
+  proposal_id?: string;
+  /** (api-types 0.171.0) The artifact a proposal-bound run makes (`<mount>/<doc>`, the mount a project id or `_unfiled`),
+   *  so a skin finds an Unfiled run's document. ABSENT on a run no proposal started. */
+  artifact_ref?: string;
+  /**
+   * (api-types 0.171.0, §6.2) A proposal-bound attempt ended without landing: the engine run failed or was stopped,
+   * crew's landing check failed (no file, the document floor, the announce), or a daemon restart interrupted it
+   * ("interrupted by a restart"). The chat and the document are released, and the chat holds a retry proposal
+   * (`<chatId>:retry:<runId>`: Try again into the same document). ABSENT when the attempt landed or is still going.
+   */
+  landing_failed?: { reason: string; at: number };
   /**
    * (crew#552) The onboarding run this run was CHAINED from (a `capture-learnings` run the daemon
    * launched when that onboarding completed) — read back from the `run.launched` entry after a
@@ -7295,6 +7363,115 @@ export interface PresetResponse {
   preset: Preset;
 }
 
+// ── The workflow catalog (api-types 0.168.0, lane wf-catalog) ───────────────────────────────────
+
+/** A catalog category id. `yours` is listed only when the operator has saved presets. */
+export type WorkflowCatalogCategoryId = 'create' | 'resolve' | 'analyze' | 'test' | 'more' | 'yours';
+
+/** One category of the catalog, in display order, with its ordered subcategories (`[]` for `more` and `yours`). */
+export interface WorkflowCatalogCategory {
+  id: WorkflowCatalogCategoryId;
+  title: string;
+  /** One line under the heading. */
+  summary: string;
+  subcategories: { id: string; title: string }[];
+}
+
+/** What a catalog entry needs before it can start. */
+export type WorkflowCatalogNeed = 'repo' | 'project' | 'running_app' | 'requirements' | 'document' | 'runs' | 'nothing';
+
+/** One field the launch asks for, in order. */
+export interface WorkflowCatalogInput {
+  id: string;
+  label: string;
+  kind: 'text' | 'repo' | 'project' | 'url' | 'requirements' | 'seats';
+  required: boolean;
+}
+
+/**
+ * How a client starts an entry: `run` = `POST /runs {workflow}`; `demo` = `POST /projects/:id/demo`;
+ * `compose` = `POST /projects/:id/product/compose` (draft epics); `document` = a new interactive document
+ * of that style (its draft run); `chat` = a chat on its own page; `none` = nothing to launch (coming soon).
+ */
+export type WorkflowCatalogLaunch =
+  | { kind: 'run'; workflow: string }
+  | { kind: 'demo' }
+  | { kind: 'compose' }
+  | { kind: 'document'; style: 'web' | 'doc' | 'ppt' | 'brochure' }
+  | { kind: 'chat' }
+  | { kind: 'none' };
+
+/** The requesting operator's use of an entry (scope: {@link WorkflowCatalogResponse.usage}). */
+export interface WorkflowCatalogUsage {
+  /** Runs this operator launched under the entry's workflow (a retry is not a new launch). */
+  launches: number;
+  /** ISO 8601 launch time of the newest such run, or null. */
+  lastUsedAt: string | null;
+  /** Median wall time in minutes of those runs that COMPLETED, or null when none did. */
+  medianMinutes: number | null;
+}
+
+/** One card of the catalog. */
+export interface WorkflowCatalogEntry {
+  /**
+   * Unique, opaque card id. For `launch.kind === 'run'` it is `launch.workflow`, prefixed `run:` when a non-run
+   * card already holds that id (a saved preset called `presentation`). Launch by `launch.workflow`, never by `id`.
+   */
+  id: string;
+  category: WorkflowCatalogCategoryId;
+  /** A subcategory id of its category, or null. */
+  subcategory: string | null;
+  title: string;
+  /** What it does, one line. */
+  summary: string;
+  /** What you get, one line. */
+  outcome: string;
+  /** 0–4 short phrases saying when to pick it. */
+  useWhen: string[];
+  needs: WorkflowCatalogNeed[];
+  inputs: WorkflowCatalogInput[];
+  /** Static hint in minutes `[low, high]` from observed runs; null = not known. */
+  typicalMinutes: [number, number] | null;
+  /** Relative cost hint (agent phases and seats); null = not known. */
+  cost: 'low' | 'medium' | 'high' | null;
+  /** Shown as chips; searchable. */
+  tags: string[];
+  /** Searchable only. */
+  synonyms: string[];
+  status: 'available' | 'coming_soon' | 'unavailable';
+  /** Why coming soon or unavailable; null when available. */
+  statusNote: string | null;
+  launch: WorkflowCatalogLaunch;
+  /** The workflow requires QE acceptance before it delivers. */
+  requiresQe: boolean;
+  delivers: 'pr' | 'document' | 'video' | 'report' | 'answer' | 'none';
+  /** Where the definition lives: the engine's built-in preset, a crew workflow, the operator's saved preset, studio's own flow, or none yet. */
+  source: 'builtin' | 'crew' | 'saved' | 'studio' | 'none';
+  usage: WorkflowCatalogUsage;
+}
+
+/**
+ * `GET /workflows/catalog[?projectId=]` (api-types 0.168.0): the workflows as a categorised catalog with
+ * the requesting operator's usage, derived from the runs the daemon already records (the `run.launched`
+ * trail's principal, the run's resolved workflow). Additive: `GET /workflows` is unchanged.
+ */
+export interface WorkflowCatalogResponse {
+  categories: WorkflowCatalogCategory[];
+  /** By category order, then subcategory order, then catalog order. */
+  entries: WorkflowCatalogEntry[];
+  /** "Your top": up to 6 available entry ids with launches, by launches then most recent. */
+  top: string[];
+  usage: {
+    /** `operator`: every run this principal launched; `project`: only those filed in `projectId`. */
+    scope: 'operator' | 'project';
+    projectId: string | null;
+    /** The principal the usage is for (`Actor.id`; `local` on a loopback daemon). */
+    actorId: string;
+    /** Runs counted across every entry. */
+    launches: number;
+  };
+}
+
 // ── Projects (DES-PROJECT-001) — the experience-plane keystone ─────────────────
 
 /** Project lifecycle: `active ⇄ archived`, no hard delete (ADR §1.3). */
@@ -7473,6 +7650,16 @@ export interface InteractiveDemoStepDraft {
 export interface InteractiveDocCreateRequest {
   /** The doc name; the bridge slugifies it (409 when taken or retired). */
   name?: string;
+  /**
+   * (api-types 0.171.0, DES-CHAT-ARTIFACTS-001 §5.2) The chat a proposal's create comes from. Accepted ONLY with
+   * `proposal_id`, and only when that chat holds a `proposal_accepting` record of the caller's whose identity names
+   * this document in this mount and whose stored resolution lists every `repo_ref(s)`: then an Unfiled document may
+   * name those repositories (`unfiled_doc_repo` is lifted through the record, nothing else). Anything else is a 400
+   * `proposal_grant_refused` and nothing is created. Crew sends these itself on a proposal's Go.
+   */
+  chat_id?: string;
+  /** (api-types 0.171.0) The proposal (`<chatId>:<turnId>` or `<chatId>:retry:<runId>`); see `chat_id`. */
+  proposal_id?: string;
   /** Omitted = a plain html doc (`html` required); `source` = generated from brief/sources; `demo` = a recording. */
   kind?: 'source' | 'demo';
   /** A plain html doc's content (or a `source` doc's seed). */
@@ -7534,9 +7721,11 @@ export interface InteractiveDocCreateRefusal {
    * Unfiled mount; `invalid_repo_ref` — junk spelling / shape / over the cap; `ambiguous_repo_ref`
    * — a name or basename shared by several member repos (name it by id); `project_mismatch` — the
    * body's `project` is not the route's project (or is present on the Unfiled mount). The proxy
-   * canonicalizes an OMITTED `project` from the route.
+   * canonicalizes an OMITTED `project` from the route. `proposal_grant_refused` (api-types 0.171.0) — `chat_id`
+   * without `proposal_id` (or the reverse), or no `proposal_accepting` record of the caller's in that chat that names
+   * this document, this mount and every requested repository.
    */
-  code: 'repo_not_in_project' | 'unfiled_doc_repo' | 'invalid_repo_ref' | 'ambiguous_repo_ref' | 'project_mismatch';
+  code: 'repo_not_in_project' | 'unfiled_doc_repo' | 'invalid_repo_ref' | 'ambiguous_repo_ref' | 'project_mismatch' | 'proposal_grant_refused';
   /** The refs the request named, as spelled (best-effort stringified when malformed). */
   requested: string[];
   /** The subset of `requested` that matched no member repo (`repo_not_in_project` only). */
@@ -7905,6 +8094,18 @@ export interface ChatOpenBody {
    * engine without it is a 409. Send it only when `GET /health.capabilities.chatWorkflows` names it.
    */
   workflow?: string;
+  /**
+   * (api-types 0.169.0, DES-CHAT-ARTIFACTS-001 §6.3) "Ask about this" on a document no open chat holds: the
+   * artifact ref (`<mount>/<doc>`). Allowed for a chat with no `projectId`, or for a project chat whose project is the
+   * document's mount (checked before anything is read; else 400 `seed_out_of_scope`). Crew then checks the document
+   * exists (404 `seed_not_found`) and, for a project chat, that every repository it was made about belongs to the
+   * project (else 400 `seed_out_of_scope`). When the request names no `repoRefs` and its `scopeKind` is not
+   * `everything` or `project`, the chat reads the repositories the document was made about (its recorded binding);
+   * a `system` or `none` kind then becomes the repository scope. A document made about no repository seeds nothing.
+   * A non-person actor is refused (403 `seed_refused`). Send only when
+   * `GET /health.capabilities.chatArtifacts.context === true`.
+   */
+  seedFromArtifact?: string;
 }
 
 /** The scope a `POST /chats` caller may name (api-types 0.39.0, studio#323 R4). */
@@ -8205,7 +8406,17 @@ export interface ChatUsage {
  */
 export type ChatTranscriptRecord =
   /** `attachments` (api-types 0.137.0): the files the message carried, ABSENT when none. */
-  | { at: number; turnId: string; kind: 'user'; text: string; seats: string[]; attachments?: ChatAttachment[] }
+  | {
+      at: number;
+      turnId: string;
+      kind: 'user';
+      text: string;
+      seats: string[];
+      attachments?: ChatAttachment[];
+      /** (api-types 0.170.0) Sent by the chat's owner, a person (the message route's own check). Only these words count
+       *  as the person's for a proposal (a demo address, a document they named). ABSENT for any other sender. */
+      owner?: true;
+    }
   | { at: number; turnId: string; kind: 'seat'; cliKey: string; text: string; ok: boolean; usage: ChatUsage | null }
   /**
    * The citation verdicts of the `seat` record with the same `turnId` + `cliKey` (api-types 0.68.0,
@@ -8238,7 +8449,235 @@ export type ChatTranscriptRecord =
    * 0.85.0, DC-S7): the rules remembered since they last heard from crew. Disclosed here so the
    * operator sees exactly what crew added; the `user` record keeps the operator's own words.
    */
-  | { at: number; turnId: string; kind: 'system'; text: string };
+  | { at: number; turnId: string; kind: 'system'; text: string }
+  /**
+   * What the seats of `turnId` were given beside the operator's words (api-types 0.169.0, DES-CHAT-ARTIFACTS-001
+   * §5.1): the open artifact's copies, the run briefs, and what was refused. Written with the turn's `user` record.
+   */
+  | ({ at: number; turnId: string; kind: 'context' } & ChatContextBinding)
+  /**
+   * (api-types 0.170.0, DES-CHAT-ARTIFACTS-001 §4.2) A proposal crew resolved from a seat's `wicked-make` block in the
+   * reply of `turnId`. A later `proposal` record with the same `proposal.pid` REPLACES it (a re-resolution after the
+   * document's head moved); a newer pid in the same chat supersedes an open one.
+   */
+  | { at: number; turnId: string; kind: 'proposal'; proposal: ArtifactProposal }
+  /** (api-types 0.170.0, §4.3 step 2) A person said go: what was accepted, written before anything starts. */
+  | ({ at: number; turnId: string; kind: 'proposal_accepting' } & ProposalAccepting)
+  /** (api-types 0.170.0) The proposal's answer: go (with what it started) or not now. */
+  | ({ at: number; turnId: string; kind: 'proposal_decided' } & ProposalDecided);
+
+// ── Chat proposals (api-types 0.170.0, DES-CHAT-ARTIFACTS-001 §4, slice A2) ─────────────────────────────────────────
+//
+// A seat proposes an artifact job in a fenced `wicked-make` block. Crew cuts it out of the reply (it never reaches a
+// reader), resolves it against its own records, and appends a `proposal` transcript record plus a `chatProposal`
+// frame. The card's facts are crew's, never the seat's. Only `POST /chats/:id/proposals/:pid` (a person, the chat's
+// owner) starts anything. Capabilities: `GET /health.capabilities.chatArtifacts.proposals` and one flag per operation.
+
+/** What a proposal makes. `create` and `demo` come from a catalog entry; `refine` changes a document; `theme` is a
+ *  studio appearance patch. */
+export type ArtifactProposalKind = 'create' | 'refine' | 'theme' | 'demo';
+
+/** One "From" chip: a source the block named, as crew resolved and authorized it. */
+export interface ProposalSource {
+  /** The token as crew reads it: `chat`, `page`, `message:<turnId>`, `run:<full id>`, `doc:<mount>/<doc>`,
+   *  `attachment:<id>` (a run prefix the seat wrote is resolved to the full id when it can be). */
+  token: string;
+  /** Plain words: "this conversation", "run 29bbbfb1 · stopped", "Release note v4". */
+  label: string;
+  /** `struck`: the draft never sees it; `reason` says why ("run 1a2b3c4d · not named in this chat"). */
+  status: 'ok' | 'struck';
+  reason?: string;
+  /** The project the source belongs to (`null`: Unfiled, or not a project's); absent for `chat` and `page`. A form that
+   *  changes the project strikes a chip whose project differs. */
+  projectId?: string | null;
+}
+
+/** "Codex and Claude Code: one writes, the other checks": two distinct eligible seats (never who writes). */
+export interface ProposalHelpers {
+  seats: string[];
+  label: string;
+}
+
+/** "About 10–20 min · 3 agent steps · median of 4 past documents here: 9 min, $0.62". Unknown parts are left out. */
+export interface ProposalTime {
+  /** The catalog entry's `typicalMinutes`. */
+  minutes: [number, number] | null;
+  /** The catalog entry's relative cost. */
+  cost: 'low' | 'medium' | 'high' | null;
+  /** Agent steps of the workflow. */
+  steps: number | null;
+  /** Over completed runs of the same workflow on this daemon. `costUsd` only from at least 3 runs whose every agent
+   *  step reported a cost (`costRuns` of them); else `null`. */
+  median: { runs: number; minutes: number; costUsd: number | null; costRuns: number } | null;
+  label: string;
+}
+
+/** A proposal as crew resolved it. Every line is crew's: the seat chose only the block's words. */
+export interface ArtifactProposal {
+  /** `<chatId>:<turnId>` for a turn's proposal (later slices add `<chatId>:redo:<runId>` / `:retry:`). */
+  pid: string;
+  chatId: string;
+  /** The turn whose reply carried the block; `null` for a crew-made proposal (`sourceRunId`). */
+  turnId: string | null;
+  sourceRunId?: string;
+  kind: ArtifactProposalKind;
+  /** The seat that wrote the block. */
+  seat: string;
+  /** The "What" line: `label` is "Slides · Domain coverage for new engineers"; `outcome` is the catalog entry's. */
+  what: { entry: string | null; title: string; label: string; outcome: string | null };
+  /** The brief (create), the ask (refine), or what to show (demo), as the seat wrote it. */
+  brief: string | null;
+  reason: string | null;
+  sources: ProposalSource[];
+  /** Repositories (names), each in the chat's scope. */
+  repos: string[];
+  /** (api-types 0.171.0) The same repositories by registry id, in the same order (two checkouts may share a name). */
+  repoRefs?: string[];
+  /** (api-types 0.171.0) A crew-made retry (`sourceRunId`): the document it fills again (`<mount>/<doc>`), the same
+   *  artifact as the failed attempt's. ABSENT on a turn's proposal (its document name derives from the pid). */
+  artifactRef?: string;
+  /** `null` for a theme (no run). */
+  helpers: ProposalHelpers | null;
+  /** `null` for a theme. */
+  time: ProposalTime | null;
+  /** "Stops for you if the check fails. The plan or an escalation may also ask." `null` for a theme. */
+  stops: string | null;
+  /** The project the result is filed in; `label` is the project's name or "Not in a project · this chat". */
+  filedIn: { projectId: string | null; label: string };
+  /** refine: the document (`<mount>/<doc>`), its title, and the head it was proposed on. */
+  target?: { ref: string; title: string; base: number };
+  /** refine: the parts the seat pointed at (`data-wid`s); hand edits are kept unless the person says otherwise. */
+  touches?: string[];
+  /** theme: the partial appearance patch and the keys it changes. */
+  theme?: { name: string; patch: Record<string, string | number | boolean>; changes: string[] };
+  /** demo: the app address (from the person's words), the audience and what to show. */
+  demo?: { url: string; audience: string | null; show: string | null };
+  /** Go is refused with this reason ("Needs a second helper to check it"); the card shows it. `null` = Go is open. */
+  blocked: string | null;
+}
+
+/**
+ * What a person may change before Go (typed per kind; crew re-checks every edit with the rules of §4.2). Crew takes
+ * `title`, `brief`, `sources`, `helpers`, `repos` and `project` on a create (api-types 0.171.0, slice A3: New document's
+ * "answer this proposal" mode), `ask` and `helpers` on a refine, `name` and `patch` on a theme, and `audience`, `show`
+ * and `helpers` on a demo; `url` and `allow` are refused (400 `edits_invalid`) until the slices whose forms edit them.
+ * `project` changes only in a chat filed in no project: then every source, repository and turn of the conversation is
+ * re-checked against the target project, and what is outside it is struck (a `message:` source whole, when any of its
+ * records is outside). `repos` must be in the chat's scope (and, with a target project, members of it). A source or
+ * repository the person adds that cannot be used is refused, never dropped. An interrupted (accepting) proposal
+ * resumes with its accepted choices: only its `helpers` may change.
+ */
+export interface ProposalEdits {
+  /** create */
+  title?: string;
+  brief?: string;
+  sources?: string[];
+  repos?: string[];
+  project?: string | null;
+  /** refine */
+  ask?: string;
+  allow?: string[];
+  /** theme */
+  name?: string;
+  patch?: Record<string, string | number | boolean>;
+  /** demo */
+  url?: string;
+  audience?: string;
+  show?: string;
+  /** any kind with a run */
+  helpers?: string[];
+}
+
+/** What the accepted proposal is named by: the artifact, and the run derived from the pid. */
+export interface ProposalIdentity {
+  /** `<mount>/<doc>`: the document a create makes (its name derived from the pid) or a refine changes; `null` for a
+   *  theme or a demo. */
+  artifactRef: string | null;
+  /** A name-based UUID of the pid: the launch's `sessionId`, so a retry can only adopt it. */
+  runId: string;
+}
+
+/** What Go started. */
+export interface ProposalResult {
+  runId: string;
+  artifactRef: string | null;
+  /** Found already launched (a retry, a second tab) and adopted rather than started again. */
+  adopted: boolean;
+  /** The test configuration's recording stub took it: nothing was started. */
+  stub: boolean;
+}
+
+export interface ProposalAccepting {
+  pid: string;
+  /** The person's actor id. */
+  actor: string;
+  edits: ProposalEdits | null;
+  /** The effective proposal after the edits were applied and checked. */
+  resolution: ArtifactProposal;
+  identity: ProposalIdentity;
+}
+
+export interface ProposalDecided {
+  pid: string;
+  actor: string;
+  decision: 'go' | 'not_now';
+  /** `null` for not now. */
+  result: ProposalResult | null;
+}
+
+/** A proposal folded from its records. */
+export interface ChatProposalView {
+  proposal: ArtifactProposal;
+  /** `accepting`: Go was recorded and its result was not (an interrupted Go: "Go again" resumes the same identity). */
+  state: 'open' | 'accepting' | 'decided' | 'superseded';
+  decision?: 'go' | 'not_now';
+  result?: ProposalResult | null;
+  /** Unix millis of the decision. */
+  decidedAt?: number;
+}
+
+/** `POST /chats/:id/proposals/:pid` body. */
+export interface ChatProposalDecisionBody {
+  decision: 'go' | 'not_now';
+  edits?: ProposalEdits;
+}
+
+/**
+ * `POST /chats/:id/proposals/:pid` → 200: the proposal as decided (a repeat of the same decision answers the stored
+ * result again, so a lost response is safe to retry). Only a person answers: under `auth: required` a worker, agent or
+ * system token is refused; under `auth: off` every request is the local person (the daemon's documented local-mode
+ * posture, as for gates). Refusals carry `code`: 403 `proposal_refused` (not a person),
+ * 404 (no such chat or proposal, or a chat that is not the caller's under `auth: required`: its existence is not
+ * disclosed), 409 `proposal_superseded` | `proposal_decided` | `proposal_blocked` | `operation_unavailable` |
+ * `chat_busy` | `document_busy` | `source_gone` | `helper_unavailable` | `chat_gone` | `proposal_reresolved` (the
+ * document moved: `view.proposal` is the fresh one), 400 `edits_invalid`, 502 `launch_failed` (accepting stays
+ * recorded; Go again resumes the same identity). A 409 carries the current `view` when there is one.
+ */
+export interface ChatProposalDecisionResponse {
+  view: ChatProposalView;
+}
+
+/**
+ * `/ws` (api-types 0.170.0): a proposal record was appended to chat `chat` (the same record the transcript holds).
+ * `project_id`: the chat's project, when it has one. A `type` alias (like the daemon's other synthetic frames) so it
+ * satisfies {@link CoreEvent}'s index signature.
+ */
+export type ChatProposalFrame = {
+  type: 'chatProposal';
+  chat: string;
+  turn_id: string;
+  record: Extract<ChatTranscriptRecord, { kind: 'proposal' | 'proposal_accepting' | 'proposal_decided' }>;
+  project_id?: string;
+};
+
+/**
+ * `/ws` (api-types 0.171.0, DES-CHAT-ARTIFACTS-001 §6.2, slice A3): a proposal-bound attempt ended without landing — the
+ * engine run failed or was stopped, crew's landing check refused it (no draft file, the document floor, a source file
+ * changed during the run, the announce), or a daemon restart interrupted it. The run's DTO carries the same
+ * `landing_failed`, the chat and the document are released, and the chat holds a retry proposal
+ * (`<chatId>:retry:<session>`, a `chatProposal` frame).
+ */
+export type RunLandingFailedFrame = { type: 'landingFailed'; session: string; artifact_ref: string; reason: string };
 
 // ── System chat: history, close, attachments (api-types 0.137.0, DES-SYSTEM-CHAT "Crew") ────────
 //
@@ -8365,6 +8804,84 @@ export interface ChatMessageBody {
    *  file: a path it can open (images as images where the CLI reads them) plus, for text and pdf,
    *  the extracted text. Send only when `GET /health.capabilities.chatAttachments === true`. */
   attachments?: string[];
+  /**
+   * (api-types 0.169.0, DES-CHAT-ARTIFACTS-001 §5.1) What studio shows beside the message: the artifact open on the
+   * surface it was sent from, the tab's appearance, and studio's page summary. Send only when
+   * `GET /health.capabilities.chatArtifacts.context === true`. Crew checks the chat's owner and scope before it
+   * reads anything; the seat gets labelled copies (data, never instructions), and the turn's `context` transcript
+   * record says what it was given.
+   */
+  context?: ChatMessageContext;
+}
+
+/** {@link ChatMessageBody.context} (api-types 0.169.0). */
+export interface ChatMessageContext {
+  /** The artifact on the surface the message was sent from (inline, pane, Made or full screen). */
+  artifact?: ChatArtifactContext;
+  /** The tab's effective appearance (DES §9), sent when `chatArtifacts.theme` is advertised. */
+  appearance?: ChatContextAppearance;
+  /**
+   * Studio's page summary (the context pack), kept apart from the person's typed words. Crew labels it as studio's
+   * and reads from it only the run of the page it describes and the runs added as chips. At most 32,768 characters.
+   */
+  page?: string;
+}
+
+/** {@link ChatMessageContext.artifact} (api-types 0.169.0). */
+export interface ChatArtifactContext {
+  /** `<mount>/<doc>`: the mount is a project id or `_unfiled`; the doc is the interactive document name. */
+  ref: string;
+  /** The version the person is looking at (≥ 0: a document's first version is 0), read after the editor's in-flight
+   *  writes finished. */
+  version: number;
+  /** The `data-wid` of each part the person selected (at most 16). */
+  anchors?: string[];
+}
+
+/** {@link ChatMessageContext.appearance} (api-types 0.169.0): studio's appearance scalars, plus an active preview. */
+export interface ChatContextAppearance {
+  theme?: string;
+  accent_h?: number;
+  accent_s?: number;
+  accent_l?: number;
+  ambient?: boolean;
+  ambient_still?: boolean;
+  /** The name of the theme proposal being previewed, when one is. */
+  previewOf?: string;
+}
+
+/**
+ * What one turn's seats were given (api-types 0.169.0, DES-CHAT-ARTIFACTS-001 §5.1 "Bindings kept"): the `context`
+ * transcript record. Paths are relative to the chat's scratch root. A reader folds it onto the turn's `user` record; a
+ * skin that does not know this kind ignores it.
+ */
+export interface ChatContextBinding {
+  /** The open artifact, when the message carried one in scope. */
+  artifact?: {
+    ref: string;
+    title: string;
+    kind: string;
+    /** The version the person was looking at, and the latest when the turn was sent. */
+    viewed: number;
+    head: number;
+    /** `null` for an Unfiled document. */
+    projectId: string | null;
+    /** The copies the seat read: `open/<mount>__<doc>-v<n>.html`. When the version they look at is missing or could
+     *  not be copied, only the latest's copy is here, and `viewed` still says what they asked about. */
+    copies: string[];
+    anchors: string[];
+  };
+  /** The run briefs the seat was given: `context/run-<id>-<sha8>.md` (named by content, so a later brief of the same
+   *  run never replaces these bytes), with the sha256 of the brief as written. */
+  runs: Array<{ id: string; status: string; brief: string; sha256: string }>;
+  /** What was named but not read, and why ("not in this chat's project", "no such run on this daemon"). */
+  refused: Array<{ token: string; reason: string }>;
+  /** Every run and document the person has named in this chat up to this turn. On later turns a run is kept while it
+   *  is still on this daemon and in the chat's scope, a document while it is in the chat's scope; an earlier brief is
+   *  offered again only while its file still holds the bytes its sha256 records. */
+  named: { runs: string[]; docs: string[] };
+  /** Studio's page summary rode as `context.page` (true), never mixed into the person's words. */
+  page: boolean;
 }
 
 /** `GET /chats/:id` → 200. */
@@ -9811,7 +10328,9 @@ export interface SystemRun {
   liveness: SystemRunLiveness;
   /** Plain-words why ("waiting on you: plan approval", "no event for 42 min"). */
   reason: string;
-  /** The cursor unit's phase (`phase_ref`, else `stage`); `null` before planning. */
+  /** The step the cursor unit is on, as display words: the step id its unit id names (`answer-1` → `answer 1`),
+   *  else a named `phase_ref`, else its catalog entry, else its `stage`; an engine-numbered step (`unit-N`, `uN`)
+   *  never shows. `null` before planning. */
   phase: string | null;
   /** The cursor unit's ord; `null` when none is in flight. */
   unitOrd: number | null;
@@ -13806,3 +14325,716 @@ export interface PutVoiceDashboardBody {
   layout: string[];
   widgets: VoiceWidgetManifest[];
 }
+
+// ── Apps (DES-APPS-001 rev 11, slice K2a; api-types 0.172.0) ──────────────────────────────────────
+//
+// An app is a git repo crew owns under `~/.wicked/apps/<slug>`: `apps.json` (an {@link AppSpec}),
+// `queries/<id>.<sql|graphql|json>` (each query's text) and `apps.lock.json` (an {@link AppLock},
+// written by crew's check, never by an agent or a person). Every version is one commit on the repo's
+// `main`; crew keeps, outside the repo, a RECEIPT per (app, tree) saying how the tree was accepted, and
+// only a tree holding one ever runs against a source.
+
+/** The `schema` value of every v1 `apps.json`. */
+export type AppSpecSchemaId = 'wicked.apps/v1';
+
+/**
+ * `apps.json`, the whole app: pages of components on a 12-column grid, the named queries and actions
+ * they bind, the theme and the hosts a link may open. No app code: the `wicked-apps` runtime interprets
+ * this document and nothing else (DES §7.1).
+ *
+ * Identifiers: page and component ids match `^[A-Za-z][A-Za-z0-9_-]{0,63}$` and are unique across the
+ * app; query and action ids match `^[a-z][a-z0-9_]{0,63}$` (a query id is a file name, so lower case
+ * only) and are unique among queries and among actions. crew refuses an unknown key anywhere in the
+ * document, so a field a newer studio writes reaches an older daemon as a refused edit, never as a
+ * silently dropped one.
+ *
+ * The whole document is at most 2 MB of JSON, nests at most 16 deep, holds no list longer than its stated
+ * limit (200 for any list not given one) and no object with more than 256 keys, and never uses the key
+ * `__proto__`.
+ */
+export interface AppSpec {
+  schema: AppSpecSchemaId;
+  /** The app's title (1-120 characters). */
+  name: string;
+  /** At most 2,000 characters. */
+  description?: string;
+  theme?: AppTheme;
+  /** 1-20 pages; the first is the one an app opens on. */
+  pages: AppPage[];
+  /** At most 100. */
+  queries: AppQuery[];
+  /** At most 50. */
+  actions: AppAction[];
+  /**
+   * Exact host names (lower case, no scheme, no port) a link component may open, over https only. The
+   * host shows the full URL before opening it (DES §7.1). At most 50.
+   */
+  linkHosts: string[];
+}
+
+/** Colours are `#rrggbb`. */
+export interface AppTheme {
+  /** `auto` follows the viewer's setting (the default). */
+  mode?: 'light' | 'dark' | 'auto';
+  accent?: string;
+  /** Chart series colours in order (at most 12). */
+  palette?: string[];
+  density?: 'comfortable' | 'compact';
+}
+
+export interface AppPage {
+  id: string;
+  /** 1-80 characters. */
+  title: string;
+  /** At most 100 per page. */
+  components: AppComponent[];
+}
+
+/**
+ * A component's place on its page's 12-column grid: column `x` (0-11), row `y` (0-999), `w` columns
+ * (1-12, `x + w <= 12`) and `h` rows (1-50). Below 640 px the runtime stacks components by (`y`, `x`).
+ */
+export interface AppBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** What every component carries. */
+export interface AppComponentBase {
+  id: string;
+  box: AppBox;
+  /** At most 120 characters; shown above the component. */
+  title?: string;
+  /** Hidden below 640 px. */
+  hideOnPhone?: boolean;
+}
+
+export type AppComponent =
+  | AppTableComponent
+  | AppChartComponent
+  | AppKpiComponent
+  | AppTextComponent
+  | AppFilterComponent
+  | AppFormComponent
+  | AppButtonComponent
+  | AppImageComponent
+  | AppLinkComponent;
+
+export type AppComponentType = AppComponent['type'];
+
+/**
+ * Where a query or action parameter's value comes from on the page (DES §4 "Binding"):
+ *  - `filter.<id>`: the value of filter component `<id>` (a `date-range` filter gives
+ *    `filter.<id>.from` and `filter.<id>.to`);
+ *  - `form.<field>`: a field of the form the binding sits on;
+ *  - `row.<column>`: a column of the row a table's row action was pressed on;
+ *  - `url.<name>`: a parameter of the page's URL.
+ * Viewer values are never bindings: a parameter declared `from: 'viewer.*'` is filled by the server.
+ */
+export type AppBindingRef = `filter.${string}` | `form.${string}` | `row.${string}` | `url.${string}`;
+// The template type is the shape; crew's grammar is the rule: `filter.<component id>` with an optional
+// `.from`/`.to`, `form.<field name>`, `row.<output column>`, `url.<^[A-Za-z_][A-Za-z0-9_]{0,63}$>`.
+
+/** A component reading a query: the query's id, and a binding for any of its parameters. */
+export interface AppQueryBinding {
+  query: string;
+  params?: Record<string, AppBindingRef>;
+}
+
+/** A control that runs an action: its label, the action's id, and a binding for any of its parameters. */
+export interface AppActionBinding {
+  /** 1-60 characters. */
+  label: string;
+  action: string;
+  params?: Record<string, AppBindingRef>;
+}
+
+/** How a value is shown. `decimals` is 0-10; a currency names its ISO 4217 code. */
+export type AppFormat =
+  | { kind: 'currency'; currency: string; decimals?: number }
+  | { kind: 'text' | 'number' | 'percent' | 'date' | 'datetime' | 'duration'; decimals?: number };
+
+export interface AppTableColumn {
+  /** A declared output column of the table's query. */
+  column: string;
+  label?: string;
+  format?: AppFormat;
+}
+
+export interface AppTableComponent extends AppComponentBase {
+  type: 'table';
+  data: AppQueryBinding;
+  /** Shown columns in order; absent = every declared output column. */
+  columns?: AppTableColumn[];
+  /** A button on every row (at most 4); its parameters may bind `row.<column>`. */
+  rowActions?: AppActionBinding[];
+  /** Rows per page, 5-500. */
+  pageSize?: number;
+}
+
+export interface AppChartSeries {
+  /** A declared output column of the chart's query. */
+  column: string;
+  label?: string;
+  color?: string;
+}
+
+export interface AppChartComponent extends AppComponentBase {
+  type: 'chart';
+  chart: 'line' | 'bar' | 'area' | 'pie';
+  data: AppQueryBinding;
+  /** The category (x axis, or pie slice) column. */
+  x: string;
+  /** 1-12 series; a pie has exactly one. */
+  series: AppChartSeries[];
+  stacked?: boolean;
+}
+
+export interface AppKpiComponent extends AppComponentBase {
+  type: 'kpi';
+  data: AppQueryBinding;
+  /** The column of the first row shown as the figure. */
+  value: string;
+  format?: AppFormat;
+  /** A column of the first row shown as the change beside the figure. */
+  delta?: string;
+  /** A line under the figure, at most 120 characters ("vs previous 90 days"). */
+  caption?: string;
+}
+
+/** Author text, always rendered as text (never HTML or markdown). At most 4,000 characters. */
+export interface AppTextComponent extends AppComponentBase {
+  type: 'text';
+  text: string;
+  style?: 'heading' | 'body' | 'caption';
+}
+
+/** `value` and `label` are at most 200 characters each. */
+export interface AppFilterOption {
+  value: string;
+  label?: string;
+}
+
+/** A select filter's choices: a query's columns, or a fixed list of at most 200. */
+export type AppFilterOptions =
+  | { kind: 'query'; query: AppQueryBinding; value: string; label?: string }
+  | { kind: 'values'; values: AppFilterOption[] };
+
+export interface AppFilterComponent extends AppComponentBase {
+  type: 'filter';
+  filter: 'select' | 'date-range' | 'search';
+  label?: string;
+  /** `select` only: the choices, from a query (its `value` and optional `label` columns) or a fixed list. */
+  options?: AppFilterOptions;
+  /** The value before the viewer picks one: a `select`/`search` string, or `{ lastDays }` for a `date-range`. */
+  default?: string | { lastDays: number };
+}
+
+export interface AppFormField {
+  /** `^[a-z][a-z0-9_]{0,63}$`; bound as `form.<name>`. */
+  name: string;
+  label?: string;
+  input: 'text' | 'textarea' | 'number' | 'date' | 'checkbox' | 'select';
+  required?: boolean;
+  /** `select` only (at most 200). */
+  options?: AppFilterOption[];
+}
+
+export interface AppFormComponent extends AppComponentBase {
+  type: 'form';
+  /** 1-30 fields. */
+  fields: AppFormField[];
+  /** The action the form submits; its parameters bind `form.<name>`. */
+  submit: AppActionBinding;
+}
+
+export interface AppButtonComponent extends AppComponentBase {
+  type: 'button';
+  action: AppActionBinding;
+}
+
+/**
+ * An image carried in the spec: `src` is a `data:image/(png|jpeg|gif|webp);base64,…` URI whose DECODED
+ * payload is at most 256 KB (262,144 bytes; the URI itself is about a third longer); `alt` is at most
+ * 300 characters. No network images (the frame's CSP has none) and no SVG.
+ */
+export interface AppImageComponent extends AppComponentBase {
+  type: 'image';
+  src: string;
+  alt: string;
+}
+
+/**
+ * Where a link goes: another page of the app (with URL parameters bound like a query's), or out to an
+ * `https://` URL whose host is in {@link AppSpec.linkHosts} (no credentials, no port).
+ */
+export type AppLinkTarget = { kind: 'page'; page: string; params?: Record<string, AppBindingRef> } | { kind: 'href'; href: string };
+
+export interface AppLinkComponent extends AppComponentBase {
+  type: 'link';
+  label: string;
+  to: AppLinkTarget;
+}
+
+/** A source kind a query reads; it names the text file: `sql` `.sql`, `graphql` `.graphql`, else `.json`. */
+export type AppQueryKind = 'sql' | 'graphql' | 'rest' | 'mcp' | 'crew';
+
+/** A declared output column's type. A value the source cannot confirm is validated on every row (DES §7.2). */
+export type AppColumnType = 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'datetime';
+
+export interface AppOutputColumn {
+  /** `^[A-Za-z_][A-Za-z0-9_-]{0,127}$` (alias an SQL expression, e.g. `AS order_total`). */
+  name: string;
+  type: AppColumnType;
+  nullable?: boolean;
+}
+
+/** `load` (the default; cached 5 s), `every` N seconds (an integer, 15-86,400), or `events` (the built-in `crew` source only). */
+export type AppRefresh = { mode: 'load' } | { mode: 'every'; seconds: number } | { mode: 'events' };
+
+/**
+ * One parameter, a JSON Schema subset (no `pattern`: an agent-written regular expression would run on
+ * the server). Names match `^[A-Za-z_][A-Za-z0-9_]{0,63}$`. `from` makes it VIEWER-BOUND: the server fills
+ * it from verified claims and refuses a client value for it, and no component may bind it.
+ *
+ * Constraints apply to their type only: `format`, `minLength` and `maxLength` to strings, `minimum` and
+ * `maximum` to numbers and integers; an `array` takes neither `enum` nor `default`. Bounds are not
+ * reversed; lengths count Unicode code points, as JSON Schema does. A `default` and every `enum` value
+ * satisfy the whole declaration (a `date` is a real calendar date, years 0001-9999; a `date-time` is
+ * RFC 3339 with seconds 00-59, any fraction, `Z` or an offset); strings in a `default` or an `enum` are at
+ * most 1,000 and 200 characters. A REQUIRED parameter with neither `from` nor a `default` must be bound at every
+ * component that uses its query or action.
+ */
+export interface AppParamSchema {
+  type: 'string' | 'number' | 'integer' | 'boolean' | 'array';
+  /** `array` only. */
+  items?: { type: 'string' | 'number' | 'integer' };
+  format?: 'date' | 'date-time' | 'uuid' | 'email';
+  enum?: Array<string | number>;
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  default?: string | number | boolean;
+  description?: string;
+  from?: 'viewer.email' | 'viewer.name' | 'viewer.id' | 'viewer.groups';
+}
+
+/** A query's or action's parameters: a JSON Schema object (at most 30 properties). */
+export interface AppParamsSchema {
+  type: 'object';
+  properties: Record<string, AppParamSchema>;
+  required?: string[];
+}
+
+/**
+ * A named read (DES §4 "Query"). Its text is `queries/<id>.<ext>` ({@link AppQueryKind}); the browser
+ * only ever sends the id and parameter values.
+ */
+export interface AppQuery {
+  id: string;
+  /** The source's name in crew's registry, or `crew` (the built-in source). */
+  source: string;
+  kind: AppQueryKind;
+  description?: string;
+  params?: AppParamsSchema;
+  /** 1-200 declared output columns; the result is projected to exactly these. */
+  output: AppOutputColumn[];
+  /** REST, GraphQL, MCP and crew (never SQL): where the rows are (a JSONPath subset, e.g. `$.items[*]`). */
+  rowPath?: string;
+  /** REST, GraphQL, MCP and crew (never SQL): where "another page exists" is read. */
+  morePath?: string;
+  refresh?: AppRefresh;
+  /** A public app may hold only public queries (DES §9.3). */
+  public?: boolean;
+}
+
+/** A value an action sends: a parameter, a literal fixed by the app (a string of at most 1,000 characters), a viewer claim, or crew's `now` or new uuid. */
+export type AppValue =
+  | AppParamValue
+  | { kind: 'literal'; value: string | number | boolean | null }
+  | { kind: 'viewer'; claim: 'email' | 'name' | 'id' }
+  | { kind: 'crew'; value: 'now' | 'uuid' };
+
+/** A declared parameter of the action. */
+export interface AppParamValue {
+  kind: 'param';
+  name: string;
+}
+
+/**
+ * An API action (DES §4 "Action"): one REST operation or MCP write tool by its registry tool name, or
+ * one GraphQL mutation document with one root field (at most 16 KB of UTF-8).
+ */
+export interface AppApiAction {
+  id: string;
+  kind: 'api';
+  source: string;
+  /** The mutation's single root field is the source stage's check. */
+  call: { kind: 'tool'; tool: string } | { kind: 'mutation'; mutation: string };
+  /** At most 50. */
+  args: Record<string, AppValue>;
+  params?: AppParamsSchema;
+  /** Shown on the card as "The app says" (at most 500 characters). */
+  description?: string;
+}
+
+/**
+ * A declared Postgres row write (DES §7.4): crew generates the one statement. `table` is
+ * schema-qualified (`support.tickets`, plain identifiers); `key` binds every primary-key column to a
+ * REQUIRED parameter; `set` is every column for an insert (each key column set from its own key
+ * parameter), the changed columns for an update (never a key column), and absent for a delete. Whether
+ * the columns are the table's real ones is the source stage's check.
+ */
+export interface AppRowWriteAction {
+  id: string;
+  kind: 'row-write';
+  source: string;
+  table: string;
+  op: 'insert' | 'update' | 'delete';
+  /** At most 200 columns. */
+  set?: Record<string, AppValue>;
+  /** 1-16 columns. */
+  key: Record<string, AppParamValue>;
+  params?: AppParamsSchema;
+  description?: string;
+}
+
+export type AppAction = AppApiAction | AppRowWriteAction;
+
+/**
+ * `apps.lock.json`, written by crew's check and committed with the tree it checked; never by an agent or
+ * a person (an edit that names it is refused). It pins what each query and action USES (DES §4):
+ * per source the kind, connection descriptor and its hash; per query the hash of its text and its
+ * contract hash; per action its declaration hash and contract hash; per upload the snapshot digest.
+ * Never a secret, never snapshot bytes. Hashes are lower-case hex SHA-256.
+ */
+export interface AppLock {
+  schema: 'wicked.apps.lock/v1';
+  sources: Record<string, AppLockSource>;
+  queries: Record<string, AppLockQuery>;
+  actions: Record<string, AppLockAction>;
+  uploads: Record<string, { digest: string }>;
+}
+
+export interface AppLockSource {
+  kind: string;
+  /** The non-secret connection descriptor (DES §4 "Source"). */
+  descriptor: Record<string, unknown>;
+  descriptorHash: string;
+}
+
+export interface AppLockQuery {
+  source: string;
+  textHash: string;
+  contractHash: string;
+}
+
+export interface AppLockAction {
+  source: string;
+  actionHash: string;
+  contractHash: string;
+}
+
+// ── Apps: the store and its routes (DES §6.4, §7.6, §9.1) ────────────────────────────────────────
+
+/**
+ * How a tree was accepted (DES §9.1). Only `you`, `reviewed` and `restored` make a tree part of the
+ * app's ACCEPTED HISTORY (undo, redo and restore move only within it); `published` binds a tree that
+ * already held one of those to a publish manifest.
+ */
+export type AppReceiptKind = 'you' | 'reviewed' | 'restored' | 'published';
+
+/**
+ * crew's record that a tree of THIS app passed a check and was accepted. Keyed by (app, tree): the same
+ * tree in another app holds nothing there. Minted only by crew: on a human actor's edit, undo, redo or
+ * restore, on an `apps-turn` run whose review by a distinct seat named the tree, and on a consented
+ * publish. Never stored in the app repo (agent seats mount it).
+ */
+export interface AppReceipt {
+  kind: AppReceiptKind;
+  tree: string;
+  /** The version that landed with it. */
+  version: number;
+  /** Unix millis. */
+  at: number;
+  /** Who accepted it: the person, or for `reviewed` the actor who launched the turn. */
+  actor: Actor;
+  /**
+   * `restored`: the version restored, and that version's own provenance followed through any chain of
+   * restores (`originKind` is `you` or `reviewed`, `originVersion` the version that first held it).
+   */
+  restoredFrom?: { version: number; originKind: 'you' | 'reviewed'; originVersion: number };
+  /** `reviewed`: the turn's run and the seats that built and reviewed it (always distinct). */
+  review?: { runId: string; builder: string; reviewer: string };
+  /** `published`: the publish run, the manifest digest and each produced artifact's digest. */
+  publish?: { runId: string; manifestDigest: string; artifacts: Record<string, string> };
+}
+
+/** Which checks ran before a version landed (DES §6.2 "Checks are staged by what changed"). */
+export interface AppCheckSummary {
+  /**
+   * `spec`: schema, bindings, link hosts and file confinement only (a layout, prop, theme or label
+   * change). `data`: those plus the read policy and the per-kind source check for what changed.
+   * `full`: those for every query and action (an undo, redo or restore, against today's sources).
+   */
+  level: 'spec' | 'data' | 'full';
+  /** Queries and actions the source stage checked (empty at `spec`). */
+  checked: string[];
+}
+
+/** One version: one commit on the app repo's `main`. */
+export interface AppVersion {
+  /** 1, 2, 3, … per app (the strip's `v14`). */
+  version: number;
+  commit: string;
+  tree: string;
+  /** The version it was made on; `null` for the first. */
+  base: number | null;
+  /** Unix millis. */
+  at: number;
+  /** A person (`human`), a seat that built a turn (`seat`), or crew itself (`crew`, an app's first version). */
+  author: { kind: 'human' | 'seat' | 'crew'; id: string };
+  /** The receipt it landed with; `null` = this tree never runs against a source. */
+  receipt: AppReceipt | null;
+  /** One line for the strip ("Moved the KPIs above the charts"), at most 200 characters. */
+  summary: string;
+  check: AppCheckSummary;
+}
+
+/**
+ * The undo pointer (DES §6.4), kept per app by crew so every tab agrees. `states` are the versions of
+ * the accepted history in order and `pointer` indexes the current one. Undo lands `states[pointer-1]`'s
+ * tree as a new version and moves the pointer back; redo lands `states[pointer+1]`'s; a new edit,
+ * landed turn or restore drops everything after the pointer and appends itself.
+ */
+export interface AppHistory {
+  states: number[];
+  pointer: number;
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+/** A turn in flight: the app is read-only for edits, undo, redo and restore until it ends (`409 turn_in_flight`). */
+export interface AppTurnState {
+  runId: string;
+  /** Unix millis. */
+  startedAt: number;
+  /** The version the turn builds on. */
+  base: number;
+  /** The actor id that launched it. */
+  actor: string;
+}
+
+/** `GET /apps` item. */
+export interface AppSummary {
+  /** `^[a-z][a-z0-9-]{0,47}$`; `check` and `uploads` are reserved. */
+  slug: string;
+  name: string;
+  projectId: string;
+  /** The app repo's id in crew's repo registry. */
+  repoId: string;
+  /** Unix millis. */
+  createdAt: number;
+  head: { version: number; tree: string; receipt: AppReceiptKind | null };
+  turn: AppTurnState | null;
+}
+
+/** `GET /apps` (observer); `?project=<id>` keeps one project's apps. */
+export interface AppsListResponse {
+  apps: AppSummary[];
+}
+
+/** `POST /apps` (operator): a new app, an empty repo in the project with crew's first version. */
+export interface CreateAppBody {
+  slug: string;
+  /** The app's title; defaults to the slug. */
+  name?: string;
+  projectId: string;
+}
+
+/** The app at head: the spec, the lock, every query's text, the versions and the undo pointer. */
+export interface AppDetail extends AppSummary {
+  spec: AppSpec;
+  lock: AppLock;
+  /** Query id → its text at head. */
+  queryText: Record<string, string>;
+  /** Oldest first. */
+  versions: AppVersion[];
+  history: AppHistory;
+}
+
+/** `GET /apps/:app` (observer), and `POST /apps` (201). */
+export interface AppDetailResponse {
+  app: AppDetail;
+}
+
+/**
+ * One change in an edit burst. `spec` replaces `apps.json`; `query-text` writes the text of a query the
+ * resulting spec declares (crew removes the text of a query the spec no longer declares). Nothing else
+ * in the repo can be written: `apps.lock.json` is crew's.
+ */
+export type AppEditOp = { op: 'spec'; spec: AppSpec } | { op: 'query-text'; query: string; text: string };
+
+/**
+ * `POST /apps/:app/edits` (HUMAN operator only): one `you` version from one edit burst (1-50 ops). `base`
+ * is the head version the edit was made on: a stale one is `409 stale_base`, and while a turn runs every
+ * edit is `409 turn_in_flight`.
+ */
+export interface AppEditsBody {
+  base: number;
+  ops: AppEditOp[];
+  /** The strip's line; crew writes one when absent. */
+  summary?: string;
+}
+
+/** `POST /apps/:app/undo` and `/redo` (HUMAN operator only). */
+export interface AppHistoryMoveBody {
+  base: number;
+}
+
+/**
+ * `POST /apps/:app/restore` (HUMAN operator only): land `version` (a version number, or a commit of the
+ * app repo) as a new version, only when its tree holds an accepted receipt for this app.
+ */
+export interface AppRestoreBody {
+  base: number;
+  version: number | string;
+}
+
+/** The answer to an edit, undo, redo or restore that landed: the app after it, and the version it made. */
+export interface AppLandedResponse {
+  app: AppDetail;
+  landed: AppVersion;
+}
+
+/**
+ * `POST /apps/:app/turns` (operator): one chat message becomes one governed `apps-turn` run (Build → Check →
+ * Review) on the head version. While it runs the app is read-only for edits, undo, redo and restore, and a second
+ * turn is `409 turn_in_flight`.
+ */
+export interface AppTurnBody {
+  /** The head version the message was written on; a stale one is `409 stale_base`. */
+  base: number;
+  /** 1-8,000 characters. */
+  message: string;
+  /** Component ids the message is about (the composer's chips), at most 20. */
+  about?: string[];
+}
+
+/** `POST /apps/:app/turns` 202. */
+export interface AppTurnResponse {
+  runId: string;
+  turn: AppTurnState;
+}
+
+/** `POST /apps/:app/query` (observer): run one named query of an accepted version (DES §7.2). */
+export interface AppQueryBody {
+  /** A version number, or a commit of the app repo; its tree must hold an accepted receipt. */
+  version: number | string;
+  query: string;
+  params?: Record<string, unknown>;
+}
+
+/** One cell: values are rendered as text by the runtime. */
+export type AppCell = string | number | boolean | null;
+
+/** `POST /apps/:app/query` 200 (DES §7.2). `rows` are aligned with `columns`. */
+export interface AppQueryResponse {
+  columns: AppOutputColumn[];
+  rows: AppCell[][];
+  truncated: boolean;
+  hasMore: boolean;
+  ms: number;
+  /** Unix millis of the cached answer, `null` when it ran now. */
+  cachedAt: number | null;
+}
+
+/** One reason a check refused a tree. `path` is a JSON path into `apps.json`, or a repo path. */
+export interface AppCheckFinding {
+  stage: 'spec' | 'files' | 'policy' | 'source';
+  code: string;
+  path: string;
+  message: string;
+}
+
+/**
+ * Every refusal the app routes answer, by `code`:
+ *  - 400 `bad_request`; 403 `human_only` (the route needs a human operator: an agent-kind token is refused);
+ *  - 404 `unknown_app`, `unknown_version`, `unknown_query`, `unknown_project`;
+ *  - 409 `stale_base` (with `head`), `turn_in_flight` (with `turn`), `not_accepted` (the tree holds no
+ *    accepted receipt for this app), `nothing_to_undo`, `nothing_to_redo`, `slug_taken` (with
+ *    `suggestion`), `source_check_unavailable` (the tree has queries or actions and this daemon cannot
+ *    run the source stage yet, so nothing lands);
+ *  - 422 `check_failed` (with `findings`), `reserved_slug`;
+ *  - 429 `rate_limited` (with `retryAfterMs`: a query queue or a per-viewer rate is full, DES §7.5);
+ *  - 501 `not_implemented` (a route a later slice serves; nothing happened);
+ *  - 503 `apps_unavailable`.
+ */
+export interface AppErrorBody {
+  code:
+    | 'bad_request'
+    | 'human_only'
+    | 'unknown_app'
+    | 'unknown_version'
+    | 'unknown_query'
+    | 'unknown_project'
+    | 'stale_base'
+    | 'turn_in_flight'
+    | 'not_accepted'
+    | 'nothing_to_undo'
+    | 'nothing_to_redo'
+    | 'slug_taken'
+    | 'source_check_unavailable'
+    | 'check_failed'
+    | 'reserved_slug'
+    | 'not_implemented'
+    | 'rate_limited'
+    | 'apps_unavailable';
+  error: string;
+  /** `rate_limited`: when to try again (also sent as `Retry-After`). */
+  retryAfterMs?: number;
+  head?: number;
+  turn?: AppTurnState;
+  findings?: AppCheckFinding[];
+  suggestion?: string;
+}
+
+/**
+ * {@link HealthCapabilities.apps} (api-types 0.172.0): present when crew serves the app store
+ * (`/api/v1/apps`, list, add, read, edits, undo, redo, restore); each flag is true only once its slice
+ * serves that route for real rather than answering `501`.
+ */
+export interface AppsCapabilities {
+  /** `POST /apps/:app/query` runs queries (until then it checks the receipt, then answers `501`). */
+  query: boolean;
+  /** `POST /apps/:app/actions/:id/prepare|run|grant`, `GET …/actions/records/:id`. */
+  actions: boolean;
+  /** `POST /apps/:app/turns` launches `apps-turn` runs. */
+  turns: boolean;
+  /** `POST /apps/:app/publish`. */
+  publish: boolean;
+  /** `POST /apps/uploads`. */
+  uploads: boolean;
+  /** The read policy and the per-kind source check run, so a change to queries or actions can land. */
+  sourceCheck: boolean;
+}
+
+/**
+ * `POST /repos` body. `create: true` (api-types 0.172.0, DES-APPS-001): crew makes `<apps root>/<name>`
+ * (`~/.wicked/apps` by default), runs `git init` with one empty commit and registers it; no onboarding
+ * run starts (`onboardRunId: null`), and `rootPath`/`gitUrl` are refused beside it. A taken name is
+ * `409 slug_taken` with a `suggestion`.
+ */
+export interface RegisterRepoBody {
+  name: string;
+  rootPath?: string;
+  gitUrl?: string;
+  create?: true;
+  projectId?: string;
+  channel?: 'studio' | 'cli' | 'api';
+  actor?: string;
+  autoCapture?: boolean;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.167.0",
+  "version": "0.172.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",