wicked-crew-api-types 0.178.0 → 0.191.0

package/index.d.ts

@@ -259,6 +259,12 @@ export interface HealthCapabilities {
    * send the field (its strict launch schema 400s on it) and do not call the preview.
    */
   linkedIssuesExclude?: boolean;
+  /**
+   * (api-types 0.187.0, DES-PM-001 PM-1) This daemon serves project-management sources: the `pm` registration field,
+   * the human-only `/tracker-links` routes (and `/tracker-links/issues`), `GET /sources/:name/trackers`, the tracker
+   * set in linked issues (`LinkedIssuesPreviewBody.projectId`), and `/runs/:id/tracker-actions`. Absent = none of it.
+   */
+  trackerLinks?: boolean;
   /**
    * Repo-bound runs get an EVIDENCE ROOT for walkthroughs (WT-W1, api-types 0.74.0): the engine
    * addon takes `LaunchOptions.evidenceRoot` (wicked-core-ts ≥ 0.7.35), so a walkthrough step on a
@@ -353,6 +359,13 @@ export interface HealthCapabilities {
    * ABSENT on an older daemon: read as `false` and hide the switch.
    */
   powerMode?: boolean | undefined;
+  /**
+   * (api-types 0.188.0, crew#1139) A `plan_approval` approval carries the operator's note: `GateDecision.amend`
+   * on `{approve: true}` or `{approve: true, plan}` at a plan gate lands on the first creator step the plan
+   * releases (else its first step) as `unitReworkAmended`. ABSENT or `false` (an engine without it refuses the
+   * note): offer no note field on the plan card.
+   */
+  planGateNote?: boolean | undefined;
   /**
    * (api-types 0.156.0, DES-VOICE) Voice mode's routes are served: `GET /voice/status`, `POST|DELETE /voice/model`,
    * `POST /voice/transcribe` and `GET|PUT /voice/dashboard`. Whether transcription can run NOW (the engine and
@@ -2456,6 +2469,18 @@ export interface GateDecision {
      *  `operator_judgment` then applies). Refused (409, gate left open) at every other gate and on a
      *  run that does not require QE acceptance. Engine: wicked-core-ts after 0.16.3. */
     | 'skip_qe'
+    /** (api-types 0.190.0, DES-RULE-CHECK-001 S2) At a `rules_unchecked` gate (a steering rule no
+     *  judge ruled on), with `approve: true` and no `amend` / `amendScope` / `plan`: RE-RUN THE RULE
+     *  CHECK on the same work (the step's seat does not run again; every verdict whose rule and
+     *  evidence are unchanged is reused). The engine refuses it at any other gate (409). */
+    | 'retry_rules'
+    /** (api-types 0.190.0) SKIP UNCHECKED STEERING RULES, each with the person's written reason in
+     *  {@link GateDecision.skipRules} (required), `approve: true`, no `amend` / `amendScope` / `plan`;
+     *  then the check re-runs. A skipped rule's row is `skipped`, labelled with its reason on the
+     *  gate receipt and the delivery. Only a rule the gate holds as `unchecked` can be skipped (a
+     *  `broken` one denies); the human operator's call alone (a seat or standing order: 403
+     *  `human_operator_only`). Refused (409, gate left open) at any other gate. */
+    | 'skip_rules'
     /** (core#820) A `consent` gate's choice from its dry-run plan (`awaitingHuman.choices`), with
      *  `approve: true`: `consent:worker` (the default), `consent:operator`, …; `reject` declines. */
     | `consent:${string}`;
@@ -2464,7 +2489,8 @@ export interface GateDecision {
    * Absent = `'cursor'` (today: the gated unit's description). `'creator'` — the first creator
    * phase at or after the cursor receives it (`unitReworkAmended{scope: 'creator'}`) while the
    * cursor dispatches unamended: the intake steer that must reach the fix phase, not triage.
-   * Identical text already present on the target is not appended twice.
+   * Identical text already present on the target is not appended twice. At a `plan_approval` gate
+   * it does not apply (api-types 0.188.0): the note lands as {@link GateDecision.plan} says.
    */
   amendScope?: 'cursor' | 'creator';
   /**
@@ -2473,8 +2499,16 @@ export interface GateDecision {
    * `plan.proposed{by:"human", kind:"edit"}`, floor-fills it (phases below the floor are ADDED,
    * never refused) and accepts it as the next `plan_rev` — or refuses it (`plan.refused`) and
    * re-opens the gate under a new `gate_id`, answering `awaiting_human`. Requires `approve: true`
-   * and `action` omitted or `'edit_plan'`; `amend` / `amendScope` do not apply. A plain approve
-   * (no `plan`) releases the held plan as it is; `approve: false` rejects (cancels).
+   * and `action` omitted or `'edit_plan'`; no `amendScope` (a 400). A plain approve (no `plan`)
+   * releases the held plan as it is; `approve: false` rejects (cancels).
+   *
+   * THE OPERATOR'S NOTE (api-types 0.188.0, crew#1139; {@link HealthCapabilities.planGateNote}): `amend`
+   * on a plan gate's approve, with or without `plan`, is carried to the steps the plan releases. It lands
+   * once the answer applies (after an edit's re-plan, so on the edited plan's units) on the FIRST CREATOR
+   * step at or after the cursor (`unitReworkAmended{scope: 'creator'}`), else on the cursor step
+   * (`scope: 'cursor'`), and the gate's recorded answer carries it. A refused edit re-opens the gate and
+   * lands nothing. An engine without it answers 501 for a note beside `plan` and 409 for one on a plain
+   * approve, with the gate left open.
    */
   plan?: LaunchPlan;
   /**
@@ -2510,6 +2544,9 @@ export interface GateDecision {
    * draft, **409** `draft_changed` when an id is not in the draft as it reads now (the gate stays open).
    */
   keepRules?: string[];
+  /** (api-types 0.190.0) With `action: 'skip_rules'` (and only with it): each unchecked rule to
+   *  skip, with the person's written reason (both non-empty, no rule twice). */
+  skipRules?: RuleSkipAnswer[];
 }
 
 /**
@@ -3278,6 +3315,50 @@ export interface AssuranceReceipt {
    *  ABSENT when every judge was the run's own (the routine case) or on an older engine. A unit
    *  receipt carries at most one; a delivery receipt lists the run's. */
   judgeFallbacks?: JudgeFallback[];
+  /** (api-types 0.190.0, DES-RULE-CHECK-001 S2) Every steering rule in force and its verdict at this
+   *  gate (the review step's rule check), or, on a delivery receipt, the worst row per rule across
+   *  the run's gates. ABSENT when no rule check ran (not a review gate, no rule store, no change, an
+   *  older engine). Deny-dominates: a `broken` row denied the gate, an `unchecked` row held it. */
+  rules?: RuleVerdict[];
+}
+
+/** (api-types 0.190.0) A steering rule's verdict: `kept` · `broken` · `n_a` (not applicable) ·
+ *  `unchecked` (no judge ruled; holds the gate) · `skipped` (the operator skipped it, with a reason;
+ *  a confirmed waiver reads `waived by instruction (…), confirmed by <who>: <reason>`) · `waived`
+ *  (the person's own instruction conflicts with the rule: holds the gate until the person confirms
+ *  it with a reason through `skip_rules`; never kept, never skipped silently) · `deferred` (api-types
+ *  0.191.0: the rule's subject only exists at delivery, by recorded fact: obligations
+ *  `evidence:delivery` or `applies_to` naming only the deliver step; it does not hold review or QE,
+ *  and the deliver step's receipt carries its verdict on the pull request's text). */
+export type RuleVerdictStatus = 'kept' | 'broken' | 'n_a' | 'unchecked' | 'skipped' | 'waived' | 'deferred';
+/** How it was reached: `fact` (a recorded fact ruled it out) · `judge` (a seat distinct from the
+ *  creators ruled) · `machine` (an engine check, e.g. `check:test-fails-on-base`) · `cache` (an
+ *  earlier verdict on the same rule and evidence) · `operator` (skipped) · `none` (unchecked). */
+export type RuleVerdictHow = 'fact' | 'judge' | 'machine' | 'cache' | 'operator' | 'none';
+
+/** (api-types 0.190.0) One steering rule's row on an assurance receipt. */
+export interface RuleVerdict {
+  ruleId: string;
+  status: RuleVerdictStatus;
+  how: RuleVerdictHow;
+  /** Why, in words: the fact, the cite, the skip's reason (`skipped by <who>: <reason>`), or why nobody ruled. */
+  reason: string;
+  /** The evidence the judge or the machine check cited, when one ruled. */
+  cite?: string;
+  /** The seat that ruled. */
+  judge?: string;
+  /** SHA-256 of the rule's judged content (statement, criteria, obligations, facets). */
+  ruleKey: string;
+  /** SHA-256 of the evidence the verdict read; absent on a `fact` row. */
+  evidenceKey?: string;
+}
+
+/** (api-types 0.190.0) One skip in a `skip_rules` gate answer. */
+export interface RuleSkipAnswer {
+  /** The unchecked rule's id. */
+  id: string;
+  /** The person's written reason (labelled on the run, the gate and the delivery). */
+  reason: string;
 }
 
 /**
@@ -3604,7 +3685,10 @@ export interface GateEscalatedEvent {
    * (0.7.27) · `governance` · `same_seat_evaluator` (a `dead_seat` condition: the review ran on its
    * builder's seat — core-ts 0.7.46, EX-01) · `evaluator_error` · `judge_unavailable` (a
    * `judge_unavailable` condition; since core-ts 0.7.46 also a required judge with no distinct
-   * seat — EX-02). `""` (EMPTY) = a hook veto whose source identity was folded away
+   * seat — EX-02) · `rule_check` (a `rule_broken` condition: a steering rule the review's rule check
+   * found broken, api-types 0.190.0) · `rules_unchecked` (a `rules_unchecked` condition: a rule no
+   * judge ruled on, answered by `retry_rules` / `skip_rules`). `""` (EMPTY) = a hook veto whose
+   * source identity was folded away
    * (`actor.rs` `boundary_deny` arm with no structured denial) — a reader keys copy on
    * `(condition, denialSource)` and treats `""` beside `boundary_deny` as input governance.
    */
@@ -6034,6 +6118,11 @@ export interface LinkedIssuesPreviewBody {
   problem: string;
   repoRef?: string;
   excludeLinkedIssues?: string[];
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3.2) The project the launch is filed in: with a registered PM source, a
+   * reference resolves only through the tracker set of this project and `repoRef`.
+   */
+  projectId?: string;
 }
 
 /** The `POST /linked-issues/preview` 200 body: the same reading `POST /runs` does, nothing launched. */
