@intentic/sandbox-contract 1.226.0 → 1.226.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.226.0",
+  "version": "1.226.1",
   "description": "oRPC wire contract for the intentic sandbox daemon, shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -89,9 +89,9 @@
     "@orpc/contract": "1.14.13",
     "tslib": "2.8.1",
     "zod": "4.4.3",
-    "@intentic/constants": "1.226.0",
-    "@intentic/registry": "1.226.0",
-    "@intentic/extension-manifest": "1.226.0"
+    "@intentic/constants": "1.226.1",
+    "@intentic/extension-manifest": "1.226.1",
+    "@intentic/registry": "1.226.1"
   },
   "devDependencies": {
     "@types/node": "24.13.2",

package/src/contracts/activity.contract.ts

@@ -4,6 +4,22 @@ import { ActivityListSchema, ActivityQuerySchema, ActivityStatusSchema } from ".
 // The activity audit feed (provider-agnostic; Discord is the first source). Read-only by design,
 // events are appended daemon-side only, so the log stays a trustworthy record of what the agent did.
 export const activityContract = {
-    list: oc.route({ method: "GET", path: "/activity" }).input(ActivityQuerySchema).output(ActivityListSchema),
-    status: oc.route({ method: "GET", path: "/activity/status" }).output(ActivityStatusSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/activity",
+            summary: "What the agent has done out in the world",
+            description:
+                "The audit trail of actions taken on outside services. Read-only on purpose: entries are written by the sandbox alone, which is what makes it a record worth trusting.",
+        })
+        .input(ActivityQuerySchema)
+        .output(ActivityListSchema),
+    status: oc
+        .route({
+            method: "GET",
+            path: "/activity/status",
+            summary: "Whether the audit trail is being kept",
+            description: "Which sources are feeding the record and whether each is working.",
+        })
+        .output(ActivityStatusSchema),
 };

package/src/contracts/agent.contract.ts

