catherd-cli 1.5.0 → 2.0.0-beta.20261022113309

package/src/entry/knowledge-command.ts

@@ -2,7 +2,15 @@ import { resolve } from "node:path";
 import { defineCommand } from "citty";
 import { CatherdError } from "../domain/errors.ts";
 import { gateEnvLines, readGateEnv, removeGateEnv, setGateEnv } from "../services/gate-env.ts";
-import { addKnowledge, knowledgeLines, knowledgePath, readKnowledge } from "../services/run-service.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import {
+  addKnowledge,
+  knowledgeLines,
+  knowledgePath,
+  readKnowledge,
+  removeKnowledge,
+  standingRules,
+} from "../services/run-service.ts";
 import { JSON_ARG, printJson, refuseInRole } from "./cli-kit.ts";
 
 /** `--repo`, else the repository the command runs in, as run_start and read_knowledge resolve it. */
@@ -13,8 +21,26 @@ const repoOf = (repo: string | undefined): string => resolve(repo ?? process.cwd
 
 const show = defineCommand({
   meta: { name: "show", description: "Print what catherd knows about the repo (its knowledge.md)" },
-  args: { ...REPO_ARG, ...JSON_ARG },
+  args: {
+    ...REPO_ARG,
+    role: { type: "string", description: "only the rules that reach this role" },
+    ...JSON_ARG,
+  },
   async run({ args }) {
+    if (args.role !== undefined) {
+      if (!(ROLES as readonly string[]).includes(args.role))
+        throw new CatherdError("E_INPUT_INVALID", `"${args.role}" is not a role`, {
+          fix: `pass one of ${ROLES.join(", ")}`,
+        });
+      const rules = await standingRules(repoOf(args.repo), args.role as Role);
+      if (args.json) {
+        const at = await knowledgePath(repoOf(args.repo));
+        return printJson({ ...at, role: args.role, rules });
+      }
+      const out = rules || "catherd: no knowledge recorded yet for this repo";
+      process.stdout.write(`${out}\n`);
+      return;
+    }
     if (args.json) return printJson(await knowledgeLines(repoOf(args.repo)));
     const text = await readKnowledge(repoOf(args.repo));
     process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
@@ -36,6 +62,21 @@ const add = defineCommand({
   },
 });
 
+const rm = defineCommand({
+  meta: {
+    name: "rm",
+    description: "Remove the one line of the repo's knowledge.md that contains the text",
+  },
+  args: {
+    text: { type: "positional", required: true, description: "text of the one line to remove" },
+    ...REPO_ARG,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd knowledge rm");
+    console.log(await removeKnowledge(repoOf(args.repo), args.text));
+  },
+});
+
 const path = defineCommand({
   meta: { name: "path", description: "Print the path of the repo's knowledge.md (it may not exist yet)" },
   args: { ...REPO_ARG, ...JSON_ARG },
@@ -119,7 +160,7 @@ const env = defineCommand({
 export const knowledgeCommand = defineCommand({
   meta: {
     name: "knowledge",
-    description: "What catherd knows about a repo: show, add or path, and its gate environment (env)",
+    description: "What catherd knows about a repo: show, add, rm or path, and its gate environment (env)",
   },
-  subCommands: { show, add, path, env },
+  subCommands: { show, add, rm, path, env },
 });

package/src/entry/lock-command.ts

@@ -3,7 +3,7 @@ import { defineCommand } from "citty";
 import { CatherdError } from "../domain/errors.ts";
 import { scrubSecrets } from "../infra/env.ts";
 import { gitToplevel } from "../infra/git.ts";
-import { heavySlots, withHeavySlot, withRoleLock } from "../infra/heavy-lock.ts";
+import { heavySlots, LOCK_HELD_ENV, withHeavySlot, withRoleLock } from "../infra/heavy-lock.ts";
 import { activityReporter, DISPATCH_ID_ENV } from "../infra/lock-activity.ts";
 import { killGroup } from "../infra/proc.ts";
 import { activeName, readProfileDoc } from "../services/profile-store.ts";
@@ -138,8 +138,7 @@ export function roleLockOwnerOf(run: string | undefined, env: NodeJS.ProcessEnv)
   return fromRole ? `run:${fromRole}` : `process:${process.pid}`;
 }
 
-/** Set in a locked command's env: a `catherd lock` inside it runs at once, holding nothing more. */
-export const LOCK_HELD_ENV = "CATHERD_LOCK_HELD";
+export { LOCK_HELD_ENV };
 
 export const lockCommand = defineCommand({
   meta: {
@@ -194,9 +193,9 @@ export const lockCommand = defineCommand({
     // killed before its first command
     const activity = activityReporter(process.env[DISPATCH_ID_ENV]);
     const waiting = activity ? { onWait: activity.tick } : {};
-    const run = () =>
+    const run = (_slot: number, tmp: string) =>
       runForwarding(argv, {
-        extraEnv: { [LOCK_HELD_ENV]: "1" },
+        extraEnv: { [LOCK_HELD_ENV]: "1", TMPDIR: tmp, GOTMPDIR: tmp },
         ...(activity ? { onOutput: activity.tick } : {}),
       });
     const role = args.role;
@@ -213,10 +212,10 @@ export const lockCommand = defineCommand({
         ? await withRoleLock(
             role,
             roleLockOwnerOf(args.run, process.env),
-            () => withHeavySlot(slots, run, waiting),
+            () => withHeavySlot(slots, run, { ...waiting, tmpBase: process.env.TMPDIR }),
             waiting,
           )
-        : await withHeavySlot(slots, run, waiting);
+        : await withHeavySlot(slots, run, { ...waiting, tmpBase: process.env.TMPDIR });
     } finally {
       activity?.done();
     }

package/src/entry/mcp/role-server.ts

@@ -6,6 +6,7 @@ import { ID_PATTERN } from "../../domain/ids.ts";
 import { ROLE_MCP_SERVER, type RoleMcpContext, roleMcpTools } from "../../domain/role-tools.ts";
 import { log } from "../../infra/log.ts";
 import { gateCheckOrList, gatePass } from "../../services/gate-service.ts";
+import { runMilestoneCheck } from "../../services/milestone-check.ts";
 import type { Deps } from "../../services/ports.ts";
 import { readKnowledge, readRunFile, writeRunFile } from "../../services/run-service.ts";
 import { findRun } from "../../services/run-store.ts";
@@ -103,6 +104,23 @@ export function buildRoleServer(context: RoleMcpContext, deps: Deps = defaultDep
       (a) => call("gate_pass", () => gatePass(deps, a)),
     );
   }
+  if (tools.has("gate_run"))
+    server.registerTool(
+      "gate_run",
+      {
+        description:
+          "The verifier's full check of a milestone, run by catherd on the committed HEAD in a detached worker under the verifier lock and a heavy slot: { running: false, record (exit, failing lines, log, secrets, rerunOf), missing, audit } once done; land reads that record. The same run, milestone, command and HEAD answers the recorded result (force: true runs it again). Refused while tracked files are uncommitted. Past 10 minutes it answers { running: true }: call it again to wait for the same run. at: a checkout of the run's base you prepared, to record the base's own failures, which then do not block.",
+        inputSchema: {
+          run: boundRun,
+          milestone: z.string().regex(ID_PATTERN),
+          command: z.string().min(1),
+          at: z.string().min(1).optional(),
+          force: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      },
+      (a) => call("gate_run", () => runMilestoneCheck(a)),
+    );
   return server;
 }
 

package/src/entry/mcp/server.ts

@@ -4,7 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { sessionKey, type HostContext } from "../../domain/host.ts";
-import { type CatherdError, errorMessage, isCatherdError } from "../../domain/errors.ts";
+import { type CatherdError, errorMessage } from "../../domain/errors.ts";
 import {
   isCoordinatorTool,
   refusedForRole,
@@ -14,21 +14,14 @@ import {
 import { takeBootLock } from "../../infra/boot-lock.ts";
 import { resolveHost } from "../../infra/host-context.ts";
 import { log } from "../../infra/log.ts";
-import { assertRoleMay } from "../../services/role-access.ts";
 import { currentSession } from "../../services/sessions.ts";
 import { startNotifier } from "../../services/notifier.ts";
 import type { Deps } from "../../services/ports.ts";
 import { adoptOwned, reconcileAll } from "../../services/reconcile.ts";
-import { backgroundSync } from "../../services/source-sync.ts";
+import { refreshIndex } from "../../services/catalog-service.ts";
 import { defaultDeps } from "../deps.ts";
-import { registerDispatchTools } from "./dispatch-tools.ts";
-import { registerLaneTools } from "./lane-tools.ts";
-import { registerProtocolTools } from "./protocol-tools.ts";
-import { registerPushTools } from "./push-tools.ts";
 import { handle, sdkToolError, toolOf } from "./result.ts";
-import { registerRunTools } from "./run-tools.ts";
-import { registerSetupTools } from "./setup-tools.ts";
-import { registerWorkspaceTools } from "./workspace-tools.ts";
+import { registerSessionTools } from "./session-tools.ts";
 
 type ObserveSession = (context: Deps) => (() => void) | undefined;
 
@@ -45,26 +38,12 @@ type RequestHandler = (
   extra: unknown,
 ) => unknown;
 
-/** The role server's tools that act on a run: in a role they are bound as their CLI forms are (assertRoleMay). */
-const RUN_BOUND_TOOLS = new Set(["read_run_file", "write_run_file", "gate_check", "gate_pass"]);
+/** How often a session looks for the new reports of the 2.0 runs it owns. */
+const REPORT_POLL_MS = 3_000;
 
-/**
- * Why a role process may not make this call on the full server, else null (plan 21 review, finding 3): a
- * coordinator tool; `record_agent_run`, which could fabricate a verifier's ok; or a run-bound tool on another
- * run or outside its role's tool set, as `catherd run-file` and `catherd gate` refuse it.
- */
-function roleRefusal(name: string, args: unknown, role: RoleScope): CatherdError | null {
-  if (refusedForRole(name, args, role) || name === "record_agent_run") return roleScopeError(name, role);
-  if (!RUN_BOUND_TOOLS.has(name)) return null;
-  const run = (args as { run?: unknown } | undefined)?.run;
-  try {
-    assertRoleMay(role, typeof run === "string" ? run : "", name);
-    return null;
-  } catch (e) {
-    if (isCatherdError(e)) return e;
-    throw e;
-  }
-}
+/** Why a role process may not make this call on the full server (plan 21 review, finding 3), else null: a coordinator tool. */
+const roleRefusal = (name: string, args: unknown, role: RoleScope): CatherdError | null =>
+  refusedForRole(name, args, role) ? roleScopeError(name, role) : null;
 
 /**
  * Spec 1.5 plan 21: in a role's process (`deps.role`) a coordinator tool call is refused with E_ROLE_SCOPE
@@ -168,13 +147,7 @@ export function buildServer(deps: Deps = defaultDeps(), observe?: ObserveSession
     log("warn", "tool", { tool: toolOf(message), ok: false, code });
     return r;
   };
-  registerRunTools(server, scoped);
-  registerWorkspaceTools(server, scoped);
-  registerLaneTools(server, scoped);
-  registerDispatchTools(server, scoped);
-  registerSetupTools(server, scoped);
-  registerProtocolTools(server, scoped);
-  registerPushTools(server, scoped);
+  registerSessionTools(server, scoped);
   refuseCoordinatorTools(server, deps);
   return server;
 }
@@ -197,7 +170,7 @@ export async function startMcpServer(
     const key = sessionKey(target);
     let active = observed.get(key);
     if (!active) {
-      active = startNotifier(context);
+      active = startNotifier(context, { reportPollMs: REPORT_POLL_MS });
       observed.set(key, active);
     }
     const n = active;
@@ -243,15 +216,15 @@ export async function startMcpServer(
     const epoch = generation;
     recovery = { ...deps };
     const context = recovery;
-    notifier = startNotifier(context);
+    notifier = startNotifier(context, { reportPollMs: REPORT_POLL_MS });
     const active = notifier;
     const target = currentSession(context);
     if (target) observed.set(sessionKey(target), active);
     void Promise.resolve()
       .then(() => {
-        if (lead && epoch === generation) return (o.sync ?? (() => backgroundSync()))();
+        if (lead && epoch === generation) return (o.sync ?? (() => refreshIndex({ auto: true })))();
       })
-      .catch((e: unknown) => log("debug", "sources", { error: errorMessage(e) }));
+      .catch((e: unknown) => log("debug", "catalog", { error: errorMessage(e) }));
     void (async () => {
       try {
         if (epoch !== generation) return;

package/src/entry/mcp/session-tools.ts

@@ -0,0 +1,149 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { CatherdError } from "../../domain/errors.ts";
+import { BaseBranchSchema } from "../../domain/branch.ts";
+import { ID_PATTERN } from "../../domain/ids.ts";
+import { PROFILE_NAME, ProfilePatchSchema } from "../../domain/profile.ts";
+import { knownQueueCapability } from "../../infra/codex-queue.ts";
+import { gitToplevel } from "../../infra/git.ts";
+import { redact } from "../../infra/log.ts";
+import { registerSavedSecrets } from "../../services/jev-service.ts";
+import { pausesOver } from "../../services/pause.ts";
+import type { Deps } from "../../services/ports.ts";
+import { inspectionHost } from "../../services/run-debug.ts";
+import { answerUnit, cancelRun, profileTool, runResult, runStart } from "../../services/run-client.ts";
+import { listRunViews, type RunView, runView } from "../../services/run-read.ts";
+import { findRun, listRuns } from "../../services/run-store.ts";
+import { handle } from "./result.ts";
+
+const RUN = z.string().min(1);
+const PROFILE = z.string().regex(PROFILE_NAME).optional();
+
+/**
+ * The git toplevel of `repo` (default: this server's directory, null outside a repository). A `repo` given
+ * outside a repository is refused: never the global profile in its stead.
+ */
+const toplevel = async (repo: string | undefined): Promise<string | null> => {
+  const top = await gitToplevel(repo ?? process.cwd());
+  if (top === null && repo !== undefined)
+    throw new CatherdError("E_IO_PATH", `${repo} is not inside a git repository`, {
+      fix: "pass the path of the repository, or leave repo out for the active profile",
+    });
+  return top;
+};
+
+/** The runs `status` shows without a name: every unfinished one, else the newest. */
+const unfinished = (v: RunView): boolean => (v.phase === null ? v.live.length > 0 : v.phase !== "ended");
+
+/** The six tools of a session: a run is started, watched, answered, cancelled and read; the profile is its own. */
+export function registerSessionTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "run_start",
+    {
+      description:
+        "Start a run that drives itself: catherd plans, dispatches, reviews, verifies and lands each milestone in a background daemon. Returns the run id and the ntfy url its questions go to.",
+      inputSchema: {
+        repo: z.string().min(1),
+        title: z.string().min(1),
+        a_lines: z.array(z.string().min(1)).min(1),
+        plan: z
+          .array(z.string().min(1))
+          .max(20)
+          .optional()
+          .describe(
+            "The reviewed plan files the run implements as written (paths, relative to repo or absolute). Without one, the architect writes a plan and the run waits for your approval.",
+          ),
+        base: BaseBranchSchema.optional().describe(
+          "A branch on origin (main, staging): each milestone then gets its own branch and worktree from origin/<base>, and independent milestones run side by side; without it the run works in the repo.",
+        ),
+      },
+    },
+    (a) =>
+      handle(() =>
+        runStart(deps, { repo: a.repo, title: a.title, aLines: a.a_lines, plan: a.plan, base: a.base }),
+      ),
+  );
+
+  server.registerTool(
+    "status",
+    {
+      description:
+        "Each run's phase, milestones, live roles, parked questions and quota holds, and whether its daemon is alive (a dead one is restarted). Without a run: every unfinished run, else the newest.",
+      inputSchema: { run: RUN.optional() },
+    },
+    (a) =>
+      handle(() => {
+        registerSavedSecrets();
+        const listing = a.run ? null : listRuns();
+        const views = a.run ? [runView(deps, a.run)] : listRunViews(deps);
+        const open = views.filter(unfinished);
+        const shown = a.run ? views : open.length ? open : views.slice(0, 1);
+        const queue =
+          deps.host.host === "codex" && !deps.host.conflict ? knownQueueCapability(process.env) : null;
+        return redact({
+          // a pause (the machine's, a workspace's) covers the runs shown, and comes first
+          paused: pausesOver(
+            (listing?.runs ?? [findRun(a.run as string)]).filter((r) => shown.some((v) => v.id === r.id)),
+          ),
+          version: deps.version,
+          host: inspectionHost(deps.host),
+          queue,
+          runs: shown,
+          warnings: (listing?.corrupt ?? []).map((c) => `skipped run ${c.id}: ${c.reason}`),
+        });
+      }),
+  );
+
+  server.registerTool(
+    "answer",
+    {
+      description: "Answer a parked unit (the run, a milestone or a lane): it runs again with your answer.",
+      inputSchema: { run: RUN, unit: z.string().min(1), answer: z.string().min(1) },
+    },
+    (a) => handle(() => answerUnit(deps, a)),
+  );
+
+  server.registerTool(
+    "cancel",
+    {
+      description: "Stop the run: every live role is cancelled and the run ends.",
+      inputSchema: { run: RUN },
+    },
+    (a) => handle(() => cancelRun(deps, a)),
+  );
+
+  server.registerTool(
+    "result",
+    {
+      description:
+        "The run's report (the MR body: digests, known issues, the judge's decisions), or with name one role's record.",
+      inputSchema: { run: RUN, name: z.string().regex(ID_PATTERN).optional() },
+    },
+    (a) => handle(() => runResult(deps, a)),
+  );
+
+  server.registerTool(
+    "profile",
+    {
+      description:
+        "Read, validate or change a profile, or set notify_url, where parked questions are sent. Without a name: the profile this repo runs on (repo, default this server's directory).",
+      inputSchema: {
+        action: z.enum(["get", "validate", "set"]),
+        name: PROFILE,
+        repo: z.string().min(1).optional(),
+        patch: ProfilePatchSchema.optional(),
+        notify_url: z.string().min(1).optional(),
+      },
+    },
+    (a) =>
+      handle(async () =>
+        profileTool(deps, {
+          action: a.action,
+          name: a.name,
+          repo: (await toplevel(a.repo)) ?? undefined,
+          patch: a.patch,
+          notifyUrl: a.notify_url,
+        }),
+      ),
+  );
+}

package/src/entry/panel/openapi.ts

@@ -0,0 +1,189 @@
+import { z } from "zod";
+import {
+  CheckSchema,
+  IndexedPairSchema,
+  IssueSchema,
+  ProfileSavedSchema,
+  SetupViewSchema,
+} from "../../services/panel-setup.ts";
+import { ParkedViewSchema, RunViewSchema, TimelineEntrySchema } from "../../services/run-read.ts";
+
+// The panel's HTTP API, in one table: it writes web/openapi.json (the web client is generated from it) and the
+// server parses every request with the same schemas, so the document and the server cannot drift.
+
+export const ErrorBodySchema = z.object({
+  error: z.object({ message: z.string(), type: z.string(), code: z.string(), fix: z.string().optional() }),
+});
+
+const Page = <T extends z.ZodType>(item: T) => z.object({ items: z.array(item), total: z.number().int() });
+
+export const LoginBodySchema = z.object({ token: z.string().min(1).max(200) });
+export const RungsBodySchema = z.object({ rungs: z.array(z.string().min(1)).max(50) });
+export const AnswerBodySchema = z.object({
+  unit: z.string().min(1).max(100),
+  answer: z.string().trim().min(1).max(10000),
+});
+export const AnswerResultSchema = z.object({ unit: z.string(), parked: z.array(z.string()) });
+export const CancelResultSchema = z.object({ cancelling: z.literal(true), live: z.array(z.string()) });
+export const SessionSchema = z.object({ authenticated: z.literal(true) });
+export const VersionSchema = z.object({ catherd: z.string() });
+export const RunListSchema = Page(RunViewSchema);
+export const TimelinePageSchema = Page(TimelineEntrySchema);
+export const QuestionListSchema = Page(ParkedViewSchema);
+
+const paging = {
+  limit: z.coerce.number().int().min(1).max(200).default(25),
+  offset: z.coerce.number().int().min(0).default(0),
+};
+export const ListRunsQuerySchema = z.object({
+  q: z.string().max(200).optional(),
+  phase: z.enum(["planning", "approval", "running", "ended"]).optional(),
+  ...paging,
+});
+export const TimelineQuerySchema = z.object(paging);
+export const QuestionsQuerySchema = z.object({
+  run: z.string().max(200).optional(),
+  q: z.string().max(200).optional(),
+  ...paging,
+});
+
+export type OperationId =
+  | "login"
+  | "logout"
+  | "getSession"
+  | "getVersion"
+  | "getSetup"
+  | "setRoleRungs"
+  | "listRuns"
+  | "getRun"
+  | "getRunTimeline"
+  | "cancelRun"
+  | "answerUnit"
+  | "listQuestions";
+
+export interface Operation {
+  id: OperationId;
+  method: "GET" | "POST" | "PUT";
+  path: string;
+  public?: true;
+  query?: z.ZodObject;
+  body?: z.ZodType;
+  /** null: 204 */
+  response: z.ZodType | null;
+}
+
+export const OPERATIONS: readonly Operation[] = [
+  {
+    id: "login",
+    method: "POST",
+    path: "/api/auth/login",
+    public: true,
+    body: LoginBodySchema,
+    response: null,
+  },
+  { id: "logout", method: "POST", path: "/api/auth/logout", response: null },
+  { id: "getSession", method: "GET", path: "/api/auth/session", response: SessionSchema },
+  { id: "getVersion", method: "GET", path: "/api/system/version", response: VersionSchema },
+  { id: "getSetup", method: "GET", path: "/api/setup", response: SetupViewSchema },
+  {
+    id: "setRoleRungs",
+    method: "PUT",
+    path: "/api/setup/roles/{role}",
+    body: RungsBodySchema,
+    response: ProfileSavedSchema,
+  },
+  { id: "listRuns", method: "GET", path: "/api/runs", query: ListRunsQuerySchema, response: RunListSchema },
+  { id: "getRun", method: "GET", path: "/api/runs/{id}", response: RunViewSchema },
+  {
+    id: "getRunTimeline",
+    method: "GET",
+    path: "/api/runs/{id}/timeline",
+    query: TimelineQuerySchema,
+    response: TimelinePageSchema,
+  },
+  { id: "cancelRun", method: "POST", path: "/api/runs/{id}/cancel", response: CancelResultSchema },
+  {
+    id: "answerUnit",
+    method: "POST",
+    path: "/api/runs/{id}/answers",
+    body: AnswerBodySchema,
+    response: AnswerResultSchema,
+  },
+  {
+    id: "listQuestions",
+    method: "GET",
+    path: "/api/questions",
+    query: QuestionsQuerySchema,
+    response: QuestionListSchema,
+  },
+];
+
+const SCHEMAS: Record<string, z.ZodType> = {
+  RunView: RunViewSchema,
+  ParkedView: ParkedViewSchema,
+  TimelineEntry: TimelineEntrySchema,
+  SetupView: SetupViewSchema,
+  Check: CheckSchema,
+  Issue: IssueSchema,
+  IndexedPair: IndexedPairSchema,
+  ProfileSaved: ProfileSavedSchema,
+  ErrorBody: ErrorBodySchema,
+  RunList: RunListSchema,
+  TimelinePage: TimelinePageSchema,
+  QuestionList: QuestionListSchema,
+  Session: SessionSchema,
+  Version: VersionSchema,
+  LoginBody: LoginBodySchema,
+  RungsBody: RungsBodySchema,
+  AnswerBody: AnswerBodySchema,
+  AnswerResult: AnswerResultSchema,
+  CancelResult: CancelResultSchema,
+};
+
+const REF = "#/components/schemas/";
+const nameOf = (s: z.ZodType): string => {
+  const hit = Object.entries(SCHEMAS).find(([, v]) => v === s);
+  if (!hit) throw new Error("an operation names a schema that panelOpenApi does not register");
+  return hit[0];
+};
+const refOf = (s: z.ZodType) => ({ $ref: REF + nameOf(s) });
+const json = (s: z.ZodType) => ({ content: { "application/json": { schema: refOf(s) } } });
+
+const without = ({ $schema: _s, $id: _i, ...rest }: Record<string, unknown>) => rest;
+
+/** The OpenAPI 3.1 document of OPERATIONS; `info.version` is the API's, never the package's. */
+export function panelOpenApi(): Record<string, unknown> {
+  const reg = z.registry<{ id: string }>();
+  for (const [id, s] of Object.entries(SCHEMAS)) reg.add(s, { id });
+  const out = z.toJSONSchema(reg, { uri: (id) => REF + id, io: "output" }) as {
+    schemas: Record<string, Record<string, unknown>>;
+  };
+  const schemas = Object.fromEntries(Object.entries(out.schemas).map(([k, v]) => [k, without(v)]));
+  const paths: Record<string, Record<string, unknown>> = {};
+  for (const op of OPERATIONS) {
+    const pathParams = [...op.path.matchAll(/\{(\w+)\}/g)].map((m) => ({
+      name: m[1],
+      in: "path",
+      required: true,
+      schema: { type: "string" },
+    }));
+    const queryParams = Object.entries(op.query?.shape ?? {}).map(([name, field]) => ({
+      name,
+      in: "query",
+      required: !(field as z.ZodType).safeParse(undefined).success,
+      schema: without(z.toJSONSchema(field as z.ZodType, { io: "input" }) as Record<string, unknown>),
+    }));
+    (paths[op.path] ??= {})[op.method.toLowerCase()] = {
+      operationId: op.id,
+      parameters: [...pathParams, ...queryParams],
+      ...(op.body ? { requestBody: { required: true, ...json(op.body) } } : {}),
+      responses: {
+        [op.response ? "200" : "204"]: op.response
+          ? { description: "ok", ...json(op.response) }
+          : { description: "no content" },
+        default: { description: "error", ...json(ErrorBodySchema) },
+      },
+    };
+  }
+  return { openapi: "3.1.0", info: { title: "catherd panel", version: "1" }, paths, components: { schemas } };
+}