@intentic/sandbox-contract 1.225.0 → 1.226.1

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),
 };

package/src/contracts/chores.contract.ts

@@ -13,11 +13,37 @@ import { ChoreLedgerWriteSchema, ChoreProbeRequestSchema, ChoresReportSchema, Ok
 export const choresContract = {
     // Every repo's standing evidence in one read: cached probe results (with their age and state), the cheap
     // resident signals, the ledger, and the daemon's node version. The rail badge polls this; so does the panel.
-    list: oc.route({ method: "GET", path: "/chores" }).output(ChoresReportSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/chores",
+            summary: "What maintenance the repos are asking for",
+            description:
+                "Every repo's standing evidence in one read: what the last measurement found and how old it is, the cheap signals that are always current, and what has already been decided about each.",
+        })
+        .output(ChoresReportSchema),
     // Re-run one repo's probe now, ignoring its TTL, the panel's per-probe refresh. An ack: the runner works in
     // the background and the result arrives on the next `list`, because a jscpd sweep outlives any sane request.
-    probe: oc.route({ method: "POST", path: "/chores/probe" }).input(ChoreProbeRequestSchema).output(OkSchema),
+    probe: oc
+        .route({
+            method: "POST",
+            path: "/chores/probe",
+            summary: "Measure one repo again now",
+            description:
+                "Re-runs a single check without waiting for it to go stale. Answers immediately: the work happens in the background and the result turns up in the next read, because some of these sweeps outlive any sane request.",
+        })
+        .input(ChoreProbeRequestSchema)
+        .output(OkSchema),
     // Record what a chore turn concluded, or snooze one. Upsert by repo+chore: a chore has one current verdict,
     // and a growing history of "we looked at this and it was fine" is not something any reader wants paged.
-    record: oc.route({ method: "POST", path: "/chores/ledger" }).input(ChoreLedgerWriteSchema).output(OkSchema),
+    record: oc
+        .route({
+            method: "POST",
+            path: "/chores/ledger",
+            summary: "Record a verdict, or snooze one",
+            description:
+                "Writes what somebody concluded about one repo's chore, replacing the previous verdict. A chore has one current answer, not a growing pile of times it was fine.",
+        })
+        .input(ChoreLedgerWriteSchema)
+        .output(OkSchema),
 };

package/src/contracts/ci.contract.ts