@@ -19,20 +19,90 @@ import {
 // turn waiting on any interactive card (plan approval, clarifying questions, a per-tool permission prompt);
 // steer injects a user message into the running turn; stop hard-cancels it daemon-side.
 export const agentContract = {
-    run: oc.route({ method: "POST", path: "/agent" }).input(AgentTurnSchema).output(StartedTurnSchema),
-    attach: oc.route({ method: "POST", path: "/agent/attach" }).input(AttachTurnSchema).output(eventIterator(AttachFrameSchema)),
-    reply: oc.route({ method: "POST", path: "/agent/reply" }).input(AgentReplySchema).output(OkSchema),
-    steer: oc.route({ method: "POST", path: "/agent/steer" }).input(SteerSchema).output(OkSchema),
-    stop: oc.route({ method: "POST", path: "/agent/stop" }).input(StopTurnSchema).output(OkSchema),
+    run: oc
+        .route({
+            method: "POST",
+            path: "/agent",
+            summary: "Say something to an agent",
+            description:
+                "Starts a turn and answers immediately with its id; the work runs inside the sandbox whether or not anybody stays connected. Watch it by attaching. Naming a conversation that does not exist yet opens it.",
+        })
+        .input(AgentTurnSchema)
+        .output(StartedTurnSchema),
+    attach: oc
+        .route({
+            method: "POST",
+            path: "/agent/attach",
+            summary: "Watch a turn happen",
+            description:
+                "Streams everything the agent does: its words, the tools it reaches for, and the answers it gets. Give it the point you have already seen and it replays from there before going live, so a reload loses nothing. The window that started the turn holds no special claim, and any number of watchers on any number of devices see the same thing.",
+        })
+        .input(AttachTurnSchema)
+        .output(eventIterator(AttachFrameSchema)),
+    reply: oc
+        .route({
+            method: "POST",
+            path: "/agent/reply",
+            summary: "Answer a question the agent asked",
+            description:
+                "Un-parks a turn that is waiting on you: approving a plan, choosing between options, or permitting a tool. The turn picks up where it stopped.",
+        })
+        .input(AgentReplySchema)
+        .output(OkSchema),
+    steer: oc
+        .route({
+            method: "POST",
+            path: "/agent/steer",
+            summary: "Interrupt a running turn",
+            description:
+                "Slips a message into a turn already under way, without stopping it. This is how you redirect an agent mid-thought rather than waiting for it to finish being wrong.",
+        })
+        .input(SteerSchema)
+        .output(OkSchema),
+    stop: oc
+        .route({
+            method: "POST",
+            path: "/agent/stop",
+            summary: "Stop a turn now",
+            description: "Cancels the running turn inside the sandbox. Whatever it had already written to disk stays written.",
+        })
+        .input(StopTurnSchema)
+        .output(OkSchema),
     // Go back to a message: restore the workspace to that turn's checkpoint, drop the messages after it, and
     // forget the provider session. CONFLICT while a turn is running, a restore cannot overwrite files an
     // agent is editing. NOT_FOUND when that message has no checkpoint to go back to.
-    rewind: oc.route({ method: "POST", path: "/agent/rewind" }).input(RewindTurnSchema).output(RewindResultSchema),
+    rewind: oc
+        .route({
+            method: "POST",
+            path: "/agent/rewind",
+            summary: "Go back to an earlier message",
+            description:
+                "Puts the files back as they stood at that point, drops every message after it, and forgets what the model remembered, so the next thing you say starts from there cleanly. Refused while a turn is running, because a restore cannot overwrite files an agent is editing, and refused for a message with no saved state to return to.",
+        })
+        .input(RewindTurnSchema)
+        .output(RewindResultSchema),
     // The provider's slash commands as last published by one of its turns, so a conversation's `/` popover is
     // populated before it has run one. The live `commands` frame stays authoritative for a running turn.
-    commands: oc.route({ method: "GET", path: "/agent/commands" }).input(AgentCommandsQuerySchema).output(AgentCommandsSchema),
+    commands: oc
+        .route({
+            method: "GET",
+            path: "/agent/commands",
+            summary: "Shortcut commands the agent knows",
+            description:
+                "The commands a provider published the last time one of its turns ran, so a composer can offer them before this conversation has run anything. A running turn's own list wins over this one.",
+        })
+        .input(AgentCommandsQuerySchema)
+        .output(AgentCommandsSchema),
     // The last refusal per provider, as reported by whichever turn was refused (ProviderRefusalSchema). Read
     // alongside the account listings by the surfaces that draw plan limits: the snapshot on an account row says
     // how full its pools were when last polled, and this says whether one of them has since said no.
-    refusals: oc.route({ method: "GET", path: "/agent/refusals" }).output(ProviderRefusalsSchema),
+    refusals: oc
+        .route({
+            method: "GET",
+            path: "/agent/refusals",
+            summary: "The last time each provider said no",
+            description:
+                "What each model provider most recently refused and why. Read this alongside an account's usage: the usage says how full it was when last checked, this says whether it has since started turning work away.",
+        })
+        .output(ProviderRefusalsSchema),
 };

package/src/contracts/agents.contract.ts

@@ -47,27 +47,96 @@ import {
 // own agent, so there should be none) and answers with what it actually deleted: a teardown that fails on one
 // agent's repo leaves that one behind rather than taking the batch down with it.
 export const agentsContract = {
-    list: oc.route({ method: "GET", path: "/agents" }).output(AgentsListSchema),
-    archived: oc.route({ method: "GET", path: "/agents/archived" }).output(AgentsListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/agents",
+            summary: "Every live conversation",
+            description:
+                "The fleet as the board draws it: each conversation with its title, what it is doing, when it last moved and whether anybody has read it since. Archived conversations are not in here.",
+        })
+        .output(AgentsListSchema),
+    archived: oc
+        .route({
+            method: "GET",
+            path: "/agents/archived",
+            summary: "Conversations put away",
+            description:
+                "The same shape as the live fleet, for the conversations somebody has decided are finished. Their work is kept, and any one of them can be brought back.",
+        })
+        .output(AgentsListSchema),
     // The board's filter. Answers over BOTH halves of the fleet, the live roster and the archive, because
     // the board hides by design (the Finished lane windows to a handful, archived agents are off the roster
     // entirely), and a filter that reports "no matches" while the agent sits one click away is a lie. The
     // never-carded conversations that are neither are `sessions.list`'s query, which matches by the same rule.
-    search: oc.route({ method: "GET", path: "/agents/search" }).input(AgentSearchQuerySchema).output(AgentSearchResultSchema),
-    get: oc.route({ method: "GET", path: "/agents/{id}" }).input(AgentIdSchema).output(AgentSummarySchema),
-    transcript: oc.route({ method: "GET", path: "/agents/{id}/transcript" }).input(AgentIdSchema).output(AgentTranscriptSchema),
+    search: oc
+        .route({
+            method: "GET",
+            path: "/agents/search",
+            summary: "Find a conversation",
+            description:
+                "Searches the live fleet and the archive together. Both halves on purpose: the board hides finished work by design, and a filter that says it found nothing while the answer sits one click away is simply wrong.",
+        })
+        .input(AgentSearchQuerySchema)
+        .output(AgentSearchResultSchema),
+    get: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}",
+            summary: "One conversation's card",
+            description: "Everything the board shows for a single conversation: its title, state, working branch, unread marker and timestamps.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentSummarySchema),
+    transcript: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}/transcript",
+            summary: "The full conversation record",
+            description:
+                "Every message in one conversation, in order, including the tool calls and their results. This is the record the chat replays and the next turn is seeded from.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentTranscriptSchema),
     /* SPEAK AS THE AGENT, append the user's words to the conversation's record as an assistant row, with no
      * turn behind them and no reply. The row is marked `placed` for human readers (RestoredMessageSchema); the
      * provider session is FORGOTTEN in the same breath, rewind-style, so the next real turn opens a fresh
      * runtime session seeded from the record, where the placed line reads as the agent's own words, because
      * the handoff renders every assistant row identically. A running turn is CONFLICT: the illusion can only be
      * established between turns, and a concurrent turn would resume the very session this exists to retire. */