@@ -6064,6 +6153,23 @@ export interface LinkedIssue {
   chars?: number;
   /** (crew#825; additive) `true` when the launch left this ref out (`excludeLinkedIssues`). */
   excluded?: true;
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3.2, Q-PM5) Read through a registered PM source: the tracker that admitted it,
+   * that source's registry name, and its system. Absent on the daemon's `gh` path (no GitHub source registered).
+   */
+  trackerId?: string;
+  source?: string;
+  system?: PmSystem;
+  /**
+   * (api-types 0.187.0) Why it was not read, as a code: `not_linked` (no tracker of the run's project or repos has
+   * it), `ambiguous` (two trackers in the set share the key: pick one, which writes `<source>:<KEY-N>`), `hidden`
+   * (the source's Agents switches keep this project out), `query_off`, `unavailable` (the vendor could not be
+   * read), `not_found`. To pick among `ambiguous` candidates, write `<source>:<KEY-N>` (two sources) or
+   * `<source>@<tenant>:<KEY-N>` (two sites behind one source).
+   */
+  code?: 'not_linked' | 'ambiguous' | 'hidden' | 'query_off' | 'unavailable' | 'not_found';
+  /** (api-types 0.187.0) `ambiguous` only: the trackers that share the key, for the composer to pick from. */
+  candidates?: Array<{ source: string; tenant: string; tenantLabel?: string; key: string; trackerId: string }>;
 }
 
 /** The `POST /runs` 201 body. `linkedIssues` (crew#627, additive) is present when the intent of a
@@ -7392,6 +7498,10 @@ export interface WorkflowCatalogInput {
  * 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).
+ * (api-types 0.187.0, additive) `app` = a new app by chat: `POST /apps` in the project, then the words as its
+ * first turn, `POST /apps/:app/turns` (DES-APPS-001 §6.2); offered only where `GET /health.capabilities.apps.turns`
+ * is true; `repo` = register a repository, which onboards it (`POST /repos`; studio's Add a repository). A
+ * client that does not know a kind shows the entry and does not start it.
  */
 export type WorkflowCatalogLaunch =
   | { kind: 'run'; workflow: string }
@@ -7399,6 +7509,8 @@ export type WorkflowCatalogLaunch =
   | { kind: 'compose' }
   | { kind: 'document'; style: 'web' | 'doc' | 'ppt' | 'brochure' }
   | { kind: 'chat' }
+  | { kind: 'app' }
+  | { kind: 'repo' }
   | { kind: 'none' };
 
 /** The requesting operator's use of an entry (scope: {@link WorkflowCatalogResponse.usage}). */
@@ -12316,7 +12428,61 @@ export interface PutDeliveryFreezeBody {
  * sources: registered through the same preview/save, but with NO tools — nothing of theirs is ever
  * offered to a governed run. Their preview answers {@link McpPreviewResponse.source} (the catalog).
  */
-export type McpUpstreamKind = 'mcp-stdio' | 'mcp-http' | 'rest' | 'sql' | 'graphql';
+export type McpUpstreamKind = 'mcp-stdio' | 'mcp-http' | 'rest' | 'sql' | 'graphql' | 'toolbox-source';
+
+// ── The one registry's entry (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5) ─────────────────────
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) A database source as MCP Toolbox for Databases models it: its
+ * own source document (`kind: source`, `type`, that type's fields), which the registry stores as the source of
+ * truth for `kind: 'toolbox-source'`. Checked against crew's deployment policy for the pinned Toolbox release
+ * (v1.15.0) at preview and at save: a field that bypasses the address check (`connectionString`), names a host
+ * path, or tunes the driver is a 400 `refused_field`; a field only crew writes (`name`, `queryParams`,
+ * `connectTimeout`: the TLS settings, startup parameters and timeouts) a 400 `crew_written_field`; any other
+ * unknown field a 400 `unknown_field`. `password` is exactly `"${WICKED_SRC_1}"`, the placeholder naming
+ * `auth.ref`'s secret (a value is a 400 `secret_literal`); `${` anywhere else is a 400 `interpolation`.
+ */
+// A type alias (not an interface) so it is assignable to a plain record: the route takes any object and the
+// deployment policy judges each field.
+export type ToolboxSourceDocument = {
+  kind: 'source';
+  /** v1: `postgres` only (any other type is a 400 `unsupported_type`). */
+  type: 'postgres';
+  /** One host name or IP address. */
+  host: string;
+  /** Toolbox takes the port as a string, `"1"`-`"65535"`. */
+  port: string;
+  database: string;
+  user: string;
+  password?: string;
+};
+
+/**
+ * (api-types 0.183.0) How crew reads a database source: `native` (crew's own adapter: K1's driver, dialer and
+ * read policy; Postgres) or `toolbox` (one Toolbox process per source; a preview is a 501 `runtime_unavailable`
+ * on a daemon without the Toolbox runtime).
+ */
+export type McpSourceRuntime = 'native' | 'toolbox';
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §7.1) What a tool's answer discloses: `rows` (needs a source's
+ * "query" switch), `structure` (needs "see"), or `none`. Reviewed at preview, bound to the tool's saved schema
+ * hash; `null` = not reviewed, or reviewed against a schema that has since changed. A tool with no class in force
+ * is offered to no agent.
+ */
+export type McpToolDisclosure = 'none' | 'structure' | 'rows';
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §7.1) A data source's agent switches: `see` (on by default),
+ * `query` (off by default; needs `see`; turned off again by a descriptor change and by a restore), `projects`
+ * (none by default) and `everyProject` (an explicit choice). Set by a human operator only.
+ */
+export interface McpSourceAgents {
+  see: boolean;
+  query: boolean;
+  projects: string[];
+  everyProject: boolean;
+}
 /**
  * A tool's class, from its own `tools/list` annotations (never from a carrier): `read` when
  * `readOnlyHint` is true; else `destructive` unless `destructiveHint` is false; else `write`. A tool
@@ -12418,6 +12584,16 @@ export interface McpServerConfigBody {
    * from `POST /apps/uploads` (a snapshot digest), not from a preview.
    */
   sql?: SqlSourceConfigBody;
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) `toolbox-source` only: Toolbox's own source document. Its
+   * password is the secret behind `auth.ref` (`auth` takes only `ref`). A `sql` body with Postgres settings is
+   * saved as the same document.
+   */
+  toolbox?: ToolboxSourceDocument;
+  /** (api-types 0.183.0) `toolbox-source` only: default `native`. */
+  runtime?: McpSourceRuntime;
+  /** (api-types 0.183.0) `toolbox-source` only: the TLS choice crew writes the driver's settings from; default `verify-full`. */
+  tls?: { mode: 'verify-full' | 'disable'; ca?: string };
   /**
    * (api-types 0.175.0) `sql` only: the views (and materialized views) a read may name, as
    * `schema.view` (MySQL `database.view`). A view not listed is refused by the read policy.
@@ -12433,6 +12609,35 @@ export interface McpServerConfigBody {
    * response, log, audit entry or file.
    */
   secret?: string;
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3) `mcp-http` and `mcp-stdio` only: this server is a project-management
+   * system's own MCP server (GitHub's `github-mcp-server`, the Atlassian remote server). Its calls then go through
+   * crew's data gate with resource bindings (§3.1), and trackers of it can be linked to projects and repos. A
+   * human operator's only, at the preview and at the save (else 403 `pm_source_human_only`). PM-1 registers `github`
+   * and `jira`; a re-save of a PM source must name the same system (409 `pm_marker_fixed`).
+   */
+  pm?: { system: 'github' | 'jira' };
+}
+
+/** (api-types 0.187.0, DES-PM-001 §1) The project-management system a registry entry is. PM-1 registers `github` and `jira`. */
+export interface McpPmMarker {
+  system: PmSystem;
+}
+
+/** (api-types 0.187.0) A project-management system. `gitlab` and `ado` are wave PM-2: a registration naming them is a 400 today. */
+export type PmSystem = 'github' | 'jira' | 'gitlab' | 'ado';
+
+/**
+ * (api-types 0.187.0, DES-PM-001 §3.1) A PM tool's resource binding as crew holds it: crew's binding for the tool
+ * (`policy`, e.g. `jira/getJiraIssue@1`), bound to the schema it was reviewed against. In force only while both
+ * match: a changed schema, or a new binding-policy version, makes the tool unavailable to agents until a person
+ * saves the server again. `null` = crew has no binding for this tool, so no agent may use it.
+ */
+export interface McpToolBinding {
+  policy: string;
+  schemaHash: string;
+  /** Whether it is in force now (the saved schema is the reviewed one and the policy is crew's current one). */
+  inForce: boolean;
 }
 
 /**
@@ -12488,9 +12693,18 @@ export interface McpTool {
   schemaHash: string | null;
   /** The hash the last probe saw. */
   observedSchemaHash: string;
