@intentic/sandbox-contract 1.225.0 → 1.226.1

package/src/contracts/share.contract.ts

@@ -11,10 +11,43 @@ import { OkSchema, ShareCreateSchema, ShareListSchema, ShareRemoveSchema, ShareU
  * There is no route to read a share back. The page is the read, it answers on the unauthenticated
  * `public-<slot>` hostname like every other published file, which is the point of having made one. */
 export const shareContract = {
-    list: oc.route({ method: "GET", path: "/share" }).output(ShareListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/share",
+            summary: "Conversations published as pages",
+            description:
+                "Every conversation that has been turned into a read-only page, with its link. There is no call to read one back: the page itself is the read, and it answers to anyone who has the link.",
+        })
+        .output(ShareListSchema),
     // Answers with the row it just wrote, link included, so the dialog can show the address without re-listing.
-    create: oc.route({ method: "POST", path: "/share" }).input(ShareCreateSchema).output(SharedConversationSchema),
+    create: oc
+        .route({
+            method: "POST",
+            path: "/share",
+            summary: "Publish a conversation",
+            description:
+                "Renders a conversation into a page anybody with the link can read, without signing in. Answers with the link, so nothing has to be listed again to find it.",
+        })
+        .input(ShareCreateSchema)
+        .output(SharedConversationSchema),
     // Re-render an existing share from the conversation as it stands now. Same id, same link, new snapshot.
-    update: oc.route({ method: "POST", path: "/share/update" }).input(ShareUpdateSchema).output(SharedConversationSchema),
-    remove: oc.route({ method: "POST", path: "/share/remove" }).input(ShareRemoveSchema).output(OkSchema),
+    update: oc
+        .route({
+            method: "POST",
+            path: "/share/update",
+            summary: "Refresh a published page",
+            description: "Re-renders an existing page from the conversation as it stands now. Same link, newer contents.",
+        })
+        .input(ShareUpdateSchema)
+        .output(SharedConversationSchema),
+    remove: oc
+        .route({
+            method: "POST",
+            path: "/share/remove",
+            summary: "Unpublish a conversation",
+            description: "Takes the page down, so the link stops answering.",
+        })
+        .input(ShareRemoveSchema)
+        .output(OkSchema),
 };

package/src/contracts/skills.contract.ts

@@ -15,10 +15,45 @@ import { OkSchema, SkillBodySchema, SkillDraftSchema, SkillIdSchema, SkillRemove
  * `read` is a GET with the id in the query rather than in the path: an id can name an owner
  * (`extension:intentic.knowledge:knowledge`), and a path template cannot carry those segments. */
 export const skillsContract = {
-    list: oc.route({ method: "GET", path: "/skills" }).output(SkillsListSchema),
-    read: oc.route({ method: "GET", path: "/skills/read" }).input(SkillIdSchema).output(SkillBodySchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/skills",
+            summary: "What the agent knows how to do",
+            description:
+                "Every skill available here and whether it is switched on, joined from all four places they come from: the owner's own, the settings, plugins a connection installed, and folders inside extensions.",
+        })
+        .output(SkillsListSchema),
+    read: oc
+        .route({
+            method: "GET",
+            path: "/skills/read",
+            summary: "Read one skill",
+            description:
+                "The full text of a single skill. The name travels in the query rather than the address, because a name can carry the owner it came from and that will not fit in a path.",
+        })
+        .input(SkillIdSchema)
+        .output(SkillBodySchema),
     // Upsert by name: saving over an existing skill rewrites it, which is also how one is renamed (the old name
     // is a different skill and is deleted on its own). A saved skill is switched ON, you wrote it to use it.
-    save: oc.route({ method: "POST", path: "/skills" }).input(SkillDraftSchema).output(OkSchema),
-    remove: oc.route({ method: "POST", path: "/skills/remove" }).input(SkillRemoveSchema).output(OkSchema),
+    save: oc
+        .route({
+            method: "POST",
+            path: "/skills",
+            summary: "Write a skill",
+            description:
+                "Creates or rewrites a skill by name, and switches it on, because you wrote it in order to use it. Renaming is saving under the new name and deleting the old.",
+        })
+        .input(SkillDraftSchema)
+        .output(OkSchema),
+    remove: oc
+        .route({
+            method: "POST",
+            path: "/skills/remove",
+            summary: "Delete a skill",
+            description:
+                "Removes the text and takes it off the enabled list in one step, so a screen never has to sequence two calls and never leaves one half done.",
+        })
+        .input(SkillRemoveSchema)
+        .output(OkSchema),
 };