-    place: oc.route({ method: "POST", path: "/agents/{id}/place" }).input(AgentPlaceSchema).output(OkSchema),
-    rename: oc.route({ method: "POST", path: "/agents/{id}/rename" }).input(AgentRenameSchema).output(AgentSummarySchema),
+    place: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/place",
+            summary: "Put words in the agent's mouth",
+            description:
+                "Writes a line into the record as though the agent had said it, with no turn behind it and no reply. Human readers see it marked as placed. The next real turn starts fresh from the record, where the line reads as the agent's own. Refused while a turn is running.",
+        })
+        .input(AgentPlaceSchema)
+        .output(OkSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/rename",
+            summary: "Retitle a conversation",
+            description:
+                "Sets the title a person chose, replacing the one that was generated. Allowed while the conversation is working, and it does not count as activity.",
+        })
+        .input(AgentRenameSchema)
+        .output(AgentSummarySchema),
     // This agent's own land-at-completion posture, an override of the sandbox-wide `autoLand` setting; null
     // clears it back to "inherit". Legal mid-turn on purpose: the setting is read at turn COMPLETION, so
     // flipping it while the agent works is exactly "hold THIS turn's work for review", the press that matters.
-    autoLand: oc.route({ method: "POST", path: "/agents/{id}/auto-land" }).input(AgentAutoLandSchema).output(AgentSummarySchema),
+    autoLand: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/auto-land",
+            summary: "Whether this conversation merges its work automatically",
+            description:
+                "Overrides the sandbox-wide setting for one conversation; clear it to go back to following the default. Deliberately allowed mid-turn, because the setting is read when the turn finishes, so flipping it while the agent works means exactly hold this piece of work for review.",
+        })
+        .input(AgentAutoLandSchema)
+        .output(AgentSummarySchema),
     /* THIS conversation's answer to a provider outage, an override of the sandbox-wide `resumeAfterOutage`
      * setting; null clears it back to "inherit". The chat's offer at the moment a turn dies writes this and
      * never the global: the press happens inside one conversation and means "finish this piece of work", so
@@ -76,20 +145,112 @@ export const agentsContract = {
      * Legal mid-turn, and unlike autoLand it is legal for a WORKSPACE conversation too, an outage kills a
      * main-tree chat exactly as readily as an isolated one, and there is no branch involved either way. */
     resumeAfterOutage: oc