@@ -15,13 +15,62 @@ import {
 // (/ci/webhook/:host) is a plain Hono route, vendors can't do Google ID tokens, so it lives outside this
 // contract, like /automations/{id}/fire.
 export const ciContract = {
-    runs: oc.route({ method: "GET", path: "/ci/runs" }).output(CiRunsResponseSchema),
-    rerun: oc.route({ method: "POST", path: "/ci/runs/rerun" }).input(CiRunParamSchema).output(OkSchema),
-    cancel: oc.route({ method: "POST", path: "/ci/runs/cancel" }).input(CiRunParamSchema).output(OkSchema),
-    jobs: oc.route({ method: "POST", path: "/ci/runs/jobs" }).input(CiRunParamSchema).output(CiJobsResponseSchema),
-    fix: oc.route({ method: "POST", path: "/ci/fix" }).input(CiFixParamSchema).output(CiFixResponseSchema),
+    runs: oc
+        .route({
+            method: "GET",
+            path: "/ci/runs",
+            summary: "Pipeline runs across the repos",
+            description:
+                "What the forges are reporting for every workspace repo that has a remote, served from a cache and filled in on demand. Repos whose notifications are not wired up say so.",
+        })
+        .output(CiRunsResponseSchema),
+    rerun: oc
+        .route({
+            method: "POST",
+            path: "/ci/runs/rerun",
+            summary: "Run a pipeline again",
+            description: "Asks the forge to re-run one pipeline. The daemon only passes the request along.",
+        })
+        .input(CiRunParamSchema)
+        .output(OkSchema),
+    cancel: oc
+        .route({
+            method: "POST",
+            path: "/ci/runs/cancel",
+            summary: "Cancel a pipeline run",
+            description: "Asks the forge to stop a run in progress.",
+        })
+        .input(CiRunParamSchema)
+        .output(OkSchema),
+    jobs: oc
+        .route({
+            method: "POST",
+            path: "/ci/runs/jobs",
+            summary: "The steps inside one pipeline run",
+            description: "Each job in a run with its outcome, which is where you look to find out what actually broke.",
+        })
+        .input(CiRunParamSchema)
+        .output(CiJobsResponseSchema),
+    fix: oc
+        .route({
+            method: "POST",
+            path: "/ci/fix",
+            summary: "Put an agent on a broken pipeline",
+            description:
+                "Opens a fresh isolated conversation already holding the failure: which job, which repo, what it said. The answer names the conversation so you can open it.",
+        })
+        .input(CiFixParamSchema)
+        .output(CiFixResponseSchema),
     // "I have looked at the pipelines", what silences the rail badge for breakages already read. No input:
     // the surface is read as a whole, and the daemon stamps its own clock so a skewed browser can't mark
     // future failures as already seen.
-    seen: oc.route({ method: "POST", path: "/ci/seen" }).output(CiSeenResponseSchema),
+    seen: oc
+        .route({
+            method: "POST",
+            path: "/ci/seen",
+            summary: "Mark the pipelines as read",
+            description:
+                "Silences the badge for breakages already looked at. Takes nothing, because the view is read as a whole, and the daemon stamps its own clock so a browser with the wrong time cannot mark future failures as already seen.",
+        })
+        .output(CiSeenResponseSchema),
 };

package/src/contracts/claude.contract.ts

@@ -19,11 +19,53 @@ import {
 // shared /providers/{provider}/models route (providers.contract.ts). What is left is what is genuinely Claude's
 //, an account handshake no other provider has.
 export const claudeContract = {
-    start: oc.route({ method: "POST", path: "/claude/oauth/start" }).output(AuthorizeChallengeSchema),
-    exchange: oc.route({ method: "POST", path: "/claude/oauth/exchange" }).input(OauthExchangeSchema).output(OauthAccountSchema),
+    start: oc
+        .route({
+            method: "POST",
+            path: "/claude/oauth/start",
+            summary: "Begin connecting a Claude account",
+            description:
+                "Hands back the address to send somebody to, and the proof this sandbox will need to finish the exchange. The sandbox holds the credential afterwards, not the browser.",
+        })
+        .output(AuthorizeChallengeSchema),
+    exchange: oc
+        .route({
+            method: "POST",
+            path: "/claude/oauth/exchange",
+            summary: "Finish connecting a Claude account",
+            description:
+                "Trades the code from the sign-in for stored tokens and answers with the account it just connected. A sandbox can hold several Claude accounts side by side.",
+        })
+        .input(OauthExchangeSchema)
+        .output(OauthAccountSchema),
     // Each account carries its plan-limit reading. `force` re-measures before answering, see
     // AccountListQuerySchema, and USAGE_WAIT_MS in claude.routes.ts for what an ordinary read waits.
-    accounts: oc.route({ method: "GET", path: "/claude/accounts" }).input(AccountListQuerySchema).output(OauthAccountListSchema),
-    rename: oc.route({ method: "POST", path: "/claude/account/rename" }).input(AccountRenameSchema).output(OauthAccountSchema),
-    disconnect: oc.route({ method: "POST", path: "/claude/account/disconnect" }).input(AccountIdSchema).output(OkSchema),
+    accounts: oc
+        .route({
+            method: "GET",
+            path: "/claude/accounts",
+            summary: "Connected Claude accounts",
+            description:
+                "Each connected account with how full its plan limits were when last measured. Ask for a fresh measurement and it takes one before answering, which is slower.",
+        })
+        .input(AccountListQuerySchema)
+        .output(OauthAccountListSchema),
+    rename: oc
+        .route({
+            method: "POST",
+            path: "/claude/account/rename",
+            summary: "Rename a Claude account",
+            description: "Changes the label one account shows under, so several are tellable apart.",
+        })
+        .input(AccountRenameSchema)
+        .output(OauthAccountSchema),
+    disconnect: oc
+        .route({
+            method: "POST",
+            path: "/claude/account/disconnect",
+            summary: "Disconnect a Claude account",
+            description: "Clears the stored tokens for one account. The others stay connected.",
+        })
+        .input(AccountIdSchema)
+        .output(OkSchema),
 };

package/src/contracts/drafts.contract.ts

@@ -5,7 +5,30 @@ import { DraftIdParamSchema, DraftsListSchema, DraftSummarySchema, OkSchema } fr
 // directly, these routes are the OWNER's side: `list` is the approval inbox, `upsert` covers approve / edit /
 // retry (all a plain re-post with a field changed, like the automations enabled toggle), `remove` is reject.
 export const draftsContract = {
-    list: oc.route({ method: "GET", path: "/drafts" }).output(DraftsListSchema),
-    upsert: oc.route({ method: "POST", path: "/drafts" }).input(DraftSummarySchema).output(OkSchema),
-    remove: oc.route({ method: "DELETE", path: "/drafts/{id}" }).input(DraftIdParamSchema).output(OkSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/drafts",
+            summary: "Posts waiting for your approval",
+            description: "The queue of things an agent has written and would like to publish. Nothing here has gone anywhere yet.",
+        })
+        .output(DraftsListSchema),
+    upsert: oc
+        .route({
+            method: "POST",
+            path: "/drafts",
+            summary: "Approve, edit or retry a draft",
+            description: "All three are the same act with a different field changed, so they share one call. Send the draft back as you want it.",
+        })
+        .input(DraftSummarySchema)
+        .output(OkSchema),
+    remove: oc
+        .route({
+            method: "DELETE",
+            path: "/drafts/{id}",
+            summary: "Reject a draft",
+            description: "Throws one away unposted.",
+        })
+        .input(DraftIdParamSchema)
+        .output(OkSchema),
 };

package/src/contracts/endpoints.contract.ts

@@ -44,6 +44,23 @@ export const TrialStatusSchema = z.object({
 export type TrialStatusResponse = z.infer<typeof TrialStatusSchema>;
 
 export const endpointsContract = {
-    models: oc.route({ method: "GET", path: "/endpoints/{id}/models" }).input(CapabilityIdParamSchema).output(ModelsSchema),
-    trial: oc.route({ method: "GET", path: "/endpoints/trial/status" }).output(TrialStatusSchema),
+    models: oc
+        .route({
+            method: "GET",
+            path: "/endpoints/{id}/models",
+            summary: "Models a connected server offers",
+            description:
+                "Asks one configured model server what it serves. There is no built-in list and no fallback: what a server offers is knowable only by asking it, so an empty answer is the honest report that we could not.",
+        })
+        .input(CapabilityIdParamSchema)
+        .output(ModelsSchema),
+    trial: oc
+        .route({
+            method: "GET",
+            path: "/endpoints/trial/status",
+            summary: "What is left of the free trial",
+            description:
+                "The allowance, what has been used, when it resets, and which model actually answered the last message. Not being available is the ordinary answer rather than a failure: most sandboxes run against a platform that offers no trial at all.",
+        })
+        .output(TrialStatusSchema),
 };

package/src/contracts/exit.contract.ts

@@ -18,25 +18,87 @@ export const exitContract = {
     // Every configured exit with its live state, where it was asked to come out and where it actually does.
     // Drives the Status card, the browser account picker and `geo list` (the CLI is `geo`: `exit` is a shell
     // builtin, so a binary of that name is unreachable from a command line).
-    list: oc.route({ method: "GET", path: "/exit" }).output(ExitListSchema),
+    list: oc
+        .route({
+            method: "GET",
+            path: "/exit",
+            summary: "Ways to come out somewhere else",
+            description:
+                "Every configured exit with its live state, the country it was asked to appear in, and the country it actually appears in. Those last two disagreeing is the whole reason this reports both.",
+        })
+        .output(ExitListSchema),
     // What this exit can reach, ranked by how much capacity is actually there. Live from the provider when it
     // answers (Tor's directory, VPN Gate's CSV, the pasted confs), from the baked fallback when it does not,
     // and `live` says which. This is what auto-fills the country picker instead of a user hunting hostnames.
-    countries: oc.route({ method: "GET", path: "/exit/{id}/countries" }).input(ExitIdParamSchema).output(ExitCountriesSchema),
+    countries: oc
+        .route({
+            method: "GET",
+            path: "/exit/{id}/countries",
+            summary: "Countries one exit can reach",
+            description:
+                "Where this exit can put you, ranked by how much capacity is really there. Asked of the provider when it answers and taken from a built-in list when it does not, and the answer says which of those you got.",
+        })
+        .input(ExitIdParamSchema)
+        .output(ExitCountriesSchema),
     // Bring the exit up at its stored country. Streams, because a first start pulls a catalog, brings up a
     // tunnel and then verifies the address, which is tens of seconds on the free providers and can fail at
     // each step with something the user has to read. Idempotent: starting an up exit reports it and stops.
-    start: oc.route({ method: "POST", path: "/exit/{id}/start" }).input(ExitIdParamSchema).output(eventIterator(IntenticLineSchema)),
+    start: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/start",
+            summary: "Bring an exit up",
+            description:
+                "Starts the exit in the country it was configured for. Streamed, because a first start fetches a catalogue, raises a tunnel and then checks the address, which takes tens of seconds on the free providers and can fail at each step with something worth reading. Starting one that is already up simply says so.",
+        })
+        .input(ExitIdParamSchema)
+        .output(eventIterator(IntenticLineSchema)),
     // Move to another country, starting the exit first if it was down. Streams for the same reason as start,
     // and THROWS when the observed country does not end up matching: a switch that silently left traffic where
     // it was is the one failure mode this whole feature exists to make impossible.
-    use: oc.route({ method: "POST", path: "/exit/{id}/use" }).input(ExitUseInputSchema).output(eventIterator(IntenticLineSchema)),
+    use: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/use",
+            summary: "Move to another country",
+            description:
+                "Switches the exit's country, starting it first if it was down. It ends by checking where the world actually sees you and fails if that does not match what you asked for. A switch that quietly left your traffic where it was is the exact failure this whole feature exists to rule out.",
+        })
+        .input(ExitUseInputSchema)
+        .output(eventIterator(IntenticLineSchema)),
     // A different address in the SAME country. Cheap on tor (a control-port signal), a re-dial to another
     // server on the rest. Fails when the address does not actually change, which on a small pool it can't.