+  /** (api-types 0.183.0) The disclosure class in force; `null` = none reviewed for the saved schema. */
+  disclosure: McpToolDisclosure | null;
+  /** (api-types 0.187.0) PM entries only: the tool's resource binding; `null` = unbound, so unavailable to agents. */
+  binding?: McpToolBinding | null;
 }
 
 export interface McpServer {
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) The entry's immutable id. Estate's source documents, `deps`,
+   * grants and records key on it, never on the name: a name removed and registered again is a new id.
+   */
+  id: string;
   name: string;
   kind: McpUpstreamKind;
   command: string | null;
@@ -12518,6 +12732,26 @@ export interface McpServer {
    * `allowWrites`). Queries, actions and grants bind to it.
    */
   descriptorHash?: string;
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1, §5.4) A database source stored as its Toolbox document. A
+   * `native` one still answers `kind: 'sql'` and `sql` (the read-path projection every existing reader uses).
+   * `descriptorVersion` 1 = mapped from a K1 record, hashed with K1's function (locks and grants unchanged);
+   * 2 = written by a save, hashed over the canonical execution descriptor.
+   */
+  runtime?: McpSourceRuntime;
+  toolbox?: ToolboxSourceDocument;
+  descriptorVersion?: 1 | 2;
+  /** The deployment policy the document was checked under, e.g. `postgres/1@toolbox-v1.15.0`. */
+  policyVersion?: string;
+  /** (api-types 0.183.0) Data sources only: the agent switches (defaults filled in). */
+  agents?: McpSourceAgents;
+  /** (api-types 0.187.0, DES-PM-001) A project-management system's server: its system. */
+  pm?: McpPmMarker;
+  /**
+   * (api-types 0.187.0) PM entries only: the trackers linked to projects or repos, with their links (read-only
+   * here; written only through `POST`/`DELETE /tracker-links`).
+   */
+  trackers?: TrackerLink[];
   /**
    * (api-types 0.174.0) `mcp-http` and `rest` only: the ranges confirmed for this server's
    * connections. A server saved before 0.174.0 shows what crew re-derived for it: the IP literal or
@@ -12549,12 +12783,79 @@ export interface McpDiscoveredServer {
   managed: boolean;
 }
 
-/** `GET /mcp/servers`. */
+/**
+ * `GET /mcp/servers`, for a human actor. (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.2, crew#1310) Any other
+ * actor, and `?view=agent`, gets {@link McpServersAgentResponse} instead; so do the answers of a save, a
+ * `PATCH /mcp/servers/:name` and a test for a non-human actor.
+ */
 export interface McpServersResponse {
   servers: McpServer[];
   discovered: McpDiscoveredServer[];
 }
 
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.2) A server as an agent may know it: no host, port, database,
+ * login, url, command, arguments, path, address, secret reference or descriptor.
+ */
+export interface McpServerAgentView {
+  id: string;
+  name: string;
+  kind: McpUpstreamKind;
+  enabled: boolean;
+  health: { state: McpHealthState };
+  /** The tools that are not `gone`. */
+  tools: Array<{ name: string; subject: string; class: McpToolClass; disclosure: McpToolDisclosure | null; enabled: boolean; status: McpToolStatus }>;
+  /** Data sources only. */
+  agents?: { see: boolean; query: boolean };
+  /** (api-types 0.187.0) PM entries only. */
+  pm?: McpPmMarker;
+}
+
+/** (api-types 0.183.0) `GET /mcp/servers?view=agent`, and `GET /mcp/servers` for any non-human actor. */
+export interface McpServersAgentResponse {
+  view: 'agent';
+  servers: McpServerAgentView[];
+}
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.5) `GET /mcp/registry/generations` (human operator only). Every
+ * write keeps the registry it replaces; the last 10 are kept.
+ */
+export interface McpRegistryGenerationsResponse {
+  /** The generation in force. */
+  current: number;
+  /** Newest first. */
+  generations: Array<{ generation: number; savedAt: string }>;
+}
+
+/** (api-types 0.183.0) `POST /mcp/registry/restore`. */
+export interface McpRegistryRestoreBody {
+  generation: number;
+}
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.5) `POST /mcp/registry/restore`'s 200 (human operator only;
+ * audited `mcp.registry.restored`). A restore fails closed: every source's "query" switch and Allow writes come
+ * back OFF; a server whose secret reference resolves to nothing comes back DISABLED (`secret_missing`); MCP
+ * approvals whose tool schema differs from the restored one are withdrawn first (a failed withdrawal refuses the
+ * restore, 500 `withdraw_failed`). A generation that is not kept is a 404 `unknown_generation`; one that does not
+ * parse, or holds a record crew could not have written, a 409 `generation_unreadable`, and nothing changes. The
+ * withdrawal and the commit hold every affected server's lock; when servers keep being registered meanwhile the
+ * restore gives up with a 409 `registry_busy`, having changed nothing. The registry in force before the restore is
+ * kept as a generation too.
+ */
+export interface McpRegistryRestoreResponse {
+  restored: number;
+  /** The generation the restore wrote. */
+  generation: number;
+  servers: number;
+  disabled: Array<{ name: string; code: 'secret_missing' }>;
+  queryReset: string[];
+  writesReset: string[];
+  /** The approval tokens withdrawn first. */
+  withdrawnApprovals?: string[];
+}
+
 /** The difference between the registered tools and a probe, by tool name. */
 export interface McpToolDiff {
   added: string[];
@@ -12587,6 +12888,13 @@ export interface McpPreviewTool {
    * approving it: `MCP-FIRST-USE` still asks on its first call.
    */
   enabledOnSave: boolean;
+  /**
+   * (api-types 0.183.0) The disclosure class a save gives the tool when `disclosures` does not name it: its
+   * class while its schema is unchanged, crew's own class for a tool of crew's Toolbox configuration, else `null`.
+   */
+  disclosure: McpToolDisclosure | null;
+  /** (api-types 0.187.0) PM entries only: the binding a save gives the tool; `null` = crew has none, so agents never get it. */
+  binding?: { policy: string } | null;
 }
 
 /**
@@ -12611,6 +12919,11 @@ export interface McpPreviewResponse {
     /** (api-types 0.175.0) `sql` only. */
     sql?: SqlSourceView;
     viewsAllowed?: string[];
+    /** (api-types 0.183.0) A database source: the Toolbox document the save will store. */
+    runtime?: McpSourceRuntime;
+    toolbox?: ToolboxSourceDocument;
+    descriptorVersion?: 1 | 2;
+    policyVersion?: string;
   };
   /**
    * (api-types 0.175.0, DES-APPS-001 §5.1) `sql`/`graphql` only: what the describe found —
@@ -12659,6 +12972,13 @@ export interface SaveMcpServerBody {
    * `egress_not_rest` for a server that is not `rest`.
    */
   allowOrigin?: string;