-        .route({ method: "POST", path: "/agents/{id}/resume-after-outage" })
+        .route({
+            method: "POST",
+            path: "/agents/{id}/resume-after-outage",
+            summary: "Whether this conversation retries after a provider outage",
+            description:
+                "Overrides the sandbox-wide setting for one conversation; clear it to follow the default again. This is what the offer shown when a turn dies writes, because the press happens inside one conversation and honestly means finish this piece of work.",
+        })
         .input(AgentResumeAfterOutageSchema)
         .output(AgentSummarySchema),
-    seen: oc.route({ method: "POST", path: "/agents/{id}/seen" }).input(AgentIdSchema).output(AgentSummarySchema),
-    seenAll: oc.route({ method: "POST", path: "/agents/seen" }).output(AgentsListSchema),
-    diff: oc.route({ method: "GET", path: "/agents/{id}/diff" }).input(AgentIdSchema).output(AgentChangesSchema),
-    fileDiff: oc.route({ method: "GET", path: "/agents/{id}/{repo}/file-diff" }).input(AgentFileDiffQuerySchema).output(FileDiffSchema),
-    land: oc.route({ method: "POST", path: "/agents/{id}/land" }).input(AgentLandSchema).output(LandResultSchema),
+    seen: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/seen",
+            summary: "Mark a conversation read",
+            description:
+                "Stamps the read marker behind the unread badge on one card. Allowed while the conversation is working, and reading never counts as activity.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentSummarySchema),
+    seenAll: oc
+        .route({
+            method: "POST",
+            path: "/agents/seen",
+            summary: "Mark every conversation read",
+            description: "Clears the unread badge across the whole fleet at once, and hands the refreshed list back.",
+        })
+        .output(AgentsListSchema),
+    diff: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}/diff",
+            summary: "Everything a conversation has changed",
+            description:
+                "One flat set of changed files per repo, measured against where each repo stood when the conversation started, with every file flagged as already merged or not. Not the staged-and-unstaged shape a working copy has, because nobody ever checks this branch out to stage into it.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentChangesSchema),
+    fileDiff: oc
+        .route({
+            method: "GET",
+            path: "/agents/{id}/{repo}/file-diff",
+            summary: "One file's before and after in a conversation's work",
+            description: "Both sides of a single file: what it held when the conversation started and what it holds on its branch now.",
+        })
+        .input(AgentFileDiffQuerySchema)
+        .output(FileDiffSchema),
+    land: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/land",
+            summary: "Merge a conversation's work into the workspace",
+            description:
+                "Brings the conversation's branches into the main tree, one repo at a time. A conflict is reported rather than raised and nothing is lost when it fails. Refused while a turn is running, and refused for a conversation that works directly in the shared tree, which has nothing to merge.",
+        })
+        .input(AgentLandSchema)
+        .output(LandResultSchema),
     // A collaborator's ask for the land they may not perform themselves (role floors put `land`/`discard` at
     // maintainer). Stamps AgentSummarySchema.landRequested with the caller's identity and re-frames the fleet,
     // so every maintainer's board carries the request; the land or discard that answers it clears the stamp.
