@kindgi/api 0.1.4-rc.0 → 0.1.4-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/api",
-  "version": "0.1.4-rc.0",
+  "version": "0.1.4-rc.1",
   "description": "REST + SSE HTTP surface for Kindgi™. createApp assembles a Hono app serving the /v1/* REST API (bearer or session-token auth; OpenAPI 3.1 document at /v1/openapi.json) and an optional S3-compatible /s3/* surface (SigV4), over caller-plugged bindings for the runtime (runs, agents, flows, HITL, supervisor) and for storage. Route conventions: docs/API-ROUTE-CONVENTIONS.md.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,30 +32,30 @@
     "openapi.json"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.4-rc.0",
-    "@kindgi/audit-events": "0.1.4-rc.0",
-    "@kindgi/compliance": "0.1.4-rc.0",
-    "@kindgi/authz": "0.1.4-rc.0",
-    "@kindgi/blob-binding": "0.1.4-rc.0",
-    "@kindgi/capabilities": "0.1.4-rc.0",
-    "@kindgi/crypto": "0.1.4-rc.0",
-    "@kindgi/flow": "0.1.4-rc.0",
-    "@kindgi/guardrails": "0.1.4-rc.0",
-    "@kindgi/memory": "0.1.4-rc.0",
-    "@kindgi/platform": "0.1.4-rc.0",
-    "@kindgi/provenance": "0.1.4-rc.0",
-    "@kindgi/runtime": "0.1.4-rc.0",
-    "@kindgi/policy-contract": "0.1.4-rc.0",
-    "@kindgi/schema": "0.1.4-rc.0",
-    "@kindgi/tools": "0.1.4-rc.0",
-    "@kindgi/types": "0.1.4-rc.0",
+    "@kindgi/agents": "0.1.4-rc.1",
+    "@kindgi/audit-events": "0.1.4-rc.1",
+    "@kindgi/compliance": "0.1.4-rc.1",
+    "@kindgi/authz": "0.1.4-rc.1",
+    "@kindgi/blob-binding": "0.1.4-rc.1",
+    "@kindgi/capabilities": "0.1.4-rc.1",
+    "@kindgi/crypto": "0.1.4-rc.1",
+    "@kindgi/flow": "0.1.4-rc.1",
+    "@kindgi/guardrails": "0.1.4-rc.1",
+    "@kindgi/memory": "0.1.4-rc.1",
+    "@kindgi/platform": "0.1.4-rc.1",
+    "@kindgi/provenance": "0.1.4-rc.1",
+    "@kindgi/runtime": "0.1.4-rc.1",
+    "@kindgi/policy-contract": "0.1.4-rc.1",
+    "@kindgi/schema": "0.1.4-rc.1",
+    "@kindgi/tools": "0.1.4-rc.1",
+    "@kindgi/types": "0.1.4-rc.1",
     "@scalar/hono-api-reference": "^0.12.2",
     "hono": "^4.6.14"
   },
   "devDependencies": {
-    "@kindgi/audit-events-inmemory": "0.1.4-rc.0",
-    "@kindgi/specs": "0.1.4-rc.0",
-    "@kindgi/testing": "0.1.4-rc.0",
+    "@kindgi/audit-events-inmemory": "0.1.4-rc.1",
+    "@kindgi/specs": "0.1.4-rc.1",
+    "@kindgi/testing": "0.1.4-rc.1",
     "@types/aws4": "^1.11.6",
     "@types/node": "^22.10.5",
     "aws4": "^1.13.2",

package/src/agent-binding.ts

@@ -6,6 +6,8 @@ import type { TupleEnqueueHook } from '@kindgi/authz';
 import type { Scope } from '@kindgi/platform';
 import type { Cursor, ProjectId, Semver, TenantId } from '@kindgi/types';
 
+import type { RegistryReadOnly } from './registry-read-only.js';
+
 /**
  * Caller-plugged surface for the agent catalog. Same shape as
  * `TokenAdmin` / `ReviewerBinding` / `RunHandlerBinding`: the API
@@ -22,6 +24,13 @@ import type { Cursor, ProjectId, Semver, TenantId } from '@kindgi/types';
  * cursor round-trips as a string; it never inspects the payload.
  */
 export interface AgentRegistryBinding {
+  /**
+   * Set when this registry takes no writes (under `kindgi dev`, the
+   * pack's files are the source of its agents): every write is refused
+   * with `409 registry-read-only` and this reason, before the binding is
+   * called. See `RegistryReadOnly`.
+   */
+  readonly readOnly?: RegistryReadOnly;
   /**
    * Cursor-paginated list of agents (latest version per id, sorted by
    * agent id ascending). Optional `nameFilter` is a prefix match on the

package/src/app.ts

@@ -1289,7 +1289,16 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
     // `evalSuiteRegistry` binding: the dispatcher itself surfaces
     // `suite-not-found` when the caller-plugged binding can't resolve
     // the suite id, so the API layer stays consumer-neutral.
-    const evalRuns = evalRunsRouters(input.evalRunBinding);
+    const evalRuns = evalRunsRouters(
+      input.evalRunBinding,
+      input.flowRegistry !== undefined
+        ? {
+            flows: input.flowRegistry,
+            ...(input.agentRegistry !== undefined && { agents: input.agentRegistry }),
+            ...(input.toolRegistry !== undefined && { tools: input.toolRegistry }),
+          }
+        : undefined,
+    );
     v1.route('/eval-suites', evalRuns.start);
     v1.route('/eval-runs', evalRuns.readback);
   }

package/src/deploy-versions.ts

@@ -151,7 +151,7 @@ async function registerNextFree<T extends PinnedDefinition>(
 }
 
 /** A definition: everything but its version and what the runtime sets. */
-function definitionKey(definition: PinnedDefinition): string {
+export function definitionKey(definition: PinnedDefinition): string {
   const { version: _v, pins: _p, pinsDigest: _d, derivedFrom: _f, ...rest } = definition;
   return canonicalize(rest);
 }

package/src/derive-agent-version.ts

@@ -16,6 +16,7 @@ import type { ProjectId, Semver, TenantId } from '@kindgi/types';
 import type { AgentRegistryBinding, AgentVersionRecord } from './agent-binding.js';
 import { activeAgentVersions } from './agent-pins.js';
 import type { BlockRegistryBinding } from './block-binding.js';
+import { definitionKey } from './deploy-versions.js';
 
 /** Which data-block pins to swap, by kind then block id → exact version. */
 export interface PinSwaps {
@@ -48,6 +49,8 @@ export interface SwapIssue {
 
 export type DeriveAgentVersionOutcome =
   | { readonly kind: 'ok'; readonly agent: Agent }
+  /** An active version already has this definition and these pins: that one, unchanged. */
+  | { readonly kind: 'reused'; readonly agent: Agent }
   | { readonly kind: 'not-found' }
   | { readonly kind: 'unpinned' }
   | { readonly kind: 'invalid'; readonly issues: readonly SwapIssue[] }
@@ -63,7 +66,10 @@ const MAX_TRIES = 100;
  * reaching an agent without a code change. The new version is the old
  * one's bag with those pins swapped (`derivedFrom: { version, reason:
  * 'edited', label, by }`), numbered the next free patch after the
- * agent's highest version (versions never change).
+ * agent's highest version (versions never change). If an active version
+ * already holds that definition and those pins (the same swap derived
+ * before, or a deploy that registered it), that version is returned
+ * unchanged (`reused`) rather than a duplicate.
  *
  * Only data-block pins swap: a swap must name a block the version
  * already references (adding one is a code change), at a published,
@@ -114,6 +120,11 @@ async function publishNextFree(
 ): Promise<DeriveAgentVersionOutcome> {
   const { agents, tenantId, agentId } = input;
   const active = await activeAgentVersions(agents, tenantId, agentId);
+  // The same swap again (or a deploy that registered it) finds the
+  // version that already holds it: versions are never duplicated.
+  const key = definitionKey(derived);
+  const same = active.find((a) => a.pinsDigest === derived.pinsDigest && definitionKey(a) === key);
+  if (same !== undefined) return { kind: 'reused', agent: same };
   const highest =
     latestVersion(active.map((a) => a.version as unknown as string)) ??
     (derived.version as unknown as string);

package/src/errors.ts

@@ -67,6 +67,7 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'duplicate-edge-id': 409,
   'agent-version-mismatch': 409,
   'agent-already-registered': 409,
+  'registry-read-only': 409,
   'agent-gone': 410,
   'flow-gone': 410,
   'policy-gone': 410,

package/src/eval-run-binding.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { AgentId } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { Scope } from '@kindgi/platform';
 import type { Cursor, FlowId, ProjectId, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
 
@@ -145,6 +146,12 @@ export interface EvalComparison {
   readonly repetitions: number;
   /** How many ranked items `weightedPrecisionAtK` looks at (1–100). */
   readonly k: number;
+  /**
+   * For a flow candidate: agents and tools its replays run at other exact
+   * versions than the flow version's pins ("this flow, with `acme.scorer`
+   * at 0.4.0"), without publishing a new flow version.
+   */
+  readonly versions?: FlowVersionOverrides;
 }
 
 export interface EvalRunStartInput {

package/src/eval-run-dispatcher.ts

@@ -4,6 +4,7 @@
 import { randomUUID } from 'node:crypto';
 
 import type { ReplayTurnReport } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { RunReplayRef } from '@kindgi/runtime';
 import type { ProjectId, RunId, TenantId, Timestamp } from '@kindgi/types';
 
@@ -63,6 +64,8 @@ export interface EvalRunSubjectInvokeInput {
   readonly replay?: RunReplayRef;
   /** The conversation before the past turn, oldest first: a replayed turn starts from it. */
   readonly history?: readonly unknown[];
+  /** A flow target's agents and tools at other exact versions (`EvalComparison.versions`). */
+  readonly versions?: FlowVersionOverrides;
 }
 
 export interface EvalRunSubjectInvokeOutcome {

package/src/flow-binding.ts

@@ -6,6 +6,8 @@ import type { Flow } from '@kindgi/flow';
 import type { Scope } from '@kindgi/platform';
 import type { Cursor, FlowId, ProjectId, TenantId } from '@kindgi/types';
 
+import type { RegistryReadOnly } from './registry-read-only.js';
+
 /**
  * Caller-plugged surface for the flow catalog. Mirrors
  * `AgentRegistryBinding` 1:1 — the API package does NOT own registry
@@ -26,6 +28,13 @@ import type { Cursor, FlowId, ProjectId, TenantId } from '@kindgi/types';
  * cursor round-trips as a string; it never inspects the payload.
  */
 export interface FlowRegistryBinding {
+  /**
+   * Set when this registry takes no writes (under `kindgi dev`, the
+   * pack's files are the source of its flows): every write is refused
+   * with `409 registry-read-only` and this reason, before the binding is
+   * called. See `RegistryReadOnly`.
+   */
+  readonly readOnly?: RegistryReadOnly;
   /**
    * Cursor-paginated list of flows (latest version per id, sorted by
    * flow id ascending). Optional `nameFilter` is a prefix match on the

package/src/guardrail-binding.ts

@@ -6,6 +6,8 @@ import type { Guardrail } from '@kindgi/guardrails';
 import type { Scope } from '@kindgi/platform';
 import type { Cursor, GuardrailId, ProjectId, TenantId } from '@kindgi/types';
 
+import type { RegistryReadOnly } from './registry-read-only.js';
+
 /**
  * Caller-plugged surface for the guardrail catalog. Same shape as
  * `AgentRegistryBinding` / `ToolRegistryBinding`: the API package does
@@ -27,6 +29,13 @@ import type { Cursor, GuardrailId, ProjectId, TenantId } from '@kindgi/types';
  * inspects the payload.
  */
 export interface GuardrailRegistryBinding {
+  /**
+   * Set when this registry takes no writes (under `kindgi dev`, the
+   * pack's files are the source of its guardrails): every write is refused
+   * with `409 registry-read-only` and this reason, before the binding is
+   * called. See `RegistryReadOnly`.
+   */
+  readonly readOnly?: RegistryReadOnly;
   /**
    * Cursor-paginated list of guardrails sorted by id ascending.
    * Optional `nameFilter` is a prefix match on the guardrail id —

package/src/handler-binding.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { AgentId } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { FlowId, ProjectId, RunId, Semver, TenantId } from '@kindgi/types';
 
 /**
@@ -107,6 +108,8 @@ export interface InvokeFlowBindingInput {
    * can't run in the background may treat `false` like `true`.
    */
   readonly wait?: boolean;
+  /** Agents and tools to run at other exact versions than the flow version's pins (`RunFlowInput.versions`). */
+  readonly versions?: FlowVersionOverrides;
 }
 
 export type RunHandlerOutcome =

package/src/index.ts

@@ -239,6 +239,7 @@ export type {
   AgentUnregisterInput,
   AgentUnregisterOutcome,
 } from './agent-binding.js';
+export type { RegistryReadOnly } from './registry-read-only.js';
 export type {
   FlowGetInput,
   FlowGetVersionInput,

package/src/judged-dispatcher.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ReplayTurnReport } from '@kindgi/agents';
+import type { FlowVersionOverrides } from '@kindgi/flow';
 import type { RunId } from '@kindgi/types';
 
 import type { EvalCaseStoreBinding, JudgedEvalCase } from './eval-case-binding.js';
@@ -81,7 +82,13 @@ export type RecordedVersion =
 /** What ran on the cases: an agent version, or a flow version. */
 export type ComparisonCandidate =
   | { readonly kind: 'agent'; readonly agentId: string; readonly version: string }
-  | { readonly kind: 'flow'; readonly flowId: string; readonly version: string };
+  | {
+      readonly kind: 'flow';
+      readonly flowId: string;
+      readonly version: string;
+      /** Agents and tools its replays ran at other versions than the flow version's pins. */
+      readonly versions?: FlowVersionOverrides;
+    };
 
 /** What a comparison eval run concluded: what a promotion gate reads. */
 export interface JudgedComparisonSummary {
@@ -150,6 +157,9 @@ export interface JudgedDispatcherOptions {
 /** Cases read per page. */
 const CASE_PAGE = 100;
 
+export const VERSIONS_NEED_A_FLOW =
+  '`versions` runs a flow with some of its agents or tools at other versions: it needs `flowRef`.';
+
 function validateComparison(
   suite: { readonly spec: Readonly<Record<string, unknown>> },
   target: AgentRef | FlowRef,
@@ -168,6 +178,9 @@ function validateComparison(
     return { kind: 'err', message: 'The test set has no cases.' };
   }
   const c = comparison ?? DEFAULT_COMPARISON;
+  if (c.versions !== undefined && 'agentId' in target) {
+    return { kind: 'err', message: VERSIONS_NEED_A_FLOW };
+  }
   if (c.baseline !== 'recorded') {
     return { kind: 'err', message: "Only `baseline: 'recorded'` runs today." };
   }
@@ -337,6 +350,8 @@ async function invokeCase(
         evalRunId: ctx.runId as unknown as string,
       },
       ...(judgedCase.subject.kind === 'agent' && { history: judgedCase.context?.history ?? [] }),
+      ...(!('agentId' in ctx.target) &&
+        ctx.comparison?.versions !== undefined && { versions: ctx.comparison.versions }),
     });
   } catch (cause) {
     return { error: cause instanceof Error ? cause.message : String(cause) };
@@ -467,7 +482,7 @@ function summarize(
           : 'failed',
     completedAt: new Date().toISOString(),
     suite: { id: ctx.suite.id, version: ctx.suite.version },
-    candidate: candidateOf(ctx.target),
+    candidate: candidateOf(ctx.target, ctx.comparison?.versions),
     baseline: {
       kind: 'recorded',
       versions: [...versions.values()].map(
@@ -500,8 +515,16 @@ function summarize(
   };
 }
 
-function candidateOf(target: AgentRef | FlowRef): ComparisonCandidate {
+function candidateOf(
+  target: AgentRef | FlowRef,
+  versions: FlowVersionOverrides | undefined,
+): ComparisonCandidate {
   return 'agentId' in target
     ? { kind: 'agent', agentId: target.agentId as unknown as string, version: target.version ?? '' }
-    : { kind: 'flow', flowId: target.flowId as unknown as string, version: target.version ?? '' };
+    : {
+        kind: 'flow',
+        flowId: target.flowId as unknown as string,
+        version: target.version ?? '',
+        ...(versions !== undefined && { versions }),
+      };
 }

package/src/openapi/operations.ts

@@ -1686,8 +1686,16 @@ export const OPERATIONS: readonly OperationSpec[] = [
     parameters: [AgentIdPathParam, IdempotencyKeyParam],
     requestBody: { required: true, schema: ref('DeriveAgentVersionBody') },
     responses: {
+      '200': {
+        description:
+          'An active version already holds this definition and these pins (the same swap derived before, or a deploy that registered it): that version, unchanged.',
+        schema: ref('Agent'),
+      },
       '201': { description: 'The derived agent version.', schema: ref('Agent') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '400': ErrorResponse(
         "`validation-failed`: `from` has no pins, a swap names a block it doesn't reference, or a version that isn't published, active or the right kind (see `details.issues`).",
       ),
@@ -1725,7 +1733,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '201': { description: 'Agent published.', schema: ref('PublishAgentResult') },
       ...CommonMutationErrors,
       '400': ErrorResponse('Validation failed (see `details.issues`).'),
-      '409': ErrorResponse('Agent already registered at that (id, version).'),
+      '409': ErrorResponse(
+        "Agent already registered at that (id, version). Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
     },
   },
   {
@@ -1740,6 +1750,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Unregistered.', schema: ref('UnregisterAgentResult') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '404': ErrorResponse('No agent at that (id, version) under this tenant.'),
     },
   },
@@ -1757,6 +1770,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Reinstated.', schema: ref('ReinstateAgentVersionResult') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '404': ErrorResponse('No agent at that (id, version) under this tenant.'),
     },
   },
@@ -1848,7 +1864,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '201': { description: 'Flow published.', schema: ref('PublishFlowResult') },
       ...CommonMutationErrors,
       '400': ErrorResponse('Validation failed (see `details.issues`).'),
-      '409': ErrorResponse('Flow already registered at that (id, version).'),
+      '409': ErrorResponse(
+        "Flow already registered at that (id, version). Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
     },
   },
   {
@@ -1863,6 +1881,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Unregistered.', schema: ref('UnregisterFlowResult') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '404': ErrorResponse('No flow at that (id, version) under this tenant.'),
     },
   },
@@ -1880,6 +1901,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Reinstated.', schema: ref('ReinstateFlowVersionResult') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '404': ErrorResponse('No flow at that (id, version) under this tenant.'),
     },
   },
@@ -1975,7 +1999,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '201': { description: 'Tool registered.', schema: ref('RegisterToolResult') },
       ...CommonMutationErrors,
       '400': ErrorResponse('Validation failed (see `details.issues`).'),
-      '409': ErrorResponse('Tool already registered at that id.'),
+      '409': ErrorResponse(
+        "Tool already registered at that id. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
     },
   },
   {
@@ -1990,6 +2016,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Unregistered.', schema: ref('UnregisterToolResult') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '404': ErrorResponse('No tool at that (id, version) under this tenant.'),
     },
   },
@@ -2007,6 +2036,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Reinstated.', schema: ref('ReinstateToolVersionResult') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '404': ErrorResponse('No tool at that (id, version) under this tenant.'),
     },
   },
@@ -2067,7 +2099,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '201': { description: 'Guardrail registered.', schema: ref('RegisterGuardrailResult') },
       ...CommonMutationErrors,
       '400': ErrorResponse('Validation failed (see `details.issues`).'),
-      '409': ErrorResponse('Guardrail already registered at that id.'),
+      '409': ErrorResponse(
+        "Guardrail already registered at that id. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
     },
   },
   {
@@ -2082,6 +2116,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '200': { description: 'Unregistered.', schema: ref('UnregisterGuardrailResult') },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '404': ErrorResponse('No guardrail with that id under this tenant.'),
     },
   },
@@ -4131,6 +4168,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
         schema: ref('DeploymentRecord'),
       },
       ...CommonMutationErrors,
+      '409': ErrorResponse(
+        "Idempotency-Key was reused with a different body, or resource-state conflict. Or `registry-read-only`: this registry takes no writes (under `kindgi dev`, the pack's files are the source); the message says what to do instead.",
+      ),
       '400': ErrorResponse(
         'Signature invalid, image unverifiable, or deployment-validation-failed with per-primitive `details[]`.',
       ),
@@ -4632,6 +4672,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Team created.', schema: ref('CreateResourceResult') },
       ...CommonMutationErrors,
+      '404': ErrorResponse(
+        'org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).',
+      ),
     },
   },
   {
@@ -4679,7 +4722,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '204': { description: 'Updated. No body.' },
       ...CommonMutationErrors,
-      '404': ErrorResponse('No team with that id under this tenant.'),
+      '404': ErrorResponse(
+        'team-not-found: no team with that id under this tenant; or org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).',
+      ),
     },
   },
   {
@@ -4893,6 +4938,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '201': { description: 'Project created.', schema: ref('CreateResourceResult') },
       ...CommonMutationErrors,
+      '404': ErrorResponse(
+        'org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).',
+      ),
     },
   },
   {
@@ -4942,7 +4990,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
     responses: {
       '204': { description: 'Updated. No body.' },
       ...CommonMutationErrors,
-      '404': ErrorResponse('No project with that id under this tenant.'),
+      '404': ErrorResponse(
+        'project-not-found: no project with that id under this tenant; or org-not-found: `orgId` names no org of the tenant (it never existed, or it was deleted).',
+      ),
     },
   },
   {