+  /**
+   * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.1) The operator's review of what each tool discloses, by tool
+   * name (`McpPreviewTool.disclosure` is what a tool not named here gets). A name the preview does not list is a
+   * 400 `unknown_tool`. Human operator only (403 `disclosure_review_human_only`); audited
+   * `mcp.tool.disclosure_reviewed`.
+   */
+  disclosures?: Record<string, McpToolDisclosure>;
 }
 
 /**
@@ -12712,6 +13032,25 @@ export interface PatchMcpServerBody {
 export interface PatchMcpToolBody {
   enabled?: boolean;
   classOverride?: McpToolClass | null;
+  /**
+   * (api-types 0.183.0) Review what the tool discloses, against its saved schema (409 `not_registered` when the
+   * schema changed since the save). Setting a class is a human operator's only (403
+   * `disclosure_review_human_only`), audited `mcp.tool.disclosure_reviewed`; `null` clears it (the tool is then
+   * offered to no agent).
+   */
+  disclosure?: McpToolDisclosure | null;
+}
+
+/**
+ * (api-types 0.183.0, DES-KNOWLEDGE-DATA-001 §5.2) `POST /mcp/servers/:name/test`'s 200 for a NON-HUMAN actor: the
+ * server as the agent-safe projection, and `error` reduced to `"the probe failed"` (a probe's words can name the host).
+ * A save and `PATCH /mcp/servers/:name` likewise answer an {@link McpServerAgentView} to a non-human actor.
+ */
+export interface McpServerTestAgentResponse {
+  ok: boolean;
+  error: string | null;
+  diff: McpToolDiff | null;
+  server: McpServerAgentView;
 }
 
 /** `POST /mcp/servers/:name/test`'s 200: a failed probe is `ok: false` and counts toward `failing`. */
@@ -13289,6 +13628,403 @@ export interface SourceAllowWritesResponse {
   withdrawnGrants: number;
 }
 