-    requestLand: oc.route({ method: "POST", path: "/agents/{id}/request-land" }).input(AgentIdSchema).output(AgentSummarySchema),
-    discard: oc.route({ method: "POST", path: "/agents/{id}/discard" }).input(AgentIdSchema).output(OkSchema),
-    archive: oc.route({ method: "POST", path: "/agents/archive" }).input(AgentArchiveSchema).output(AgentsMovedSchema),
-    unarchive: oc.route({ method: "POST", path: "/agents/unarchive" }).input(AgentIdsSchema).output(AgentsMovedSchema),
-    purge: oc.route({ method: "POST", path: "/agents/purge" }).output(AgentsRemovedSchema),
+    requestLand: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/request-land",
+            summary: "Ask a maintainer to merge this work",
+            description:
+                "For a collaborator who is not allowed to merge: marks the conversation as waiting for review, with who asked. The request shows on every maintainer's board and clears when somebody merges or discards it.",
+        })
+        .input(AgentIdSchema)
+        .output(AgentSummarySchema),
+    discard: oc
+        .route({
+            method: "POST",
+            path: "/agents/{id}/discard",
+            summary: "Throw a conversation's work away",
+            description:
+                "Deletes the conversation's working copies, its branches and its entry. Nothing is kept. Refused while a turn is running, and refused for a conversation working in the shared tree.",
+        })
+        .input(AgentIdSchema)
+        .output(OkSchema),
+    archive: oc
+        .route({
+            method: "POST",
+            path: "/agents/archive",
+            summary: "Put conversations away",
+            description:
+                "The gentle counterpart to discarding. Commits whatever the conversation still has in progress onto its own branch, releases its working copy, and keeps the entry and the record. It leaves the live fleet and joins the archive. Refused for a conversation that is running.",
+        })
+        .input(AgentArchiveSchema)
+        .output(AgentsMovedSchema),
+    unarchive: oc
+        .route({
+            method: "POST",
+            path: "/agents/unarchive",
+            summary: "Bring conversations back",
+            description:
+                "Returns archived conversations to the live fleet. The next turn picks up a fresh working copy from the branch that was kept.",
+        })
+        .input(AgentIdsSchema)
+        .output(AgentsMovedSchema),
+    purge: oc
+        .route({
+            method: "POST",
+            path: "/agents/purge",
+            summary: "Empty the archive for good",
+            description:
+                "Discards every conversation already in the archive: working copies, branches and entries. The whole archive rather than a chosen few, because the archive is the pile somebody has already decided is over. A teardown that fails on one conversation leaves that one behind instead of taking the rest down with it.",
+        })
+        .output(AgentsRemovedSchema),
 };

package/src/contracts/automations.contract.ts

