@smithers-orchestrator/gateway 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/gateway",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Stable Smithers Gateway RPC contracts, auth scopes, and deployment metadata",
   "type": "module",
   "sideEffects": false,

package/src/auth/scopes.ts

@@ -8,6 +8,12 @@ export const GATEWAY_SCOPE_VALUES = [
   "signal:submit",
   "cron:read",
   "cron:write",
+  "account:read",
+  "memory:read",
+  "prompt:read",
+  "score:read",
+  "ticket:read",
+  "ticket:write",
   "observability:read",
 ] as const;
 
@@ -21,11 +27,18 @@ export const GATEWAY_SCOPE_DESCRIPTIONS: Record<GatewayScope, string> = {
   "signal:submit": "Submit workflow signals.",
   "cron:read": "List cron schedules.",
   "cron:write": "Create, delete, and trigger cron schedules.",
+  "account:read": "List registered agent accounts (API keys redacted).",
+  "memory:read": "List cross-run memory facts.",
+  "prompt:read": "List registered prompts.",
+  "score:read": "List scorer/eval results for a run.",
+  "ticket:read": "List work docs (tickets/plans/specs/proposals).",
+  "ticket:write": "Create, update, and soft-delete work docs.",
   "observability:read": "Read DevTools and other observability streams.",
 };
 
 const RUN_SCOPE_ORDER: GatewayScope[] = ["run:read", "run:write", "run:admin"];
 const CRON_SCOPE_ORDER: GatewayScope[] = ["cron:read", "cron:write"];