+/**
+ * (api-types 0.184.0, DES-KNOWLEDGE-DATA-001 §7.1) A live source's agent switches. Agents reach a source
+ * only through crew's data gate (`mcp:<source>/<tool>` through the broker); Apps units get none of its tools,
+ * whatever this says (D-7). Never a write, never a credential.
+ */
+export type SourceAgentAccess = McpSourceAgents;
+
+/** `PUT /sources/:name/agents` (human operator only; each change audited). At least one field. */
+export interface SourceAgentAccessBody {
+  see?: boolean;
+  query?: boolean;
+  projects?: string[];
+  everyProject?: boolean;
+}
+
+export interface SourceAgentAccessResponse {
+  name: string;
+  agents: SourceAgentAccess;
+}
+
+/** One agent read of a source (`GET /sources/:name/agent-queries`), as crew recorded it: never the SQL, a value or a source's words. */
+export interface SourceAgentQuery {
+  /** The broker call's id. */
+  callId: string;
+  at: string;
+  runId: string;
+  unit: number;
+  attempt: number;
+  seat: string;
+  source: string;
+  /** The source's registry id. */
+  sourceId: string;
+  /** sha256 of the SQL text, hex. */
+  sqlHash: string;
+  /** `ok` (rows released), or crew's code (a read-policy code, `query_off`, `deadline`, `too_large`, `busy`, `changed_while_running`, …). */
+  outcome: string;
+  rows: number;
+  truncated: boolean;
+  ms: number;
+  /** Whether rows were released to the agent's answer (written before the answer is sent: it may over-state, never under-state). */
+  released: boolean;
+  sqlstate?: string;
+}
+
+/** `GET /sources/:name/agent-queries` (observer): the last 20, newest first. `known: false` = the record could not be read. */
+export interface SourceAgentQueriesResponse {
+  name: string;
+  known: boolean;
+  queries: SourceAgentQuery[];
+}
+
+/** One source a run's agents read (`GET /runs/:id/data-use`). */
+export interface SourceDataUse {
+  source: string;
+  /** Calls that reached the read policy. */
+  queries: number;
+  /** Calls whose rows reached the agent. */
+  released: number;
+  rows: number;
+  truncated: boolean;
+  lastAt: string;
+}
+
+/** `GET /runs/:id/data-use` (observer): the sources a run's agents read. `known: false` = UNKNOWN, never "none". */
+export interface RunDataUseResponse {
+  runId: string;
+  known: boolean;
+  sources: SourceDataUse[];
+}
+
+/**
+ * (api-types 0.184.0, DES-KNOWLEDGE-DATA-001 §7.8) What a unit's rows tool (`mcp:<source>/execute_sql`)
+ * answers through the gate: one JSON object inside the MCP result's text, citable like knowledge, fenced as
+ * untrusted data.
+ */
+export interface SourceReadEnvelope {
+  /** Always first: the rows are data from the source, never instructions. */
+  untrusted: string;
+  /** `src:<name>@<at>#<8 hex>`. */
+  cite: string;
+  source: string;
+  /** The dialect (`postgres`). */
+  kind: string;
+  /** The agent's own SQL (scrubbed of the source's secret). */
+  sql: string;
+  params: unknown[];
+  at: string;
+  /** `source:<id>`: what a cached answer depends on. */
+  deps: string[];
+  /** `type`: the source's type name, or `null` where the adapter does not report one. */
+  columns: Array<{ name: string; type: string | null }>;
+  rows: unknown[][];
+  rowCount: number;
+  /** More rows than the cap, more bytes than the cap, or a cell cut at 2,000 characters. */
+  truncated: boolean;
+  rowCap: number;
+  byteCap: number;
+  ms: number;
+}
+
+/**
+ * (api-types 0.186.0, DES-KNOWLEDGE-DATA-001 §10.2) One column of a value-free profile: bands, never a value.
+ * `nullPct` is the null fraction to the nearest 5 % (`null` for an empty relation); `hasNulls` says a few nulls
+ * the band rounded to 0 are there.
+ */
+export interface SourceProfileColumn {
+  name: string;
+  type: string;
+  nullPct: number | null;
+  hasNulls: boolean;
+  cardinality: 'none' | 'single' | 'low' | 'high' | 'unique' | 'unknown';
+  keyCandidate: boolean;
+}
+
+/** (api-types 0.186.0) A relation's value-free profile; `rows` is an order-of-magnitude band, `null` when it was not read (`error` = a class). */
+export interface SourceProfileRelation {
+  /** `schema.table`, the catalog document's key. */
+  key: string;
+  rows: '0' | '1-99' | '100-9,999' | '10,000-999,999' | '1,000,000+' | null;
+  columns: SourceProfileColumn[];
+  error: string | null;
+  /** Columns not profiled (more than the profiler reads per relation). */
+  columnsNotListed?: number;
+}
+
+/** (api-types 0.186.0) A join the profiler found: a declared foreign key, or a name-and-type match the overlap band confirmed. */
+export interface SourceProfileJoin {
+  from: string;
+  columns: string[];
+  to: string;
+  references: string[];
+  basis: 'fk' | 'name_type';
+  /** How many of the referencing side's distinct values the other side holds (one-column joins); measured at the source. */
+  overlap: 'empty' | 'none' | 'some' | 'most' | 'all' | null;
+}
+
+/**
+ * (api-types 0.186.0) `POST /sources/:name/profile`, a human operator's only (403 `profile_human_only`). The
+ * value-free profile of a described native Postgres source, through the data gate's person read, and the data shapes
+ * it filed as `knowledge` proposals for the review (one per relation; an identical shape already in the queue is not
+ * filed again). 409 `not_in_knowledge`: estate holds no structure for the source yet.
+ */
+export interface SourceProfileResponse {
+  name: string;
+  /** The registry id. */
+  sourceId: string;
+  profiledAt: string;
+  relations: SourceProfileRelation[];
+  joins: SourceProfileJoin[];
+  /** Code entities named exactly like a relation, in the repos' code graphs. */
+  describes: Array<{ relation: string; repo: string; name: string; kind: string; file: string }>;
+  proposed: Array<{ id: string; relation: string }>;
+  alreadyProposed: number;
+  codeSearch: { searched: string[]; notSearched: string[] };
+  /** Catalog documents estate holds that crew's own catalog does not (or a view not allowed): not profiled. */
+  notInKnowledge?: number;
+  /** Relations beyond what one profile reads (too many): not profiled. */
+  notListed?: number;
+  /** Estate holds more catalog pages than one read takes: the rest were not profiled. */
+  catalogTruncated?: true;
+}
+
+/**
+ * (api-types 0.186.0) The crew-owned record a data-shape proposal carries in `payload.shape` (a `knowledge`
+ * proposal filed by the profiler). The review shows it; estate stores it as given.
+ */
+export interface KnowledgeShapeRecord {
+  format: 1;
+  sourceId: string;
+  source: string;
+  relation: string;
+  profile: SourceProfileRelation;
+  joins: SourceProfileJoin[];
+  describes: Array<{ repo: string; symbolId: string; name: string; kind: string; file: string }>;
+  /** Related tables whose join did not fit estate's 200 links per proposal (`joins` above keeps every one). */
+  linksNotListed?: number;
+}
+
+/** (api-types 0.186.0) A node of the Knowledge map. `key` is `<store>:<id>` (`source:`, `repo:`, `knowledge:`, `estate:`). */
+export interface KnowledgeMapNode {
+  key: string;
+  /**
+   * (api-types 0.187.0, DES-PM-001 §3.4) `tracker`: a linked tracker; `project`: a studio project a tracker is
+   * `tracked_in`; `issue`: an issue a run addresses (an `issue_ref`, only its key); `run`: the job that addresses it;
+   * `pr`: the pull request that run delivered (`closes` the issue; `repo` names its repo).
+   */
+  kind: 'source' | 'table' | 'shape' | 'code' | 'repo' | 'knowledge' | 'tracker' | 'project' | 'issue' | 'run' | 'pr';
+  label: string;
+  /** (api-types 0.187.0) A tracker node's PM source (registry name) and key. */
+  tracker?: { source: string; key: string };
+  /** A table's source name. */
+  source?: string;
+  /** A code entity's repo id. */
+  repo?: string;
+  /** A shape's proposal id. */
+  proposalId?: string;
+  /** A shape's value-free summary. */
+  summary?: string;
+}
+
+/**
+ * (api-types 0.186.0) A typed edge of the Knowledge map (`describes`, `joins`, `governed_by`, `derived_from`, …;
+ * `contains` is drawn structure). A `joins` edge's evidence is `{basis, on: [{columns, references, basis, overlap?,
+ * cut?}], more?}`: every condition between the two tables, held under estate's 1 KiB evidence bound.
+ */
+export interface KnowledgeMapEdge {
+  rel: string;
+  from: string;
+  to: string;
+  confidence: number | null;
+  evidence: Record<string, unknown> | null;
+  /** The node of the shape that asserts it (`kconcept synthetic proposal:<id>:`, estate's id); `null` for drawn structure. */
+  owner: string | null;
+}
+
+/**
+ * (api-types 0.186.0) `GET /knowledge/map`, a human operator's only. The source catalogs and the APPROVED data shapes
+ * estate holds live, with their typed edges; a pending or declined shape is never in it. Every source and repo is in
+ * the read's visible set; a repo is drawn when a shape links into it. A catalog estate replaced while it was read is
+ * left out with a note, never drawn half.
+ */
+export interface KnowledgeMapResponse {
+  nodes: KnowledgeMapNode[];
+  edges: KnowledgeMapEdge[];
+  sources: Array<{ id: string; name: string; described: boolean; inKnowledge: boolean; tables: number }>;
+  shapes: number;
+  /** Approved shapes estate no longer holds, or hides. */
+  skipped: number;
+  truncated: boolean;
+  notes: string[];
+}
+
+// ── Project-management trackers (DES-PM-001 rev 4, PM-1; api-types 0.187.0) ───────────────────────────────
+
+/**
+ * What a tracker link points at: a studio project (`proj_…`) or a registered repo. A tracker linked to a repo is in
+ * the tracker set of every project that repo belongs to, and of any run that targets it; a tracker linked to a
+ * project reaches only units filed in that project, never another project through a shared repo (§3.2).
+ */
+export type TrackerLinkTarget = { kind: 'project'; id: string } | { kind: 'repo'; id: string };
+
+/**
+ * One link of one tracker (§3.3). A tracker is (source, tenant, key): one project inside one tenant of a registered PM
+ * system (a Jira project on one site, a GitHub repo's issues). Ids are derived: `trk_` + 16 hex of
+ * sha256(source id, tenant, key) and `tl_` + 16 hex of sha256(tracker id, kind, id), so linking twice is one link.
+ */
+export interface TrackerLink {
+  /** `tl_<hash16>` */
+  id: string;
+  /** `trk_<hash16>` */
+  trackerId: string;
+  /** The PM source's registry name, for display. */
+  source: string;
+  /** The PM source's registry id. */
+  sourceId: string;
+  system: PmSystem;
+  /** Jira: the site's `cloudId`; GitHub: the host (`github.com`). */
+  tenant: string;
+  /** The tenant as a person reads it (a Jira site's name or URL host); absent when not known. */
+  tenantLabel?: string;
+  /** Jira: the project key (`PROJA`); GitHub: `owner/repo`. */
+  key: string;
+  /** The vendor's name for it, at most 120 characters. Vendor text: render it as text. */
+  label: string;
+  target: TrackerLinkTarget;
+  linkedAt: string;
+  /** The person who linked it (the actor id). */
+  linkedBy: string;
+  /** Whether estate holds the link yet (Understand follows when it lands; access follows the registry at once). */
+  projection: 'current' | 'pending' | 'failed';
+}
+
+/** `POST /tracker-links` (human-only). */
+export interface CreateTrackerLinkBody {
+  /** The PM source's registry name. */
+  source: string;
+  tenant: string;
+  key: string;
+  target: TrackerLinkTarget;
+}
+
+/**
+ * `GET /tracker-links?project=<id>`, `?repo=<id>`, or both (human-only; 403 `tracker_links_human_only` for any other
+ * actor). With both, `links` + `viaRepos` are the tracker set a run in that project targeting that repo would have.
+ */
+export interface TrackerLinksResponse {
+  target: { project?: string; repo?: string };
+  /** Linked to the target itself (the project, or with only `repo`, that repo). */
+  links: TrackerLink[];
+  /** With a project: the links of its member repos (and of `repo`, when given), each marked with the repo it comes through. */
+  viaRepos: Array<TrackerLink & { viaRepo: string }>;
+  /** With only a repo: the projects the repo is in (its links reach each of them). */
+  projects: Array<{ id: string; name: string }>;
+  /** With a project: for each PM source with a link here, whether its Agents switches let this project see / query it. */
+  agents: Array<{ source: string; see: boolean; query: boolean }>;
+}
+
+/**
+ * `GET /sources/:name/trackers?q=<text>&cursor=<c>&tenant=<t>` (human-only): one page of the projects the PM source
+ * lists NOW (a live read with the source's own credential), each with its links. `next` is the following page's
+ * cursor, `null` at the end. 503 `source_unavailable` when the vendor cannot be reached; 409 `not_a_tracker` for a
+ * source that is not a PM system.
+ */
+export interface SourceTrackersResponse {
+  name: string;
+  trackers: Array<{ tenant: string; tenantLabel?: string; key: string; label: string; links: TrackerLink[] }>;
+  next: string | null;
+}
+
+/**
+ * `GET /tracker-links/issues?project=<id>&repo=<id>&q=<text>` (human-only): for "Start a job from an issue" (§6 step 1),
+ * the issues of each tracker in the tracker set that project and repo would give a run (under the sources' Agents
+ * switches), read live through the same bindings and response projectors an agent's reads go through. `key` is the
+ * reference a launch intent takes (`PROJA-12`, `owner/repo#212`). A tracker that cannot be read says why in `error`
+ * (`query_off`, `unavailable`, `tool_unbound`) and has no issues.
+ */
+export interface TrackerIssuesResponse {
+  trackers: Array<{
+    trackerId: string;
+    source: string;
+    system: PmSystem;
+    key: string;
+    label: string;
+    tenantLabel?: string;
+    via: { kind: 'project' } | { kind: 'repo'; id: string };
+    /** Jira: the site's cloudId; GitHub: the host. */
+    tenant: string;
+    /** `ref`: the reference a launch intent takes for it (`<source>@<tenant>:KEY-N` when two trackers share the key). */
+    issues: Array<{ key: string; ref: string; title: string; state: string | null }>;
+    error?: string;
+  }>;
+}
+
+/**
+ * (DES-PM-001 §5) A governed action on an issue of a run's tracker set: a comment, a transition, or both on one card.
+ * `POST /runs/:id/tracker-actions` (human-only). Without `confirm` it does NOTHING and answers the card (exactly what
+ * would be posted, as whom, from and to which state, and the link that admits the issue) and its `actionHash`; with
+ * `confirm` equal to that hash it does exactly that. An issue outside the run's tracker set has no card: 404
+ * `issue_not_in_tracker_set`. Recorded against the run and audited `knowledge.tracker.action`.
+ */
+export interface TrackerActionBody {
+  /**
+   * Jira `PROJA-1` (`<source>:PROJA-1` or `<source>@<cloudId>:PROJA-1` picks one of several trackers with that key);
+   * GitHub `owner/repo#42` (or `#42` for the run's own repo).
+   */
+  issue: string;
+  /** The exact comment text (at most 8,000 characters). */
+  comment?: string;
+  /** The state to move it to, by name: a Jira transition's target status (`In Review`), or GitHub `closed` / `open`. */
+  transition?: string;
+  confirm?: string;
+}
+
+export interface TrackerActionCard {
+  runId: string;
+  source: string;
+  system: PmSystem;
+  tenant: string;
+  tenantLabel?: string;
+  /** The issue as the tracker names it (`PROJA-1`, `owner/repo#42`). */
+  issue: string;
+  /** The issue's title; vendor text, render it as text. `null` when it could not be read. */
+  title: string | null;
+  /** Who the tracker will say did it (the registered credential's account), `null` when it could not be read. */
+  identity: string | null;
+  comment?: string;
+  transition?: {
+    from: string | null;
+    to: string;
+    /** The states mapped to `todo` / `doing` / `done` (Jira status categories; GitHub open = todo, closed = done). */
+    mapped: { from: 'todo' | 'doing' | 'done' | null; to: 'todo' | 'doing' | 'done' | null };
+  };
+  /** The link that admits the issue for this run: to its project, or through one of its repos. */
+  admittedBy: { kind: 'project'; id: string } | { kind: 'repo'; id: string };
+}
+
+export type TrackerActionResponse =
+  | { done: false; card: TrackerActionCard; actionHash: string }
+  | {
+      done: true;
+      card: TrackerActionCard;
+      at: string;
+      /** Each part as it went; a transition after a failed comment is not attempted. */
+      results: Array<{ part: 'comment' | 'transition'; ok: boolean; error?: string }>;
+    };
+
+/**
+ * `GET /runs/:id/tracker-actions` (human-only): the issues this run addresses (resolved at launch through its tracker
+ * set) that a governed action can be proposed for, each with the link that still admits it (`null`: no longer in the
+ * run's tracker set, so no card).
+ */
+export interface RunTrackerIssuesResponse {
+  runId: string;
+  /** `ref`: the reference `POST` takes for it (`<source>@<tenant>:KEY-N` when two trackers of the run's set share the key). */
+  issues: Array<{ issue: string; ref: string; source: string; system: PmSystem; trackerId: string; admittedBy: TrackerActionCard['admittedBy'] | null }>;
+}
+
 /**
  * `POST /sources/:name/test-call` (G6) — human operator only. Without `confirm` it sends NOTHING and
  * answers the exact request it would send and its `requestHash`; with `confirm` equal to that hash it
@@ -13341,6 +14077,106 @@ export interface CrewSourceCatalog {
   routes: Array<{ path: string; responseType: string; params: string[] }>;
 }
 
+// ── Test connection, and ask a question of a source (operator 2026-11-03; api-types 0.179.0) ─────────
+
+/**
+ * `POST /sources/:name/test` — "Test connection" on a saved `sql` or `graphql` source (it replaces
+ * "Describe again"). crew connects with the saved credentials resolved now, describes the source again
+ * and saves that description, then (SQL) checks a probe read of one table with the read policy and a
+ * prepare at the source; the probe is never executed. A failure is a result (`ok: false`, HTTP 200):
+ * crew's `code` and words (a source's own words reach a human only, scrubbed of the secret). No answer
+ * carries the secret.
+ */
+export interface SourceConnectionTestResponse {
+  name: string;
+  kind: 'sql' | 'graphql';
+  driver: 'postgres' | 'mysql' | 'sqlite' | null;
+  ok: boolean;
+  /** Connecting and describing, in milliseconds (a failure: until it failed). */
+  ms: number;
+  /** When crew ran the test (ISO 8601). */
+  testedAt: string;
+  /**
+   * How crew connects: `verified` (TLS, the certificate checked against the host: Postgres
+   * `verify-full`, MySQL `VERIFY_IDENTITY`, HTTPS), `off` (plaintext, allowed on this confirmed
+   * address), `local` (an upload: crew opens its own snapshot, there is no connection).
+   */
+  tls: 'verified' | 'off' | 'local';
+  /** `ok`: the fresh description (saved): structure, and for Postgres the login's privilege report. */
+  catalog?: SourceCatalogResponse;
+  /** `ok`, SQL: the read-policy check of the probe read (`null`: no table to probe). */
+  readCheck?: ({ ok: true; text: string; relation: string } | { ok: false; text: string; relation: string; code: string; detail: string }) | null;
+  /** `!ok`: why (`secret_missing`, a dialer refusal code, `source_connection`, `source_timeout`, `source_source`, `test_failed`, …). */
+  code?: string;
+  error?: string;
+}
+
+/** `POST /sources/:name/ask` — HUMAN operator only (403 `ask_human_only`). SQL sources. */
+export interface SourceAskBody {
+  /** The person's question, e.g. "How many tickets are open?" (1-1000 characters). */
+  question: string;
+}
+
+/**
+ * The draft: one seat wrote one read query from the question and the source's STRUCTURE only (what
+ * agents see: names, types, keys, declared enum literals, row estimates; never a row or a credential),
+ * and crew checked it with the read policy, then a prepare at the source. NOTHING RAN. `confirm` is
+ * crew's run token for exactly `sql` (only when the check passed): `POST /sources/:name/query` with it
+ * runs that text. Audited `apps.source.asked` (no question, no SQL).
+ */
+export interface SourceAskResponse {
+  /** The query the seat wrote (`''`: it said the structure cannot answer the question). */
+  sql: string;
+  /** The seat's one line: what the query returns and how to read it (or why there is no query). */
+  explanation: string;
+  /** The seat that drafted it. */
+  seat: string;
+  /** The check of `sql` (`null` when there is no query). */
+  check: SourceCheckResponse | null;
+  confirm: string | null;
+}
+
+/** `POST /sources/:name/query` — HUMAN operator only (403 `query_human_only`). SQL sources. */
+export interface SourceQueryBody {
+  /** The SQL to check (or run): a draft, an edited draft, or the person's own. */
+  sql: string;
+  /** crew's run token for exactly `sql` (from the ask, or from this route without `confirm`). */
+  confirm?: string;
+}
+
+/**
+ * Without `confirm`: the check only (`ran: false`; nothing reaches the source but a prepare) and, when
+ * it passed, the run token. With `confirm`: crew verifies the token is its own for exactly this text
+ * and this source as it is now (`409 query_changed` otherwise), then runs it: the read policy again,
+ * a `READ ONLY` transaction, the 10 s deadline cancelled at the source (`504 source_timeout`), at most
+ * {@link SourceQueryRan.rowCap} rows. The rows go to this answer only: never to a seat, a log or the
+ * audit trail (`apps.source.queried` records the relations, counts and time).
+ */
+export type SourceQueryResponse = SourceQueryChecked | SourceQueryRan;
+
+export interface SourceQueryChecked {
+  ran: false;
+  check: SourceCheckResponse;
+  confirm: string | null;
+}
+
+export interface SourceQueryRan {
+  ran: true;
+  columns: Array<{ name: string; type: string }>;
+  /**
+   * Cells as the source's driver reads them, as JSON carries them: Postgres and MySQL dates, times,
+   * numerics and 64-bit integers as the source's own text (`2026-01-01 01:00:00+00`, in the session's
+   * time zone), bytes as `\x` hex (the first 32,767 bytes, `…` past them; Postgres `bytea` arrives as the source's `\x`
+   * text and is cut like any text), JSON values as JSON; text past 64 KB
+   * is cut.
+   */
+  rows: unknown[][];
+  /** More rows than the cap, or past 1 MB of rows as encoded: only the first are shown. */
+  truncated: boolean;
+  rowCap: number;
+  ms: number;
+}
+
 // ── Decision capture (DES-decision-capture §4.2.1 / §4.6; DC-S4a, api-types 0.80.0) ──────────────
 
 /** The laya codebook's decision types. `none` is crew's label for "no decision". */