@@ -17,15 +17,54 @@ import {
 // The `pending*` routes are the owner's approval queue: a `requireApproval` automation holds each fire here
 // instead of waking; `approve` runs the held wake, `reject` drops it.
 export const automationsContract = {
-    list: oc.route({ method: "GET", path: "/automations" }).output(AutomationsListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/automations",
+            summary: "Things that wake an agent on their own",
+            description: "Every automation with its recent runs and when it fires next.",
+        })
+        .output(AutomationsListSchema),
     /* WHAT CAN WAKE AN AGENT HERE, and what to start from, the daemon's own sources and templates merged with
      * every installed extension's. The composer's entire vocabulary, so that adding a trigger to an area is a
      * change to that area and to nothing else. `upsert` below validates against the same merge, which is what
      * keeps the surface and the daemon from disagreeing about what is allowed. */
-    catalog: oc.route({ method: "GET", path: "/automations/catalog" }).output(AutomationCatalogSchema),
-    upsert: oc.route({ method: "POST", path: "/automations" }).input(AutomationSchema).output(OkSchema),
-    setEnabled: oc.route({ method: "POST", path: "/automations/{id}/enabled" }).input(AutomationEnabledInputSchema).output(OkSchema),
-    remove: oc.route({ method: "DELETE", path: "/automations/{id}" }).input(AutomationIdParamSchema).output(OkSchema),
+    catalog: oc
+        .route({
+            method: "GET",
+            path: "/automations/catalog",
+            summary: "What can trigger an automation here",
+            description:
+                "Every trigger this sandbox understands and every template worth starting from, the daemon's own merged with each installed extension's. Writing an automation is checked against this same list, so a screen and the daemon can never disagree about what is allowed.",
+        })
+        .output(AutomationCatalogSchema),
+    upsert: oc
+        .route({
+            method: "POST",
+            path: "/automations",
+            summary: "Create or edit an automation",
+            description: "Writes an automation by id. Nothing needs provisioning: the scheduler picks it up on its next sweep.",
+        })
+        .input(AutomationSchema)
+        .output(OkSchema),
+    setEnabled: oc
+        .route({
+            method: "POST",
+            path: "/automations/{id}/enabled",
+            summary: "Turn an automation on or off",
+            description: "Flips only the switch, so a row in a list can be toggled without rebuilding the whole record.",
+        })
+        .input(AutomationEnabledInputSchema)
+        .output(OkSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/automations/{id}",
+            summary: "Delete an automation",
+            description: "Removes it, so nothing fires from it again.",
+        })
+        .input(AutomationIdParamSchema)
+        .output(OkSchema),
     /* Fire one automation NOW, by hand, the answer to "I wrote a 3 a.m. cron and I have no way to try it".
      * It runs the SAME path the real trigger runs: a schedule stays a headless main-tree wake, because a
      * test-fire that proves an isolated worktree works proves nothing about the fire it is standing in for. The
@@ -45,8 +84,40 @@ export const automationsContract = {
      *
      * Acks immediately with the turn detached, like /fire and `approve`: the guard alone may take a minute, and
      * the run history (with the session that makes it openable) is where the outcome lands. */
-    run: oc.route({ method: "POST", path: "/automations/{id}/run" }).input(AutomationIdParamSchema).output(OkSchema),
-    pendingList: oc.route({ method: "GET", path: "/automations/pending" }).output(AutomationApprovalsListSchema),
-    approve: oc.route({ method: "POST", path: "/automations/pending/{id}/approve" }).input(AutomationApprovalIdParamSchema).output(OkSchema),
-    reject: oc.route({ method: "POST", path: "/automations/pending/{id}/reject" }).input(AutomationApprovalIdParamSchema).output(OkSchema),
+    run: oc
+        .route({
+            method: "POST",
+            path: "/automations/{id}/run",
+            summary: "Fire an automation by hand",
+            description:
+                "The answer to writing something that runs at three in the morning and having no way to try it. It takes exactly the path the real trigger takes, including the check that decides whether there was anything to do, since skipped by the guard is the most useful thing this can tell you. A switched-off automation fires too, because trying it before switching it on is the main reason to press this. Not available for the trigger that listens for incoming messages, where a hand-fire would produce an agent asked to handle events and handed none; send the bot a message instead. Answers straight away and runs detached.",
+        })
+        .input(AutomationIdParamSchema)
+        .output(OkSchema),
+    pendingList: oc
+        .route({
+            method: "GET",
+            path: "/automations/pending",
+            summary: "Automations waiting for a yes",
+            description: "The queue an automation set to ask first lands in each time it would have fired.",
+        })
+        .output(AutomationApprovalsListSchema),
+    approve: oc
+        .route({
+            method: "POST",
+            path: "/automations/pending/{id}/approve",
+            summary: "Let a held automation run",
+            description: "Releases one waiting automation and runs the wake it was holding. Answers straight away and runs detached.",
+        })
+        .input(AutomationApprovalIdParamSchema)
+        .output(OkSchema),
+    reject: oc
+        .route({
+            method: "POST",
+            path: "/automations/pending/{id}/reject",
+            summary: "Drop a held automation",
+            description: "Throws one waiting fire away. The automation stays on, and the next trigger queues as usual.",
+        })
+        .input(AutomationApprovalIdParamSchema)
+        .output(OkSchema),
 };