+const TICKET_SCOPE_ORDER: GatewayScope[] = ["ticket:read", "ticket:write"];
 
 function normalizeScope(scope: string): string {
   return scope.trim();
@@ -45,15 +58,18 @@ function gatewayScopeImplies(granted: GatewayScope, required: GatewayScope): boo
   if (granted.startsWith("cron:") && required.startsWith("cron:")) {
     return CRON_SCOPE_ORDER.indexOf(granted) >= CRON_SCOPE_ORDER.indexOf(required);
   }
+  if (granted.startsWith("ticket:") && required.startsWith("ticket:")) {
+    return TICKET_SCOPE_ORDER.indexOf(granted) >= TICKET_SCOPE_ORDER.indexOf(required);
+  }
   return false;
 }
 
 function legacyAccessImplies(scope: string, required: GatewayScope): boolean {
   switch (scope) {
     case "read":
-      return required === "run:read" || required === "cron:read" || required === "observability:read";
+      return required === "run:read" || required === "cron:read" || required === "account:read" || required === "memory:read" || required === "prompt:read" || required === "score:read" || required === "ticket:read" || required === "observability:read";
     case "execute":
-      return required === "run:read" || required === "run:write" || required === "signal:submit" || required === "cron:read" || required === "cron:write";
+      return required === "run:read" || required === "run:write" || required === "signal:submit" || required === "cron:read" || required === "cron:write" || required === "ticket:read" || required === "ticket:write";
     case "approve":
       return required === "approval:submit" || legacyAccessImplies("execute", required);
     case "admin":

package/src/rpc/index.ts

@@ -32,6 +32,7 @@ export type GatewayRpcErrorCode =
   | "RunNotFound"
   | "RUN_NOT_ACTIVE"
   | "CronNotFound"
+  | "TicketNotFound"
   | "NodeNotFound"
   | "IterationNotFound"
   | "NodeHasNoOutput"
@@ -79,8 +80,10 @@ export type GatewayRpcMethod =
   | "submitSignal"
   | "getRun"
   | "listRuns"
+  | "getSchemaSignature"
   | "listWorkflows"
   | "listApprovals"
+  | "listDocs"
   | "streamRunEvents"
   | "streamDevTools"
   | "getNodeOutput"
@@ -88,7 +91,15 @@ export type GatewayRpcMethod =
   | "cronList"
   | "cronCreate"
   | "cronDelete"
-  | "cronRun";
+  | "cronRun"
+  | "listAccounts"
+  | "listMemoryFacts"
+  | "listPrompts"
+  | "listScores"
+  | "listTickets"
+  | "createTicket"
+  | "updateTicket"
+  | "deleteTicket";
 
 export type LaunchRunRequest = {
   workflow: string;
@@ -178,6 +189,14 @@ export type ListRunsRequest = {
   };
 };
 
+export type GetSchemaSignatureRequest = Record<string, never>;
+
+export type GetSchemaSignatureResponse = {
+  schemaVersion: string;
+  signature: string;
+  components?: Record<string, string>;
+};
+
 export type GatewayWorkflowSummary = {
   key: string;
   readableName?: string;
@@ -219,6 +238,26 @@ export type ListApprovalsRequest = {
 
 export type ListApprovalsResponse = GatewayApprovalSummary[];
 
+export type GatewayDocRow = {
+  path: string;
+  kind: "ticket" | "plan" | "spec" | "proposal" | "conflict" | string;
+  content: string;
+  contentHash: string;
+  updatedAtMs: number;
+  deletedAtMs: number | null;
+};
+
+export type ListDocsRequest = {
+  filter?: {
+    kind?: string;
+    includeDeleted?: boolean;
+    updatedAfterMs?: number;
+    limit?: number;
+  };
+};
+
+export type ListDocsResponse = GatewayDocRow[];
+
 export type StreamRunEventsRequest = {
   runId: string;
   afterSeq?: number;
@@ -266,6 +305,158 @@ export type CronRunRequest = {
   input?: Record<string, unknown>;
 };
 
+/**
+ * One registered Smithers agent account — a row in the user-level
+ * `~/.smithers/accounts.json` registry that the `smithers agents` CLI manages,
+ * surfaced read-only by the `listAccounts` server handler (via the
+ * `@smithers-orchestrator/accounts` package). Each account is either a
+ * subscription provider (a per-account CLI `configDir`) or an API provider (an
+ * `apiKey`); the two are mutually exclusive.
+ *
+ * SECRET REDACTION: the raw `apiKey` is NEVER sent over the wire — it is a
+ * plaintext credential stored mode-600 on disk. Instead `hasApiKey` reports
+ * whether an api-key account carries a non-empty key, and `hasConfigDir`
+ * reports whether a subscription account has a config dir, so a client can
+ * render the account's auth posture without ever receiving the secret.
+ */
+export type GatewayAccount = {
+  /** Unique account label (the registry key, `--label`). */
+  label: string;
+  /** Provider id, one of the fixed `smithers agents` catalog. */
+  provider:
+    | "claude-code"
+    | "antigravity"
+    | "codex"
+    | "gemini"
+    | "kimi"
+    | "anthropic-api"
+    | "openai-api"
+    | "gemini-api";
+  /** Per-account CLI config dir for subscription providers (absent for api-key accounts). */
+  configDir?: string | null;
+  /** True when a subscription account has a non-empty config dir. */
+  hasConfigDir: boolean;
+  /** True when an api-key account carries a non-empty key (the key itself is NEVER returned). */
+  hasApiKey: boolean;
+  /** Optional default model baked into the account. */
+  model?: string | null;
+  /** ISO timestamp of when the account was added, when known. */
+  addedAt?: string | null;
+};
+
+export type ListAccountsRequest = Record<string, never>;
+
+export type ListAccountsResponse = GatewayAccount[];
+
+/** One cross-run memory fact row (the `_smithers_memory_facts` table, snake→camel cased). */
+export type GatewayMemoryFact = {
+  namespace: string;
+  key: string;
+  valueJson: string;
+  schemaSig?: string | null;
+  createdAtMs: number;
+  updatedAtMs: number;
+  ttlMs?: number | null;
+};
+
+export type ListMemoryFactsRequest = {
+  namespace?: string;
+};
+
+export type ListMemoryFactsResponse = GatewayMemoryFact[];
+
+/**
+ * One registered prompt row — a `.md`/`.mdx` file walked from the project's
+ * `.smithers/prompts/` directory by the `listPrompts` server handler. `id` is the
+ * prompt's relative path without extension (e.g. `refactor` or
+ * `release-content/changelog`); `entryFile` is the workspace-relative source path
+ * (e.g. `prompts/refactor.mdx`); `source` is the raw file text. The timestamps
+ * come from `fs.stat` (`birthtimeMs`/`mtimeMs`) so a freshly-edited prompt sorts
+ * recent.
+ */
+export type GatewayPrompt = {
+  id: string;
+  entryFile: string;
+  source: string;
+  createdAtMs?: number;
+  updatedAtMs?: number;
+};
+
+export type ListPromptsRequest = Record<string, never>;
+
+export type ListPromptsResponse = GatewayPrompt[];
+
+/**
+ * One scorer/eval result row (the `_smithers_scorers` table, snake→camel cased).
+ * `score` is the scorer's verdict; `latencyMs`/`durationMs` are the only timing
+ * metrics the table carries (there is NO token/cost data — those tiles are
+ * computed client-side and em-dashed when absent).
+ */
+export type GatewayScoreRow = {
+  runId: string;
+  nodeId: string;
+  iteration: number;
+  attempt: number;
+  scorerId: string;
+  scorerName: string;
+  source: string;
+  score: number;
+  reason?: string | null;
+  scoredAtMs: number;
+  latencyMs?: number | null;
+  durationMs?: number | null;
+};
+
+export type ListScoresRequest = {
+  runId: string;
+  nodeId?: string;
+};
+
+export type ListScoresResponse = GatewayScoreRow[];
+
+/** A doc kind stored in `_smithers_docs`; the tickets surface uses `ticket`. */
+export type GatewayDocKind = "ticket" | "plan" | "spec" | "proposal";
+
+/**
+ * One LIVE doc row (the `_smithers_docs` table, snake→camel cased) returned by
+ * `listTickets`. Tombstones (`deletedAtMs != null`) are filtered server-side and
+ * NEVER appear here. `status` rides the row so a ticket's status survives reload
+ * (LOCKED Path A); `contentHash` is `sha256(content)`.
+ */
+export type GatewayTicketRow = {
+  path: string;
+  kind: GatewayDocKind;
+  content: string;
+  contentHash: string;
+  status?: string | null;
+  updatedAtMs: number;
+};
+
+export type ListTicketsRequest = {
+  /** Optional doc-kind filter; omit to list every kind. Defaults to all. */
+  kind?: GatewayDocKind;
+};
+
+export type ListTicketsResponse = GatewayTicketRow[];
+
+export type CreateTicketRequest = {
+  /** Doc identity (PK); e.g. a ticket id like `feat-issues-card`. */
+  path: string;
+  content: string;
+  kind?: GatewayDocKind;
+  status?: string;
+};
+
+export type UpdateTicketRequest = {
+  path: string;
+  content?: string;
+  status?: string;
+};
+
+export type DeleteTicketRequest = {
+  path: string;
+};
+
 const stringSchema = (description: string): JsonSchema => ({ type: "string", description });
 const booleanSchema = (description: string): JsonSchema => ({ type: "boolean", description });
 const integerSchema = (description: string, minimum = 0): JsonSchema => ({
@@ -361,6 +552,7 @@ export const GATEWAY_RPC_ERRORS: Record<GatewayRpcErrorCode, GatewayRpcErrorDefi
   RunNotFound: { version: SMITHERS_API_VERSION, code: "RunNotFound", httpStatus: 404, description: "The run does not exist." },
   RUN_NOT_ACTIVE: { version: SMITHERS_API_VERSION, code: "RUN_NOT_ACTIVE", httpStatus: 409, description: "The run is not currently active and cannot be cancelled." },
   CronNotFound: { version: SMITHERS_API_VERSION, code: "CronNotFound", httpStatus: 404, description: "The cron schedule does not exist." },
+  TicketNotFound: { version: SMITHERS_API_VERSION, code: "TicketNotFound", httpStatus: 404, description: "The ticket/work doc does not exist." },
   NodeNotFound: { version: SMITHERS_API_VERSION, code: "NodeNotFound", httpStatus: 404, description: "The node does not exist on the run." },
   IterationNotFound: { version: SMITHERS_API_VERSION, code: "IterationNotFound", httpStatus: 404, description: "The requested node iteration does not exist." },
   NodeHasNoOutput: { version: SMITHERS_API_VERSION, code: "NodeHasNoOutput", httpStatus: 404, description: "The node has not produced output." },
@@ -543,6 +735,24 @@ export const GATEWAY_RPC_DEFINITIONS: readonly GatewayRpcDefinition[] = [
     exampleRequest: { filter: { status: "finished", limit: 20 } },
     exampleResponse: [{ runId: "run_01", workflowKey: "deploy", status: "finished", createdAtMs: 1710000000000 }],
   },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "getSchemaSignature",
+    title: "Get Schema Signature",
+    description: "Return the server Smithers schema migration head and table-catalog signature used by client persistence.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "run:read",
+    requestSchema: objectSchema({}),
+    responseSchema: objectSchema({
+      schemaVersion: stringSchema("Current _smithers_schema_migrations head id."),
+      signature: stringSchema("Stable hash of the server schema catalog."),
+      components: objectSchema({}, [], "Per-table schema component hashes.", true),
+    }, ["schemaVersion", "signature"]),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "Internal"],
+    exampleRequest: {},
+    exampleResponse: { schemaVersion: "0016", signature: "sha256" },
+  },
   {
     version: SMITHERS_API_VERSION,
     method: "listWorkflows",
@@ -587,6 +797,34 @@ export const GATEWAY_RPC_DEFINITIONS: readonly GatewayRpcDefinition[] = [
     exampleRequest: { filter: { workflow: "deploy", limit: 20 } },
     exampleResponse: [{ runId: "run_01", workflowKey: "deploy", nodeId: "approve", iteration: 0, requestTitle: "Approve deploy", requestedAtMs: 1710000000000 }],
   },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "listDocs",
+    title: "List Docs",
+    description: "List DB-backed Smithers markdown artifacts for tickets, plans, specs, proposals, and conflict markers.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "run:read",
+    requestSchema: objectSchema({
+      filter: objectSchema({
+        kind: stringSchema("Optional doc kind filter."),
+        includeDeleted: booleanSchema("Include tombstone rows."),
+        updatedAfterMs: integerSchema("Only return docs updated after this millisecond timestamp.", 0),
+        limit: integerSchema("Maximum number of docs.", 1),
+      }),
+    }),
+    responseSchema: arraySchema(objectSchema({
+      path: stringSchema("Path relative to .smithers, e.g. tickets/smithers/0030.md."),
+      kind: stringSchema("ticket, plan, spec, proposal, or conflict."),
+      content: stringSchema("Markdown or conflict marker content."),
+      contentHash: stringSchema("SHA-256 hash of content."),
+      updatedAtMs: integerSchema("Last DB update time in milliseconds.", 0),
+      deletedAtMs: { type: ["integer", "null"], description: "Tombstone timestamp when deleted." },
+    }, ["path", "kind", "content", "contentHash", "updatedAtMs"]), "Smithers docs rows."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "Internal"],
+    exampleRequest: { filter: { kind: "ticket", limit: 100 } },
+    exampleResponse: [{ path: "tickets/smithers/0030-jjhub-sse-seam.md", kind: "ticket", content: "# Ticket", contentHash: "sha256", updatedAtMs: 1710000000000, deletedAtMs: null }],
+  },
   {
     version: SMITHERS_API_VERSION,
     method: "streamRunEvents",
@@ -704,6 +942,195 @@ export const GATEWAY_RPC_DEFINITIONS: readonly GatewayRpcDefinition[] = [
     exampleRequest: { cronId: "cron_01", input: { dryRun: true } },
     exampleResponse: { runId: "run_02", workflow: "deploy" },
   },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "listAccounts",
+    title: "List Accounts",
+    description: "List the registered Smithers agent accounts — the entries in the user-level `~/.smithers/accounts.json` registry that the `smithers agents` CLI manages. Each account's raw API key is redacted; `hasApiKey`/`hasConfigDir` report its auth posture instead.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "account:read",
+    requestSchema: objectSchema({}),
+    responseSchema: arraySchema(objectSchema({
+      label: stringSchema("Unique account label (the registry key)."),
+      provider: {
+        type: "string",
+        enum: ["claude-code", "antigravity", "codex", "gemini", "kimi", "anthropic-api", "openai-api", "gemini-api"],
+        description: "Provider id, one of the fixed `smithers agents` catalog.",
+      },
+      configDir: { type: ["string", "null"], description: "Per-account CLI config dir for subscription providers (null for api-key accounts)." },
+      hasConfigDir: booleanSchema("True when a subscription account has a non-empty config dir."),
+      hasApiKey: booleanSchema("True when an api-key account carries a non-empty key (the key itself is never returned)."),
+      model: { type: ["string", "null"], description: "Optional default model baked into the account." },
+      addedAt: { type: ["string", "null"], description: "ISO timestamp of when the account was added, when known." },
+    }, ["label", "provider", "hasConfigDir", "hasApiKey"]), "Registered agent accounts."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "Internal"],
+    exampleRequest: {},
+    exampleResponse: [{ label: "claude-work", provider: "claude-code", configDir: "/Users/me/.claude", hasConfigDir: true, hasApiKey: false, model: "claude-opus-4-8", addedAt: "2026-01-01T00:00:00.000Z" }],
+  },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "listMemoryFacts",
+    title: "List Memory Facts",
+    description: "List cross-run memory facts, optionally scoped to a namespace.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "memory:read",
+    requestSchema: objectSchema({ namespace: stringSchema("Optional namespace filter (e.g. 'workflow:deploy').") }),
+    responseSchema: arraySchema(objectSchema({
+      namespace: stringSchema("Fact namespace."),
+      key: stringSchema("Fact key (unique within the namespace)."),
+      valueJson: stringSchema("Stored value as a JSON string."),
+      schemaSig: { type: ["string", "null"], description: "Optional value-schema signature." },
+      createdAtMs: integerSchema("Unix epoch milliseconds when first written.", 0),
+      updatedAtMs: integerSchema("Unix epoch milliseconds when last written.", 0),
+      ttlMs: { type: ["integer", "null"], description: "Time-to-live in milliseconds, or null when the fact does not expire." },
+    }, ["namespace", "key", "valueJson", "createdAtMs", "updatedAtMs"]), "Memory facts."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "Internal"],
+    exampleRequest: { namespace: "workflow:deploy" },
+    exampleResponse: [{ namespace: "workflow:deploy", key: "last-sha", valueJson: "\"abc123\"", createdAtMs: 1710000000000, updatedAtMs: 1710000000000 }],
+  },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "listPrompts",
+    title: "List Prompts",
+    description: "List registered prompts — the `.md`/`.mdx` files under the project's `.smithers/prompts/` directory, each returned with its source.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "prompt:read",
+    requestSchema: objectSchema({}),
+    responseSchema: arraySchema(objectSchema({
+      id: stringSchema("Prompt id — the relative path under `.smithers/prompts/` without its extension (e.g. 'refactor')."),
+      entryFile: stringSchema("Workspace-relative source path (e.g. 'prompts/refactor.mdx')."),
+      source: stringSchema("Raw prompt file text."),
+      createdAtMs: integerSchema("Unix epoch milliseconds the file was created (fs birthtime).", 0),
+      updatedAtMs: integerSchema("Unix epoch milliseconds the file was last modified (fs mtime).", 0),
+    }, ["id", "entryFile", "source"]), "Registered prompts."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "Internal"],
+    exampleRequest: {},
+    exampleResponse: [{ id: "refactor", entryFile: "prompts/refactor.mdx", source: "# Refactor\n\nRefactor {{file}}.", createdAtMs: 1710000000000, updatedAtMs: 1710000000000 }],
+  },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "listScores",
+    title: "List Scores",
+    description: "List scorer/eval results for one run, optionally scoped to a node.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "score:read",
+    requestSchema: objectSchema({
+      runId: stringSchema("Run id whose scorer results to list."),
+      nodeId: stringSchema("Optional node id filter."),
+    }, ["runId"]),
+    responseSchema: arraySchema(objectSchema({
+      runId: stringSchema("Run id the score belongs to."),
+      nodeId: stringSchema("Node id the score was produced for."),
+      iteration: integerSchema("Node iteration the score belongs to.", 0),
+      attempt: integerSchema("Node attempt the score belongs to.", 0),
+      scorerId: stringSchema("Stable scorer id."),
+      scorerName: stringSchema("Human scorer name."),
+      source: stringSchema("Where the score came from (e.g. 'scorer', 'eval')."),
+      score: { type: "number", description: "The scorer's numeric verdict." },
+      reason: { type: ["string", "null"], description: "Optional human reason for the score." },
+      scoredAtMs: integerSchema("Unix epoch milliseconds when the score was recorded.", 0),
+      latencyMs: { type: ["number", "null"], description: "Optional scorer latency in milliseconds." },
+      durationMs: { type: ["number", "null"], description: "Optional node duration in milliseconds." },
+    }, ["runId", "nodeId", "iteration", "attempt", "scorerId", "scorerName", "source", "score", "scoredAtMs"]), "Scorer results."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "RunNotFound", "Internal"],
+    exampleRequest: { runId: "run_01", nodeId: "review" },
+    exampleResponse: [{ runId: "run_01", nodeId: "review", iteration: 0, attempt: 0, scorerId: "correctness", scorerName: "correctness", source: "scorer", score: 0.92, scoredAtMs: 1710000000000 }],
+  },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "listTickets",
+    title: "List Tickets",
+    description: "List live work docs (tickets/plans/specs/proposals) from `_smithers_docs`; soft-deleted tombstones are never returned.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "ticket:read",
+    requestSchema: objectSchema({
+      kind: { type: "string", enum: ["ticket", "plan", "spec", "proposal"], description: "Optional doc-kind filter; omit to list every kind." },
+    }),
+    responseSchema: arraySchema(objectSchema({
+      path: stringSchema("Doc identity (primary key); e.g. a ticket id."),
+      kind: { type: "string", enum: ["ticket", "plan", "spec", "proposal"], description: "Doc kind." },
+      content: stringSchema("Full markdown body."),
+      contentHash: stringSchema("sha256(content), lowercase hex."),
+      status: { type: ["string", "null"], description: "Free-form status (e.g. todo/in-progress/done); rides the row so it survives reload." },
+      updatedAtMs: integerSchema("Unix epoch milliseconds of the last write.", 0),
+    }, ["path", "kind", "content", "contentHash", "updatedAtMs"]), "Live work docs."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "Internal"],
+    exampleRequest: { kind: "ticket" },
+    exampleResponse: [{ path: "feat-issues-card", kind: "ticket", content: "# Issues card", contentHash: "0000000000000000000000000000000000000000000000000000000000000000", status: "in-progress", updatedAtMs: 1710000000000 }],
+  },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "createTicket",
+    title: "Create Ticket",
+    description: "Create or replace a work doc by `path`. Stamps `content_hash = sha256(content)` and `updated_at_ms = now`; reviving a previously soft-deleted path is intentional.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "ticket:write",
+    requestSchema: objectSchema({
+      path: stringSchema("Doc identity (primary key); e.g. `feat-issues-card`."),
+      content: stringSchema("Full markdown body."),
+      kind: { type: "string", enum: ["ticket", "plan", "spec", "proposal"], description: "Doc kind (default `ticket`)." },
+      status: stringSchema("Optional initial status."),
+    }, ["path", "content"]),
+    responseSchema: objectSchema({
+      path: stringSchema("Doc identity (primary key)."),
+      kind: { type: "string", enum: ["ticket", "plan", "spec", "proposal"], description: "Doc kind." },
+      content: stringSchema("Full markdown body."),
+      contentHash: stringSchema("sha256(content), lowercase hex."),
+      status: { type: ["string", "null"], description: "Free-form status." },
+      updatedAtMs: integerSchema("Unix epoch milliseconds of the write.", 0),
+    }, ["path", "kind", "content", "contentHash", "updatedAtMs"], "The created doc row."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "Internal"],
+    exampleRequest: { path: "feat-issues-card", content: "# Issues card", kind: "ticket", status: "todo" },
+    exampleResponse: { path: "feat-issues-card", kind: "ticket", content: "# Issues card", contentHash: "0000000000000000000000000000000000000000000000000000000000000000", status: "todo", updatedAtMs: 1710000000000 },
+  },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "updateTicket",
+    title: "Update Ticket",
+    description: "Patch a work doc's `content` and/or `status` by `path`. Re-stamps `content_hash` + `updated_at_ms` when content changes.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "ticket:write",
+    requestSchema: objectSchema({
+      path: stringSchema("Doc identity (primary key)."),
+      content: stringSchema("Optional new markdown body."),
+      status: stringSchema("Optional new status."),
+    }, ["path"]),
+    responseSchema: objectSchema({
+      path: stringSchema("Doc identity (primary key)."),
+      kind: { type: "string", enum: ["ticket", "plan", "spec", "proposal"], description: "Doc kind." },
+      content: stringSchema("Full markdown body."),
+      contentHash: stringSchema("sha256(content), lowercase hex."),
+      status: { type: ["string", "null"], description: "Free-form status." },
+      updatedAtMs: integerSchema("Unix epoch milliseconds of the write.", 0),
+    }, ["path", "kind", "content", "contentHash", "updatedAtMs"], "The updated doc row."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "TicketNotFound", "Internal"],
+    exampleRequest: { path: "feat-issues-card", status: "in-progress" },
+    exampleResponse: { path: "feat-issues-card", kind: "ticket", content: "# Issues card", contentHash: "0000000000000000000000000000000000000000000000000000000000000000", status: "in-progress", updatedAtMs: 1710000000000 },
+  },
+  {
+    version: SMITHERS_API_VERSION,
+    method: "deleteTicket",
+    title: "Delete Ticket",
+    description: "Soft-delete a work doc by `path` (stamps a `deleted_at_ms` tombstone). The row survives so `listTickets` hides it without losing history; the watcher never materializes a tombstone to disk.",
+    maturity: "stable",
+    transport: "http+websocket",
+    requiredScope: "ticket:write",
+    requestSchema: objectSchema({ path: stringSchema("Doc identity (primary key).") }, ["path"]),
+    responseSchema: objectSchema({
+      path: stringSchema("Doc identity (primary key)."),
+      deleted: booleanSchema("True when the doc was soft-deleted."),
+    }, ["path", "deleted"], "Soft-delete acknowledgement."),
+    errors: ["InvalidRequest", "Unauthorized", "Forbidden", "TicketNotFound", "Internal"],
+    exampleRequest: { path: "feat-issues-card" },
+    exampleResponse: { path: "feat-issues-card", deleted: true },
+  },
 ] as const;
 
 const definitionByMethod = new Map<string, GatewayRpcDefinition>(