@@ -14918,8 +15754,12 @@ export interface AppLinkComponent extends AppComponentBase {
   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 source kind a query reads; it names the text file: `sql` `.sql`, `graphql` `.graphql`, else `.json`.
+ * (api-types 0.189.0) `recall` reads the system's KNOWLEDGE (DES-KNOWLEDGE-DATA-001 §9.1) in the app's own project,
+ * on the reserved source `estate`: its text is an {@link AppRecallQueryText}. Studio-hosted only: Publish refuses it.
+ */
+export type AppQueryKind = 'sql' | 'graphql' | 'rest' | 'mcp' | 'crew' | 'recall';
 
 /** 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';
@@ -15105,6 +15945,80 @@ export interface AppCrewQueryText {
   query: Record<string, AppQueryArg>;
 }
 
+/**
+ * (api-types 0.189.0, DES-KNOWLEDGE-DATA-001 §9.1) `queries/<id>.json` of a `recall` query (source `estate`): one
+ * read of the knowledge the APP'S project may see (crew computes `visible` from the app's project, never from the
+ * request, and re-checks every item before release). `from` names what is read:
+ *
+ * - `knowledge`: documents, source structure and approved data shapes (estate recall); needs `query`; `source`
+ *   keeps only what was derived from that registry source;
+ * - `memories`: what the project remembers (estate memory recall, the project's facet); needs `query`;
+ * - `steering`: the active steering rules that apply to the project; `query` keeps rules whose statement holds its
+ *   words;
+ * - `tables`: one registry source's tables as estate holds them (structure, never rows), with each table's approved
+ *   data shape (its text says what the table joins); needs `source`, takes no `query`.
+ *
+ * Rows have the columns of {@link AppRecallColumns} for that `from` (an app's `output` declares a subset, with
+ * exactly these types); with `group` they are `key` (string) and `count` (integer) per value of that column instead.
+ * `limit` is 1-50 (default 20). Text from a source's structure is marked `untrusted`.
+ */
+export interface AppRecallQueryText {
+  from: AppRecallFrom;
+  /**
+   * The words recalled: a literal of 1-200 characters, or the query's ONE parameter (a string, never viewer-bound:
+   * no `from`), which a search filter binds.
+   */
+  query?: AppQueryArg;
+  /** A registry source name (`tables`: required; `knowledge`: optional). */
+  source?: string;
+  group?: 'kind' | 'source' | 'severity';
+  limit?: number;
+}
+
+export type AppRecallFrom = 'knowledge' | 'memories' | 'steering' | 'tables';
+
+/**
+ * (api-types 0.189.0) The columns a `recall` query answers, per `from`, with their types. Every `from` has `title`,
+ * `content`, `cite` (where it came from: `memory:<id>`, `rule:<id>`, `src:<source>/<table>`, a document's
+ * provenance) and `kind` (document, table, shape or note; a memory's tier; a rule's steering type).
+ */
+export interface AppRecallColumns {
+  knowledge: 'title' | 'content' | 'cite' | 'kind' | 'source' | 'score' | 'untrusted';
+  memories: 'title' | 'content' | 'cite' | 'kind' | 'score';
+  steering: 'title' | 'content' | 'cite' | 'kind' | 'severity';
+  tables: 'title' | 'content' | 'cite' | 'kind' | 'columns' | 'shape' | 'untrusted';
+}
+
+/**
+ * (api-types 0.189.0) `GET /knowledge/summary?project=<id>` (a HUMAN operator): what knowledge an app in that project
+ * can be built on, as counts and registry names only (never a row, a document's text or a memory's words). The same
+ * summary is in the apps builder's knowledge package, so a suggestion never names knowledge the builder cannot use.
+ */
+export interface KnowledgeSummaryResponse {
+  projectId: string;
+  /** The data sources the project may see (the agents switch `see`), in name order. */
+  sources: Array<{
+    name: string;
+    /** Its structure is in estate under its current description (a `tables` query can read it). */
+    described: boolean;
+    /** Agents may read its rows for this project. */
+    query: boolean;
+    /**
+     * Approved data shapes on it that the project may see, each verified against estate's own node and deps, counted
+     * up to 5. `null` = the count could not be established (the review queue or a shape's node could not be read, or
+     * the summary's budget ran out before enough were checked): unknown, not zero.
+     */
+    shapes: number | null;
+  }>;
+  /**
+   * Memories a recall in this project can reach (every facet of a memory must match the project's: faceted to it, or
+   * to nothing), working memories left out (an app's memory recall leaves them out too). `null` = estate did not answer.
+   */
+  memories: { project: number; shared: number } | null;
+  /** Active steering rules that apply to this project, by steering type. `null` = the engine did not answer. */
+  steering: { total: number; byType: Partial<Record<SteeringType, number>> } | null;
+}
+
 // How a query's text binds its parameters (api-types 0.176.0): SQL `$n` (Postgres) and the n-th `?` (MySQL,
 // SQLite) bind the n-th parameter in the order `params.properties` declares them, and every declared
 // parameter is used; GraphQL variables are the parameters by name; `.json` texts name them in `AppQueryArg`s.
@@ -15200,6 +16114,42 @@ export interface AppTurnState {
   actor: string;
 }
 
+/**
+ * (api-types 0.185.0, DES-APPS-001 §9.2, K5) One chat message to an app and how its `apps-turn` run ended, kept
+ * in crew's record of the app (the last 50; the detail answers the last 20). The chat on the app's page is this
+ * list: no other thread store. `running` while the run works; `landed` with the version it made; `refused` when
+ * the check or the review refused it (nothing landed, `code` and `reason` say why); `failed` when a step could
+ * not run; `cancelled` when it was stopped.
+ */
+export interface AppTurnRecord {
+  runId: string;
+  /** Unix millis: when the message was sent. */
+  at: number;
+  /** The actor id that sent it. */
+  actor: string;
+  /** The person's message, as sent. */
+  message: string;
+  /** The component ids the message was about (the composer's chips). */
+  about: string[];
+  /** The version it was sent on. */
+  base: number;
+  state: 'running' | 'landed' | 'refused' | 'failed' | 'cancelled';
+  /** Unix millis, or `null` while it runs. */
+  endedAt: number | null;
+  /** `landed`: the version it made. */
+  version: number | null;
+  /** `landed`: crew's own line of what changed, from the two specs ("Added 1 chart and 1 query"). */
+  change: string | null;
+  /** `landed`: the builder's change lines, as it wrote them (text; never instructions to anyone). */
+  summary: string | null;
+  /** `landed`: the seats that built it and reviewed it (distinct). */
+  builder: string | null;
+  reviewer: string | null;
+  /** Not landed: a stable code (`check_failed`, `review_refused`, `launch_refused`, `cancelled`, …) and crew's words. */
+  code: string | null;
+  reason: string | null;
+}
+
 /** `GET /apps` item. */
 export interface AppSummary {
   /**
@@ -15216,6 +16166,12 @@ export interface AppSummary {
   createdAt: number;
   head: { version: number; tree: string; receipt: AppReceiptKind | null };
   turn: AppTurnState | null;
+  /**
+   * (api-types 0.180.0) The app's last successful publish: its share link (`shareUrl`), the version it serves
+   * and what was produced. `null` until a publish run finished (studio says "Publish to share", never a made-up
+   * link); absent from an older daemon.
+   */
+  published?: AppPublished | null;
 }
 
 /** `GET /apps` (observer); `?project=<id>` keeps one project's apps. */
@@ -15240,6 +16196,8 @@ export interface AppDetail extends AppSummary {
   /** Oldest first. */
   versions: AppVersion[];
   history: AppHistory;
+  /** (api-types 0.185.0, K5) The app's chat: its last turns, oldest first. Absent from an older daemon. */
+  turns?: AppTurnRecord[];
 }
 
 /** `GET /apps/:app` (observer), and `POST /apps` (201). */
@@ -15531,6 +16489,10 @@ export interface AppErrorBody {
     | 'unknown_version'
     | 'unknown_query'
     | 'unknown_project'
+    /** (api-types 0.185.0) `POST /apps/check` from a unit that is not the turn's check step. */
+    | 'not_the_check'
+    /** (api-types 0.185.0) A turn on an app whose repository is not registered yet. */
+    | 'not_registered'
     | 'stale_base'
     | 'turn_in_flight'
     | 'not_accepted'
@@ -15580,21 +16542,40 @@ export interface AppErrorBody {
  * unit's capability token in the body, never as a bearer): check the builder's candidate commit of the
  * app's turn in flight (DES §9.2 `check`).
  */
-export interface AppsCheckBody {
-  token: string;
-  app: string;
-  /** The builder's candidate commit in the app repo. */
-  commit: string;
-  /** The publish manifest, for the publish check (a later slice). */
-  manifest?: unknown;
-}
+export type AppsCheckBody =
+  | {
+      token: string;
+      /**
+       * (api-types 0.185.0) The builder's worktree as the engine snapshotted it (`WICKED_TREE`, a tree in the app
+       * repo's objects); crew finds the app by the unit's run.
+       */
+      tree: string;
+      /** The publish manifest, for the publish check (a later slice). */
+      manifest?: unknown;
+    }
+  | {
+      token: string;
+      app: string;
+      /** The builder's candidate commit in the app repo (the older form). */
+      commit: string;
+      /** The publish manifest, for the publish check (a later slice). */
+      manifest?: unknown;
+    };
 
 /**
  * (api-types 0.173.0) `POST /apps/check` 200: on a pass, the commit crew made on the candidate with its lock (the only tree the
  * turn's review can land) and what the check ran; on a refusal, why.
  */
 export type AppsCheckResponse =
-  | { ok: true; commit: string; tree: string; summary: AppCheckSummary }
+  | {
+      ok: true; commit: string; tree: string; summary: AppCheckSummary;
+      /**
+       * (api-types 0.185.0) The checked tree's files as text (`apps.json`, `apps.lock.json`, `queries/<id>.<ext>`):
+       * `wicked-crew apps-check` writes exactly these into the turn's worktree, so the review is dispatched on the
+       * tree that can land.
+       */
+      files?: Array<{ path: string; text: string }>;
+    }
   | { ok: false; code: 'check_failed' | 'source_check_unavailable'; findings: AppCheckFinding[] };
 
 /**
@@ -15613,7 +16594,7 @@ export interface AppsCapabilities {
    * since api-types 0.178.0 (K2b, the write path: API actions and Postgres row writes).
    */
   actions: boolean;
-  /** `POST /apps/:app/turns` launches `apps-turn` runs. */
+  /** `POST /apps/:app/turns` launches `apps-turn` runs (true since api-types 0.185.0 on a daemon whose engine runs them). */
   turns: boolean;
   /** `POST /apps/:app/publish`. */
   publish: boolean;
@@ -15644,3 +16625,164 @@ export interface RegisterRepoBody {
   actor?: string;
   autoCapture?: boolean;
 }
+
+// ── Apps: publish and the standalone site (api-types 0.180.0, DES-APPS-001 §8.1-8.2, §9.3, slice K6) ──────────
+//
+// Publish turns an accepted version into a container image the deployer runs: `wicked-apps-server` with the
+// runtime, the checked `apps.json`, `queries/`, `apps.lock.json`, the snapshots by digest and the manifest
+// below. The SHARE LINK is the site's own address, the base URL the deployer gives in the publish settings
+// (`site.origin`): after a successful publish it is `AppPublished.shareUrl`, and anyone in the app's audience
+// (anyone at all, for a public app) opens it. crew never invents one and pushes nothing anywhere.
+
+/** Where a publish puts the app. `studio` is always on; `embed` needs a public app; `teams` needs the Entra profile. */
+export type AppPublishTarget = 'studio' | 'site' | 'embed' | 'teams';
+
+/**
+ * Who may open the site, judged on the verified token (DES §8.2). `public`: anyone, read-only (every query
+ * public, no action). `oidc-groups`: a group claim value (`claim`, default `groups`). `oidc-email-domain`: the
+ * email's domain, only with `email_verified: true` (a Boolean). `entra-roles`: an app-role VALUE in `roles`
+ * (recommended). `entra-groups`: a group object id in `groups` (a token with a groups overage marker is refused).
+ */
+export type AppAudienceRule =
+  | { kind: 'public' }
+  | { kind: 'oidc-groups'; groups: string[]; claim?: string }
+  | { kind: 'oidc-email-domain'; domains: string[] }
+  | { kind: 'entra-roles'; roles: string[] }
+  | { kind: 'entra-groups'; groups: string[] };
+
+/**
+ * The site's one issuer, fixed at publish. `oidc`: the page signs in with authorization code + PKCE and sends
+ * the ID token (`aud` = `clientId`). `entra`: the page sends a v2 ACCESS token for the app's own
+ * `access_as_user` scope (`aud` = `clientId`, `scp` has `access_as_user`, `tid` = `tenantId`); app-only tokens and
+ * ID tokens are refused. The issuer is `https://` (Entra: `https://login.microsoftonline.com/<tenantId>/v2.0`).
+ */
+export interface AppPublishIdentity {
+  profile: 'oidc' | 'entra';
+  issuer: string;
+  clientId: string;
+  /** `entra` only. */
+  tenantId?: string;
+  /** The scope the page asks for. Default: `openid email profile groups` (oidc), `api://<site host>/<clientId>/access_as_user openid profile` (entra). */
+  scope?: string;
+  /**
+   * Loopback or private CIDR ranges the issuer may be reached at when it is a NAME on a private network (crew's
+   * `OidcConfig.allowRanges`); an IP-literal issuer confirms itself. Never metadata or link-local.
+   */
+  allowRanges?: string[];
+}
+
+/** `POST /apps/:app/publish` (HUMAN operator): launch an `apps-publish` run bound to the head tree and this manifest. */
+export interface AppPublishBody {
+  /** The head version the person is publishing (`409 stale_base` if head moved). */
+  base: number;
+  targets: AppPublishTarget[];
+  /**
+   * The site's address: `https://<host>[:port]`, or `http://localhost:<port>` / `http://127.0.0.1:<port>` for a
+   * local run. No path, query or credentials. It is the share link, the redirect URI's origin
+   * (`<origin>/auth/callback`), and the only origin a POST to the site may come from.
+   */
+  site: { origin: string };
+  /** `null` = a public app (no sign-in). */
+  identity: AppPublishIdentity | null;
+  audience: AppAudienceRule;
+  /** `embed`: the origins that may frame the public site (`https://…`, no path). `teams` adds the Teams origins itself. */
+  embedOrigins?: string[];
+}
+
+/** One source as the person consents to shipping it (DES §9.3 step 3). */
+export interface AppManifestSource {
+  name: string;
+  kind: 'sql' | 'graphql' | 'rest' | 'mcp-http';
+  descriptorHash: string;
+  /** Where the container must reach it (`db.support.internal:5432`, a URL's origin), or `null` for a snapshot. */
+  reach: string | null;
+  /** The address is loopback or private: the container's network must reach it. */
+  privateAddress: boolean;
+  /** The environment variable the deployer passes its secret in, or `null` when it has none. */
+  env: string | null;
+  /** A Postgres source's Allow writes switch at publish. */
+  allowWrites: boolean;
+  /** An upload: the snapshot's digest, shipped in the image. */
+  snapshot?: string;
+}
+
+/** The manifest a publish run is bound to (its digest is on the run, the QE verdict and the `published` receipt). */
+export interface AppPublishManifest {
+  schema: 'wicked.apps.manifest/v1';
+  app: { slug: string; name: string; version: number; tree: string; commit: string };
+  targets: AppPublishTarget[];
+  site: { origin: string };
+  /**
+   * The issuer, with the endpoints its discovery document named at publish (the page's `connect-src`) and the ID
+   * token signing algorithms it named (`id_token_signing_alg_values_supported`; the page checks the ID token's).
+   */
+  identity: (AppPublishIdentity & { endpoints: { authorization: string; token: string; idTokenAlgs?: string[] } }) | null;
+  audience: AppAudienceRule;
+  embedOrigins: string[];
+  sources: AppManifestSource[];
+  queries: Array<{ id: string; source: string; public: boolean }>;
+  /** Each action with the grant the image enforces (revoking = publishing again without it). */
+  actions: Array<{ id: string; kind: 'api' | 'row-write'; source: string; grant: AppActionGrant; table?: string; columns?: string[] }>;
+  /** Every environment name the image needs, sorted. A missing one fails the server's start, by name. */
+  env: string[];
+  /** `/data` must be a mounted volume when the app has an action (its action records and logs live there). */
+  volume: '/data' | null;
+}
+
+/** An app's last successful publish (`AppSummary.published`, so also on `AppDetail`): the share link and what was produced. */
+export interface AppPublished {
+  version: number;
+  tree: string;
+  /** The `apps-publish` run. */
+  runId: string;
+  /** Unix millis, when the image was produced. */
+  at: number;
+  /** Who consented. */
+  actor: Actor;
+  targets: AppPublishTarget[];
+  /** The share link: `site.origin` + `/`. What studio's Copy link copies. */
+  shareUrl: string;
+  /** Who can open it, in one line ("People in group support-ops who sign in at dex.apps.test"). */
+  audience: string;
+  /** The image in the local container engine (never pushed): its tag and its id (`sha256:…`). */
+  image: { tag: string; id: string };
+  /** `embed`: the iframe snippet (a public app only); otherwise `null`. */
+  snippet: string | null;
+  /** `teams`: the Teams app package, at `GET /api/v1/apps/:app/published/teams.zip`; otherwise `null`. */
+  teamsPackage: { url: string; sha256: string } | null;
+  manifestDigest: string;
+  /** How the deployer runs it: the environment names, the volume (or `null`), the port the server listens on. */
+  run: { env: string[]; volume: '/data' | null; port: number };
+}
+
+// The standalone site's own routes (`wicked-apps-server`; the page's in-process host calls them). Bearer only,
+// no cookies; every POST needs `Origin` = the site's origin and `Content-Type: application/json`.
+
+/** `GET /spec` (a token in the audience, or a public app): the published version and who is viewing. */
+export interface AppSiteSpecResponse {
+  app: { slug: string; name: string; version: number };
+  spec: AppSpec;
+  /** What the server took from the verified token; `null` on a public site. */
+  viewer: { email: string | null; name: string | null } | null;
+  /** Actions run on this site (a mounted `/data`, `APPS_READ_ONLY` unset). The page still refuses them in a frame. */
+  actions: boolean;
+  /**
+   * Queries and actions the server refuses NOW, each with its reason. They are judged again at every refresh (every
+   * 10 minutes, and after a failed read): a source back as it was published clears them; a source that really
+   * changed needs the app checked and published again.
+   */
+  refused: Array<{ kind: 'query' | 'action'; id: string; reason: string }>;
+}
+
+/**
+ * `GET /healthz` (no sign-in): up, and what it refuses, by kind, id and a code only (`contract_changed`,
+ * `table_changed`, `source_unavailable`, …). The reasons, which can name a source or a table, are on `GET /spec`
+ * behind the sign-in.
+ */
+export interface AppSiteHealth {
+  ok: boolean;
+  app: string;
+  version: number;
+  refused: Array<{ kind: 'query' | 'action'; id: string; code: string }>;
+  actions: boolean;
+}