package/src/contracts/capabilities.contract.ts

@@ -29,32 +29,127 @@ import {
  * anything runs, the only way to change one setting on a tunnel without re-typing its key. A marker with
  * nothing behind it is refused rather than written. */
 export const capabilitiesContract = {
-    list: oc.route({ method: "GET", path: "/capabilities" }).output(CapabilitiesListSchema),
-    add: oc.route({ method: "POST", path: "/capabilities" }).input(CapabilitySchema).output(eventIterator(IntenticLineSchema)),
-    remove: oc.route({ method: "DELETE", path: "/capabilities/{id}" }).input(CapabilityIdParamSchema).output(OkSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/capabilities",
+            summary: "Everything this sandbox is connected to",
+            description:
+                "Each connection with its live state, the settings that are safe to show, and the names of the credentials it holds. The values of those credentials are never in the answer, on any route but one.",
+        })
+        .output(CapabilitiesListSchema),
+    add: oc
+        .route({
+            method: "POST",
+            path: "/capabilities",
+            summary: "Connect something, or change a connection",
+            description:
+                "Writes a connection and streams the work of applying it, because some kinds provision real infrastructure and take a while. Sending an id that already exists edits that connection: this is the edit as well as the create. Since a caller is never shown stored credentials, it marks the ones it is leaving alone and the daemon fills them in, which is the only way to change one setting without retyping a key.",
+        })
+        .input(CapabilitySchema)
+        .output(eventIterator(IntenticLineSchema)),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/capabilities/{id}",
+            summary: "Disconnect something",
+            description:
+                "Tears a connection down. The kinds that own real infrastructure refuse, because deleting those would be losing data rather than losing a connection.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(OkSchema),
     /* Give a connection a different name, carrying what the old one keyed: a browser profile with its logins,
      * a connected machine's enrollment, an extension's checkout. The name is the agent's handle for the thing,
      * so this is a migration, add + remove would lose exactly the state that makes the connection worth
      * keeping. A kind whose name is part of what it IS (the scaffolders, the one-per-sandbox cards) refuses. */
-    rename: oc.route({ method: "POST", path: "/capabilities/{id}/rename" }).input(CapabilityRenameSchema).output(OkSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/capabilities/{id}/rename",
+            summary: "Rename a connection",
+            description:
+                "Carries everything the old name keyed across with it: a browser profile and its logins, an enrolled machine, an extension's copy of its source. Removing and re-adding would lose exactly the state that made the connection worth keeping. Kinds whose name is part of what they are refuse.",
+        })
+        .input(CapabilityRenameSchema)
+        .output(OkSchema),
     // Replace just the secret in a capability's config (the /secrets page's edit) and re-run its apply.