package/src/contracts/system.contract.ts

@@ -26,33 +26,101 @@ import {
 // aborts. `clientId` is the tab's per-connection presence key; absent (an older web client) means the
 // connection simply never joins the roster.
 export const systemContract = {
-    info: oc.route({ method: "GET", path: "/info" }).output(InfoSchema),
+    info: oc
+        .route({
+            method: "GET",
+            path: "/info",
+            summary: "What this sandbox is",
+            description:
+                "The sandbox's own identity and state: which workspace it holds, which image it runs, what it is called, and the list of calls it actually implements. Start here, because a browser is routinely newer than the sandbox it is talking to and this is how it finds out what is there.",
+        })
+        .output(InfoSchema),
     // What the daemon could not read in its own `.intentic/` manifests, a file it fell back on, a key it did
     // not recognise, an entry it skipped. Its own route rather than a field on /info because it is invalidated
     // by a different thing: a manifest changing on disk, which the workspace-state table already broadcasts.
-    manifestProblems: oc.route({ method: "GET", path: "/system/manifest-problems" }).output(ManifestProblemsSchema),
+    manifestProblems: oc
+        .route({
+            method: "GET",
+            path: "/system/manifest-problems",
+            summary: "Settings files the sandbox could not read",
+            description:
+                "Anything the daemon tripped over in its own configuration on disk: a file it had to fall back from, a key it did not recognise, an entry it skipped. Separate from the identity call because it goes stale for a different reason, namely a file changing.",
+        })
+        .output(ManifestProblemsSchema),
     // Exchange the request's verified bearer (a Google ID token, or a still-valid session, which makes this
     // route sliding renewal) for a daemon-minted session, the credential every steady-state call presents.
-    session: oc.route({ method: "POST", path: "/system/session" }).output(DaemonSessionSchema),
+    session: oc
+        .route({
+            method: "POST",
+            path: "/system/session",
+            summary: "Trade a sign-in for a session",
+            description:
+                "Exchanges a verified sign-in, or a session that has not expired yet, for a fresh session the daemon minted. That session is the credential every other call carries, and calling this again with a live one renews it.",
+        })
+        .output(DaemonSessionSchema),
     events: oc
-        .route({ method: "GET", path: "/events" })
+        .route({
+            method: "GET",
+            path: "/events",
+            summary: "The live event stream",
+            description:
+                "A stream held open for as long as you want it, carrying heartbeats so a caller notices the sandbox dying at once, batches of file changes so a tree or an editor can refresh itself, and the roster of who else is looking. Give it an id for this connection to appear in that roster; leave it out and you watch without being seen.",
+        })
         .input(z.object({ clientId: z.string().optional() }))
         .output(eventIterator(SystemEventSchema)),
     // A tab's activity self-report (view/session/file/idle), fanned back out to every member on /events.
-    presence: oc.route({ method: "POST", path: "/system/presence" }).input(PresenceReportSchema).output(OkSchema),
+    presence: oc
+        .route({
+            method: "POST",
+            path: "/system/presence",
+            summary: "Say what you are looking at",
+            description:
+                "Reports which view, conversation or file this connection is on, or that it has gone idle. The daemon fans it back out on the event stream so everyone else's roster updates.",
+        })
+        .input(PresenceReportSchema)
+        .output(OkSchema),
     // Per-account token/cost totals, aggregated from the activity log's turn.completed events.
-    usage: oc.route({ method: "GET", path: "/system/usage" }).output(UsageSummarySchema),
+    usage: oc
+        .route({
+            method: "GET",
+            path: "/system/usage",
+            summary: "What has been spent",
+            description: "Token and cost totals per account, added up from the record of every finished turn.",
+        })
+        .output(UsageSummarySchema),
     // The web-owned tmux sessions behind the terminal tabs. `terminals` enumerates them (the panel rebuilds a tab
     // per name on load/reload); `killTerminal` destroys one when its tab's close button is clicked. The live I/O
     // is the separate /system/terminal WebSocket, these are just the control plane. Bearer-authed like the rest
     // (browser fetch sends the header), unlike the header-less WS route which app.ts exempts.
-    terminals: oc.route({ method: "GET", path: "/system/terminals" }).output(TerminalsListSchema),
-    killTerminal: oc.route({ method: "DELETE", path: "/system/terminals/{name}" }).input(TerminalNameParamSchema).output(OkSchema),
+    terminals: oc
+        .route({
+            method: "GET",
+            path: "/system/terminals",
+            summary: "Open terminals",
+            description:
+                "The terminal sessions this sandbox is holding, which is what a terminal panel rebuilds its tabs from after a reload. The live typing and output run over a separate socket; this is the list.",
+        })
+        .output(TerminalsListSchema),
+    killTerminal: oc
+        .route({
+            method: "DELETE",
+            path: "/system/terminals/{name}",
+            summary: "Close a terminal",
+            description: "Destroys one terminal session and whatever was running inside it.",
+        })
+        .input(TerminalNameParamSchema)
+        .output(OkSchema),
     // One session's pane history as selectable text, the answer to "scroll back and copy that" in a surface
     // whose live view is a tmux client on the alternate screen, where the scrollback is on the far side of the
     // socket and the page has nothing to select. See TerminalScrollbackSchema.
     terminalScrollback: oc
-        .route({ method: "GET", path: "/system/terminals/{name}/scrollback" })
+        .route({
+            method: "GET",
+            path: "/system/terminals/{name}/scrollback",
+            summary: "A terminal's history as plain text",
+            description:
+                "What has scrolled past in one terminal, as text you can select and copy. The live view is a picture of a screen on the far side of a socket, with nothing in the page to select, so scrolling back and copying is this call rather than a gesture.",
+        })
         .input(TerminalScrollbackQuerySchema)
         .output(TerminalScrollbackSchema),
     // The agent's live Chromiums and the pages each has open, the Browsers view's roster, polled while it is on
@@ -60,8 +128,25 @@ export const systemContract = {
     // separate /system/browser-view WebSocket; this is the control plane, exactly as `terminals` is for tmux.
     // `closeBrowser` shuts one Chromium down: the agent's next browser tool call then fails as if it had crashed,
     // which is the honest account of the owner pulling the plug.
-    browsers: oc.route({ method: "GET", path: "/system/browsers" }).output(BrowsersListSchema),
-    closeBrowser: oc.route({ method: "DELETE", path: "/system/browsers/{name}" }).input(BrowserNameParamSchema).output(OkSchema),
+    browsers: oc
+        .route({
+            method: "GET",
+            path: "/system/browsers",
+            summary: "Browsers the agent has open",
+            description:
+                "Every browser a conversation currently has running and the pages inside each one. The picture of what they are showing comes over a separate socket; this is the roster.",
+        })
+        .output(BrowsersListSchema),
+    closeBrowser: oc
+        .route({
+            method: "DELETE",
+            path: "/system/browsers/{name}",
+            summary: "Shut a browser down",
+            description:
+                "Closes one of the agent's browsers. Its next attempt to use that browser then fails as though it had crashed, which is the honest account of somebody pulling the plug.",
+        })
+        .input(BrowserNameParamSchema)
+        .output(OkSchema),
     // The agents this sandbox's agents started. SDK subagents and delegated Codex/Grok runs alike (see
     // SubagentSessionSchema). Same two-route shape as the browsers above, and same division of labour: the list
     // is polled by the Subagents area while it is on screen and loosely by the rail, so its tile can appear the
@@ -69,9 +154,23 @@ export const systemContract = {
     // what you watch it through is its TRANSCRIPT, which `subagentTranscript` serves in the one shape every
     // other transcript route already answers in: live from the parent turn's frame log while it runs, off the
     // provider's own store once it has finished.
-    subagents: oc.route({ method: "GET", path: "/system/subagents" }).output(SubagentsListSchema),
+    subagents: oc
+        .route({
+            method: "GET",
+            path: "/system/subagents",
+            summary: "Helpers the agents have started",
+            description:
+                "Every helper agent this sandbox's conversations have delegated work to, whichever tool started it, with what each one is doing.",
+        })
+        .output(SubagentsListSchema),
     subagentTranscript: oc
-        .route({ method: "GET", path: "/system/subagents/{id}/transcript" })
+        .route({
+            method: "GET",
+            path: "/system/subagents/{id}/transcript",
+            summary: "A helper agent's record",
+            description:
+                "The full record of one delegated helper, in the same shape as any other conversation. It comes live from the parent turn while the helper works, and from stored history once it has finished.",
+        })
         .input(SubagentIdParamSchema)
         .output(SessionTranscriptSchema),
     /* Start, stop, restart, update, rebuild, roll back or remove a sandbox on one of the user's own computers,
@@ -82,7 +181,13 @@ export const systemContract = {
      * judgement, the machine enforces its own switches and its refusal arrives as the terminal `error` line,
      * in its own words, naming the control to flip. */
     manageMachineSandbox: oc
-        .route({ method: "POST", path: "/system/computers/{id}/sandboxes/{slug}" })
+        .route({
+            method: "POST",
+            path: "/system/computers/{id}/sandboxes/{slug}",
+            summary: "Drive a sandbox on one of your own computers",
+            description:
+                "Start, stop, restart, update, rebuild, roll back or remove a sandbox running on a machine you own, relayed over the connection that machine holds open. The answer is a stream because the slowest of these takes minutes, and it is the same stream whichever you ask for. The daemon adds no opinion: the machine enforces its own permissions and a refusal arrives as the last line, in the machine's words, naming the switch to flip.",
+        })
         .input(MachineSandboxFlowInputSchema)
         .output(eventIterator(MachineFlowLineSchema)),
 };

package/src/contracts/translator.contract.ts

@@ -12,14 +12,42 @@ import { KeyedProviderSchema, OkSchema, TranslatorAccountsSchema, TranslatorComp
 // URL this sandbox can't receive, so `complete` hands the landing URL to the translator. `connect.flow` tells the
 // card which mechanic it received without inferring it from whether an optional device code happened to exist.
 export const translatorContract = {
-    accounts: oc.route({ method: "GET", path: "/translator/accounts" }).output(TranslatorAccountsSchema),
+    accounts: oc
+        .route({
+            method: "GET",
+            path: "/translator/accounts",
+            summary: "Subscriptions connected through the translator",
+            description:
+                "What is signed in per provider. Each provider can hold several accounts at once, and the translator spreads work across them.",
+        })
+        .output(TranslatorAccountsSchema),
     connect: oc
-        .route({ method: "POST", path: "/translator/{provider}/connect" })
+        .route({
+            method: "POST",
+            path: "/translator/{provider}/connect",
+            summary: "Start connecting a subscription",
+            description:
+                "Begins the sign-in for one provider and says which of the two shapes it is: a code you type into a device page, which finishes by itself in the background, or a redirect whose landing address you hand back afterwards.",
+        })
         .input(z.object({ provider: KeyedProviderSchema }))
         .output(TranslatorStartSchema),
-    complete: oc.route({ method: "POST", path: "/translator/{provider}/complete" }).input(TranslatorCompleteSchema).output(OkSchema),
+    complete: oc
+        .route({
+            method: "POST",
+            path: "/translator/{provider}/complete",
+            summary: "Finish a redirect sign-in",
+            description:
+                "For the providers that redirect somewhere this sandbox cannot receive: hand back the address you landed on and the connection completes.",
+        })
+        .input(TranslatorCompleteSchema)
+        .output(OkSchema),
     disconnect: oc
-        .route({ method: "POST", path: "/translator/{provider}/disconnect" })
+        .route({
+            method: "POST",
+            path: "/translator/{provider}/disconnect",
+            summary: "Disconnect one subscription",
+            description: "Clears a single account by name. Any others under the same provider stay connected.",
+        })
         .input(z.object({ provider: KeyedProviderSchema, name: z.string().min(1) }))
         .output(OkSchema),
 };

package/src/contracts/usage.contract.ts

@@ -6,5 +6,14 @@ import { DayWindowQuerySchema, UsageRollupSchema } from "../schemas.js";
 // activity log. `rollup` serves every cost/usage panel: it groups by day × provider × account × model, and the
 // browser re-projects from there (spend per day, cost by model, cache hit rate) without another round trip.
 export const usageContract = {
-    rollup: oc.route({ method: "GET", path: "/usage/rollup" }).input(DayWindowQuerySchema).output(UsageRollupSchema),
+    rollup: oc
+        .route({
+            method: "GET",
+            path: "/usage/rollup",
+            summary: "What was spent, grouped",
+            description:
+                "The spending record over a range of days, grouped by day, provider, account and model. Everything a cost screen shows is a rearrangement of this one answer, so nothing needs a second call. Read-only: rows are written by the sandbox as turns end, which is what makes it worth trusting.",
+        })
+        .input(DayWindowQuerySchema)
+        .output(UsageRollupSchema),
 };

package/src/contracts/vpn.contract.ts

@@ -19,17 +19,48 @@ import {
 // tunnel from a shell and the UI dropping it are the same event, and a daemon restart observes the truth.
 export const vpnContract = {
     // Every configured VPN with its live link state, the Status card, the rail indicator, and `vpn list`.
-    list: oc.route({ method: "GET", path: "/vpn" }).output(VpnListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/vpn",
+            summary: "Configured tunnels and which are up",
+            description:
+                "Every stored VPN with its live link state, read back from the operating system rather than from memory, so a tunnel dropped from a shell and one dropped from a screen look the same here.",
+        })
+        .output(VpnListSchema),
     // Dial a stored VPN. Streams the client's progress (auth, then routing) because a dial takes seconds and
     // can fail with something the user must read, a wrong password, an untrusted gateway certificate, or a
     // required 2FA code. Idempotent: connecting an already-up tunnel reports it and stops.
-    connect: oc.route({ method: "POST", path: "/vpn/{id}/connect" }).input(VpnConnectInputSchema).output(eventIterator(IntenticLineSchema)),
+    connect: oc
+        .route({
+            method: "POST",
+            path: "/vpn/{id}/connect",
+            summary: "Dial a VPN",
+            description:
+                "Brings a stored tunnel up, streaming the client's progress as it authenticates and then sets up routing. Streamed because a dial takes seconds and can fail with something you have to read: a wrong password, a gateway certificate nobody trusts, a code it wants. Connecting one that is already up simply says so.",
+        })
+        .input(VpnConnectInputSchema)
+        .output(eventIterator(IntenticLineSchema)),
     // Drop a tunnel. Tolerates an already-down one, "make it not be up" is the contract, not "it was up".
-    disconnect: oc.route({ method: "POST", path: "/vpn/{id}/disconnect" }).input(VpnIdParamSchema).output(OkSchema),
+    disconnect: oc
+        .route({
+            method: "POST",
+            path: "/vpn/{id}/disconnect",
+            summary: "Drop a tunnel",
+            description: "Takes the tunnel down. One that was already down is fine: the promise is that it is not up afterwards.",
+        })
+        .input(VpnIdParamSchema)
+        .output(OkSchema),
     // Parse an exported FortiClient configuration into addable connections, so a user with that file fills the
     // add form by picking a connection instead of re-keying host/port/protocol per tunnel.
     importForticlient: oc
-        .route({ method: "POST", path: "/vpn/import-forticlient" })
+        .route({
+            method: "POST",
+            path: "/vpn/import-forticlient",
+            summary: "Read connections out of an exported config",
+            description:
+                "Turns an exported FortiClient configuration into a list of connections you can add, so somebody holding that file picks from a list instead of retyping a host and port for every tunnel.",
+        })
         .input(ForticlientImportInputSchema)
         .output(ForticlientImportSchema),
 };

package/src/contracts/workflows.contract.ts

@@ -26,25 +26,68 @@ import {
 export const workflowsContract = {
     // Every saved workflow with its run history, newest run first. One route rather than two because the list
     // page shows both and a workflow with no runs is the interesting case, not an error.
-    list: oc.route({ method: "GET", path: "/workflows" }).output(WorkflowsListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/workflows",
+            summary: "Saved workflows and their runs",
+            description:
+                "Every workflow somebody has designed, each with its own run history, newest first. One answer rather than two, because a workflow that has never been run is the interesting case rather than a mistake.",
+        })
+        .output(WorkflowsListSchema),
     /* Create or replace a workflow, with the operation made explicit so an accidental id collision cannot turn
      * a create into replacement. Refuses a graph that cannot run, a cycle, a `needs` naming a step
      * that is not there, a step with no way to know it is finished, with the same sentences the designer shows
      * while you type (see workflowFaults). Validation lives in the contract precisely so those two can never
      * disagree about what is legal. */
-    save: oc.route({ method: "POST", path: "/workflows" }).input(WorkflowSaveSchema).output(WorkflowSchema),
+    save: oc
+        .route({
+            method: "POST",
+            path: "/workflows",
+            summary: "Create or replace a workflow",
+            description:
+                "Writes a workflow design. Say which of the two you mean, so an id that happens to collide cannot silently overwrite somebody's work. A design that could never run is refused, in the same words the editor shows while you type: a loop in the steps, a step waiting on one that is not there, a step with no way of knowing it is finished.",
+        })
+        .input(WorkflowSaveSchema)
+        .output(WorkflowSchema),
     // Deleting a workflow does NOT stop a run of it that is in flight, and does not delete its history: the run
     // snapshotted its definition when it started, so it stays readable and stays stoppable.
-    remove: oc.route({ method: "DELETE", path: "/workflows/{id}" }).input(WorkflowIdParamSchema).output(OkSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/workflows/{id}",
+            summary: "Delete a workflow",
+            description:
+                "Removes the design. A run of it that is already going keeps going and stays readable and stoppable, because a run takes its own copy of the design when it starts.",
+        })
+        .input(WorkflowIdParamSchema)
+        .output(OkSchema),
     /* Start a run, optionally pointed at a request, the sentence the user typed in the composer, which every
      * step is handed on top of its own prompt. Every step is recorded `pending` up front, so the graph is
      * complete from the first frame and a missing node never has to mean two things. Several runs of one
      * workflow may be in flight at once, they derive different conversation ids, so nothing is shared and
      * nothing can collide, which is what makes "run this design again on a different question" free. */
-    run: oc.route({ method: "POST", path: "/workflows/{id}/run" }).input(WorkflowRunStartSchema).output(WorkflowRunSchema),
+    run: oc
+        .route({
+            method: "POST",
+            path: "/workflows/{id}/run",
+            summary: "Start a workflow",
+            description:
+                "Kicks a workflow off and answers immediately with the run as recorded; the work carries on without you. Point it at a question and every step gets that on top of its own instructions. Every step is written down as waiting up front, so the picture is complete from the first frame. Several runs of one design can be in flight at once without colliding.",
+        })
+        .input(WorkflowRunStartSchema)
+        .output(WorkflowRunSchema),
     // Every run across every workflow, newest first, the history the run view opens onto, and the only place a
     // deleted workflow's runs are still reachable.
-    runs: oc.route({ method: "GET", path: "/workflows/runs" }).output(WorkflowRunsListSchema),
+    runs: oc
+        .route({
+            method: "GET",
+            path: "/workflows/runs",
+            summary: "Every workflow run",
+            description:
+                "All runs across all workflows, newest first. This is also the only place the runs of a deleted workflow are still reachable.",
+        })
+        .output(WorkflowRunsListSchema),
     /* Stop a run: nothing that has not started will start, and the steps in flight are CUT OFF where they
      * are, their turns aborted exactly as /agent/stop aborts one, so whatever they had written stays on
      * their branches and the step settles as stopped.
@@ -58,7 +101,16 @@ export const workflowsContract = {
      * was replaced mid-flight. That case used to be refused, which made the stuck run permanent: a Stop that
      * could not work, a step count that would never move, and no way off the board.
      */
-    stopRun: oc.route({ method: "POST", path: "/workflows/runs/{runId}/stop" }).input(WorkflowRunIdParamSchema).output(OkSchema),
+    stopRun: oc
+        .route({
+            method: "POST",
+            path: "/workflows/runs/{runId}/stop",
+            summary: "Stop a run now",
+            description:
+                "Nothing further starts, and the steps already going are cut off where they stand. Whatever they had written stays on their branches. Deliberately abrupt rather than letting the current step finish: a step is a whole agent turn, and a stop that kept spending for minutes afterwards is indistinguishable from a button that does nothing. It always ends the run, including one left stranded by a daemon that was replaced mid-flight.",
+        })
+        .input(WorkflowRunIdParamSchema)
+        .output(OkSchema),
     /* Take an ENDED run off the board, the run's half of `agents.archive`, and the same bargain: nothing is
      * lost, the checkouts are reclaimed, and `unarchiveRun` puts it all back. It needs an exit of its own
      * because nothing about a run transitions once it is over, so a failed one would sit in Attention until
@@ -71,8 +123,25 @@ export const workflowsContract = {
      * route archives what the user named without re-litigating whether each one was ready to go, and a run the
      * user has archived is exactly that gesture made once for the whole graph.
      */
-    archiveRun: oc.route({ method: "POST", path: "/workflows/runs/{runId}/archive" }).input(WorkflowRunIdParamSchema).output(OkSchema),
+    archiveRun: oc
+        .route({
+            method: "POST",
+            path: "/workflows/runs/{runId}/archive",
+            summary: "Take a finished run off the board",
+            description:
+                "Nothing is lost and the working copies are reclaimed. Every conversation the run started is put away with it, which is what makes this an archive rather than a dismissal: a step has no card of its own, so merely dropping the run would spill its conversations onto the board at the moment somebody said they were done. Refused while the run is still going.",
+        })
+        .input(WorkflowRunIdParamSchema)
+        .output(OkSchema),
     // Put an archived run and its sessions back on the board, the inverse of the above and the run's half of
     // `agents.unarchive`.
-    unarchiveRun: oc.route({ method: "POST", path: "/workflows/runs/{runId}/unarchive" }).input(WorkflowRunIdParamSchema).output(OkSchema),
+    unarchiveRun: oc
+        .route({
+            method: "POST",
+            path: "/workflows/runs/{runId}/unarchive",
+            summary: "Bring an archived run back",
+            description: "Puts a run and every conversation it started back on the board.",
+        })
+        .input(WorkflowRunIdParamSchema)
+        .output(OkSchema),
 };