-    rotate: oc.route({ method: "POST", path: "/exit/{id}/rotate" }).input(ExitIdParamSchema).output(eventIterator(IntenticLineSchema)),
+    rotate: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/rotate",
+            summary: "Take a different address, same country",
+            description:
+                "Swaps to another address in the country you are already in. Fails if the address does not actually change, which on a small pool it sometimes cannot.",
+        })
+        .input(ExitIdParamSchema)
+        .output(eventIterator(IntenticLineSchema)),
     // What the world sees through this exit right now. Cheap, unstreamed, and the honest answer to "am I
     // actually in Germany", which is the question every other route here is judged against.
-    check: oc.route({ method: "POST", path: "/exit/{id}/check" }).input(ExitIdParamSchema).output(ExitObservationSchema),
+    check: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/check",
+            summary: "Where the world sees you right now",
+            description:
+                "Looks up the address and country as seen through this exit. Cheap, and the honest answer to whether you are really where you meant to be, which is what every other call here is judged against.",
+        })
+        .input(ExitIdParamSchema)
+        .output(ExitObservationSchema),
     // Take it down. Tolerates an already-down exit: "make it not be up" is the contract, not "it was up".
-    stop: oc.route({ method: "POST", path: "/exit/{id}/stop" }).input(ExitIdParamSchema).output(OkSchema),
+    stop: oc
+        .route({
+            method: "POST",
+            path: "/exit/{id}/stop",
+            summary: "Take an exit down",
+            description:
+                "Shuts the exit off. One that was already down is fine: the promise is that it is not up afterwards, not that it was up before.",
+        })
+        .input(ExitIdParamSchema)
+        .output(OkSchema),
 };