-    setSecret: oc.route({ method: "POST", path: "/capabilities/{id}/secret" }).input(CapabilitySecretInputSchema).output(OkSchema),
-    status: oc.route({ method: "GET", path: "/capabilities/{id}/status" }).input(CapabilityIdParamSchema).output(CapabilityStatusSchema),
+    setSecret: oc
+        .route({
+            method: "POST",
+            path: "/capabilities/{id}/secret",
+            summary: "Replace a stored credential",
+            description: "Swaps one connection's key or token for a new one and re-applies it, without touching any of its other settings.",
+        })
+        .input(CapabilitySecretInputSchema)
+        .output(OkSchema),
+    status: oc
+        .route({
+            method: "GET",
+            path: "/capabilities/{id}/status",
+            summary: "Re-check one connection",
+            description: "Probes a single connection right now, for a screen that wants to refresh one row rather than the whole list.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(CapabilityStatusSchema),
     /* One capability's stored config, secrets included, how an extension BACKEND dials the service behind a
      * connected capability (ext-deployments reads its Komodo's key pair through this). Never a browser's: the
      * handler refuses any caller with a member identity, so only the daemon's header grants reach it, and an
      * extension's grant reaches it only when its manifest declares the route in `permissions.daemon`, which
      * is the install dialog saying, in one line, "this extension can read connected credentials". */
-    connection: oc.route({ method: "GET", path: "/capabilities/{id}/connection" }).input(CapabilityIdParamSchema).output(CapabilityConnectionSchema),
-    marketplace: oc.route({ method: "POST", path: "/capabilities/marketplace" }).input(MarketplaceRequestSchema).output(MarketplaceSchema),
+    connection: oc
+        .route({
+            method: "GET",
+            path: "/capabilities/{id}/connection",
+            summary: "A connection's settings, credentials included",
+            description:
+                "The one call that hands back stored secrets, so an extension's own backend can dial the service behind a connection. Never answered for a signed-in person: only a machine credential reaches it, and an extension's only if its manifest asked for this route out loud at install time.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(CapabilityConnectionSchema),
+    marketplace: oc
+        .route({
+            method: "POST",
+            path: "/capabilities/marketplace",
+            summary: "Read a plugin marketplace",
+            description: "Resolves a plugin marketplace source into the list of connections you could install from it.",
+        })
+        .input(MarketplaceRequestSchema)
+        .output(MarketplaceSchema),
     // "Not needed": stop offering this card until the workspace evidence behind it changes. Nothing is torn
     // down and nothing is remembered about the card itself, only the evidence it was declined against.
-    dismiss: oc.route({ method: "DELETE", path: "/capabilities/recommendations/{card}" }).input(CapabilityCardParamSchema).output(OkSchema),
+    dismiss: oc
+        .route({
+            method: "DELETE",
+            path: "/capabilities/recommendations/{card}",
+            summary: "Stop suggesting this connection",
+            description:
+                "Not needed, for now. Nothing is torn down. The suggestion comes back if what prompted it in the workspace changes, because what is remembered is the evidence, not the refusal.",
+        })
+        .input(CapabilityCardParamSchema)
+        .output(OkSchema),
     // Start an agent-kind capability's interactive login (its declared loginCommand) in a visible terminal
     // session the user types into, device-code sign-in flows. Returns the session the panel attaches to.
-    login: oc.route({ method: "POST", path: "/capabilities/{id}/login" }).input(CapabilityIdParamSchema).output(CapabilityLoginSchema),
+    login: oc
+        .route({
+            method: "POST",
+            path: "/capabilities/{id}/login",
+            summary: "Sign in to a connection by hand",
+            description:
+                "Opens the connection's own sign-in in a terminal a person can type into, for the flows that need a code pasted or a device confirmed. The answer names the terminal to attach to.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(CapabilityLoginSchema),
     // Mint one TOTP code from the capability's stored seed (a field its card marks `totp`). The one capability
     // read the agent token is admitted to (see auth/grants): a code expires within its period and never reveals
     // the seed, so the in-sandbox `otp` command can answer a 2FA prompt without the agent holding the factor.
-    otp: oc.route({ method: "GET", path: "/capabilities/{id}/otp" }).input(CapabilityIdParamSchema).output(CapabilityOtpSchema),
+    otp: oc
+        .route({
+            method: "GET",
+            path: "/capabilities/{id}/otp",
+            summary: "Mint a one-time code",
+            description:
+                "Generates a single two-factor code from a stored seed. The one credential-adjacent read an agent is allowed, and it is safe because a code expires in seconds and never reveals the seed, so an agent can answer a prompt without ever holding the factor.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(CapabilityOtpSchema),
 };