@intentic/sandbox-contract 1.225.0 → 1.226.1

package/dist/schemas.js

@@ -3,22 +3,39 @@ import { ExtensionManifestSchema } from "@intentic/extension-manifest";
 import { RegistryEntrySchema } from "@intentic/registry";
 import { z } from "zod";
 import { OutputFieldsSchema } from "./output-fields.js";
-export const OkSchema = z.object({ ok: z.literal(true) });
+export const OkSchema = z.object({
+    ok: z
+        .literal(true)
+        .describe("Always true. A route that answers this either did the thing or refused with a status; there is no third outcome to report."),
+});
 export const MemberRoleSchema = z.enum(["viewer", "collaborator", "maintainer", "owner"]);
 export const GrantedRoleSchema = z.enum(["viewer", "collaborator", "maintainer"]);
 const MEMBER_ROLE_RANK = { viewer: 0, collaborator: 1, maintainer: 2, owner: 3 };
 export const roleAtLeast = (role, floor) => MEMBER_ROLE_RANK[role] >= MEMBER_ROLE_RANK[floor];
-export const RepoParamSchema = z.object({ repo: z.string() });
+export const RepoParamSchema = z.object({
+    repo: z
+        .string()
+        .describe('Which repository. "root" is the workspace itself; anything else is a repository\'s folder relative to the workspace root, URL-encoded.'),
+});
 export const NATIVE_PROVIDERS = ["claude", "codex", "grok", "kimi", "gemini"];
 export const AgentProviderSchema = z.string().min(1);
 export const NativeProviderParamSchema = z.object({ provider: z.enum(NATIVE_PROVIDERS) });
 export const AgentHarnessSchema = z.enum(["native", "claude-code"]);
 export const RepoBaseSchema = z.object({ repo: z.string(), base: z.string().min(1) });
 export const EditorContextSchema = z.object({
-    file: z.string().min(1),
-    startLine: z.number().int().min(1).optional(),
-    endLine: z.number().int().min(1).optional(),
-    selection: z.string().max(20_000).optional(),
+    file: z.string().min(1).describe("The file open in the editor, as a workspace path."),
+    startLine: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("First line of the selection, counting from one. Leave both out when the whole file is the context."),
+    endLine: z.number().int().min(1).optional().describe("Last line of the selection, counting from one."),
+    selection: z
+        .string()
+        .max(20_000)
+        .optional()
+        .describe("The selected text itself. Cut it down before sending if it is long: this is context, not an upload."),
 });
 export const ConversationIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/);
 const entryId = z
@@ -57,35 +74,70 @@ export const ForkedFromSchema = z.object({
 });
 export const AgentTurnSchema = z
     .object({
-    prompt: z.string(),
-    title: z.string().max(80).optional(),
-    attachments: z.array(z.string().min(1)).max(20).optional(),
-    agent: AgentProviderSchema.optional(),
-    harness: AgentHarnessSchema.optional(),
-    account: z.string().optional(),
-    actsAs: entryId.optional(),
-    sessionId: z.string().optional(),
-    conversationId: ConversationIdSchema.optional(),
-    isolated: z.boolean().optional(),
-    worktreeBase: z.array(RepoBaseSchema).min(1).max(50).optional(),
-    autoLand: z.boolean().optional(),
-    origin: AgentOriginSchema.optional(),
+    prompt: z.string().describe("What to say to the agent. May be empty if you are only attaching files."),
+    title: z
+        .string()
+        .max(80)
+        .optional()
+        .describe("A title for a conversation this turn is opening. Ignored for a conversation that already has one."),
+    attachments: z
+        .array(z.string().min(1))
+        .max(20)
+        .optional()
+        .describe("Files to hand the agent along with the prompt, as workspace paths. Upload them first."),
+    agent: AgentProviderSchema.optional().describe("Which model provider serves this turn. Leave it out for Claude."),
+    harness: AgentHarnessSchema.optional().describe("Which agentic loop runs the turn. Leave it out to use each provider's own."),
+    account: z.string().optional().describe("Which of that provider's connected accounts pays for the turn. Leave it out for the first one."),
+    actsAs: entryId.optional().describe("Which persona the turn speaks as out in the world. Not the same as which account pays for it."),
+    sessionId: z.string().optional().describe("Resume this provider session instead of starting a fresh one."),
+    conversationId: ConversationIdSchema.optional().describe("The conversation this turn belongs to. You choose it, it survives model switches, and it is how you address the conversation later. Naming one that does not exist opens it."),
+    isolated: z
+        .boolean()
+        .optional()
+        .describe("Work in this conversation's own private copy of the repos rather than the shared tree, so several agents can work at once. Needs a conversation id."),
+    worktreeBase: z
+        .array(RepoBaseSchema)
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Pin a new private copy to these exact commits instead of today's workspace. Used when several agents must start from identical files."),
+    autoLand: z
+        .boolean()
+        .optional()
+        .describe("Whether this turn's work merges into the workspace when it finishes. Overrides the conversation's own setting for this turn only."),
+    origin: AgentOriginSchema.optional().describe("Set by the sandbox alone: this turn opened a conversation on behalf of a message from outside rather than a person."),
     forkOf: z
         .object({
-        conversationId: ConversationIdSchema,
-        keep: z.number().int().nonnegative(),
-        files: z.enum(["then", "now"]),
+        conversationId: ConversationIdSchema.describe("The conversation this one was cut from."),
+        keep: z.number().int().nonnegative().describe("How many of that conversation's messages to copy in before this turn runs."),
+        files: z
+            .enum(["then", "now"])
+            .describe('Which files the fork opens on: "now" is the workspace as it stands, "then" is the files as they were at the cut, which needs a private copy.'),
     })
-        .optional(),
-    model: z.string().optional(),
-    unattended: z.boolean().optional(),
-    outsideWake: z.string().min(1).optional(),
-    permissionMode: PermissionModeSchema.optional(),
-    allowedTools: z.array(z.string().min(1)).optional(),
-    effort: z.string().optional(),
-    thinking: z.boolean().optional(),
-    fast: z.boolean().optional(),
-    editorContext: EditorContextSchema.optional(),
+        .optional()
+        .describe("Where this conversation was cut from, on its first turn only. Only the client knows this, so only the client can say it."),
+    model: z.string().optional().describe("Which model to use. Leave it out for the provider's default."),
+    unattended: z
+        .boolean()
+        .optional()
+        .describe("Nobody chose a model for this turn because a screen started it rather than a person. The sandbox then fills in the model its owner picked for unwatched work."),
+    outsideWake: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Content from outside caused this turn, and what to call the source. It is what makes the sandbox treat the turn as carrying somebody else's words."),
+    permissionMode: PermissionModeSchema.optional().describe("How tool calls are gated: ask each time, accept file edits, propose a plan first, or run everything. The agent can move itself between these mid-turn."),
+    allowedTools: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Narrow the turn to these tools. Leave it out for everything the runtime has. For a turn driven by an outside message this list is the real boundary, because prompt wording is only advice."),
+    effort: z.string().optional().describe("How hard the model should think, where the provider offers a choice."),
+    thinking: z.boolean().optional().describe("Whether to show the model's reasoning as it works."),
+    fast: z
+        .boolean()
+        .optional()
+        .describe("Ask for the same work at a higher rate for a higher price. A request rather than a promise: the answer says what actually happened."),
+    editorContext: EditorContextSchema.optional().describe('What the user has open in their editor, folded into the prompt so that pointing words like "this" resolve.'),
 })
     .refine((turn) => turn.prompt.trim().length > 0 || (turn.attachments?.length ?? 0) > 0, {
     message: "prompt or attachments required",
@@ -105,86 +157,189 @@ export const AgentTurnSchema = z
     .refine((turn) => turn.forkOf?.files !== "then" || turn.isolated === true, {
     message: 'forkOf.files "then" requires isolated',
 });
-export const AgentRunPickSchema = z.object({ agent: z.string().min(1), model: z.string().min(1) }).optional();
-export const StartedTurnSchema = z.object({ run: z.string() });
+export const AgentRunPickSchema = z
+    .object({
+    agent: z.string().min(1).describe("Which provider."),
+    model: z
+        .string()
+        .min(1)
+        .describe("Which of its models. Both or neither, because a model name only means anything to the provider that serves it."),
+})
+    .optional();
+export const StartedTurnSchema = z.object({
+    run: z.string().describe("The id of the run that just started. Hand it back when you attach, so the stream resumes rather than replaying."),
+});
 export const AttachTurnSchema = z.object({
-    conversationId: ConversationIdSchema,
-    run: z.string().optional(),
-    after: z.number().int().min(0).optional(),
+    conversationId: ConversationIdSchema.describe("Which conversation to watch."),
+    run: z
+        .string()
+        .optional()
+        .describe("The run you were watching. If a newer turn has started since, the stream replays that one from its beginning instead."),
+    after: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("The last frame you already have. Everything after it replays, then the stream goes live. Leave it out to start from the beginning."),
 });
 export const LoopContextSchema = z.enum(["fresh", "continue"]);
 export const LoopOutputSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("none") }),
-    z.object({ kind: z.literal("claim") }),
-    z.object({ kind: z.literal("json"), fields: OutputFieldsSchema }),
+    z.object({
+        kind: z
+            .literal("none")
+            .describe("It produces nothing but its work. The classic make the suite pass: what it leaves behind is a passing suite, and asking it to also file a report is asking it to spend a round on paperwork."),
+    }),
+    z.object({
+        kind: z
+            .literal("claim")
+            .describe("Each round says whether it is done and why. Structured prose: done is a value read rather than a sentence interpreted. Self-assessment, so advisory by construction; it exists because plenty of goals have no command that could check them."),
+    }),
+    z.object({
+        kind: z
+            .literal("json")
+            .describe("Each round writes a real answer in a shape you declared. This is the one that makes a step's output usable as the next step's input: a paragraph mentioning three files cannot be fed to anything, a list of three files can."),
+        fields: OutputFieldsSchema.describe("The shape that answer has to match."),
+    }),
 ]);
 export const LoopCheckSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("command"), command: z.string().min(1) }),
-    z.object({ kind: z.literal("judge"), rubric: z.string().min(1), model: z.string().optional() }),
+    z.object({
+        kind: z
+            .literal("command")
+            .describe("Run something and see if it passes. Deterministic, free, and the only signal here whose answer does not come from a model. A passing test suite beats any amount of self-report."),
+        command: z.string().min(1).describe("The command to run in the conversation's own tree. Exiting cleanly means satisfied."),
+    }),
+    z.object({
+        kind: z
+            .literal("judge")
+            .describe("Put the question to a separate model with no tools, which reads the round's own report and rules on it, having done none of the work and nothing invested in its being finished."),
+        rubric: z.string().min(1).describe("What that judge is asked."),
+        model: z.string().optional().describe("Which model judges. Leave it out for the cheap one the other small jobs use."),
+    }),
 ]);
 export const LoopDocumentSchema = z.object({
-    done: z.boolean(),
-    reason: z.string(),
-    evidence: z.string().optional(),
-    data: z.record(z.string(), z.unknown()).optional(),
+    done: z.boolean().describe("Whether the goal is met. Reading this is the whole point of the file."),
+    reason: z.string().describe("Why, in one line. The most-read sentence in the feature: the next round reads it first and the history shows it."),
+    evidence: z
+        .string()
+        .optional()
+        .describe("What was checked to know that. Optional, so a round with nothing to point at says so by leaving it out rather than by inventing a sentence."),
+    data: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("The declared answer, for a loop that asked for one, checked against the shape it declared."),
 });
 const LOOP_ITERATIONS_MAX = 50;
 export const LoopSchema = z.object({
-    conversationId: ConversationIdSchema,
-    goal: z.string().min(1),
-    prompt: z.string().min(1),
-    context: LoopContextSchema,
+    conversationId: ConversationIdSchema.describe("The conversation to loop. It need not exist yet: naming a fresh one opens it, which is what lets run this until it passes be the first thing you ever say."),
+    goal: z
+        .string()
+        .min(1)
+        .describe("What done means, in your words. It goes into every round's instructions and into the judge's question, so the model is told the bar rather than left to infer it."),
+    prompt: z
+        .string()
+        .min(1)
+        .describe("What each round is asked to do. The suite passes is the goal; run the tests, take the top failure, fix it is the instruction."),
+    context: LoopContextSchema.describe("How each round meets the last. Starting fresh makes the files the memory rather than the conversation, so the twentieth round reads the tree as clearly as the first, and costs a re-read each time. Carrying on is cheaper and keeps the reasoning, which suits a short polish-this loop and degrades on long ones: a session that has spent eleven rounds arguing for its own approach is the worst available judge of whether that approach is finished."),
     output: LoopOutputSchema,
-    checks: z.array(LoopCheckSchema),
-    maxIterations: z.number().int().min(1).max(LOOP_ITERATIONS_MAX),
-    maxSpendUsd: z.number().positive().optional(),
-    stallLimit: z.number().int().min(1),
-    isolated: z.boolean(),
-    agent: AgentProviderSchema.optional(),
-    harness: AgentHarnessSchema.optional(),
-    account: z.string().optional(),
-    model: z.string().optional(),
-    actsAs: entryId.optional(),
-    worktreeBase: z.array(RepoBaseSchema).min(1).max(50).optional(),
-    autoLand: z.boolean().optional(),
+    checks: z
+        .array(LoopCheckSchema)
+        .describe("What else has to be true, all of them together. A list because the suite passes and the report is written is a real bar, and running it as two loops would do the work twice."),
+    maxIterations: z
+        .number()
+        .int()
+        .min(1)
+        .max(LOOP_ITERATIONS_MAX)
+        .describe("How many rounds before it gives up. A loop that has not got there in fifty is not one round short of it."),
+    maxSpendUsd: z
+        .number()
+        .positive()
+        .optional()
+        .describe("A ceiling on what the whole loop may spend, in dollars. Optional for a short loop somebody is watching, and strongly wanted otherwise: this is the first thing here that can keep spending with nobody pressing anything between rounds."),
+    stallLimit: z
+        .number()
+        .int()
+        .min(1)
+        .describe("Stop after this many rounds in a row that changed nothing on disk. The guard that matters most: a loop's failure is not runaway success, it is an agent re-reading the same three files, restating the same plan and declaring more work remains, eleven times. Every one of those rounds succeeds, so only the tree not moving catches it."),
+    isolated: z
+        .boolean()
+        .describe("Whether it works in the conversation's own private copy or in the shared tree. It also decides where a check runs: testing the shared tree would be testing code this loop has not merged yet."),
+    agent: AgentProviderSchema.optional().describe("Which provider the rounds run on. Absent falls back to the conversation's own last choice."),
+    harness: AgentHarnessSchema.optional().describe("Which agentic loop they run on."),
+    account: z.string().optional().describe("Which account pays."),
+    model: z.string().optional().describe("Which model."),
+    actsAs: entryId
+        .optional()
+        .describe("Which persona the rounds act as. It matters here: every round is unwatched, and an unwatched turn naming no persona reaches no signed-in account at all, so pinning one is how a loop gets hands."),
+    worktreeBase: z
+        .array(RepoBaseSchema)
+        .min(1)
+        .max(50)
+        .optional()
+        .describe("Pin the private copy to these exact commits, so a restart cannot quietly change what the loop is working on."),
+    autoLand: z.boolean().optional().describe("Whether the work merges as it goes."),
 });
 export const loopCanConverge = (loop) => loop.output.kind !== "none" || loop.checks.length > 0;
 export const LOOP_DIR = `${STATE_DIR}/records/artifacts/loops`;
 export const LoopIterationSchema = z.object({
-    n: z.number().int().min(1),
-    at: z.number(),
-    outcome: z.enum(["continue", "done", "error"]),
-    detail: z.string().optional(),
-    costUsd: z.number().optional(),
-    changed: z.boolean(),
-    sessionId: z.string().optional(),
+    n: z.number().int().min(1).describe("Which round this was."),
+    at: z.number().describe("When it ran, in milliseconds."),
+    outcome: z
+        .enum(["continue", "done", "error"])
+        .describe("How the round ended, which is not the same question as how the loop did. A round that errored does not end the loop by itself: a failing turn is often exactly what the next round is meant to fix."),
+    detail: z
+        .string()
+        .optional()
+        .describe("What the check said, in its own words. What a run history is actually read for: why it kept going, and why it stopped."),
+    costUsd: z.number().optional().describe("What the round cost, in dollars."),
+    changed: z.boolean().describe("Whether anything on disk moved. Three unchanged rounds in a row is the shape of a loop that is not working."),
+    sessionId: z.string().optional().describe("The session it ran on, and the way from a history row to a readable record."),
 });
 export const LoopStateSchema = z.enum(["running", "done", "exhausted", "stalled", "overspent", "stopped", "error"]);
 export const LoopRecordSchema = LoopSchema.extend({
-    state: LoopStateSchema,
-    startedAt: z.number(),
-    endedAt: z.number().optional(),
-    resumed: z.number().int().min(0),
-    detail: z.string().optional(),
-    iterations: z.array(LoopIterationSchema),
-});
-export const LoopsListSchema = z.object({ loops: z.array(LoopRecordSchema) });
-export const LoopIdParamSchema = z.object({ conversationId: ConversationIdSchema });
+    state: LoopStateSchema.describe("How it ended, and each of these is a different thing to be told. Out of rounds says give it more room; stalled says it is not making progress and more room will not help. Overspent, stopped by a person, and the loop itself failing are all their own answers."),
+    startedAt: z.number().describe("When it began, in milliseconds."),
+    endedAt: z.number().optional().describe("When it ended, in milliseconds."),
+    resumed: z
+        .number()
+        .int()
+        .min(0)
+        .describe("How many times the sandbox restarted under it and picked it back up. Counted rather than flagged, so a loop whose round reliably kills the sandbox is not resurrected on every boot for ever."),
+    detail: z.string().optional().describe("Why it ended, for the endings whose reason is not in their name."),
+    iterations: z
+        .array(LoopIterationSchema)
+        .describe("Every round, in order. Why it stopped at the fourth is the question a loop gets read for, and this is the answer."),
+});
+export const LoopsListSchema = z.object({
+    loops: z.array(LoopRecordSchema).describe("Every loop this workspace has run, newest first, kept after they end."),
+});
+export const LoopIdParamSchema = z.object({ conversationId: ConversationIdSchema.describe("Which conversation's loop.") });
 export const LoopDesignSchema = z.object({
-    id: entryId,
-    name: z.string().min(1).max(60),
-    description: z.string().max(280).optional(),
-    prompt: z.string().optional(),
-    context: LoopContextSchema,
-    output: LoopOutputSchema,
-    checks: z.array(LoopCheckSchema),
-    maxIterations: z.number().int().min(1).max(LOOP_ITERATIONS_MAX),
-    maxSpendUsd: z.number().positive().optional(),
-    stallLimit: z.number().int().min(1),
-});
-export const LoopDesignsListSchema = z.object({ designs: z.array(LoopDesignSchema) });
-export const LoopDesignSaveSchema = z.object({ design: LoopDesignSchema, create: z.boolean() });
-export const LoopDesignIdParamSchema = z.object({ id: entryId });
+    id: entryId.describe("The design's id."),
+    name: z.string().min(1).max(60).describe("What to call it. Short, because it has to be readable on a small badge."),
+    description: z.string().max(280).optional().describe("What it is for, in one line. Optional, because a well-named loop has already said it."),
+    prompt: z
+        .string()
+        .optional()
+        .describe("What each round is asked to do, when that is worth saying separately from the goal. Absent means each round works towards the goal however it sees fit."),
+    context: LoopContextSchema.describe("How each round meets the last: starting clean, or carrying on."),
+    output: LoopOutputSchema.describe("What it has to produce."),
+    checks: z.array(LoopCheckSchema).describe("What else has to be true."),
+    maxIterations: z.number().int().min(1).max(LOOP_ITERATIONS_MAX).describe("How many rounds before it gives up."),
+    maxSpendUsd: z.number().positive().optional().describe("A ceiling on what it may spend, in dollars."),
+    stallLimit: z.number().int().min(1).describe("Stop after this many rounds in a row that changed nothing."),
+});
+export const LoopDesignsListSchema = z.object({
+    designs: z
+        .array(LoopDesignSchema)
+        .describe("Saved loops: the machinery with the goal left out, so one design can be pointed at a different job every time."),
+});
+export const LoopDesignSaveSchema = z.object({
+    design: LoopDesignSchema.describe("The design to write."),
+    create: z
+        .boolean()
+        .describe("Whether you mean to make a new one or replace an existing one, so an id that happens to collide cannot silently overwrite the one you had."),
+});
+export const LoopDesignIdParamSchema = z.object({ id: entryId.describe("Which saved loop.") });
 export const loopFromDesign = (design, aim) => ({
     conversationId: aim.conversationId,
     goal: aim.goal,
@@ -223,125 +378,274 @@ export const AgentStatusSchema = z.enum([
     "interrupted",
 ]);
 export const AgentActivitySchema = z.object({
-    tool: z.string().optional(),
-    target: z.string().optional(),
-    todo: z.string().optional(),
+    tool: z.string().optional().describe("The last tool it reached for."),
+    target: z.string().optional().describe("What it reached for that tool with: a file, a command, a URL."),
+    todo: z.string().optional().describe("The item on its own list that it is working through."),
 });
 export const AgentAttentionSchema = z.object({
-    plan: z.boolean(),
-    question: z.boolean(),
-    permission: z.boolean(),
-    service: z.boolean(),
-    capability: z.boolean(),
-    conflict: z.boolean(),
+    plan: z.boolean().describe("It has proposed a plan and is waiting for a yes."),
+    question: z.boolean().describe("It has asked you something."),
+    permission: z.boolean().describe("It wants to use a tool it needs permission for."),
+    service: z
+        .boolean()
+        .describe("It wants to spend money on a paid service and is waiting for approval. The one pause where waiting costs it the whole call."),
+    capability: z.boolean().describe("It needs something connected that is not connected yet."),
+    conflict: z.boolean().describe("Its work cannot be merged without somebody resolving a clash."),
 });
 export const LandedMessageSchema = z.object({
-    subject: z.string(),
-    note: z.string().optional(),
-    breaking: z.string().optional(),
+    subject: z
+        .string()
+        .describe("One line saying what the merged work did, read off the code rather than off the opening request. A conversation that asks for an audit and then spends four turns fixing what it found needs a subject about the fixes."),
+    note: z
+        .string()
+        .optional()
+        .describe("The same change said to somebody who uses the product, for a repository that keeps a changelog. Usually absent, because most changes are not ones a user would notice."),
+    breaking: z
+        .string()
+        .optional()
+        .describe("What this change takes away, for anything already relying on it. Nearly always absent: it is for removals, not for additions."),
 });
 export const LandedMessageStepSchema = z.object({
-    provider: z.string().min(1),
-    model: z.string().min(1),
-    status: z.enum(["asking", "answered", "refused", "skipped"]),
-    at: z.number().optional(),
-    ms: z.number().optional(),
-    reason: z.string().optional(),
+    provider: z.string().min(1).describe("Which provider was asked."),
+    model: z.string().min(1).describe("Which of its models."),
+    status: z
+        .enum(["asking", "answered", "refused", "skipped"])
+        .describe("How this one went. Skipped means it was not asked at all, because it refused a few minutes ago and the walk stepped over it."),
+    at: z.number().optional().describe("When it started being asked, in milliseconds. Absent for one that was skipped, which cost no time."),
+    ms: z.number().optional().describe("How long it took. Absent while it is still being asked."),
+    reason: z.string().optional().describe("Why it refused, in its own words."),
 });
 export const LandedMessageDraftSchema = z.object({
-    startedAt: z.number(),
-    steps: z.array(LandedMessageStepSchema),
-    outcome: z.enum(["written", "failed"]).optional(),
-    reason: z.string().optional(),
-    finishedAt: z.number().optional(),
+    startedAt: z.number().describe("When the drafting began, in milliseconds."),
+    steps: z
+        .array(LandedMessageStepSchema)
+        .describe("Each model that was asked, in the order they were spent, so the list is the timeline. Empty with no outcome means the diff is still being read."),
+    outcome: z.enum(["written", "failed"]).optional().describe("How it ended. Absent means it is still going."),
+    reason: z
+        .string()
+        .optional()
+        .describe("The one-line account of a failure, for a screen with one line to spend. The steps carry each model's own words."),
+    finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
 });
 export const AgentSummarySchema = z.object({
-    id: z.string(),
-    sessionId: z.string().optional(),
-    title: z.string().optional(),
-    status: AgentStatusSchema,
-    failure: z.string().optional(),
-    provider: AgentProviderSchema,
-    harness: AgentHarnessSchema,
-    model: z.string().optional(),
-    effort: z.string().optional(),
-    thinking: z.boolean().optional(),
-    fast: z.boolean().optional(),
-    account: z.string().optional(),
-    branch: z.string().optional(),
-    autoLand: z.boolean().optional(),
+    id: z.string().describe("The conversation id, which is how every other call addresses it."),
+    sessionId: z.string().optional().describe("The provider session behind the last turn. It is retired whenever the model or account changes."),
+    title: z.string().optional().describe("What to call it: the first prompt cut to one line, unless somebody renamed it."),
+    status: AgentStatusSchema.describe("What it is doing. Stopping and stopped are the two halves of somebody pressing stop, because a cancel is not instant; resuming means the sandbox is already putting right whatever killed the turn."),
+    failure: z
+        .string()
+        .optional()
+        .describe("Why the last turn failed, in the words it died on. Absent unless it did, and cleared the moment it runs again. Carried here because the word error on its own is not an answer, least of all for a run nobody was watching."),
+    provider: AgentProviderSchema.describe("Which model provider it runs on."),
+    harness: AgentHarnessSchema.describe("Which agentic loop it runs on."),
+    model: z
+        .string()
+        .optional()
+        .describe("What its last turn ran with. Kept per conversation so opening it restores the choices made in it, rather than whatever some other tab last picked."),
+    effort: z.string().optional().describe("How hard that turn was told to think."),
+    thinking: z.boolean().optional().describe("Whether that turn showed its reasoning."),
+    fast: z.boolean().optional().describe("Whether that turn asked for higher speed. What was asked for, not what was served."),
+    account: z.string().optional().describe("Which connected account paid for it."),
+    branch: z.string().optional().describe("The branch its private copy works on. Absent for a conversation that works directly in the shared tree."),
+    autoLand: z
+        .boolean()
+        .optional()
+        .describe("This conversation's own answer to whether its work merges automatically. Absent means it follows the sandbox-wide setting, which is the common case."),
     resumeAfterOutage: z.boolean().optional(),
-    landRequested: z.object({ email: z.string(), name: z.string().optional(), at: z.number() }).optional(),
-    origin: AgentOriginSchema.optional(),
-    forkedFrom: ForkedFromSchema.optional(),
-    base: z.string().optional(),
-    costUsd: z.number().optional(),
-    inputTokens: z.number().optional(),
-    outputTokens: z.number().optional(),
-    contextTokens: z.number().optional(),
-    contextWindow: z.number().optional(),
-    activity: AgentActivitySchema.optional(),
-    landedMessageDraft: LandedMessageDraftSchema.optional(),
-    landedMessage: LandedMessageSchema.optional(),
-    startedAt: z.number().optional(),
-    updatedAt: z.number(),
-    seenAt: z.number().optional(),
-    attention: AgentAttentionSchema,
-    turns: z.number().optional(),
-    toolUses: z.number().optional(),
-    subagents: z.object({ running: z.number(), total: z.number() }).optional(),
-    diff: z.object({ files: z.number(), insertions: z.number(), deletions: z.number() }).optional(),
-    landedPresence: z.object({ landed: z.number(), present: z.number() }).optional(),
+    landRequested: z
+        .object({
+        email: z.string().describe("Who asked."),
+        name: z.string().optional().describe("Their display name."),
+        at: z.number().describe("When they asked, in milliseconds."),
+    })
+        .optional()
+        .describe("A collaborator has asked a maintainer to merge this work. Cleared by whichever merge or discard answers it. Absent means nobody is waiting."),
+    origin: AgentOriginSchema.optional().describe("Where the conversation came from when nobody typed it: a chat mention, a visitor's message, a webhook. Absent means a person started it."),
+    forkedFrom: ForkedFromSchema.optional().describe("The conversation this one was cut from. Recorded once and never cleared: it is the relationship, not a pending state."),
+    base: z.string().optional().describe("The commit its private copy started from, shortened."),
+    costUsd: z.number().optional().describe("What it has cost so far, in dollars. A helper agent's spend is its own and is not folded in here."),
+    inputTokens: z.number().optional().describe("Tokens sent."),
+    outputTokens: z.number().optional().describe("Tokens received."),
+    contextTokens: z.number().optional().describe("How much of the window the conversation currently fills."),
+    contextWindow: z.number().optional().describe("How large that window is."),
+    activity: AgentActivitySchema.optional().describe("What it is doing at this moment."),
+    landedMessageDraft: LandedMessageDraftSchema.optional().describe("The whole story of this merge's commit message being written: which models were asked, how long each took, what refused and in what words. Forgotten on restart, which is right, because a restart also killed the drafting it describes."),
+    landedMessage: LandedMessageSchema.optional().describe("What this conversation's merged work is called, once the drafting above has finished. It arrives on the same push that ends the draft, so the promise and the answer travel together."),
+    startedAt: z.number().optional().describe("When the running turn started, in milliseconds. Absent when none is running."),
+    updatedAt: z.number().describe("When it last did something, in milliseconds. Reading it does not count."),
+    seenAt: z
+        .number()
+        .optional()
+        .describe("When somebody last opened it, in milliseconds. Newer activity than this is what makes it unread. Kept by the sandbox rather than by a browser, so clearing site data or picking up a phone does not resurrect every badge."),
+    attention: AgentAttentionSchema.describe("Which kinds of waiting-for-you it is doing."),
+    turns: z.number().optional().describe("Turns it has finished."),
+    toolUses: z.number().optional().describe("Tools it has used, over its whole life."),
+    subagents: z
+        .object({
+        running: z.number().describe("Helpers working right now."),
+        total: z.number().describe("Helpers it has started over its whole life."),
+    })
+        .optional()
+        .describe("Helper agents this one delegated to. Absent means it never has, which is most conversations. Their spend is their own and is not folded into this conversation's cost."),
+    diff: z
+        .object({
+        files: z.number().describe("Files touched."),
+        insertions: z.number().describe("Lines added."),
+        deletions: z.number().describe("Lines removed."),
+    })
+        .optional()
+        .describe("Everything it has written, measured from where it started. Independent of how much has been merged."),
+    landedPresence: z
+        .object({
+        landed: z.number().describe("Paths this conversation merged in."),
+        present: z.number().describe("How many of them are still there, either pending or committed."),
+    })
+        .optional()
+        .describe("Present only when some of what it merged has since been thrown away. Absent is the steady state: its presence is the signal, so an ordinary card spends no line on it."),
     loop: z
-        .object({ state: LoopStateSchema, iteration: z.number().int().min(0), maxIterations: z.number().int().min(1), goal: z.string() })
-        .optional(),
+        .object({
+        state: LoopStateSchema.describe("How the loop is going."),
+        iteration: z.number().int().min(0).describe("Which round it is on."),
+        maxIterations: z.number().int().min(1).describe("How many rounds it will attempt before giving up."),
+        goal: z.string().describe("What it is looping towards."),
+    })
+        .optional()
+        .describe("The loop driving this conversation, if one is. Absent for an ordinary conversation, which is nearly all of them."),
     workflow: z
         .object({
-        runId: z.string(),
-        name: z.string(),
-        step: z.string(),
-        index: z.number().int().min(1),
-        total: z.number().int().min(1),
+        runId: z.string().describe("The run this belongs to, which is how a board groups its steps together."),
+        name: z.string().describe("The workflow's name."),
+        step: z.string().describe("Which step this conversation is on now. It moves when steps are chained."),
+        index: z.number().int().min(1).describe("This step's place in the workflow, counting from one."),
+        total: z.number().int().min(1).describe("How many steps the workflow has."),
     })
-        .optional(),
-    archivedAt: z.number().optional(),
-});
-export const AgentIdSchema = z.object({ id: z.string().min(1) });
-export const AgentArchiveSchema = z.object({ ids: z.array(z.string().min(1)).max(500).optional() });
-export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).max(500) });
-export const AgentsMovedSchema = z.object({ moved: z.array(AgentSummarySchema), rev: z.number() });
-export const AgentsRemovedSchema = z.object({ removed: z.array(z.string()) });
-export const AgentSearchQuerySchema = z.object({ query: z.string().trim().min(2), caseSensitive: z.stringbool().optional() });
+        .optional()
+        .describe("The workflow run this conversation is a step of. Without it, a four-step run reads as four unrelated conversations that happen to have started together."),
+    archivedAt: z
+        .number()
+        .optional()
+        .describe("When it was put away, in milliseconds. Nothing was lost: its branch, its record and every counter stayed, and bringing it back gives it a fresh working copy. Absent means it is live on the board."),
+});
+export const AgentIdSchema = z.object({ id: z.string().min(1).describe("Which conversation.") });
+export const AgentArchiveSchema = z.object({
+    ids: z
+        .array(z.string().min(1))
+        .max(500)
+        .optional()
+        .describe("Which conversations to put away. Leave it out for every finished one that can be archived right now."),
+});
+export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).max(500).describe("Which conversations.") });
+export const AgentsMovedSchema = z.object({
+    moved: z
+        .array(AgentSummarySchema)
+        .describe("What actually moved, whole, rather than the fleet afterwards. Two archives finishing at once would each carry a snapshot from a different instant, and swapping one in wholesale would let the slower answer resurrect what the faster one just filed away."),
+    rev: z
+        .number()
+        .describe("The version of the fleet that includes this move, so a caller can hold its own optimistic change until it sees a list at least that new."),
+});
+export const AgentsRemovedSchema = z.object({
+    removed: z
+        .array(z.string())
+        .describe("Which conversations were deleted, as ids. Ids rather than whole cards, because these no longer exist anywhere: there is nothing left to show and nothing to put back."),
+});
+export const AgentSearchQuerySchema = z.object({
+    query: z
+        .string()
+        .trim()
+        .min(2)
+        .describe("What to look for. Searched against what was said, both sides of the conversation, and nothing else: not the thinking, not the tool output, which between them name nearly every identifier in the workspace and would return most of the board."),
+    caseSensitive: z.stringbool().optional().describe("Whether capitals matter."),
+});
 export const SpeakerSchema = z.enum(["user", "agent"]);
-export const MatchSnippetSchema = z.object({ text: z.string(), speaker: SpeakerSchema });
-export const AgentMatchSchema = z.object({ id: z.string(), snippet: MatchSnippetSchema.optional() });
-export const AgentSearchResultSchema = z.object({ matches: z.array(AgentMatchSchema), scanned: z.number() });
-export const AgentRenameSchema = z.object({ id: z.string().min(1), title: z.string().trim().min(1).max(80) });
-export const AgentPlaceSchema = z.object({ id: z.string().min(1), text: z.string().trim().min(1).max(8_000) });
-export const AgentAutoLandSchema = z.object({ id: z.string().min(1), autoLand: z.boolean().nullable() });
-export const AgentResumeAfterOutageSchema = z.object({ id: z.string().min(1), resumeAfterOutage: z.boolean().nullable() });
-export const AgentFileDiffQuerySchema = z.object({ id: z.string().min(1), repo: z.string().min(1), path: z.string().min(1) });
+export const MatchSnippetSchema = z.object({
+    text: z.string().describe("The matching line, with a little either side of it."),
+    speaker: SpeakerSchema.describe("Who said it. Carried with the words rather than beside them, because a line of the agent's prose under a card reads as something you typed until the row says otherwise."),
+});
+export const AgentMatchSchema = z.object({
+    id: z.string().describe("Which conversation matched."),
+    snippet: MatchSnippetSchema.optional().describe("Why, in its own words. Absent when the title was the match, which the card already shows: repeating it underneath is noise where evidence was wanted."),
+});
+export const AgentSearchResultSchema = z.object({
+    matches: z.array(AgentMatchSchema).describe("What matched, from the live fleet and the archive together."),
+    scanned: z
+        .number()
+        .describe("How many conversations were actually read, so a screen can say when a search saw less than everything rather than implying it saw all of it."),
+    indexing: z
+        .boolean()
+        .describe("Whether what was said is still being read in the background. True means this answer can still grow, so a screen must say it is incomplete rather than presenting it as the whole list."),
+});
+export const AgentRenameSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    title: z.string().trim().min(1).max(80).describe("What to call it from now on."),
+});
+export const AgentPlaceSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    text: z
+        .string()
+        .trim()
+        .min(1)
+        .max(8_000)
+        .describe("The words to put in the agent's mouth. Bounded just above what the next turn can carry whole, because a line too long to be handed over intact would reach the agent truncated and quietly break the very thing this is for."),
+});
+export const AgentAutoLandSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    autoLand: z
+        .boolean()
+        .nullable()
+        .describe("Whether its work merges automatically when a turn finishes. Null clears the override and goes back to following the sandbox-wide setting, so a conversation does not sit holding a frozen copy of a default it has quietly stopped following."),
+});
+export const AgentResumeAfterOutageSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    resumeAfterOutage: z
+        .boolean()
+        .nullable()
+        .describe("Whether it retries by itself when the model provider was what failed. Null clears the override back to the sandbox-wide setting."),
+});
+export const AgentFileDiffQuerySchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    repo: z.string().min(1).describe("Which repository."),
+    path: z.string().min(1).describe("Which file, relative to that repository."),
+});
 export const LandConflictReasonSchema = z.enum(["workspace", "diverged", "binary"]);
-export const LandConflictPathSchema = z.object({ path: z.string(), reason: LandConflictReasonSchema });
+export const LandConflictPathSchema = z.object({
+    path: z.string().describe("Which file."),
+    reason: LandConflictReasonSchema.describe("Why it would not merge, and the three have nothing in common but the symptom. Your own uncommitted edits on that path, where yours is the copy at risk. The shared tree having moved under the conversation since it started, where nothing of yours is at risk. Or a file git cannot merge at all, where no automatic answer exists."),
+});
 export const LandConflictSchema = z.object({
-    repo: z.string(),
-    paths: z.array(LandConflictPathSchema),
-    clean: z.number(),
-    mainBranch: z.string().optional(),
+    repo: z.string().describe("Which repository."),
+    paths: z
+        .array(LandConflictPathSchema)
+        .describe("The files that genuinely would not apply. Not the whole change: reporting everything whenever the cause could not be pinned down turned four real conflicts into a wall of fourteen."),
+    clean: z
+        .number()
+        .describe("How many files would apply regardless, so a screen can say how much is being held back by how little and offer to take it. Zero alongside an empty list means the repository could not be reached at all."),
+    mainBranch: z
+        .string()
+        .optional()
+        .describe("The branch your own checkout is on, which is what the conversation has to rebase onto. Carried because only the sandbox can see it. Absent where there is no name to give."),
 });
 export const LandResultSchema = z.object({
-    landed: z.boolean(),
-    conflicts: z.array(LandConflictSchema).optional(),
-    resolving: z.array(z.object({ repo: z.string(), paths: z.array(z.string()) })).optional(),
-    held: z.boolean().optional(),
+    landed: z.boolean().describe("Whether anything was applied."),
+    conflicts: z.array(LandConflictSchema).optional().describe("What stopped it, per repository."),
+    resolving: z
+        .array(z.object({
+        repo: z.string().describe("Which repository."),
+        paths: z.array(z.string()).describe("Which files now hold conflict markers to sort out by hand."),
+    }))
+        .optional()
+        .describe("Files left half-merged, when you asked for the mode that lands what it can and leaves the rest marked up."),
+    held: z
+        .boolean()
+        .optional()
+        .describe("Nothing was applied and nothing failed: there is work waiting on the branch for a deliberate merge. Not merged on its own cannot say that, because on its own it means refused."),
 });
 export const LandModeSchema = z.enum(["check", "merge", "measure"]);
 export const AgentSpanSchema = z.enum(["cumulative", "outstanding"]);
 export const AgentLandSchema = z.object({
-    id: z.string().min(1),
-    mode: LandModeSchema.optional(),
-    span: AgentSpanSchema.optional(),
-    force: z.boolean().optional(),
+    id: z.string().min(1).describe("Which conversation's work to merge."),
+    mode: LandModeSchema.optional().describe("How to apply it. The default applies all of it or none, so a refusal leaves the workspace exactly as it was. The other lands every clean file and leaves the rest with conflict markers to resolve by hand."),
+    span: AgentSpanSchema.optional().describe("How much of the work to take. Leave it out for everything not yet merged."),
+    force: z.boolean().optional().describe("Go ahead despite a check that would otherwise refuse."),
 });
 export const KeyedProviderSchema = z.enum(["codex", "grok", "kimi", "gemini"]);
 export const UsageWindowSchema = z.object({
@@ -355,12 +659,18 @@ export const AccountUsageSchema = z.object({
     measuredAt: z.number(),
 });
 export const ProviderRefusalSchema = z.object({
-    at: z.number(),
-    kind: z.enum(["limit", "auth", "entitlement"]),
-    message: z.string(),
-    account: z.string().optional(),
+    at: z.number().describe("When it refused, in milliseconds."),
+    kind: z
+        .enum(["limit", "auth", "entitlement"])
+        .describe("Three different noes, kept apart because what fixes each is different. A spent allowance is answered by waiting; a refused credential by signing in again; and an entitlement refusal, where somebody has switched this off for your seat, by neither of those. That last one authenticates fine and reports healthy limits the whole time it refuses everything."),
+    message: z.string().describe("The provider's own words, verbatim. The only part that says which limit or which credential."),
+    account: z.string().optional().describe("Which account was serving, where that is known."),
+});
+export const ProviderRefusalsSchema = z.object({
+    refusals: z
+        .record(z.string(), ProviderRefusalSchema)
+        .describe("The most recent refusal per provider. Read alongside an account's usage: that says how full it was when last checked, this says whether it has since started saying no."),
 });
-export const ProviderRefusalsSchema = z.object({ refusals: z.record(z.string(), ProviderRefusalSchema) });
 export const TranslatorAccountSchema = z.object({
     name: z.string(),
     label: z.string(),
@@ -374,62 +684,90 @@ export const TranslatorAccountsSchema = z.object({
 });
 export const AgentReplySchema = z.discriminatedUnion("kind", [
     z.object({
-        kind: z.literal("plan"),
-        requestId: z.string().min(1),
-        approve: z.boolean(),
-        feedback: z.string().optional(),
+        kind: z.literal("plan").describe("Answering a plan the agent proposed."),
+        requestId: z.string().min(1).describe("Which card you are answering, from the frame that raised it."),
+        approve: z
+            .boolean()
+            .describe("Whether to go ahead. Approving means the plan then runs without asking again per tool, because being asked whether a plan you just approved may run its first command is not a question worth having."),
+        feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
     }),
     z.object({
-        kind: z.literal("question"),
-        requestId: z.string().min(1),
-        answers: z.record(z.string(), z.array(z.string())).optional(),
-        cancelled: z.boolean().optional(),
+        kind: z.literal("question").describe("Answering a question the agent asked."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        answers: z
+            .record(z.string(), z.array(z.string()))
+            .optional()
+            .describe("What you chose, keyed by the question, with the chosen labels or your own words."),
+        cancelled: z
+            .boolean()
+            .optional()
+            .describe("Dismissing it instead, which tells the agent to carry on using sensible defaults rather than leaving it waiting."),
     }),
     z.object({
-        kind: z.literal("permission"),
-        requestId: z.string().min(1),
-        decision: z.enum(["once", "always", "deny"]),
-        feedback: z.string().optional(),
+        kind: z.literal("permission").describe("Answering a request to use a tool."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        decision: z
+            .enum(["once", "always", "deny"])
+            .describe("Once allows this call alone; always allows that whole tool for the rest of the conversation; no blocks it."),
+        feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
     }),
     z.object({
-        kind: z.literal("browser_help"),
-        requestId: z.string().min(1),
-        helped: z.boolean(),
-        note: z.string().optional(),
+        kind: z
+            .literal("browser_help")
+            .describe("Answering a request for help in the agent's browser: a captcha, a password it does not hold, a check on your phone."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        helped: z
+            .boolean()
+            .describe("Whether you cleared it. Yes means the turn carries on from the page as you left it; no tells the agent so, and it moves on rather than waiting for ever."),
+        note: z.string().optional().describe("Anything the agent should know, which goes back to it either way."),
     }),
     z.object({
-        kind: z.literal("terminal_help"),
-        requestId: z.string().min(1),
-        helped: z.boolean(),
-        note: z.string().optional(),
+        kind: z
+            .literal("terminal_help")
+            .describe("Answering a request for help at a terminal: a code to type, a confirmation only a person can give."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        helped: z
+            .boolean()
+            .describe("Whether you did it. Yes also hands the agent what the terminal now says, because a person answering a prompt is exactly the moment the agent cannot see."),
+        note: z.string().optional().describe("Anything the agent should know, which goes back to it either way."),
     }),
     z.object({
-        kind: z.literal("service_offer"),
-        requestId: z.string().min(1),
-        approve: z.boolean(),
+        kind: z.literal("service_offer").describe("Answering a request to spend on a paid service."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        approve: z
+            .boolean()
+            .describe("Yes releases exactly one run. Anything else charges nothing. This click is the only way the spend can happen."),
     }),
     z.object({
-        kind: z.literal("capability_offer"),
-        requestId: z.string().min(1),
-        connect: z.boolean(),
+        kind: z.literal("capability_offer").describe("Answering a request to connect something the agent needs."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        connect: z
+            .boolean()
+            .describe("Yes keeps the agent waiting while you set it up, and it carries on the moment the connection comes alive. No tells it to continue without. The reply itself connects nothing: setting it up is still your own doing."),
     }),
     z.object({
-        kind: z.literal("payment_offer"),
-        requestId: z.string().min(1),
-        approve: z.boolean(),
+        kind: z.literal("payment_offer").describe("Answering a request to pay for something."),
+        requestId: z.string().min(1).describe("Which card you are answering."),
+        approve: z
+            .boolean()
+            .describe("Yes releases exactly one payment. Anything else spends nothing. This click is the only way the money can move."),
     }),
 ]);
 export const SteerSchema = z
     .object({
-    conversationId: z.string().min(1),
-    text: z.string().max(20_000),
-    attachments: z.array(z.string().min(1)).max(20).optional(),
-    editorContext: EditorContextSchema.optional(),
+    conversationId: z.string().min(1).describe("Which running conversation to interrupt."),
+    text: z.string().max(20_000).describe("What to say to it. It arrives mid-turn without stopping the turn."),
+    attachments: z
+        .array(z.string().min(1))
+        .max(20)
+        .optional()
+        .describe("Files to send with it, as workspace paths. A screenshot dropped in mid-turn with no words is a legitimate thing to send."),
+    editorContext: EditorContextSchema.optional().describe("What you have open, folded in so that pointing words resolve."),
 })
     .refine((steer) => steer.text.trim().length > 0 || (steer.attachments?.length ?? 0) > 0, {
     message: "text or attachments required",
 });
-export const StopTurnSchema = z.object({ conversationId: z.string().min(1) });
+export const StopTurnSchema = z.object({ conversationId: z.string().min(1).describe("Which conversation's running turn to cancel.") });
 export const RateLimitInfoSchema = z.object({
     status: z.enum(["allowed", "allowed_warning", "rejected"]),
     resetsAt: z.number().optional(),
@@ -438,56 +776,91 @@ export const RateLimitInfoSchema = z.object({
 });
 export const FastModeStateSchema = z.enum(["off", "cooldown", "on"]);
 export const OauthAccountSchema = z.object({
-    id: z.string(),
-    label: z.string(),
-    email: z.string().optional(),
-    organization: z.string().optional(),
-    scope: z.string().optional(),
-    connectedAt: z.number(),
-    needsReauth: z.boolean().optional(),
-    detail: z.string().optional(),
-    usage: AccountUsageSchema.optional(),
+    id: z.string().describe("The account's id, which is what a turn names to spend on it and what disconnecting takes."),
+    label: z.string().describe("What it is called here, which somebody can change."),
+    email: z
+        .string()
+        .optional()
+        .describe("Who it signs in as, in the provider's own words. Kept beside the label rather than folded into it, so a renamed account can still say whose it is. Absent when the provider says nothing, which is exactly when renaming is the only answer."),
+    organization: z.string().optional().describe("Which organisation it belongs to, where the provider says."),
+    scope: z.string().optional().describe("What the credential is permitted to do, in the provider's terms."),
+    connectedAt: z.number().describe("When it was connected, in milliseconds."),
+    needsReauth: z
+        .boolean()
+        .optional()
+        .describe("Its stored credential can no longer be renewed and somebody has to sign in again. Absent means healthy, or not checked yet."),
+    detail: z.string().optional().describe("Why, in words a person can act on."),
+    usage: AccountUsageSchema.optional().describe("How full its plan limits were when last measured, so a picker can show what is left before committing work to it. Absent until a reading exists, which reads as unknown rather than as nothing left."),
+});
+export const OauthAccountListSchema = z.object({
+    accounts: z
+        .array(OauthAccountSchema)
+        .describe("The connected accounts. Tokens never travel in this shape: being in this list is what connected means."),
+});
+export const AccountListQuerySchema = z.object({
+    force: z
+        .stringbool()
+        .default(false)
+        .describe("Measure the plan limits again before answering, rather than serving a recent reading. Slower, and the right thing when somebody has just changed a plan and is asking whether what they can see is still true."),
+});
+export const AccountIdSchema = z.object({ id: z.string().min(1).describe("Which account.") });
+export const AccountRenameSchema = z.object({
+    id: z.string().min(1).describe("Which account."),
+    label: z.string().max(80).describe("The new name. Blank restores the one derived from the sign-in, rather than leaving a nameless row."),
 });
-export const OauthAccountListSchema = z.object({ accounts: z.array(OauthAccountSchema) });
-export const AccountListQuerySchema = z.object({ force: z.stringbool().default(false) });
-export const AccountIdSchema = z.object({ id: z.string().min(1) });
-export const AccountRenameSchema = z.object({ id: z.string().min(1), label: z.string().max(80) });
 export const OauthExchangeSchema = z.object({
-    code: z.string().min(1),
-    verifier: z.string().min(1),
-    state: z.string().min(1),
-    label: z.string().optional(),
+    code: z.string().min(1).describe("The code the sign-in handed back."),
+    verifier: z.string().min(1).describe("The proof from the start of the handshake, which is what stops somebody else's code being redeemed here."),
+    state: z.string().min(1).describe("The handshake this belongs to. A mismatch is refused."),
+    label: z.string().optional().describe("What to call the account. Blank derives one from the sign-in."),
+});
+export const AuthorizeChallengeSchema = z.object({
+    authorizeUrl: z.string().describe("Where to send somebody to sign in."),
+    verifier: z.string().describe("Keep this and send it back when finishing. It is what proves the code that comes back belongs to this handshake."),
+    state: z.string().describe("The handshake's own id, sent back with it."),
+});
+export const DeviceStartSchema = z.object({
+    url: z.string().describe("The page to open, which already has the code in it."),
+    code: z
+        .string()
+        .describe("The one-time code, shown as well so the page and the card say the same thing. Nothing is pasted back: the sandbox waits for the sign-in to complete on its own."),
 });
-export const AuthorizeChallengeSchema = z.object({ authorizeUrl: z.string(), verifier: z.string(), state: z.string() });
-export const DeviceStartSchema = z.object({ url: z.string(), code: z.string() });
 export const TranslatorStartSchema = z.object({
-    url: z.string(),
-    code: z.string(),
-    state: z.string(),
-    flow: z.enum(["device", "redirect"]),
+    url: z.string().describe("The page to open."),
+    code: z.string().describe("The one-time code, where the provider uses one."),
+    state: z.string().describe("The handshake's id, which the finishing call sends back."),
+    flow: z
+        .enum(["device", "redirect"])
+        .describe("Which shape this is. A device sign-in finishes by itself and you poll the account list; a redirect needs the address it landed on handed back. Said outright rather than guessed at from whether a code happens to exist."),
 });
 export const TranslatorCompleteSchema = z.object({
-    provider: KeyedProviderSchema,
-    redirectUrl: z.string().min(1),
-    state: z.string().min(1),
+    provider: KeyedProviderSchema.describe("Which provider."),
+    redirectUrl: z.string().min(1).describe("The address the browser was sent to, whole. The grant is inside it."),
+    state: z.string().min(1).describe("The handshake this belongs to. A mismatch is refused."),
 });
 export const ModelBadgeSchema = z.enum(["reasoning", "fast"]);
 export const ModelSchema = z.object({
-    id: z.string(),
-    label: z.string(),
-    efforts: z.array(z.string()).optional(),
-    description: z.string().optional(),
-    badges: z.array(ModelBadgeSchema).optional(),
+    id: z.string().describe("What to name when asking for this model."),
+    label: z.string().describe("What to call it on screen."),
+    efforts: z.array(z.string()).optional().describe("The thinking levels it accepts, where the provider says. Empty means use your own defaults."),
+    description: z
+        .string()
+        .optional()
+        .describe("What it is good for, in the provider's own words. Absent where the provider publishes only ids, which is the honest answer rather than something to paper over with a hand-written table."),
+    badges: z.array(ModelBadgeSchema).optional().describe("What it is known for, where the provider says so."),
+});
+export const ModelsSchema = z.object({
+    models: z.array(ModelSchema).describe("What this provider serves, in its own preference order, which is not rearranged here. Never empty."),
+    default: z.string().describe("Which one a fresh conversation starts on. Always present."),
 });
-export const ModelsSchema = z.object({ models: z.array(ModelSchema), default: z.string() });
-export const SessionIdParamSchema = z.object({ id: z.string() });
+export const SessionIdParamSchema = z.object({ id: z.string().describe("Which past conversation.") });
 export const SessionSummarySchema = z.object({
-    id: z.string(),
-    title: z.string(),
-    updatedAt: z.number(),
-    snippet: MatchSnippetSchema.optional(),
+    id: z.string().describe("Its id."),
+    title: z.string().describe("What it is called."),
+    updatedAt: z.number().describe("When it last moved, in milliseconds."),
+    snippet: MatchSnippetSchema.optional().describe("Why a search matched: the line it hit, with a little around it, and who said it. Absent on an unfiltered list, and on a match the title already shows, where repeating it would be noise rather than evidence."),
 });
-export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySchema) });
+export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySchema).describe("Past conversations, newest first.") });
 export const SystemPromptModeSchema = z.enum(["intentic", "claude", "custom"]);
 export const BuiltinPromptSchema = z.object({ base: z.enum(["intentic", "claude"]) });
 export const RuleMomentSchema = z.enum([
@@ -533,59 +906,158 @@ export const RuleFiringsSchema = z.record(z.string(), z.number());
 export const SkillOriginSchema = z.enum(["builtin", "own", "capability", "extension", "plugin", "persona", "dropped"]);
 export const SkillNameSchema = z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "a skill name is lowercase letters, digits and dashes");
 export const SkillSummarySchema = z.object({
-    id: z.string(),
-    name: z.string(),
-    description: z.string(),
-    origin: SkillOriginSchema,
-    owner: z.string().optional(),
-    enabled: z.boolean(),
-    switchable: z.boolean(),
-    editable: z.boolean(),
+    id: z
+        .string()
+        .describe("Its handle, which reading and deleting take. A skill of your own is simply its name; one belonging to something else is qualified, because two packages may each ship a review."),
+    name: z.string().describe("Its name."),
+    description: z
+        .string()
+        .describe("What it is for, which is the line the agent reads to decide whether to reach for it. Empty when the skill declares none, which is worth showing as the blank it is: a skill with no description is rarely picked."),
+    origin: SkillOriginSchema.describe("Where it came from."),
+    owner: z.string().optional().describe("Who ships it, as the row would name them."),
+    enabled: z.boolean().describe("Whether the agent can reach it."),
+    switchable: z
+        .boolean()
+        .describe("Whether this surface can switch it. Everything else is on because its extension or its plugin is, and a switch here that silently did nothing would be worse than none, so the row names its owner instead."),
+    editable: z
+        .boolean()
+        .describe("Whether it can be rewritten here. Your own only: editing somebody else's in place would be undone the next time the thing that ships it catches up."),
     removable: z.boolean(),
 });
 export const SkillsListSchema = z.array(SkillSummarySchema);
 export const SkillBodySchema = z.object({
-    id: z.string(),
-    name: z.string(),
-    body: z.string(),
+    id: z.string().describe("The skill's id, which can carry the owner it came from."),
+    name: z.string().describe("Its name."),
+    body: z.string().describe("The instructions themselves, as written."),
+});
+export const SkillIdSchema = z.object({
+    id: z
+        .string()
+        .min(1)
+        .describe("Which skill. It travels in the query rather than the address, because an id can name the owner it came from and that will not fit in a path."),
 });
-export const SkillIdSchema = z.object({ id: z.string().min(1) });
 export const SkillDraftSchema = z.object({
-    name: SkillNameSchema,
-    description: z.string().min(1).max(1024),
-    body: z.string().min(1),
+    name: SkillNameSchema.describe("What to call it. Saving over an existing name rewrites it, which is also how one is renamed."),
+    description: z.string().min(1).max(1024).describe("What it is for, which is what the agent reads to decide whether to reach for it."),
+    body: z.string().min(1).describe("The skill itself."),
+});
+export const SkillRemoveSchema = z.object({
+    name: SkillNameSchema.describe("Which skill to delete. The text and the enabled list are both updated, so nothing is left half done."),
 });
-export const SkillRemoveSchema = z.object({ name: SkillNameSchema });
 export const SandboxSettingsSchema = z.object({
-    stableSystemPrompt: z.boolean().default(false),
-    skills: z.array(z.string()).default(["lsp"]),
-    hashlineEdits: z.boolean().default(false),
-    terseOutput: z.boolean().default(false),
-    terseHoldout: z.number().min(0).max(1).default(0),
-    systemPromptMode: SystemPromptModeSchema.default("intentic"),
-    systemPrompt: z.string().max(20000).default(""),
-    iqSearch: z.boolean().default(false),
-    iqSearchHoldout: z.number().min(0).max(1).default(0),
-    workspaceMap: z.boolean().default(false),
-    outputCleaners: z.string().default("off"),
-    outputHoldout: z.number().min(0).max(1).default(0),
-    quickModel: z.array(z.string()).max(10).default([]),
-    changelogRepos: z.array(z.string()).max(50).default([]),
-    agentRunModels: z.array(z.string()).max(10).default([]),
-    agentRunEffort: z.string().default(""),
-    autoTier: z.enum(["off", "shadow", "on"]).default("shadow"),
-    autoFastModels: z.array(z.string()).max(10).default([]),
-    agentRetentionDays: z.number().min(0).max(365).default(3),
-    resumeAfterOutage: z.boolean().default(false),
-    autoResumeOnRestart: z.boolean().default(false),
-    rules: z.array(RuleSchema).max(50).default([]),
-    automationFailureLimit: z.number().min(0).max(20).default(0),
-    admission: AdmissionPolicySchema.prefault({}),
-    actionRules: z.record(z.string(), AdmissionRuleSchema).default({}),
-    commandRules: z.partialRecord(CommandClassSchema, AdmissionRuleSchema).default({}),
-    subagentsAtOnce: z.number().min(1).max(200).default(20),
-    subagentsPerTurn: z.number().min(1).max(2000).default(200),
-    subagentDepth: z.number().min(1).max(10).default(3),
+    stableSystemPrompt: z
+        .boolean()
+        .default(false)
+        .describe("Keep the instructions identical between turns so the provider can cache them, moving anything that varies into the message instead. Cheaper, at the cost of some flexibility."),
+    skills: z.array(z.string()).default(["lsp"]).describe("Which skills are switched on."),
+    hashlineEdits: z
+        .boolean()
+        .default(false)
+        .describe("Have the agent edit files by line number rather than by quoting the text it wants replaced. Cheaper on large files, and less forgiving of a stale read."),
+    terseOutput: z.boolean().default(false).describe("Ask the agent to say less. It changes how much it narrates, not how much it does."),
+    terseHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe("What share of turns to run without that instruction, so the two can be compared honestly. It has to be measured this way, because a turn cannot be re-run to see what it would have said. Zero means no measurement, which is the default, since the comparison costs the very tokens it is measuring."),
+    systemPromptMode: SystemPromptModeSchema.default("intentic").describe("Which instructions the agent starts from: intentic's own, the ones the installed Claude Code carries, or your own. The first two both get this product's own guidance added on top; your own gets nothing added, which is the point of it."),
+    systemPrompt: z
+        .string()
+        .max(20000)
+        .default("")
+        .describe("Your own instructions, used only when the mode above says custom. Then it is the whole of them: both built-in bases go, and so does everything this product would otherwise add, including the guidance the chat's own cards are driven by. That is the price of total control."),
+    iqSearch: z
+        .boolean()
+        .default(false)
+        .describe("Teach the agent how to use this workspace's own search tool, rather than leaving it to grep around."),
+    iqSearchHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe("What share of conversations to run without that teaching, so the two can be compared. Whole conversations rather than individual turns, because once the teaching is in a session, withholding it from the next request does not make the model forget it."),
+    workspaceMap: z
+        .boolean()
+        .default(false)
+        .describe("Open every conversation with a map of the project it starts in: what is in it, what each part is for, and where the agent is standing. Worked out fresh each time rather than written down anywhere, because a written layout is wrong within a fortnight. Off by default, since it spends tokens on the first message of every conversation."),
+    outputCleaners: z
+        .string()
+        .default("off")
+        .describe("Which command outputs to trim before the agent reads them, cutting the noise a build tool prints without cutting what it said."),
+    outputHoldout: z
+        .number()
+        .min(0)
+        .max(1)
+        .default(0)
+        .describe("What share of commands to leave untrimmed, so the saving can be measured against a real comparison rather than estimated."),
+    quickModel: z
+        .array(z.string())
+        .max(10)
+        .default([])
+        .describe("Which models do the small automatic jobs that are not a conversation, such as writing a commit message. A list rather than one pick, tried in order, because the interesting failure is a model that is connected and simply will not answer today. Empty means work it out from whatever is connected, which improves by itself as accounts are added."),
+    changelogRepos: z
+        .array(z.string())
+        .max(50)
+        .default([])
+        .describe("Which repositories keep a changelog, and so get a user-facing note written alongside each merge. A list rather than a switch, and empty by default, because the commit writer's standing rule is to copy the house style rather than impose one, and a repository that has never written such a note gives it nothing to copy."),
+    agentRunModels: z
+        .array(z.string())
+        .max(10)
+        .default([])
+        .describe("Which models run the work a screen starts rather than a person: fixing a red pipeline, a maintenance chore, an acceptance run. Tried in order, so one spent account does not take every such run down. Empty falls back to whatever the chat would have used, which is the honest floor because it is the model you already chose to work with."),
+    agentRunEffort: z.string().default("").describe("How hard those runs should think."),
+    autoTier: z
+        .enum(["off", "shadow", "on"])
+        .default("shadow")
+        .describe("Whether an easy-looking turn may run on a cheaper model from the same provider. Three states rather than a switch, because the middle one is the only honest road to the third: it scores every turn and routes nothing, so the guess can become a measurement before it changes anything. It can only ever route down, so the worst case is one turn's quality rather than a bill nobody asked for."),
+    autoFastModels: z
+        .array(z.string())
+        .max(10)
+        .default([])
+        .describe("Which cheaper model a downgraded turn lands on. A list so a sandbox spanning providers can name a rung on each, but not a fallback ladder: an entry naming a different provider than the turn is on is skipped rather than tried, because switching provider retires the conversation and starting over to save a fraction of a penny is not a saving. Empty picks the cheapest the turn's own provider publishes."),
+    agentRetentionDays: z
+        .number()
+        .min(0)
+        .max(365)
+        .default(3)
+        .describe("How many days a finished conversation stays on the board before being put away. Zero means never. The one setting here that defaults on, because each card left behind is a real working copy on disk, not just a row."),
+    resumeAfterOutage: z
+        .boolean()
+        .default(false)
+        .describe("Whether a turn killed by the model provider failing is re-run automatically, backing off between attempts. The sandbox-wide default; any one conversation can say otherwise. Off to begin with, because a retry spends your allowance on a turn you sent once and only you can say whether it was worth paying for twice. Worth turning on for a sandbox whose work mostly happens with nobody in the room."),
+    autoResumeOnRestart: z
+        .boolean()
+        .default(false)
+        .describe("Whether a turn killed by the sandbox restarting is re-run once it comes back. Off to begin with, for the same reason: it would spend your allowance on work you are not watching and edit files while you are still waiting for the sandbox to return. Either way the interruption is recorded rather than silently lost."),
+    rules: z
+        .array(RuleSchema)
+        .max(50)
+        .default([])
+        .describe("Standing instructions you give the sandbox about its own work: ask for proof before a turn ends, run something before a push, hold or release finished work. Empty is the default and is exactly the behaviour of a fresh sandbox, because each of those defaults is what no rule matched means at its own moment."),
+    automationFailureLimit: z
+        .number()
+        .min(0)
+        .max(20)
+        .default(0)
+        .describe("How many failures in a row before an automation switches itself off. Zero means never, which is the default, because the failure is not always the automation's fault and a job disabled at three in the morning is one nobody re-enables. Only real errors count: a guard deciding there was nothing to do, or the sandbox dying mid-run, say nothing about the automation."),
+    admission: AdmissionPolicySchema.prefault({}).describe("Whether work started from outside may run, per kind of trigger: let it, hold it for approval, or refuse it. Composes with each automation's own setting, and the stricter of the two wins, so holding every visitor's message needs no edit to each automation."),
+    actionRules: z
+        .record(z.string(), AdmissionRuleSchema)
+        .default({})
+        .describe("What an agent may do out in the world, per kind of action: go ahead, ask first, or never."),
+    commandRules: z
+        .partialRecord(CommandClassSchema, AdmissionRuleSchema)
+        .default({})
+        .describe("What an agent may run inside the sandbox, for the five kinds of command that are hard to take back: rewriting git history, deleting recursively, reading credential files, publishing a package, reaching out to the network. Everything else is recoverable in a container that is itself disposable, and gating it would be friction bought with nothing."),
+    subagentsAtOnce: z.number().min(1).max(200).default(20).describe("How many helper agents may work at the same time."),
+    subagentsPerTurn: z.number().min(1).max(2000).default(200).describe("How many a single turn may start in total."),
+    subagentDepth: z
+        .number()
+        .min(1)
+        .max(10)
+        .default(3)
+        .describe("How many levels deep the delegation may go, since a helper can start helpers of its own."),
 });
 export const BuiltinPromptTextSchema = z.object({ text: z.string(), version: z.string() });
 export const SavingsStageSchema = z.object({ id: z.string(), commands: z.number(), savedTokens: z.number() });
@@ -622,314 +1094,603 @@ export const SavingsReportSchema = z.object({
 });
 export const IntenticRunSchema = z.object({ args: z.array(z.string()) });
 export const CommitSchema = RepoParamSchema.extend({
-    message: z.string().min(1),
-    all: z.boolean().optional(),
-    paths: z.array(z.string().min(1)).max(500).optional(),
+    message: z.string().min(1).describe("The commit message."),
+    all: z
+        .boolean()
+        .optional()
+        .describe("Stage every change in the repository first, then commit. An alternative to naming paths, not a companion to it."),
+    paths: z
+        .array(z.string().min(1))
+        .max(500)
+        .optional()
+        .describe("Stage exactly these paths, then commit everything staged. Leave this and `all` out to commit whatever is already staged."),
 });
 export const DiscardSchema = RepoParamSchema.extend({
-    paths: z.array(z.string().min(1)).max(500).optional(),
+    paths: z
+        .array(z.string().min(1))
+        .max(500)
+        .optional()
+        .describe("Which paths to throw away. Leave it out to discard every uncommitted change in the repository."),
+});
+export const GitStageSchema = RepoParamSchema.extend({
+    paths: z.array(z.string().min(1)).max(500).describe("The paths to move. Nothing on disk changes, so this is always safe and always reversible."),
+});
+export const PushSchema = RepoParamSchema.extend({
+    branch: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Which branch to push. Leave it out for the checked-out one. A branch with no upstream yet gets one set on this push."),
+});
+export const GitFileQuerySchema = RepoParamSchema.extend({ path: z.string().min(1).describe("The file to read, relative to the repository root.") });
+export const GitFileWriteSchema = RepoParamSchema.extend({
+    path: z.string().min(1).describe("Where to write, relative to the repository root. Missing folders are created."),
+    content: z.string().describe("The file's whole new contents."),
 });
-export const GitStageSchema = RepoParamSchema.extend({ paths: z.array(z.string().min(1)).max(500) });
-export const PushSchema = RepoParamSchema.extend({ branch: z.string().min(1).optional() });
-export const GitFileQuerySchema = RepoParamSchema.extend({ path: z.string().min(1) });
-export const GitFileWriteSchema = RepoParamSchema.extend({ path: z.string().min(1), content: z.string() });
 export const GitDiffSideSchema = z.enum(["staged", "unstaged", "conflicted"]);
-export const GitFileDiffQuerySchema = RepoParamSchema.extend({ path: z.string().min(1), side: GitDiffSideSchema });
-export const GitStatusSchema = z.object({ branch: z.string(), dirty: z.boolean(), files: z.array(z.string()) });
-export const GitFilesSchema = z.object({ files: z.array(z.string()) });
-export const GitFileSchema = z.object({ path: z.string(), content: z.string() });
-export const RepoPathsSchema = z.object({ repo: z.string().min(1), paths: z.array(z.string().min(1)).max(500).optional() });
+export const GitFileDiffQuerySchema = RepoParamSchema.extend({
+    path: z.string().min(1).describe("The file, relative to the repository root."),
+    side: GitDiffSideSchema.describe("Which comparison you want. A file that is staged and then edited again has genuinely different answers for each, which is why this is required rather than assumed."),
+});
+export const GitStatusSchema = z.object({
+    branch: z.string().describe("The checked-out branch."),
+    dirty: z.boolean().describe("Whether anything is uncommitted."),
+    files: z.array(z.string()).describe("Every path with something pending, staged or not."),
+});
+export const GitFilesSchema = z.object({
+    files: z.array(z.string()).describe("Every path git tracks, relative to the repository root. Ignored and untracked files are not here."),
+});
+export const GitFileSchema = z.object({
+    path: z.string().describe("The path, as asked for."),
+    content: z.string().describe("The file's contents as they stand on disk."),
+});
+export const RepoPathsSchema = z.object({
+    repo: z.string().min(1).describe("Which repository."),
+    paths: z.array(z.string().min(1)).max(500).optional().describe("Which of its paths. Leave it out for the whole repository."),
+});
 export const GitChangeSchema = z.object({
-    path: z.string(),
-    status: z.enum(["added", "modified", "deleted", "renamed", "type-changed", "conflicted"]),
-    from: z.string().optional(),
-    additions: z.number().optional(),
-    deletions: z.number().optional(),
+    path: z.string().describe("The path, relative to the repository root. For a rename this is the new one."),
+    status: z
+        .enum(["added", "modified", "deleted", "renamed", "type-changed", "conflicted"])
+        .describe("What happened to it. Conflicted is not a kind of edit: nothing can be committed anywhere in the repository while one exists."),
+    from: z.string().optional().describe("Where a renamed file came from."),
+    additions: z
+        .number()
+        .optional()
+        .describe("Lines added. Absent for a binary file, and for an untracked one, which has nothing to compare against."),
+    deletions: z.number().optional().describe("Lines removed. Absent for the same reasons additions is."),
 });
 export const GitRemoteStateSchema = z.object({
-    remote: z.string().optional(),
-    branch: z.string().optional(),
-    upstream: z.string().optional(),
-    ahead: z.number(),
-    behind: z.number(),
+    remote: z
+        .string()
+        .optional()
+        .describe("The remote this branch pushes to. Absent means none is configured. In a fork with two remotes, pushing to the wrong one succeeds and leaves the count stuck, which is why this says which."),
+    branch: z.string().optional().describe("The checked-out branch. Absent when the repository is on a bare commit, or has no commits yet."),
+    upstream: z.string().optional().describe("The branch on the remote this one follows. Absent means the next push will publish it."),
+    ahead: z.number().describe("Commits you have that the remote does not."),
+    behind: z.number().describe("Commits the remote has that you do not, as of the last fetch. Fetch before trusting it."),
 });
 const RefNameSchema = z
     .string()
     .regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/)
     .max(200);
 export const GitBranchSchema = z.object({
-    name: z.string(),
-    current: z.boolean(),
-    upstream: z.string().optional(),
-    ahead: z.number(),
-    behind: z.number(),
-    gone: z.boolean().optional(),
-    at: z.number(),
+    name: z.string().describe("The branch name."),
+    current: z.boolean().describe("Whether this is the one checked out."),
+    upstream: z.string().optional().describe("The branch on the remote it follows, if any."),
+    ahead: z.number().describe("Commits this branch has that its remote counterpart does not."),
+    behind: z.number().describe("Commits its remote counterpart has that it does not."),
+    gone: z
+        .boolean()
+        .optional()
+        .describe("The branch it followed no longer exists on the remote, usually because a merged pull request deleted it. The signal that this one is safe to delete."),
+    at: z.number().describe("When its tip was committed, in milliseconds. Lists are newest first."),
+});
+export const GitRemoteBranchSchema = z.object({
+    name: z.string().describe("The full name, such as origin/main."),
+    remote: z.string().describe("Just the remote part, so a picker can group by it without re-parsing."),
+    branch: z.string().describe("Just the branch part."),
+    at: z.number().describe("When its tip was committed, in milliseconds, as this repository last saw it."),
+});
+export const GitBranchesSchema = z.object({
+    branches: z.array(GitBranchSchema).describe("Branches in this repository."),
+    remotes: z
+        .array(GitRemoteBranchSchema)
+        .describe("Branches on its remotes, as last seen. Sent together with the locals so a switcher never draws a half-filled list."),
 });
-export const GitRemoteBranchSchema = z.object({ name: z.string(), remote: z.string(), branch: z.string(), at: z.number() });
-export const GitBranchesSchema = z.object({ branches: z.array(GitBranchSchema), remotes: z.array(GitRemoteBranchSchema) });
 export const GitBranchCreateAtSchema = RepoParamSchema.extend({
-    name: RefNameSchema,
-    start: z.string().min(1).optional(),
-    checkout: z.boolean().optional(),
+    name: RefNameSchema.describe("The new branch's name."),
+    start: z.string().min(1).optional().describe("Where to start it: a commit or another branch. Leave it out to start from where you are."),
+    checkout: z.boolean().optional().describe("Switch to it as well as creating it."),
+});
+export const GitBranchDeleteSchema = RepoParamSchema.extend({
+    name: RefNameSchema.describe("The branch to delete."),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Delete it even though it holds work that was never merged. The deliberate retry after the first attempt refuses."),
 });
-export const GitBranchDeleteSchema = RepoParamSchema.extend({ name: RefNameSchema, force: z.boolean().optional() });
 export const GitOperationSchema = z.enum(["merge", "rebase", "cherry-pick", "revert"]);
-export const GitOperationStateSchema = z.object({ repo: z.string(), operation: GitOperationSchema.optional() });
+export const GitOperationStateSchema = z.object({
+    repo: z.string().describe("The repository asked about."),
+    operation: GitOperationSchema.optional().describe("Which operation the working tree is stuck inside. Absent means it is not stuck at all, which is almost always. While one is present git refuses nearly everything else, and abandoning it is the only way out."),
+});
 export const RepoChangesSchema = z.object({
     repo: z.string(),
-    branch: z.string().optional(),
-    conflicted: z.array(GitChangeSchema),
-    operation: GitOperationSchema.optional(),
-    staged: z.array(GitChangeSchema),
-    unstaged: z.array(GitChangeSchema),
-    truncated: z.number().optional(),
-    remote: GitRemoteStateSchema.optional(),
-    origins: z.record(z.string(), z.array(z.string())).optional(),
-    error: z.string().optional(),
+    branch: z.string().optional().describe("The checked-out branch. Absent in a repository that has no commits yet."),
+    conflicted: z
+        .array(GitChangeSchema)
+        .describe("Paths a merge or rebase could not finish. First, because nothing anywhere in this repository can be committed until they are resolved. Held apart from the two lists below, because staged or not is not a question one of these has an answer to."),
+    operation: GitOperationSchema.optional().describe("What halted, when something did. This is the sentence that explains the conflicts above and names the way out of them."),
+    staged: z.array(GitChangeSchema).describe("What a plain commit would record right now."),
+    unstaged: z
+        .array(GitChangeSchema)
+        .describe("Edits on disk that are not staged, plus untracked files. A path can be in both lists at once with different line counts, which is why they are separate."),
+    truncated: z
+        .number()
+        .optional()
+        .describe("How many changes were cut from the two lists above. A freshly cloned monorepo or a mass delete runs to six figures, which no screen can draw, so past a budget the lists arrive short and this says by how much. Absent means they are complete."),
+    remote: GitRemoteStateSchema.optional().describe("Where this repository stands against its remote."),
+    origins: z
+        .record(z.string(), z.array(z.string()))
+        .optional()
+        .describe("Which conversation put each path here, newest first, keyed by path. Only work that went through a merge can appear: edits made in the shared tree, in a terminal, or by a person are simply absent rather than guessed at."),
+    error: z
+        .string()
+        .optional()
+        .describe("Why the repository could not be read at all, in git's own words. A repository left broken by a failed import arrives with empty lists and this set, rather than vanishing from the answer with nothing to act on."),
 });
 export const OriginAgentSchema = z.object({
-    title: z.string().optional(),
-    provider: AgentProviderSchema,
-    landedMessage: LandedMessageSchema.optional(),
+    title: z.string().optional().describe("The conversation's title. Absent for one that never got as far as having a title."),
+    provider: AgentProviderSchema.describe("Which model provider it ran on."),
+    landedMessage: LandedMessageSchema.optional().describe("What the merged work did, drafted by the conversation itself. Carried here as well as on its card, because merged lines outlive the card: archiving a finished conversation does not uncommit its work."),
 });
 export const GitChangesSchema = z.object({
-    repos: z.array(RepoChangesSchema),
-    originAgents: z.record(z.string(), OriginAgentSchema).optional(),
-    committing: z.array(z.string()).optional(),
+    repos: z
+        .array(RepoChangesSchema)
+        .describe("One entry per repository that has something pending, is out of step with its remote, or could not be read. A clean repository is simply absent."),
+    originAgents: z
+        .record(z.string(), OriginAgentSchema)
+        .optional()
+        .describe("Who each conversation named above is, keyed by id, so a caller need not look them up. Absent when nothing in the review can be attributed."),
+    committing: z
+        .array(z.string())
+        .optional()
+        .describe("Repositories with a commit running right now. The sandbox's answer rather than any one tab's, so a reload, a second window and another device all know. Absent means nothing is committing."),
 });
 export const CommitResultSchema = z.object({
-    committed: z.boolean(),
-    changes: RepoChangesSchema.optional(),
-    originAgents: z.record(z.string(), OriginAgentSchema).optional(),
-});
-export const WorkspaceModuleSchema = z.object({ dir: z.string(), name: z.string() });
-export const RepoModulesSchema = z.object({ repo: z.string(), modules: z.array(WorkspaceModuleSchema) });
-export const WorkspaceModulesSchema = z.object({ repos: z.array(RepoModulesSchema) });
-export const AgentChangeSchema = GitChangeSchema.extend({ landed: z.boolean() });
+    committed: z.boolean().describe("Whether a commit was actually recorded."),
+    changes: RepoChangesSchema.optional().describe("What this repository looks like now, read in the same breath as the commit so a caller can redraw from here instead of asking for a fresh scan. Absent means there is nothing left to show."),
+    originAgents: z
+        .record(z.string(), OriginAgentSchema)
+        .optional()
+        .describe("Who the conversations named in those changes are. Merge it over what you already hold rather than replacing: other repositories still name their own."),
+});
+export const WorkspaceModuleSchema = z.object({
+    dir: z.string().describe("Where the package lives, relative to its repository. Empty when the repository is itself one package."),
+    name: z.string().describe("The name the package declares for itself."),
+});
+export const RepoModulesSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    modules: z.array(WorkspaceModuleSchema).describe("Its packages."),
+});
+export const WorkspaceModulesSchema = z.object({ repos: z.array(RepoModulesSchema).describe("Every repository with the packages inside it.") });
+export const AgentChangeSchema = GitChangeSchema.extend({
+    landed: z
+        .boolean()
+        .describe("Whether this change is already in the shared tree. The list is everything the conversation wrote, not just what is left over, because a clean turn merges in milliseconds and a list of leftovers would show an empty panel for work nobody had looked at yet."),
+});
 export const AgentRepoChangesSchema = z.object({
-    repo: z.string(),
-    branch: z.string().optional(),
-    changes: z.array(AgentChangeSchema),
-    modules: z.array(WorkspaceModuleSchema),
+    repo: z.string().describe("Which repository."),
+    branch: z.string().optional().describe("The branch this conversation's work sits on."),
+    changes: z.array(AgentChangeSchema).describe("What it changed there."),
+    modules: z
+        .array(WorkspaceModuleSchema)
+        .describe("The packages of the tree these changes came from, so a review can group by package. Carried with the changes rather than looked up separately, because a package the conversation has just created exists only in its own copy and the shared tree has never heard of it."),
+});
+export const AgentChangesSchema = z.object({
+    repos: z.array(AgentRepoChangesSchema).describe("One entry per repository the conversation touched."),
+    conflicts: z
+        .array(LandConflictSchema)
+        .optional()
+        .describe("Why the last merge refused, when one did. Carried here as well as in the merge's own answer, because a conflict is found the moment a turn ends and dealt with hours later on this surface, which would otherwise open with nothing to explain what it promised to resolve."),
 });
-export const AgentChangesSchema = z.object({ repos: z.array(AgentRepoChangesSchema), conflicts: z.array(LandConflictSchema).optional() });
 const ShaSchema = z.string().regex(/^[0-9a-f]{4,64}$/);
 export const GitCommitSchema = z.object({
-    sha: z.string(),
-    short: z.string(),
-    parents: z.array(z.string()),
-    subject: z.string(),
-    body: z.string(),
-    author: z.string(),
-    email: z.string(),
-    at: z.number(),
-    refs: z.array(z.string()),
-    head: z.boolean(),
+    sha: z.string().describe("The commit, in full."),
+    short: z.string().describe("The abbreviated form, for showing."),
+    parents: z
+        .array(z.string())
+        .describe("What it came from. None means the first commit, one is ordinary, two or more is a merge, which is what a graph draws its lanes from."),
+    subject: z.string().describe("Its first line."),
+    body: z.string().describe("Everything after that."),
+    author: z.string().describe("Who wrote it."),
+    email: z.string().describe("Their address."),
+    at: z.number().describe("When they wrote it, in milliseconds."),
+    refs: z.array(z.string()).describe("Branches and tags sitting on it."),
+    head: z.boolean().describe("Whether this is where the repository currently stands."),
 });
 export const GitLogSchema = z.object({
-    repo: z.string(),
-    branch: z.string().optional(),
-    commits: z.array(GitCommitSchema),
-    hasMore: z.boolean(),
+    repo: z.string().describe("Which repository."),
+    branch: z.string().optional().describe("Which branch these are from."),
+    commits: z.array(GitCommitSchema).describe("The commits, newest first."),
+    hasMore: z
+        .boolean()
+        .describe("There are older ones behind this page. It is also what stops the last row being drawn as the beginning of history, which is how a truncated log used to claim it started where the page happened to stop."),
 });
 export const GitLogQuerySchema = RepoParamSchema.extend({
-    limit: z.coerce.number().int().positive().max(2000).optional(),
-    skip: z.coerce.number().int().nonnegative().max(1_000_000).optional(),
+    limit: z.coerce.number().int().positive().max(2000).optional().describe("How many commits to return."),
+    skip: z.coerce
+        .number()
+        .int()
+        .nonnegative()
+        .max(1_000_000)
+        .optional()
+        .describe("How many newer commits to step over, which is how you page further back. Paged rather than read whole, because a large repository's history is tens of thousands of rows."),
+});
+export const GitReposSchema = z.object({
+    repos: z.array(z.string()).describe('Every repository\'s id. The workspace itself is always present as "root".'),
+});
+export const GitRemoteRepoSchema = z.object({
+    repo: z.string().describe("The workspace repository."),
+    host: z.string().describe("Which forge its remote points at."),
+    project: z.string().describe("Which project there, as owner and name."),
+});
+export const GitRemoteReposSchema = z.object({
+    repos: z.array(GitRemoteRepoSchema).describe("Each repository matched to the project its remote points at."),
+});
+export const GitPublishFileSchema = RepoParamSchema.extend({
+    path: z.string().min(1).describe("Which file, relative to the repository."),
+    content: z.string().describe("Its whole new contents."),
+    message: z.string().min(1).describe("The commit message."),
 });
-export const GitReposSchema = z.object({ repos: z.array(z.string()) });
-export const GitRemoteRepoSchema = z.object({ repo: z.string(), host: z.string(), project: z.string() });
-export const GitRemoteReposSchema = z.object({ repos: z.array(GitRemoteRepoSchema) });
-export const GitPublishFileSchema = RepoParamSchema.extend({ path: z.string().min(1), content: z.string(), message: z.string().min(1) });
 export const GitPublishFileResultSchema = z.object({
-    ok: z.boolean(),
-    wrote: z.boolean(),
-    committed: z.boolean(),
-    pushed: z.boolean(),
-    branch: z.string().optional(),
-    defaultBranch: z.string().optional(),
-    reason: z.string().optional(),
-});
-export const GitCommitDiffQuerySchema = RepoParamSchema.extend({ sha: ShaSchema });
-export const GitCommitDiffSchema = z.object({ files: z.array(GitChangeSchema) });
-export const GitCommitFileDiffQuerySchema = RepoParamSchema.extend({ sha: ShaSchema, path: z.string().min(1) });
-export const GitBranchCreateSchema = RepoParamSchema.extend({ sha: ShaSchema, name: RefNameSchema });
-export const GitTagCreateSchema = RepoParamSchema.extend({ sha: ShaSchema, name: RefNameSchema });
-export const GitCheckoutSchema = RepoParamSchema.extend({ ref: RefNameSchema });
-export const GitTagDeleteSchema = RepoParamSchema.extend({ name: RefNameSchema, remote: RefNameSchema.optional() });
-export const GitTagPushSchema = RepoParamSchema.extend({ name: RefNameSchema, remote: RefNameSchema });
-export const GitResetSchema = RepoParamSchema.extend({ sha: ShaSchema, mode: z.enum(["soft", "mixed", "hard"]) });
-export const GitCommitActionSchema = RepoParamSchema.extend({ sha: ShaSchema });
-export const GitActionResultSchema = z.object({ ok: z.boolean(), reason: z.string().optional() });
+    ok: z.boolean().describe("Whether the whole thing went through."),
+    wrote: z.boolean().describe("The file was written."),
+    committed: z.boolean().describe("The commit was recorded."),
+    pushed: z.boolean().describe("It reached the remote."),
+    branch: z.string().optional().describe("Which branch it happened on."),
+    defaultBranch: z.string().optional().describe("Which branch the repository considers its main one, so a caller can see it was on a side branch."),
+    reason: z
+        .string()
+        .optional()
+        .describe("Why it stopped where it did. Being on a side branch, having no remote and having no credentials are all reported here rather than raised."),
+});
+export const GitCommitDiffQuerySchema = RepoParamSchema.extend({ sha: ShaSchema.describe("Which commit.") });
+export const GitCommitDiffSchema = z.object({
+    files: z
+        .array(GitChangeSchema)
+        .describe("Which files it touched, with counts but not contents. Fetch any one file's contents separately, so a commit with a thousand files stays one cheap answer."),
+});
+export const GitCommitFileDiffQuerySchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit."),
+    path: z.string().min(1).describe("Which file in it."),
+});
+export const GitBranchCreateSchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit to start it at."),
+    name: RefNameSchema.describe("The new branch's name."),
+});
+export const GitTagCreateSchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit to tag."),
+    name: RefNameSchema.describe("The tag's name."),
+});
+export const GitCheckoutSchema = RepoParamSchema.extend({ ref: RefNameSchema.describe("Where to switch to: a branch, a tag, or a commit.") });
+export const GitTagDeleteSchema = RepoParamSchema.extend({
+    name: RefNameSchema.describe("Which tag."),
+    remote: RefNameSchema.optional().describe("Also delete it there. Leave it out to remove it locally only."),
+});
+export const GitTagPushSchema = RepoParamSchema.extend({
+    name: RefNameSchema.describe("Which tag."),
+    remote: RefNameSchema.describe("Which remote to send it to."),
+});
+export const GitResetSchema = RepoParamSchema.extend({
+    sha: ShaSchema.describe("Which commit to move the branch to."),
+    mode: z
+        .enum(["soft", "mixed", "hard"])
+        .describe("How much to take with it: move the branch alone, also unstage, or also throw away what is on disk. The last one takes a checkpoint first."),
+});
+export const GitCommitActionSchema = RepoParamSchema.extend({ sha: ShaSchema.describe("Which commit to act on.") });
+export const GitActionResultSchema = z.object({
+    ok: z.boolean().describe("Whether it worked."),
+    reason: z
+        .string()
+        .optional()
+        .describe("Why not, in git's own words. A conflict, a missing remote and missing credentials are all reported here rather than raised, because they are things a screen has to render rather than breakages."),
+});
 export const StashEntrySchema = z.object({
-    ref: z.string(),
-    sha: z.string(),
-    short: z.string(),
-    subject: z.string(),
-    branch: z.string().optional(),
-    at: z.number(),
-    parents: z.array(z.string()),
+    ref: z.string().describe("How to address it, which applying and dropping take."),
+    sha: z.string().describe("The commit behind it, because a stash entry is a commit."),
+    short: z.string().describe("The abbreviated form, for showing."),
+    subject: z.string().describe("What it was set aside as, with git's own scaffolding stripped off."),
+    branch: z.string().optional().describe("Which branch it was set aside from."),
+    at: z.number().describe("When, in milliseconds."),
+    parents: z.array(z.string()).describe("What it sits on, so a graph can draw it like any other commit."),
+});
+export const StashListSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    stashes: z.array(StashEntrySchema).describe("What is set aside, newest first."),
 });
-export const StashListSchema = z.object({ repo: z.string(), stashes: z.array(StashEntrySchema) });
 const StashRefSchema = z.string().regex(/^stash@\{\d{1,4}\}$/);
-export const StashPushSchema = RepoParamSchema.extend({ message: z.string().max(500).optional(), includeUntracked: z.boolean().optional() });
-export const StashApplySchema = RepoParamSchema.extend({ ref: StashRefSchema, pop: z.boolean().optional() });
-export const StashRefParamSchema = RepoParamSchema.extend({ ref: StashRefSchema });
-export const StashDiffQuerySchema = RepoParamSchema.extend({ ref: StashRefSchema });
+export const StashPushSchema = RepoParamSchema.extend({
+    message: z.string().max(500).optional().describe("What to call it, so you know what it was later."),
+    includeUntracked: z.boolean().optional().describe("Also set aside files git is not yet tracking, which are otherwise left where they are."),
+});
+export const StashApplySchema = RepoParamSchema.extend({
+    ref: StashRefSchema.describe("Which entry."),
+    pop: z.boolean().optional().describe("Remove it from the stash once it has been applied cleanly."),
+});
+export const StashRefParamSchema = RepoParamSchema.extend({ ref: StashRefSchema.describe("Which entry.") });
+export const StashDiffQuerySchema = RepoParamSchema.extend({ ref: StashRefSchema.describe("Which entry.") });
 export const UndoKindSchema = z.enum(["commit", "amend", "merge", "rebase", "cherry-pick", "revert", "reset", "pull", "other"]);
 export const UndoableActionSchema = z.object({
-    kind: UndoKindSchema,
-    description: z.string(),
-    branch: z.string(),
-    sha: z.string(),
-    previousSha: z.string(),
-    changesWorkingTree: z.boolean(),
+    kind: UndoKindSchema.describe("What the last action was."),
+    description: z.string().describe("What undoing it would do, in words."),
+    branch: z.string().describe("Which branch would move."),
+    sha: z.string().describe("Where it stands now."),
+    previousSha: z
+        .string()
+        .describe("Where it would go back to. Send this with the undo as proof you looked, so one prepared against a view that has since moved is refused rather than landing somewhere unexamined."),
+    changesWorkingTree: z
+        .boolean()
+        .describe("Undoing would rewrite files as well as moving the branch, so anything offering it should warn about losing work."),
+});
+export const GitUndoStateSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    action: UndoableActionSchema.optional().describe("What undoing would reverse. Absent means there is nothing to go back from."),
+});
+export const GitUndoSchema = RepoParamSchema.extend({
+    previousSha: ShaSchema.describe("Where to go back to, from the matching read. It is also proof you looked: one prepared against a stale view is refused."),
+    discardChanges: z.boolean().optional().describe("Also rewrite the files, rather than only moving the branch."),
 });
-export const GitUndoStateSchema = z.object({ repo: z.string(), action: UndoableActionSchema.optional() });
-export const GitUndoSchema = RepoParamSchema.extend({ previousSha: ShaSchema, discardChanges: z.boolean().optional() });
 export const SnapshotTriggerSchema = z.enum(["turn", "interval", "pre-restore", "restore", "user"]);
 export const SnapshotSchema = z.object({
-    id: z.string(),
-    at: z.number(),
-    trigger: SnapshotTriggerSchema,
-    label: z.string().optional(),
+    id: z.string().describe("The saved point's id, which is what restoring and diffing take."),
+    at: z.number().describe("When it was taken, in milliseconds."),
+    trigger: SnapshotTriggerSchema.describe("What caused it. The automatic between-turn captures are a safety net and are not listed; they dissolve into the next visible point's differences."),
+    label: z.string().optional().describe("What to call it. For one taken before a turn, that turn's prompt."),
 });
-export const SnapshotsListSchema = z.object({ snapshots: z.array(SnapshotSchema) });
+export const SnapshotsListSchema = z.object({ snapshots: z.array(SnapshotSchema).describe("Every point you can go back to, newest first.") });
 export const RewindTurnSchema = z.object({
-    conversationId: z.string().min(1),
-    index: z.number().int().nonnegative(),
+    conversationId: z.string().min(1).describe("Which conversation to rewind."),
+    index: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("Which message to go back to, counting from the start. It is also how many messages survive: rewinding to the first keeps none of them and puts the files back to before it ran."),
 });
 export const RewindResultSchema = z.object({
-    snapshot: z.string().optional(),
-    dropped: z.number().int().nonnegative(),
+    snapshot: z
+        .string()
+        .optional()
+        .describe("The saved point the files were put back to. Absent for a conversation working in its own copy, whose rewind moved a branch rather than the shared timeline."),
+    dropped: z.number().int().nonnegative().describe("How many messages were removed."),
 });
-export const SnapshotIdSchema = z.object({ id: z.string().min(1) });
+export const SnapshotIdSchema = z.object({ id: z.string().min(1).describe("Which saved point.") });
 export const SnapshotChangeSchema = z.object({
-    scope: z.string(),
-    path: z.string(),
-    status: z.enum(["added", "modified", "deleted", "type-changed"]),
+    scope: z.string().describe("Which part of the workspace the path belongs to: the workspace root, or one of the repositories inside it."),
+    path: z.string().describe("The path, relative to that scope."),
+    status: z.enum(["added", "modified", "deleted", "type-changed"]).describe("What happened to it."),
+});
+export const SnapshotDiffSchema = z.object({
+    changes: z.array(SnapshotChangeSchema).describe("Everything that differs between this saved point and the one before it."),
 });
-export const SnapshotDiffSchema = z.object({ changes: z.array(SnapshotChangeSchema) });
 export const SnapshotFileDiffQuerySchema = z.object({
-    id: z.string().min(1),
-    scope: z.string().min(1),
-    path: z.string().min(1),
+    id: z.string().min(1).describe("Which saved point."),
+    scope: z.string().min(1).describe("Which part of the workspace the path belongs to."),
+    path: z.string().min(1).describe("The file, relative to that scope."),
 });
 export const FileDiffSchema = z.object({
-    before: z.string().optional(),
-    after: z.string().optional(),
-    binary: z.boolean().optional(),
-    truncated: z.boolean().optional(),
+    before: z.string().optional().describe("The whole file as it was. Absent when it did not exist yet."),
+    after: z.string().optional().describe("The whole file as it is now. Absent when it was deleted."),
+    binary: z.boolean().optional().describe("The file is not text, so neither side is sent."),
+    truncated: z.boolean().optional().describe("The file was too large to send whole, so what you have is the start of it."),
+});
+export const WorkspaceScopeSchema = z.object({
+    agent: ConversationIdSchema.optional().describe("Read a conversation's own private copy of the workspace rather than the shared tree. Leave it out for the shared tree. A conversation that is not working privately resolves back to the shared tree rather than failing, so a link need not know which mode it runs in."),
 });
-export const WorkspaceScopeSchema = z.object({ agent: ConversationIdSchema.optional() });
 export const WorkspaceLinkSchema = z.object({
-    to: z.string(),
-    state: z.enum(["broken", "outside"]).optional(),
+    to: z
+        .string()
+        .describe("What the link says, verbatim, rather than where it ends up. That is what the person who made it wrote, and what they would edit."),
+    state: z
+        .enum(["broken", "outside"])
+        .optional()
+        .describe("Absent for an ordinary link. Broken means there is nothing at the other end, and it is listed anyway because a dangling link is worth seeing. Outside means it leads out of the workspace, so it is shown and refused."),
 });
 export const WorkspaceTreeEntrySchema = z.object({
-    name: z.string(),
-    path: z.string(),
-    type: z.enum(["file", "dir"]),
-    size: z.number().optional(),
-    ignored: z.boolean().optional(),
-    link: WorkspaceLinkSchema.optional(),
+    name: z.string().describe("Just this entry's own name."),
+    path: z.string().describe("Its full path from the workspace root, which feeds straight back into the file routes."),
+    type: z.enum(["file", "dir"]).describe("What it is. For a link, what it points at, so a link to a folder opens like a folder."),
+    size: z.number().optional().describe("Size in bytes, for a file."),
+    ignored: z
+        .boolean()
+        .optional()
+        .describe("Tooling ignores it: installed packages, git internals, anything the ignore rules exclude. Usually drawn greyed out."),
+    link: WorkspaceLinkSchema.optional().describe("Present when this entry is a link."),
     get children() {
-        return z.array(WorkspaceTreeEntrySchema).optional();
+        return z
+            .array(WorkspaceTreeEntrySchema)
+            .optional()
+            .describe("What is inside a folder. Absent means it was not opened, either because it is ignored or because the walk ran out of budget above it, so ask for it separately. An empty list means it really is empty.");
     },
 });
 export const WorkspaceTreeSchema = z.object({
-    root: z.string(),
-    tree: z.array(WorkspaceTreeEntrySchema),
-    hidden: z.number(),
+    root: z.string().describe("The path everything below is relative to."),
+    tree: z.array(WorkspaceTreeEntrySchema).describe("The workspace, one entry per file and folder."),
+    hidden: z.number().describe("How many entries at the top level were cut for size. Zero means the listing is complete."),
+});
+export const WorkspaceChildrenQuerySchema = WorkspaceScopeSchema.extend({
+    path: z.string().min(1).describe("The folder to open, as a workspace path."),
 });
-export const WorkspaceChildrenQuerySchema = WorkspaceScopeSchema.extend({ path: z.string().min(1) });
 export const WorkspaceChildrenSchema = z.object({
-    entries: z.array(WorkspaceTreeEntrySchema),
-    hidden: z.number(),
+    entries: z
+        .array(WorkspaceTreeEntrySchema)
+        .describe("What is directly inside it. Folders in here carry no contents of their own, so they open the same way."),
+    hidden: z.number().describe("How many entries were cut for size. Zero means the listing is complete."),
+});
+export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1).describe("The file or folder, as a workspace path.") });
+export const WorkspaceMediaTicketQuerySchema = WorkspaceScopeSchema.extend({
+    path: z.string().min(1).describe("The media file the ticket should cover."),
+});
+export const WorkspaceMediaTicketSchema = z.object({
+    ticket: z.string().describe("Hand this to the streaming route in the query string. It buys exactly the one file it was minted for."),
+    expiresAt: z.number().describe("When it stops working, in milliseconds, so a player can tell a dead ticket from a dead file."),
 });
-export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1) });
-export const WorkspaceMediaTicketQuerySchema = WorkspaceScopeSchema.extend({ path: z.string().min(1) });
-export const WorkspaceMediaTicketSchema = z.object({ ticket: z.string(), expiresAt: z.number() });
 export const WorkspaceFileReadQuerySchema = WorkspaceScopeSchema.extend({
-    path: z.string().min(1),
-    offset: z.coerce.number().int().optional(),
-    limit: z.coerce.number().int().min(1).optional(),
+    path: z.string().min(1).describe("The file to read, as a workspace path."),
+    offset: z.coerce
+        .number()
+        .int()
+        .optional()
+        .describe("Which byte to start at. A negative number reads that many bytes from the end, which is how you follow a growing log without knowing its size first."),
+    limit: z.coerce
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe("How many bytes to read. Capped by the sandbox, so leaving it out or asking for too much gives you the cap rather than the whole file."),
 });
 export const WorkspaceFilePresentSchema = z.object({
-    present: z.literal(true),
-    path: z.string(),
-    content: z.string(),
-    size: z.number(),
-    offset: z.number(),
-    bytes: z.number(),
-    shared: z.boolean(),
+    present: z.literal(true).describe("There is something at that path."),
+    path: z.string().describe("The path, as asked for."),
+    content: z.string().describe("The bytes of the window you asked for, as text."),
+    size: z.number().describe("How large the whole file is. Compare it with the window below to know whether there is more."),
+    offset: z.number().describe("Which byte the window starts at."),
+    bytes: z.number().describe("How many bytes the window holds."),
+    shared: z
+        .boolean()
+        .describe("Which tree answered. True when no conversation was named, and also when one was but its own copy has no such file, which is the case a reader has to be told about rather than left to assume."),
+});
+export const WorkspaceFileAbsentSchema = z.object({
+    present: z
+        .literal(false)
+        .describe("Nothing there. An answer, not a failure: reading a file that may not exist yet is the ordinary case for half the reads in this product."),
+    path: z.string().describe("The path, as asked for."),
 });
-export const WorkspaceFileAbsentSchema = z.object({ present: z.literal(false), path: z.string() });
 export const WorkspaceFileSchema = z.discriminatedUnion("present", [WorkspaceFilePresentSchema, WorkspaceFileAbsentSchema]);
-export const WorkspaceResolveQuerySchema = WorkspaceScopeSchema.extend({ path: z.string().min(1).max(512) });
-export const WorkspaceResolveSchema = z.object({ path: z.string().optional() });
-export const WorkspaceDirSchema = z.object({ path: z.string().min(1) });
-export const WorkspaceMoveSchema = z.object({ from: z.string().min(1), to: z.string().min(1) });
+export const WorkspaceResolveQuerySchema = WorkspaceScopeSchema.extend({
+    path: z
+        .string()
+        .min(1)
+        .max(512)
+        .describe("The reference as somebody wrote it. Often only the tail of the real path, which is why this is matched against the tree rather than read as-is."),
+});
+export const WorkspaceResolveSchema = z.object({
+    path: z.string().optional().describe("The real path it means. Absent when nothing in the workspace ends that way."),
+});
+export const WorkspaceDirSchema = z.object({ path: z.string().min(1).describe("The folder to create. Missing folders above it are created too.") });
+export const WorkspaceMoveSchema = z.object({
+    from: z.string().min(1).describe("What to move or copy, as a workspace path."),
+    to: z.string().min(1).describe("Where it should end up. Changing only the last part is how you rename something."),
+});
 export const WorkspaceBucketSchema = z.enum(["repositories", "documents", "media", "archives", "other"]);
 export const WorkspaceClassificationSchema = z.object({
-    classifications: z.array(z.object({ path: z.string(), bucket: WorkspaceBucketSchema, reason: z.string() })),
+    classifications: z
+        .array(z.object({
+        path: z.string().describe("What was looked at."),
+        bucket: WorkspaceBucketSchema.describe("Which bucket it was sorted into."),
+        reason: z.string().describe("The signal that decided it, so the proposal can be argued with rather than trusted."),
+    }))
+        .describe("One entry per repository folder and loose file at the top of the workspace. A read-only proposal: nothing moves until you apply it."),
 });
 export const WorkspaceSearchQuerySchema = z.object({
-    query: z.string().min(2).max(512),
-    mode: z.enum(["q", "find", "files", "def", "refs", "sym", "ast"]).optional(),
-    includeIgnored: z.stringbool().optional(),
-    literal: z.stringbool().optional(),
-    word: z.stringbool().optional(),
-    caseSensitive: z.stringbool().optional(),
-    include: z.string().max(512).optional(),
-    limit: z.coerce.number().int().positive().optional(),
-    after: z.string().optional(),
+    query: z.string().min(2).max(512).describe("What to look for. Plain words, a pattern, a symbol name, or a question."),
+    mode: z
+        .enum(["q", "find", "files", "def", "refs", "sym", "ast"])
+        .optional()
+        .describe("Narrow the search to one kind: plain text, filenames, definitions, references, symbols, or code structure. Leave it out to blend them, which also answers a question asked in words."),
+    includeIgnored: z.stringbool().optional().describe("Search inside installed packages and other ignored folders too."),
+    literal: z.stringbool().optional().describe("Treat the query as fixed text rather than a pattern."),
+    word: z.stringbool().optional().describe("Match whole words only."),
+    caseSensitive: z.stringbool().optional().describe("Whether capitals matter. Off means they do not, rather than being guessed at from the query."),
+    include: z
+        .string()
+        .max(512)
+        .optional()
+        .describe("Which files to ask, in the same grammar an editor's files-to-include box takes: comma-separated patterns, matched at any depth unless anchored, a leading exclamation mark excluding instead."),
+    limit: z.coerce.number().int().positive().optional().describe("How many results to return."),
+    after: z.string().optional().describe("Resume from the cursor a previous answer handed back."),
 });
 export const WorkspaceSearchTagSchema = z.object({
-    kind: z.enum(["def", "text", "sem", "bm25", "rerank", "path", "import", "call", "type", "write", "fuzzy", "heuristic"]),
-    score: z.number().optional(),
+    kind: z
+        .enum(["def", "text", "sem", "bm25", "rerank", "path", "import", "call", "type", "write", "fuzzy", "heuristic"])
+        .describe("Why this line matched: the literal text, its meaning, the path, a definition, a call, and so on. Several kinds can agree on one line."),
+    score: z.number().optional().describe("How strongly that reason applied."),
+});
+export const WorkspaceSearchSpanSchema = z.object({
+    start: z.number().describe("First character of the match within the line."),
+    end: z.number().describe("One past the last."),
 });
-export const WorkspaceSearchSpanSchema = z.object({ start: z.number(), end: z.number() });
 export const WorkspaceSearchHitSchema = z.object({
-    line: z.number(),
-    text: z.string(),
-    spans: z.array(WorkspaceSearchSpanSchema),
-    tags: z.array(WorkspaceSearchTagSchema),
-    context: z.string().optional(),
+    line: z.number().describe("Which line, counting from one."),
+    text: z.string().describe("The line itself."),
+    spans: z
+        .array(WorkspaceSearchSpanSchema)
+        .describe("Where in the line the matches are, so you can highlight without searching again. Empty when the whole line is the match rather than part of it."),
+    tags: z.array(WorkspaceSearchTagSchema).describe("Why it matched."),
+    context: z
+        .string()
+        .optional()
+        .describe("What it sits inside: the function, the class, the heading. Often enough that you need not open the file."),
 });
 export const WorkspaceSearchGroupSchema = z.object({
-    path: z.string(),
-    score: z.number(),
-    hits: z.array(WorkspaceSearchHitSchema),
-    capped: z.boolean().optional(),
+    path: z.string().describe("The file."),
+    score: z.number().describe("How well it matched. Groups arrive best first, never in path order."),
+    hits: z.array(WorkspaceSearchHitSchema).describe("The matching lines in it."),
+    capped: z
+        .boolean()
+        .optional()
+        .describe("This file had more matches than are kept per file, so the count is a floor. Say fifty-plus rather than fifty."),
 });
 export const WorkspaceSearchFreshnessSchema = z.object({
-    state: z.enum(["fresh", "building", "stale"]),
-    ageMs: z.number().optional(),
-    progress: z.number().optional(),
-    behind: z.number().optional(),
+    state: z.enum(["fresh", "building", "stale"]).describe("Whether the index matches what is on disk, is still filling, or has fallen behind."),
+    ageMs: z.number().optional().describe("How long since it last matched the disk, in milliseconds."),
+    progress: z.number().optional().describe("How far through building it is, from zero to one."),
+    behind: z
+        .number()
+        .optional()
+        .describe("How many files it has not caught up with. Worth showing, because the word stale on its own reads as a warning about the answer, which it almost never is."),
 });
 export const WorkspaceSearchResultSchema = z.object({
-    mode: z.string(),
-    total: z.number(),
-    files: z.number(),
-    shown: z.number(),
-    groups: z.array(WorkspaceSearchGroupSchema),
-    freshness: WorkspaceSearchFreshnessSchema,
-    truncated: z.boolean(),
-    partial: z.boolean().optional(),
-    cursor: z.string().optional(),
-    hint: z.string().optional(),
-    note: z.string().optional(),
-    related: z.array(z.string()).optional(),
-    candidates: z.array(z.string()).optional(),
-    features: z.array(z.string()).optional(),
+    mode: z.string().describe("Which kind of search actually ran, which matters when you let it choose."),
+    total: z.number().describe("Matching lines across the whole workspace, not just this page."),
+    files: z.number().describe("Files the query matched in total."),
+    shown: z.number().describe("How many of those lines are on this page."),
+    groups: z.array(WorkspaceSearchGroupSchema).describe("The results, grouped by file, best first."),
+    freshness: WorkspaceSearchFreshnessSchema.describe("Whether the index behind the answer is up to date."),
+    truncated: z.boolean().describe("This page is not all of it. Use the cursor."),
+    partial: z
+        .boolean()
+        .optional()
+        .describe("At least one file had more matches than are kept per file, so the total is a floor. Different from the page being truncated: a complete page can still count partially."),
+    cursor: z.string().optional().describe("Pass this back as `after` to get the next page."),
+    hint: z.string().optional().describe("A suggestion for getting a better answer out of this query."),
+    note: z
+        .string()
+        .optional()
+        .describe("What the engine did that you did not ask for: a pattern rerun as plain text because it was not valid, escapes rewritten, a language filter that matched nothing."),
+    related: z.array(z.string()).optional().describe("Places next door to the best results: where each is defined, and whatever calls it most."),
+    candidates: z
+        .array(z.string())
+        .optional()
+        .describe("Ranked places that scored but did not make the page, best first. The answer often sits at rank five to thirteen, so this saves paging through to find out."),
+    features: z.array(z.string()).optional().describe("Which stages of the search were switched off for this run. Absent means all of them ran."),
 });
 export const HEALTH_LIMIT = 20;
 export const WorkspaceHealthQuerySchema = z.object({
-    repo: z.string().min(1),
-    since: z.string().max(16).optional(),
-    limit: z.coerce.number().int().positive().max(200).optional(),
+    repo: z.string().min(1).describe("Which repository, using the same ids the git routes take."),
+    since: z
+        .string()
+        .max(16)
+        .optional()
+        .describe("How far back to count changes, written as a span such as 2d, 12h, 1w or 3m. Leave it out for all of history."),
+    limit: z.coerce
+        .number()
+        .int()
+        .positive()
+        .max(200)
+        .optional()
+        .describe("How many files and modules to rank. A leaderboard rather than an inventory: past a screenful the ranking stops being the point."),
 });
 export const WorkspaceHotspotSchema = z.object({
     path: z.string(),
@@ -942,78 +1703,127 @@ export const WorkspaceHotspotSchema = z.object({
 });
 export const WorkspaceKeyModuleSchema = z.object({ path: z.string(), exports: z.number() });
 export const WorkspaceHealthSchema = z.object({
-    repo: z.string(),
-    totals: z.object({
-        files: z.number(),
-        symbols: z.number(),
-        complexity: z.number(),
-        hotspots: z.number(),
-    }),
-    hotspots: z.array(WorkspaceHotspotSchema),
-    modules: z.array(WorkspaceKeyModuleSchema),
-    freshness: WorkspaceSearchFreshnessSchema,
+    repo: z.string().describe("Which repository this describes."),
+    totals: z
+        .object({
+        files: z.number().describe("Files counted."),
+        symbols: z.number().describe("Named things they export."),
+        complexity: z.number().describe("Branch points across all of them added up."),
+        hotspots: z.number().describe("How many files qualify as hotspots at all. The list below is capped; this is not."),
+    })
+        .describe("Counts anybody could recount in the files themselves. Deliberately no single maintainability grade: those cannot be checked and are not comparable between projects."),
+    hotspots: z.array(WorkspaceHotspotSchema).describe("Files that change often and are complicated at the same time, worst first."),
+    modules: z.array(WorkspaceKeyModuleSchema).describe("The parts of the codebase the rest of it leans on most."),
+    freshness: WorkspaceSearchFreshnessSchema.describe("Whether the index these numbers were read from is up to date."),
 });
 export const ProjectSetupSchema = z.object({
-    dir: z.string(),
-    ecosystem: z.enum(["node", "python"]),
-    manager: z.string(),
-    command: z.string(),
-    evidence: z.string(),
-    state: z.enum(["ready", "installing", "needs-setup", "unsupported", "stale"]),
-    missing: z.number().optional(),
-});
-export const WorkspaceSetupSchema = z.object({ projects: z.array(ProjectSetupSchema) });
-export const WorkspaceInstallSchema = z.object({ dirs: z.array(z.string().max(500)).min(1).max(50) });
-export const WorkspaceInstallResultSchema = z.object({ queued: z.array(z.string()) });
-export const ReposListSchema = z.object({ repos: z.array(z.string()) });
-export const CloneRepoSchema = z.object({ name: z.string().min(1), cloneUrl: z.string().min(1), branch: z.string().optional() });
-export const CloneResultSchema = z.object({ name: z.string(), path: z.string() });
-export const RepoSyncSchema = z.object({
-    repo: z.string(),
-    status: z.enum(["updated", "current", "dirty", "diverged", "no-remote", "skipped", "error"]),
-    behind: z.number().optional(),
-    ahead: z.number().optional(),
-    head: z.string().optional(),
-    message: z.string().optional(),
+    dir: z.string().describe("Where the project is, relative to the workspace root. Empty means the root itself."),
+    ecosystem: z.enum(["node", "python"]).describe("Which language's tooling it uses."),
+    manager: z.string().describe("The tool that would do the installing."),
+    command: z.string().describe("The exact command that would run."),
+    evidence: z.string().describe("The file that decided all of the above, so the answer can be checked rather than trusted."),
+    state: z
+        .enum(["ready", "installing", "needs-setup", "unsupported", "stale"])
+        .describe("Ready means its dependencies are really there. Stale means it was installed once and has since outgrown that, which is what an agent leaves behind when it adds a dependency without installing it. Unsupported means this sandbox has no such tool."),
+    missing: z.number().optional().describe("How many declared dependencies cannot be found on disk. What separates never-installed from outgrown."),
+});
+export const WorkspaceSetupSchema = z.object({
+    projects: z.array(ProjectSetupSchema).describe("Every project the sandbox found, and whether each is usable."),
+});
+export const WorkspaceInstallSchema = z.object({
+    dirs: z
+        .array(z.string().max(500))
+        .min(1)
+        .max(50)
+        .describe("Which projects to install, by folder. Ones already ready, already installing, or with no tool to install them are skipped rather than refused."),
+});
+export const WorkspaceInstallResultSchema = z.object({
+    queued: z.array(z.string()).describe("Which of them actually started, which is not necessarily what you asked for."),
 });
-export const WorkspaceSyncSchema = z.object({ repos: z.array(RepoSyncSchema) });
+export const ReposListSchema = z.object({
+    repos: z
+        .array(z.string())
+        .describe('Every repository\'s id, sorted. An id is its folder relative to the workspace root, and "root" is the workspace itself.'),
+});
+export const CloneRepoSchema = z.object({
+    name: z.string().min(1).describe("What to call it in the workspace."),
+    cloneUrl: z.string().min(1).describe("Where to clone it from."),
+    branch: z.string().optional().describe("Which branch to check out. Leave it out for the repository's default."),
+});
+export const CloneResultSchema = z.object({
+    name: z.string().describe("What it ended up called."),
+    path: z.string().describe("Where it landed."),
+});
+export const RepoSyncSchema = z.object({
+    repo: z.string().describe("Which repository."),
+    status: z
+        .enum(["updated", "current", "dirty", "diverged", "no-remote", "skipped", "error"])
+        .describe("What happened to it. Dirty and diverged are why a repository was left alone: it had uncommitted work, or it had moved in a way that cannot be fast-forwarded."),
+    behind: z.number().optional().describe("How many commits it was behind."),
+    ahead: z.number().optional().describe("How many commits it was ahead."),
+    head: z.string().optional().describe("The commit it ended up on."),
+    message: z.string().optional().describe("What went wrong, when something did."),
+});
+export const WorkspaceSyncSchema = z.object({ repos: z.array(RepoSyncSchema).describe("One entry per repository, saying what happened to it.") });
 export const AppInstanceInputSchema = z.object({
-    template: z.string().min(1),
+    template: z.string().min(1).describe("Which kind of app to scaffold, by its key in the template list."),
     name: z
         .string()
         .min(1)
-        .regex(/^[a-z][a-z0-9-]*$/),
+        .regex(/^[a-z][a-z0-9-]*$/)
+        .describe("What to call this one."),
 });
 export const AddAppsSchema = z.object({
-    repo: z.string(),
-    apps: z.array(AppInstanceInputSchema).min(1),
+    repo: z.string().describe("Which repository to scaffold into."),
+    apps: z.array(AppInstanceInputSchema).min(1).describe("The apps to add."),
 });
 export const RunTestsSchema = z.object({
-    repo: z.string(),
-    session: z.string(),
-    dirs: z.array(z.string()).min(1),
+    repo: z.string().describe("Which repository."),
+    session: z.string().describe("What to call the terminal this runs in, so you can find it again."),
+    dirs: z.array(z.string()).min(1).describe("Which projects to test, as folders relative to the repository. Empty targets the repository root."),
+});
+export const TemplateSummarySchema = z.object({
+    key: z.string().describe("The id to name when scaffolding one."),
+    label: z.string().describe("What to call it on screen."),
+    description: z.string().describe("What you get."),
+});
+export const TemplatesListSchema = z.object({
+    templates: z.array(TemplateSummarySchema).describe("The kinds of app the configured source repository knows how to scaffold."),
 });
-export const TemplateSummarySchema = z.object({ key: z.string(), label: z.string(), description: z.string() });
-export const TemplatesListSchema = z.object({ templates: z.array(TemplateSummarySchema) });
 export const RepoAppSchema = z.object({
-    app: z.string(),
-    kind: z.string().optional(),
-    previewUrl: z.string().optional(),
-    running: z.boolean(),
-    healthy: z.boolean(),
+    app: z.string().describe("The app's name, which is also its folder."),
+    kind: z
+        .string()
+        .optional()
+        .describe("What sort of app it is: the template it came from, or the framework worked out from its dependencies. Absent when it was found purely by having a dev script."),
+    previewUrl: z.string().optional().describe("Where to open it. Absent when this sandbox has no outside address."),
+    running: z.boolean().describe("Whether its dev server is up."),
+    healthy: z.boolean().describe("Whether it is actually answering."),
+});
+export const AppsListSchema = z.object({ apps: z.array(RepoAppSchema).describe("The apps in this repository.") });
+export const WorkspacePackageSchema = z.object({
+    name: z.string().describe("The name the package declares."),
+    dir: z.string().describe("Where it lives, relative to the repository."),
+    group: z.string().describe("The top-level folder it sits under, which is what a diagram colours by."),
 });
-export const AppsListSchema = z.object({ apps: z.array(RepoAppSchema) });
-export const WorkspacePackageSchema = z.object({ name: z.string(), dir: z.string(), group: z.string() });
 export const WorkspaceDepTypeSchema = z.enum(["prod", "dev", "peer"]);
-export const WorkspaceDepEdgeSchema = z.object({ from: z.string(), to: z.string(), type: WorkspaceDepTypeSchema });
-export const WorkspaceGraphSchema = z.object({ packages: z.array(WorkspacePackageSchema), edges: z.array(WorkspaceDepEdgeSchema) });
-export const RepoAppsParamSchema = z.object({ repo: z.string() });
+export const WorkspaceDepEdgeSchema = z.object({
+    from: z.string().describe("The package that depends."),
+    to: z.string().describe("The package it depends on."),
+    type: WorkspaceDepTypeSchema.describe("Which kind of dependency declared it."),
+});
+export const WorkspaceGraphSchema = z.object({
+    packages: z.array(WorkspacePackageSchema).describe("Every package in the repository."),
+    edges: z.array(WorkspaceDepEdgeSchema).describe("Which of them use which. Pure data: how to lay it out is yours to decide."),
+});
+export const RepoAppsParamSchema = z.object({ repo: z.string().describe("Which repository.") });
 export const AppParamSchema = z.object({
-    repo: z.string(),
+    repo: z.string().describe("Which repository."),
     app: z
         .string()
         .min(1)
-        .regex(/^[a-z][a-z0-9-]*$/),
+        .regex(/^[a-z][a-z0-9-]*$/)
+        .describe("Which app inside it."),
 });
 export const InventoryProviderSchema = z.enum(["host", "cloudflare", "github", "gitlab", "stripe"]);
 export const ServiceKindSchema = z.enum(["signoz", "outline", "paperless", "openproject", "invoiceninja", "infisical"]);
@@ -1024,25 +1834,25 @@ const inventoryName = z
     .max(60)
     .regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/);
 export const BackendEntrySchema = z.object({
-    kind: z.literal("backend"),
-    provider: InventoryProviderSchema,
-    name: z.string(),
-    values: InventoryValuesSchema,
+    kind: z.literal("backend").describe("Something you already have: a machine, an account with a hosting provider."),
+    provider: InventoryProviderSchema.describe("Which provider it is with."),
+    name: z.string().describe("What to call it, which is also how everything else refers to it."),
+    values: InventoryValuesSchema.describe("Its settings. Anything secret is stored separately and referred to here, never written in."),
 });
 export const ServiceEntrySchema = z.object({
-    kind: z.literal("service"),
-    service: ServiceKindSchema,
-    name: z.string(),
-    values: InventoryValuesSchema,
-    on: z.string(),
-    expose: z.string(),
+    kind: z.literal("service").describe("Something you want provisioned."),
+    service: ServiceKindSchema.describe("Which service."),
+    name: z.string().describe("What to call it."),
+    values: InventoryValuesSchema.describe("Its settings."),
+    on: z.string().describe("Which of your machines to put it on."),
+    expose: z.string().describe("How it should be reachable."),
 });
 export const AppEntrySchema = z.object({
-    kind: z.literal("app"),
-    name: z.string(),
-    values: InventoryValuesSchema,
-    on: z.string(),
-    expose: z.string(),
+    kind: z.literal("app").describe("An app of your own, built from source and deployed."),
+    name: z.string().describe("What to call it."),
+    values: InventoryValuesSchema.describe("Its settings, including the address it should answer on."),
+    on: z.string().describe("Which of your machines to put it on."),
+    expose: z.string().describe("How it should be reachable."),
 });
 export const InventoryEntrySchema = z.discriminatedUnion("kind", [BackendEntrySchema, ServiceEntrySchema, AppEntrySchema]);
 export const AddInventoryInputSchema = z.discriminatedUnion("kind", [
@@ -1050,8 +1860,10 @@ export const AddInventoryInputSchema = z.discriminatedUnion("kind", [
     ServiceEntrySchema.extend({ name: inventoryName }),
     AppEntrySchema.extend({ name: inventoryName }),
 ]);
-export const InventoryNameParamSchema = z.object({ name: z.string() });
-export const InventoryListSchema = z.object({ entries: z.array(InventoryEntrySchema) });
+export const InventoryNameParamSchema = z.object({ name: z.string().describe("Which entry, by name.") });
+export const InventoryListSchema = z.object({
+    entries: z.array(InventoryEntrySchema).describe("Everything declared: what you have, and what you want provisioned."),
+});
 export const EnrollHostInputSchema = z.object({
     name: inventoryName,
     user: z.string().min(1),
@@ -1084,51 +1896,74 @@ export const CapabilityKindSchema = z.enum([
     "wallet",
 ]);
 export const CapabilityStateSchema = z.enum(["active", "pending", "error", "inactive"]);
-export const McpConfigSchema = z.object({ url: z.url(), token: z.string().optional() });
+export const McpConfigSchema = z.object({
+    url: z.url().describe("Where the tool server answers."),
+    token: z.string().optional().describe("The credential it needs, if any. Stored, never echoed back."),
+});
 export const ServiceConfigSchema = z.object({
-    service: ServiceKindSchema,
-    domain: z.string().min(1),
-    on: z.string().min(1),
-    expose: z.string().min(1),
+    service: ServiceKindSchema.describe("Which service to provision."),
+    domain: z.string().min(1).describe("The address it should answer on."),
+    on: z.string().min(1).describe("Which machine to put it on."),
+    expose: z.string().min(1).describe("How it should be reachable."),
+});
+export const IntegrationConfigSchema = z.object({
+    provider: z.literal("stripe").describe("Which outside service's credential to make available to deployed apps."),
 });
-export const IntegrationConfigSchema = z.object({ provider: z.literal("stripe") });
-export const CliConfigSchema = z.object({ provider: z.string().min(1) }).catchall(z.string());
+export const CliConfigSchema = z
+    .object({
+    provider: z
+        .string()
+        .min(1)
+        .describe("Which tool to give the agent. The rest of the fields are whatever that tool's own card declares it needs, and are checked against it when you connect."),
+})
+    .catchall(z.string());
 export const PluginConfigSchema = z.object({
-    url: z.url(),
-    ref: z.string().min(1).optional(),
+    url: z.url().describe("The repository to take the plugin from."),
+    ref: z.string().min(1).optional().describe("A branch, tag or commit to pin to. Leave it out to follow the default branch."),
     path: z
         .string()
         .min(1)
         .refine((value) => !value.split("/").includes(".."), { message: "path must stay inside the checkout" })
-        .optional(),
-    token: z.string().min(1).optional(),
+        .optional()
+        .describe("Where inside the repository the plugin lives, for one that sits in a larger checkout."),
+    token: z.string().min(1).optional().describe("A credential for a private repository. Stored, never echoed back."),
 });
 export const ExtensionConfigSchema = z.object({
-    url: z.url(),
-    ref: z.string().regex(/^[0-9a-f]{40}$/, "ref must be a full 40-character commit sha"),
+    url: z.url().describe("The repository to take the extension from."),
+    ref: z
+        .string()
+        .regex(/^[0-9a-f]{40}$/, "ref must be a full 40-character commit sha")
+        .describe("The exact commit to install, in full. Required rather than optional because extension code runs with your browser's trust: the owner approves precisely the code that runs, and an update is a deliberate re-install at a new commit."),
     path: z
         .string()
         .min(1)
         .refine((value) => !value.split("/").includes(".."), { message: "path must stay inside the checkout" })
-        .optional(),
-    token: z.string().min(1).optional(),
-    tier: z.enum(["free", "premium"]).optional(),
-    registry: z.url().optional(),
+        .optional()
+        .describe("Where inside the repository the extension lives, for one that sits in a larger checkout."),
+    token: z.string().min(1).optional().describe("A credential for a private repository. Stored, never echoed back."),
+    tier: z
+        .enum(["free", "premium"])
+        .optional()
+        .describe("Whether installing this donates credits to its publisher. Absent means free, which donates nothing and asks for nothing. Taken from the listing rather than checked against it, which is the honesty an open-source posture accepts."),
+    registry: z
+        .url()
+        .optional()
+        .describe("Which registry this install came from, which is what update checks and security advisories are read against. Absent falls back to the official one."),
 });
 export const SshConfigSchema = z.discriminatedUnion("auth", [
     z.object({
-        auth: z.literal("key"),
-        host: z.string().min(1),
-        port: z.coerce.number().default(22),
-        user: z.string().min(1),
-        privateKey: z.string().min(1),
+        auth: z.literal("key").describe("Sign in with a key."),
+        host: z.string().min(1).describe("The machine's address."),
+        port: z.coerce.number().default(22).describe("Which port it listens on."),
+        user: z.string().min(1).describe("Which user to connect as."),
+        privateKey: z.string().min(1).describe("The private key, whole. Stored with tight permissions and never echoed back."),
     }),
     z.object({
-        auth: z.literal("password"),
-        host: z.string().min(1),
-        port: z.coerce.number().default(22),
-        user: z.string().min(1),
-        password: z.string().min(1),
+        auth: z.literal("password").describe("Sign in with a password."),
+        host: z.string().min(1).describe("The machine's address."),
+        port: z.coerce.number().default(22).describe("Which port it listens on."),
+        user: z.string().min(1).describe("Which user to connect as."),
+        password: z.string().min(1).describe("The password. Stored, never echoed back."),
     }),
 ]);
 export const VpnProviderSchema = z.enum(["wireguard", "fortinet", "ipsec"]);
@@ -1286,10 +2121,19 @@ export const CapabilitySchema = z.discriminatedUnion("kind", [
     z.object({ id: entryId, kind: z.literal("wallet"), config: WalletConfigSchema }),
 ]);
 export const PersonaPowersSchema = z.object({
-    files: z.enum(["none", "read", "write"]).default("write"),
-    shell: z.boolean().default(true),
-    code: z.boolean().default(true),
-    web: z.boolean().default(true),
+    files: z
+        .enum(["none", "read", "write"])
+        .default("write")
+        .describe("What it may do with files: nothing, look and search, or also create and change."),
+    shell: z
+        .boolean()
+        .default(true)
+        .describe("Whether it may run commands, and with them the terminals, the test runs and every tool on the image. The switch the strength of the others depends on."),
+    code: z
+        .boolean()
+        .default(true)
+        .describe("Whether it may write and run a script rather than a command line. Its fence is real where the shell's is not: reads and writes follow the files answer, and it can start no other program unless commands are allowed too. The one stated gap is that the fence cannot cut the network."),
+    web: z.boolean().default(true).describe("Whether it may fetch a page or run a search."),
     browser: z.boolean().default(true),
     delegate: z.boolean().default(true),
     sandbox: z.boolean().default(true),
@@ -1298,16 +2142,23 @@ export const PersonaPowersSchema = z.object({
     mcp: z.array(entryId).max(50).optional(),
 });
 export const PersonaWorkspaceSchema = z.object({
-    startIn: z.string().max(200).optional(),
-    folders: z.array(z.string().min(1)).max(50).optional(),
+    startIn: z.string().max(200).optional().describe("Which folder a conversation opens in."),
+    folders: z.array(z.string().min(1)).max(50).optional().describe("Which folders it may touch at all. Absent means the whole workspace."),
 });
 export const PersonaSchema = z.object({
-    id: entryId,
-    label: z.string().max(60).optional(),
-    capabilities: z.array(entryId).max(50),
-    repos: z.array(z.string().min(1)).max(50).optional(),
-    powers: PersonaPowersSchema.optional(),
-    workspace: PersonaWorkspaceSchema.optional(),
+    id: entryId.describe("The persona's id."),
+    label: z.string().max(60).optional().describe("What to call it on screen. Absent falls back to the id, which somebody chose anyway."),
+    capabilities: z
+        .array(entryId)
+        .max(50)
+        .describe("Which connected accounts are its hands. Named individually rather than by site, because two accounts on one site is the whole problem this solves. Naming one that is not connected yet is not an error: it is a card describing an account this sandbox has still to sign into."),
+    repos: z
+        .array(z.string().min(1))
+        .max(50)
+        .optional()
+        .describe("Which repositories prefer this persona, so a conversation opened on one starts with the right choice already made. A preference rather than a fence."),
+    powers: PersonaPowersSchema.optional().describe("What a conversation wearing it may do. Absent means the full toolbox, so a card written before this existed behaves exactly as it did."),
+    workspace: PersonaWorkspaceSchema.optional().describe("Where it works. Absent means the whole workspace."),
     systemPromptMode: SystemPromptModeSchema.optional(),
 });
 export const FRONT_DESK_PERSONA = "front-desk";
@@ -1336,49 +2187,82 @@ export const personaBounds = (persona) => {
     ].filter(Boolean).length;
     return limits === 0 ? "Full powers" : `${limits} limit${limits === 1 ? "" : "s"}`;
 };
-export const PersonaIdParamSchema = z.object({ id: entryId });
+export const PersonaIdParamSchema = z.object({ id: entryId.describe("Which persona.") });
 export const PersonasListSchema = z.object({
-    personas: z.array(PersonaSchema),
-    connected: z.array(z.string()),
+    personas: z.array(PersonaSchema).describe("The characters an agent can wear."),
+    connected: z
+        .array(z.string())
+        .describe("Which accounts are actually connected right now, so a persona naming one that has since been disconnected can be shown as broken rather than as working."),
 });
 export const PersonaKitSchema = z.object({
-    prompt: z.string(),
-    skills: z.array(z.object({ name: z.string(), description: z.string() })),
+    prompt: z
+        .string()
+        .describe("What this persona is told, on top of everything else. Empty means it simply follows the sandbox's own instructions."),
+    skills: z
+        .array(z.object({
+        name: z.string().describe("The skill's name."),
+        description: z.string().describe("What it is for."),
+    }))
+        .describe("Skills only this persona's conversations can reach. A different question from what the agent knows generally, with a different answer."),
+});
+export const PersonaPromptSchema = PersonaIdParamSchema.extend({
+    prompt: z
+        .string()
+        .max(20000)
+        .describe("What to tell this persona. Sending an empty one removes it entirely rather than storing a blank, so the persona falls back to the sandbox's own instructions."),
 });
-export const PersonaPromptSchema = PersonaIdParamSchema.extend({ prompt: z.string().max(20000) });
 export const PersonaSkillSchema = PersonaIdParamSchema.extend(SkillDraftSchema.shape);
-export const PersonaSkillNameSchema = PersonaIdParamSchema.extend({ name: SkillNameSchema });
-export const PersonaSkillBodySchema = z.object({ name: z.string(), description: z.string(), body: z.string() });
+export const PersonaSkillNameSchema = PersonaIdParamSchema.extend({ name: SkillNameSchema.describe("Which skill.") });
+export const PersonaSkillBodySchema = z.object({
+    name: z.string().describe("The skill's name."),
+    description: z.string().describe("What it is for."),
+    body: z.string().describe("The skill itself, in full."),
+});
 export const CapabilityStatusSchema = z.object({
-    state: CapabilityStateSchema,
-    detail: z.string().optional(),
-    code: z.string().optional(),
+    state: CapabilityStateSchema.describe("Whether it is live, still coming up, broken, or switched off."),
+    detail: z.string().optional().describe("What is wrong, in words a person can act on."),
+    code: z.string().optional().describe("A short marker for that reason, for anything deciding what to do about it."),
 });
 export const CapabilitySummarySchema = z.object({
-    id: z.string(),
-    kind: CapabilityKindSchema,
-    status: CapabilityStatusSchema,
-    config: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
-    secrets: z.array(z.string()).default([]),
+    id: z.string().describe("The connection's id."),
+    kind: CapabilityKindSchema.describe("What sort of thing it is."),
+    status: CapabilityStatusSchema.describe("Whether it is working."),
+    config: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).describe("Its settings, minus anything secret."),
+    secrets: z
+        .array(z.string())
+        .default([])
+        .describe("Which credentials it holds, by name. The values are on one route only, and it is not this one."),
 });
 export const CapabilityRecommendationSchema = z.object({
-    card: z.string(),
-    evidence: z.string(),
-    reason: z.string(),
-    prefill: z.record(z.string(), z.string()),
+    card: z.string().describe("Which connection is being suggested."),
+    evidence: z
+        .string()
+        .describe("What was seen that prompted it: a file, a remote, printed verbatim so the claim can be checked rather than believed."),
+    reason: z.string().describe("The same claim in words, without repeating the evidence into it."),
+    prefill: z
+        .record(z.string(), z.string())
+        .describe("Settings the scan could read, to fill the form so you supply only the credential. Never a secret, even when one is sitting in a checked-in file: the suggestion points at such a file, it does not absorb what is in it."),
 });
 export const CapabilitiesListSchema = z.object({
-    capabilities: z.array(CapabilitySummarySchema),
-    recommendations: z.array(CapabilityRecommendationSchema).default([]),
+    capabilities: z.array(CapabilitySummarySchema).describe("What this sandbox is connected to."),
+    recommendations: z
+        .array(CapabilityRecommendationSchema)
+        .default([])
+        .describe("Things worth connecting, worked out from what is actually in the workspace rather than from anything you configured. Re-derived on every read, so one whose evidence has moved simply stops being suggested."),
 });
-export const CapabilityIdParamSchema = z.object({ id: z.string() });
+export const CapabilityIdParamSchema = z.object({ id: z.string().describe("Which connection.") });
 export const CapabilityConnectionSchema = z.object({
-    id: z.string(),
-    kind: z.string(),
-    config: z.record(z.string(), z.string()),
+    id: z.string().describe("The connection's id."),
+    kind: z.string().describe("What sort of thing it is."),
+    config: z
+        .record(z.string(), z.string())
+        .describe("Its settings exactly as stored, credentials included. The field names are its own kind's, which the caller already knows."),
+});
+export const CapabilityCardParamSchema = z.object({ card: z.string().describe("Which suggestion to stop making.") });
+export const CapabilitySecretInputSchema = z.object({
+    id: z.string().describe("Which connection."),
+    value: z.string().min(1).describe("The new credential. Its other settings are left alone."),
 });
-export const CapabilityCardParamSchema = z.object({ card: z.string() });
-export const CapabilitySecretInputSchema = z.object({ id: z.string(), value: z.string().min(1) });
 export const CapabilityRenameSchema = z.object({
     id: z.string(),
     to: z
@@ -1387,8 +2271,13 @@ export const CapabilityRenameSchema = z.object({
         .max(60)
         .regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/),
 });
-export const CapabilityLoginSchema = z.object({ session: z.string() });
-export const CapabilityOtpSchema = z.object({ code: z.string(), secondsRemaining: z.number() });
+export const CapabilityLoginSchema = z.object({ session: z.string().describe("The terminal the sign-in is happening in. Attach to it to type.") });
+export const CapabilityOtpSchema = z.object({
+    code: z.string().describe("The code."),
+    secondsRemaining: z
+        .number()
+        .describe("How long it lasts. Its expiring is what makes handing one to an agent safe, since the seed behind it is never revealed."),
+});
 export const HostFactsSchema = z.object({
     os: z.string(),
     arch: z.string(),
@@ -1413,37 +2302,66 @@ export const VpnStateSchema = z.enum([
     "failed",
 ]);
 export const VpnLinkSchema = z.object({
-    id: z.string(),
-    provider: VpnProviderSchema,
-    state: VpnStateSchema,
-    gateway: z.string().optional(),
-    interface: z.string().optional(),
-    address: z.string().optional(),
-    routes: z.array(z.string()).default([]),
-    dns: z.array(z.string()).default([]),
-    since: z.number().optional(),
-    autoConnect: z.boolean(),
-    detail: z.string().optional(),
+    id: z.string().describe("Which tunnel."),
+    provider: VpnProviderSchema.describe("What kind of tunnel it is."),
+    state: VpnStateSchema.describe("Whether it is up, dialling, resting, failed, or not installable yet because its client needs a rebuild to arrive."),
+    gateway: z.string().optional().describe("What it dials. For display only, and never a credential."),
+    interface: z.string().optional().describe("The network interface carrying it, once one exists."),
+    address: z
+        .string()
+        .optional()
+        .describe("The address the far end gave this sandbox, which is the single most useful answer to whether you are on the VPN."),
+    routes: z
+        .array(z.string())
+        .default([])
+        .describe("What goes through it. Everything, when the range covers the whole internet. Empty until it is up."),
+    dns: z.array(z.string()).default([]).describe("Name servers it pushed, when it pushed any."),
+    since: z.number().optional().describe("When it came up, in milliseconds. Absent unless it is."),
+    autoConnect: z.boolean().describe("Whether it dials itself when the sandbox starts."),
+    detail: z.string().optional().describe("Why it failed, or a note about a healthy one. Never a credential."),
+});
+export const VpnListSchema = z.object({
+    links: z
+        .array(VpnLinkSchema)
+        .describe("Every configured tunnel with its live state, read back from the operating system each time rather than remembered."),
+});
+export const VpnConnectInputSchema = z.object({
+    id: z.string().describe("Which tunnel to dial."),
+    otp: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A one-time code, where the gateway wants one. Supplied per dial and never stored; without it such a gateway refuses and says so."),
+});
+export const VpnIdParamSchema = z.object({ id: z.string().describe("Which tunnel.") });
+export const ForticlientImportInputSchema = z.object({
+    xml: z.string().min(1).describe("The exported configuration file, whole. Nothing is stored: it is read and thrown away."),
 });
-export const VpnListSchema = z.object({ links: z.array(VpnLinkSchema) });
-export const VpnConnectInputSchema = z.object({ id: z.string(), otp: z.string().min(1).optional() });
-export const VpnIdParamSchema = z.object({ id: z.string() });
-export const ForticlientImportInputSchema = z.object({ xml: z.string().min(1) });
 export const ForticlientConnectionSchema = z.object({
-    id: z.string(),
-    label: z.string(),
-    provider: VpnProviderSchema,
-    server: z.string(),
-    port: z.number(),
-    username: z.string().optional(),
-    description: z.string().optional(),
-    localId: z.string().optional(),
-    aggressive: z.boolean().optional(),
-    pfs: z.boolean().optional(),
-    dhGroup: z.string().optional(),
-    needs: z.array(z.string()),
-});
-export const ForticlientImportSchema = z.object({ connections: z.array(ForticlientConnectionSchema) });
+    id: z.string().describe("The id it would be added under."),
+    label: z.string().describe("Its name as the file has it, so somebody recognises the connection they are picking."),
+    provider: VpnProviderSchema.describe("What kind of tunnel it is."),
+    server: z.string().describe("Where it dials."),
+    port: z.number().describe("On which port."),
+    username: z
+        .string()
+        .optional()
+        .describe("The username, but only when the file stored it in the clear. An encrypted one is dropped rather than guessed at."),
+    description: z.string().optional().describe("Whatever the file said about it."),
+    localId: z.string().optional().describe("An identity some tunnel types need, when the file stored it readably."),
+    aggressive: z.boolean().optional().describe("Which negotiation mode it used."),
+    pfs: z.boolean().optional().describe("Whether it asked for forward secrecy."),
+    dhGroup: z
+        .string()
+        .optional()
+        .describe("Which key-exchange group it used. Together with the setting above, this is what decides whether the connection can complete at all."),
+    needs: z
+        .array(z.string())
+        .describe("What you still have to type in before it can dial. Always at least the password, because the export wraps credentials in encryption that cannot be undone here."),
+});
+export const ForticlientImportSchema = z.object({
+    connections: z.array(ForticlientConnectionSchema).describe("The connections found in the file, ready to be added one at a time."),
+});
 export const ExitStateSchema = z.enum([
     "up",
     "starting",
@@ -1452,35 +2370,50 @@ export const ExitStateSchema = z.enum([
     "failed",
 ]);
 export const ExitObservationSchema = z.object({
-    ip: z.string(),
-    country: z.string().optional(),
-    countryName: z.string().optional(),
+    ip: z.string().describe("The address the world sees, looked up through the exit's own proxy rather than assumed."),
+    country: z
+        .string()
+        .optional()
+        .describe("Which country that address is in. Absent when the lookup gave an address and no country, in which case a switch is judged on the address having changed instead."),
+    countryName: z.string().optional().describe("That country's name, spelled out."),
 });
 export const ExitPointSchema = z.object({
-    country: z.string(),
-    countryName: z.string(),
-    servers: z.number(),
-    share: z.number().optional(),
+    country: z.string().describe("The country's code."),
+    countryName: z.string().describe("Its name, spelled out."),
+    servers: z.number().describe("How many servers this provider has there."),
+    share: z
+        .number()
+        .optional()
+        .describe("How much of the provider's actual capacity is there, from zero to one. This is what a list should be sorted by: a third of the countries on offer are one overloaded machine behind a flag, and a count of servers would rank them first."),
 });
 export const ExitCountriesSchema = z.object({
-    countries: z.array(ExitPointSchema),
-    live: z.boolean(),
+    countries: z.array(ExitPointSchema).describe("Where this exit can put you, best-supplied first."),
+    live: z
+        .boolean()
+        .describe("Whether the provider answered, or this came from a built-in list. Said out loud rather than presenting an old list as current."),
 });
 export const ExitLinkSchema = z.object({
-    id: z.string(),
-    provider: ExitProviderSchema,
-    state: ExitStateSchema,
-    proxy: z.string(),
-    country: z.string().optional(),
-    observedCountry: z.string().optional(),
-    ip: z.string().optional(),
-    checkedAt: z.number().optional(),
-    interface: z.string().optional(),
-    since: z.number().optional(),
-    autoStart: z.boolean(),
-    detail: z.string().optional(),
+    id: z.string().describe("Which exit."),
+    provider: ExitProviderSchema.describe("What it runs on."),
+    state: ExitStateSchema.describe("Whether it is carrying traffic, coming up, resting, failed, or not installable yet because its client needs a rebuild to arrive."),
+    proxy: z
+        .string()
+        .describe("Where to point traffic that should go through it. Fixed per exit and unchanged by a country switch, which is what lets a long job move country halfway through without reconfiguring anything."),
+    country: z.string().optional().describe("Where it was asked to come out. Absent means the provider chose."),
+    observedCountry: z
+        .string()
+        .optional()
+        .describe("Where it actually comes out, as last checked. Kept separate from what was asked for, because those two disagreeing is the most useful fault signal this whole feature has."),
+    ip: z.string().optional().describe("The address behind that observation."),
+    checkedAt: z.number().optional().describe("When that was checked, in milliseconds, so an old reading can be shown as old."),
+    interface: z.string().optional().describe("The network interface, for the kinds that have one."),
+    since: z.number().optional().describe("When it came up, in milliseconds."),
+    autoStart: z.boolean().describe("Whether it starts itself when the sandbox does."),
+    detail: z.string().optional().describe("Why it failed, or a note about a healthy one."),
+});
+export const ExitListSchema = z.object({
+    links: z.array(ExitLinkSchema).describe("Every configured exit, with where it was asked to come out and where it actually does."),
 });
-export const ExitListSchema = z.object({ links: z.array(ExitLinkSchema) });
 export const TOR_EXIT_COUNTRIES = [
     { country: "NL", countryName: "Netherlands", servers: 607, share: 0.304 },
     { country: "DE", countryName: "Germany", servers: 415, share: 0.242 },
@@ -1514,10 +2447,25 @@ export const VPNGATE_EXIT_COUNTRIES = [
     { country: "CN", countryName: "China", servers: 1, share: 0.01 },
     { country: "BY", countryName: "Belarus", servers: 1, share: 0.01 },
 ];
-export const ExitIdParamSchema = z.object({ id: z.string() });
-export const ExitUseInputSchema = z.object({ id: z.string(), country: CountryCodeSchema.optional() });
-export const MarketplaceRequestSchema = z.object({ url: z.url(), token: z.string().min(1).optional() });
-export const MarketplaceSchema = z.object({ name: z.string(), plugins: z.array(RegistryEntrySchema) });
+export const ExitIdParamSchema = z.object({ id: z.string().describe("Which exit.") });
+export const ExitUseInputSchema = z.object({
+    id: z.string().describe("Which exit."),
+    country: CountryCodeSchema.optional().describe("Where to come out. Leaving it out means letting the provider choose, so clearing a country is something you can actually say rather than only setting one."),
+});
+export const MarketplaceRequestSchema = z.object({
+    url: z.url().describe("The registry to read."),
+    token: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A credential for a private one. Sent as a body rather than in the address, so it never lands in a log."),
+});
+export const MarketplaceSchema = z.object({
+    name: z.string().describe("What the registry calls itself."),
+    plugins: z
+        .array(RegistryEntrySchema)
+        .describe("What it lists, each with the curated decision, the resolved pointer and what a scan found upstream."),
+});
 const extensionId = z
     .string()
     .min(1)
@@ -1528,100 +2476,189 @@ export const ExtensionUpdatePolicySchema = z.object({
     advisories: z.enum(["auto-disable", "notify"]),
 });
 export const ExtensionUpdateSchema = z.object({
-    ref: z.string(),
-    version: z.string().optional(),
-    url: z.string(),
-    path: z.string().optional(),
-    trust: z.enum(["verified", "listed"]),
-    securityFix: z.boolean().optional(),
-    registry: z.string(),
-    at: z.string(),
-    needsReview: z.string().optional(),
-    review: z.object({ conversationId: z.string(), at: z.string() }).optional(),
+    ref: z.string().describe("The commit being offered."),
+    version: z.string().optional().describe("What it calls itself."),
+    url: z.string().describe("Where it comes from."),
+    path: z.string().optional().describe("Where inside that repository it lives."),
+    trust: z.enum(["verified", "listed"]).describe("Whether anybody vouched for it, or it is merely listed."),
+    securityFix: z
+        .boolean()
+        .optional()
+        .describe("This release fixes a security problem in earlier ones, so here the old version is the dangerous one."),
+    registry: z.string().describe("Which registry said so."),
+    at: z.string().describe("When it was published."),
+    needsReview: z
+        .string()
+        .optional()
+        .describe("Why this one was not taken automatically and is asking for a person instead: it wants more than it used to, or nobody has vouched for it."),
+    review: z
+        .object({
+        conversationId: z.string().describe("Where to read what it found."),
+        at: z.string().describe("When it looked."),
+    })
+        .optional()
+        .describe("An agent has already read the difference between what is installed and this, so the card can link to what it found rather than offer to start looking."),
 });
 export const ExtensionAdvisorySchema = z.object({
-    reason: z.string(),
-    registry: z.string(),
-    at: z.string(),
-    autoDisabled: z.boolean(),
+    reason: z
+        .string()
+        .describe("Why the registry pulled the listing, in its own words. Delisting protects people browsing; this record is for the person already running it."),
+    registry: z.string().describe("Which registry said so."),
+    at: z.string().describe("When."),
+    autoDisabled: z.boolean().describe("Whether the sandbox has already switched it off."),
 });
 export const ExtensionHealthSchema = z.object({
-    state: z.enum(["watching", "healthy", "unhealthy"]),
-    detail: z.string().optional(),
-    fromRef: z.string().optional(),
-    at: z.string(),
-    autoReverted: z.boolean().optional(),
+    state: z
+        .enum(["watching", "healthy", "unhealthy"])
+        .describe("How it has behaved since the last update. Checks catch broken, not wrong, so for a while after a swap it is simply watched."),
+    detail: z.string().optional().describe("What is going wrong, when something is."),
+    fromRef: z.string().optional().describe("Which version it was updated from, which is what going back would return to."),
+    at: z.string().describe("When the watching started."),
+    autoReverted: z
+        .boolean()
+        .optional()
+        .describe("The update was already rolled back without anybody asking. The record stays rather than pretending the attempt never happened."),
+});
+export const PowersDiffSchema = z.object({
+    added: z.array(z.string()).describe("What the new version asks for that the running one does not. The whole point of the comparison."),
+    removed: z.array(z.string()).describe("What it no longer asks for."),
+    unchanged: z.array(z.string()).describe("What stays the same."),
 });
-export const PowersDiffSchema = z.object({ added: z.array(z.string()), removed: z.array(z.string()), unchanged: z.array(z.string()) });
 export const ExtensionUpdateActionSchema = z.object({
-    id: extensionId,
+    id: extensionId.describe("Which extension."),
     ref: z
         .string()
         .regex(/^[0-9a-f]{40}$/)
-        .optional(),
+        .optional()
+        .describe("Which commit, in full. Leave it out for whatever the last check found, which is what most callers mean."),
 });
 export const ExtensionUpdatePreviewSchema = z.object({
-    ref: z.string(),
-    version: z.string(),
-    installedVersion: z.string(),
-    engines: z.string(),
-    compatible: z.boolean(),
-    powers: PowersDiffSchema,
-});
-export const ExtensionUpdateAppliedSchema = z.object({ ok: z.literal(true), ref: z.string(), rebuildNeeded: z.boolean().optional() });
+    ref: z.string().describe("The commit this would install."),
+    version: z.string().describe("What that version calls itself."),
+    installedVersion: z.string().describe("What is running now."),
+    engines: z.string().describe("Which sandbox versions the new one says it needs."),
+    compatible: z.boolean().describe("Whether this sandbox is one of them."),
+    powers: PowersDiffSchema.describe("Exactly what the new code asks for that the running one does not. This is what approving an update is approving."),
+});
+export const ExtensionUpdateAppliedSchema = z.object({
+    ok: z.literal(true).describe("It went through."),
+    ref: z.string().describe("Which commit is now running."),
+    rebuildNeeded: z
+        .boolean()
+        .optional()
+        .describe("The new version changes what the sandbox image contains, so a one-time rebuild is still pending and the update is not wholly landed yet."),
+});
 export const ExtensionUpdatePolicyInputSchema = z.object({
-    id: extensionId,
-    updates: z.enum(["notify", "agent", "auto"]).optional(),
-    advisories: z.enum(["auto-disable", "notify"]).optional(),
+    id: extensionId.describe("Which extension."),
+    updates: z
+        .enum(["notify", "agent", "auto"])
+        .optional()
+        .describe("What to do about a newer version: tell you, have an agent read the difference first, or just take it."),
+    advisories: z.enum(["auto-disable", "notify"]).optional().describe("What to do about a security warning: switch it off at once, or tell you."),
+});
+export const ExtensionUpdatesCheckedSchema = z.object({
+    ok: z.literal(true).describe("The check ran."),
+    checkedAt: z.string().describe("When, so a screen can date the answer."),
 });
-export const ExtensionUpdatesCheckedSchema = z.object({ ok: z.literal(true), checkedAt: z.string() });
 export const ExtensionSummarySchema = z.object({
-    id: extensionId,
-    manifest: ExtensionManifestSchema,
-    commit: z.string(),
-    source: z.enum(["builtin", "installed", "workspace"]),
-    enabled: z.boolean(),
-    essential: z.boolean().optional(),
-    usage: z.record(z.string(), z.object({ calls: z.number().int().nonnegative(), last: z.string() })).optional(),
+    id: extensionId.describe("The extension's id."),
+    manifest: ExtensionManifestSchema.describe("What it declares about itself: what it contributes, what it needs, and what it may reach."),
+    commit: z.string().describe("Exactly which commit is installed."),
+    source: z
+        .enum(["builtin", "installed", "workspace"])
+        .describe("Where the code comes from: baked into the sandbox image and not removable, installed from a repository at a pinned commit, or written in this workspace and edited in place."),
+    enabled: z
+        .boolean()
+        .describe("The owner's switch. A switched-off extension is still listed, which is what makes it switchable back on, but nothing it contributes is wired up."),
+    essential: z
+        .boolean()
+        .optional()
+        .describe("Its switch is fixed on, because it is the only way to see or stop an engine the sandbox runs regardless. Hiding that page would not stop the spending, only your ability to notice it. Declared by the core about its own surfaces, never by an extension about itself, which would be a pack making itself un-removable."),
+    usage: z
+        .record(z.string(), z.object({ calls: z.number().int().nonnegative().describe("How many times."), last: z.string().describe("When, most recently.") }))
+        .optional()
+        .describe("How much of the reach it asked for it has actually used, keyed by what it declared. Absent means never observed doing anything, which is a different claim from uses none of them, and the two have to stay tellable apart: reading either as these permissions are unnecessary turns evidence into a guess with a number on it."),
     backend: z
         .object({
-        state: z.enum(["running", "error", "absent", "incompatible", "starting", "stopped"]),
-        detail: z.string().optional(),
+        state: z
+            .enum(["running", "error", "absent", "incompatible", "starting", "stopped"])
+            .describe("How its server half is doing. Absent means the code is not in this image at all; incompatible means it needs a different sandbox version."),
+        detail: z
+            .string()
+            .optional()
+            .describe("What went wrong, so a backend that failed to start is a sentence rather than an address that answers nothing."),
     })
-        .optional(),
-    update: ExtensionUpdateSchema.optional(),
-    advisory: ExtensionAdvisorySchema.optional(),
-    health: ExtensionHealthSchema.optional(),
-    previous: z.object({ ref: z.string(), version: z.string().optional() }).optional(),
-    updatePolicy: ExtensionUpdatePolicySchema.optional(),
+        .optional()
+        .describe("Present only for an extension that ships a server half."),
+    update: ExtensionUpdateSchema.optional().describe("A newer version waiting. All five of these exist only for one installed from a repository: a built-in updates with the image and one written here is edited live."),
+    advisory: ExtensionAdvisorySchema.optional().describe("A security warning about the installed version."),
+    health: ExtensionHealthSchema.optional().describe("How it has behaved since the last update, which is what decides whether that update sticks."),
+    previous: z
+        .object({
+        ref: z.string().describe("The commit that was running before."),
+        version: z.string().optional().describe("What it called itself."),
+    })
+        .optional()
+        .describe("The version kept one step back, which is what going back means."),
+    updatePolicy: ExtensionUpdatePolicySchema.optional().describe("The owner's standing answer for this one: tell me, have an agent look, or just do it."),
+});
+export const InvalidWorkspaceExtensionSchema = z.object({
+    dir: z.string().describe("Which folder."),
+    error: z.string().describe("Why it could not be read."),
 });
-export const InvalidWorkspaceExtensionSchema = z.object({ dir: z.string(), error: z.string() });
 export const ExtensionsListSchema = z.object({
-    extensions: z.array(ExtensionSummarySchema),
-    invalid: z.array(InvalidWorkspaceExtensionSchema),
-    updatesCheckedAt: z.string().optional(),
+    extensions: z.array(ExtensionSummarySchema).describe("What is installed."),
+    invalid: z
+        .array(InvalidWorkspaceExtensionSchema)
+        .describe("Extensions written here that could not be read at all. Listed rather than dropped, because there is no install moment at which to reject a broken one, so this is its only way of saying anything."),
+    updatesCheckedAt: z
+        .string()
+        .optional()
+        .describe("When updates were last looked for. Absent until the first check has run. Sent so a screen can say checked an hour ago rather than presenting staleness as certainty."),
 });
 export const ExtensionSettingsSchema = z.object({
-    settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
-    secretsSet: z.array(z.string()),
+    settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).describe("The values, minus anything marked secret."),
+    secretsSet: z
+        .array(z.string())
+        .describe("Which of its secret settings actually hold a value. Names only: the values themselves never come back."),
 });
 export const ExtensionSettingsInputSchema = z.object({
-    id: z.string(),
-    settings: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
+    id: z.string().describe("Which extension."),
+    settings: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+        .describe("The values to write. A key the extension never declared is refused rather than quietly stored."),
+});
+export const ExtensionEnabledInputSchema = z.object({
+    id: z.string().describe("Which extension."),
+    enabled: z.boolean().describe("On or off."),
 });
-export const ExtensionEnabledInputSchema = z.object({ id: z.string(), enabled: z.boolean() });
 export const WorkspaceExtensionCreateSchema = z.object({
-    publisher: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
-    name: z.string().regex(/^[a-z0-9][a-z0-9-]*$/),
+    publisher: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/)
+        .describe("Who it is by, which together with the name makes its id."),
+    name: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/)
+        .describe("What it is called."),
+});
+export const WorkspaceExtensionCreatedSchema = z.object({
+    id: z.string().describe("The id it was given."),
+    dir: z.string().describe("Where its files are, so you can open them."),
+});
+export const ExtensionUsageInputSchema = z.object({
+    id: z.string().describe("Which extension."),
+    used: z.record(z.string(), z.number().int().positive()).describe("Which of its declared powers it exercised, and how many times."),
+});
+export const ExtensionProcessParamSchema = z.object({
+    id: z.string().describe("Which extension."),
+    name: z.string().describe("Which of its declared processes."),
 });
-export const WorkspaceExtensionCreatedSchema = z.object({ id: z.string(), dir: z.string() });
-export const ExtensionUsageInputSchema = z.object({ id: z.string(), used: z.record(z.string(), z.number().int().positive()) });
-export const ExtensionProcessParamSchema = z.object({ id: z.string(), name: z.string() });
 export const ExtensionProcessStatusSchema = z.object({
-    name: z.string(),
-    running: z.boolean(),
-    port: z.number().optional(),
-    previewUrl: z.string().optional(),
+    name: z.string().describe("Which process."),
+    running: z.boolean().describe("Whether it is up."),
+    port: z.number().optional().describe("The port it was given."),
+    previewUrl: z.string().optional().describe("Where to open it, when it has an address."),
 });
 export const WorkspaceEventKindSchema = z.enum(["turn.settled", "agent.landed", "deps.broken", "deps.fixed"]);
 export const WorkspaceEventSchema = z.object({
@@ -1642,26 +2679,56 @@ export const WorkspaceEventSchema = z.object({
         .optional(),
 });
 export const TriggerSchema = z.discriminatedUnion("kind", [
-    z.object({ kind: z.literal("schedule"), cron: z.string().min(1) }),
-    z.object({ kind: z.literal("event"), token: z.string().min(1).optional() }),
     z.object({
-        kind: z.literal("listener"),
-        provider: z.string().min(1),
-        channelId: z.string().min(1).optional(),
-        eventType: z.string().min(1).optional(),
-        mentioned: z.boolean().optional(),
-        branch: z.string().min(1).optional(),
-        allowedOrigins: z.array(z.string()).optional(),
+        kind: z.literal("schedule").describe("On a clock."),
+        cron: z.string().min(1).describe("When, in cron notation."),
+    }),
+    z.object({
+        kind: z.literal("event").describe("When something calls its webhook."),
+        token: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The credential a caller presents. It is the only one in the exchange, because an outside sender has no identity here."),
+    }),
+    z.object({
+        kind: z.literal("listener").describe("When a message arrives from somewhere outside."),
+        provider: z.string().min(1).describe("Which service to listen to."),
+        channelId: z.string().min(1).optional().describe("Narrow it to one channel or thread."),
+        eventType: z.string().min(1).optional().describe("Narrow it to one kind of event."),
+        mentioned: z.boolean().optional().describe("Only when the agent is actually addressed, rather than on everything said in earshot."),
+        branch: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Narrow it to one branch, for the sources that have branches. Absent means every branch of the repositories it matches."),
+        allowedOrigins: z.array(z.string()).optional().describe("Which websites may reach the chat widget. Absent or empty admits nobody."),
+    }),
+    z.object({
+        kind: z.literal("workspace").describe("When something happens to the files or the repositories."),
+        event: WorkspaceEventKindSchema.describe("Which happening."),
+        repo: z.string().min(1).optional().describe("Narrow it to one repository. Absent means any of them."),
     }),
-    z.object({ kind: z.literal("workspace"), event: WorkspaceEventKindSchema, repo: z.string().min(1).optional() }),
 ]);
 export const WebchatConfigSchema = z.object({
-    access: z.enum(["public", "google"]).optional(),
-    requireName: z.boolean().optional(),
-    antiBot: z.enum(["turnstile", "pow"]).optional(),
-    turnstileSiteKey: z.string().optional(),
-    turnstileSecret: z.string().optional(),
-    googleClientId: z.string().optional(),
+    access: z
+        .enum(["public", "google"])
+        .optional()
+        .describe("Who may write to it. Absent means anyone, which is the anonymous support box it looks like."),
+    requireName: z
+        .boolean()
+        .optional()
+        .describe("Ask a visitor for a name first. Cosmetic: the name is typed, so it reaches the model as something a stranger said, never as identity."),
+    antiBot: z
+        .enum(["turnstile", "pow"])
+        .optional()
+        .describe("How to keep bots out: a third-party check that needs the site's own keys, or a puzzle the sandbox sets and the widget solves, so a site with no such account still has something. Absent leaves the site allowlist and the rate limit as the whole boundary."),
+    turnstileSiteKey: z.string().optional().describe("The public half of those keys, which ships to the visitor's browser."),
+    turnstileSecret: z.string().optional().describe("The private half, which the sandbox keeps and the widget never sees."),
+    googleClientId: z
+        .string()
+        .optional()
+        .describe("The site's own sign-in client id. It cannot be ours: a sign-in is only issued to an approved origin, and no single client can list every customer's domain."),
     title: z.string().max(80).optional(),
     greeting: z.string().max(500).optional(),
     accent: z
@@ -1700,40 +2767,64 @@ export const WebchatMessageSchema = z.object({
         .optional(),
 });
 export const AutomationSchema = z.object({
-    id: entryId,
-    trigger: TriggerSchema,
-    guard: z.string().min(1).optional(),
-    prompt: z.string().min(1),
-    webchat: WebchatConfigSchema.optional(),
-    allowedTools: z.array(z.string().min(1)).optional(),
-    agent: AgentProviderSchema.optional(),
-    account: z.string().optional(),
-    actsAs: entryId.optional(),
-    harness: AgentHarnessSchema.optional(),
-    model: z.string().optional(),
-    requireApproval: z.boolean().optional(),
-    holdForSeconds: z.number().optional(),
-    chore: z.boolean().optional(),
-    enabled: z.boolean(),
+    id: entryId.describe("The automation's id."),
+    trigger: TriggerSchema.describe("What sets it off: a schedule, an event in the workspace, a message arriving from outside, or a webhook."),
+    guard: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("A command run before the wake that decides whether there is anything to do. Skipped by the guard is often the most useful thing an automation can report."),
+    prompt: z.string().min(1).describe("What the woken agent is told."),
+    webchat: WebchatConfigSchema.optional().describe("Settings for the public chat widget, for an automation that answers visitors."),
+    allowedTools: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Narrow the woken turn to these tools. For one driven by an outside message this list is the real boundary, because prompt wording is only advice and an empty toolbox is not."),
+    agent: AgentProviderSchema.optional().describe("Which provider serves the wake."),
+    account: z.string().optional().describe("Which account pays for it."),
+    actsAs: entryId.optional().describe("Which persona it speaks as. An unwatched turn naming none reaches no signed-in account at all."),
+    harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it."),
+    model: z.string().optional().describe("Which model runs it."),
+    requireApproval: z.boolean().optional().describe("Hold every fire for a person instead of running it. Only a person can release one of those."),
+    holdForSeconds: z.number().optional().describe("Hold each fire this long before running it anyway, which is a delay rather than a decision."),
+    chore: z
+        .boolean()
+        .optional()
+        .describe("This automation is a maintenance job, which is what files it under chores rather than among ordinary automations."),
+    enabled: z.boolean().describe("Whether it fires at all."),
 });
 export const AutomationApprovalSchema = z.object({
-    id: entryId,
-    automationId: z.string(),
-    payload: z.string().optional(),
-    origin: AgentOriginSchema.optional(),
-    title: z.string().optional(),
-    conversationId: z.string().optional(),
-    sessionId: z.string().optional(),
-    createdAt: z.number(),
-    autoRunAt: z.number().optional(),
+    id: entryId.describe("This waiting item's own id, which approving and rejecting take."),
+    automationId: z.string().describe("Which automation it came from."),
+    payload: z
+        .string()
+        .optional()
+        .describe("What set it off, kept whole so an approved wake carries the same thing it would have had. Absent for one on a schedule, which carries nothing."),
+    origin: AgentOriginSchema.optional().describe("Where the message came from, kept alongside the payload so an approved wake appears on the board exactly as an automatic one would have."),
+    title: z.string().optional().describe("What the conversation would be called."),
+    conversationId: z
+        .string()
+        .optional()
+        .describe("The thread this belongs to, when it has one, so approving continues that conversation rather than opening a new one. Without it, one visitor's chat becomes a card per approved message and an agent that meets them again every turn."),
+    sessionId: z.string().optional().describe("The provider session that thread last ran on."),
+    createdAt: z.number().describe("When it started waiting, in milliseconds."),
+    autoRunAt: z
+        .number()
+        .optional()
+        .describe("When it goes ahead on its own, in milliseconds, for a hold that is only a delay. Absent for one that genuinely waits on a person."),
 });
 export const AgentsListSchema = z.object({
-    agents: z.array(AgentSummarySchema),
-    rev: z.number(),
-    held: z.array(AutomationApprovalSchema).default([]),
-});
-export const AutomationApprovalsListSchema = z.object({ approvals: z.array(AutomationApprovalSchema) });
-export const AutomationApprovalIdParamSchema = z.object({ id: z.string() });
+    agents: z.array(AgentSummarySchema).describe("The conversations."),
+    rev: z
+        .number()
+        .describe("Which version of the fleet this is. The fleet is published as whole snapshots, so without a version a list read before a change but delivered after it would silently undo that change. Drop any list older than the newest you have already applied."),
+    held: z
+        .array(AutomationApprovalSchema)
+        .default([])
+        .describe("Automations waiting at the door for a yes, put alongside the running conversations so needs-you sits beside working rather than on a page nobody opens."),
+});
+export const AutomationApprovalsListSchema = z.object({ approvals: z.array(AutomationApprovalSchema).describe("Everything waiting for a yes.") });
+export const AutomationApprovalIdParamSchema = z.object({ id: z.string().describe("Which waiting item.") });
 export const AutomationRunSchema = z.object({
     at: z.number(),
     outcome: z.enum(["completed", "skipped", "error", "interrupted"]),
@@ -1790,197 +2881,379 @@ const StepIdSchema = z
 export const WorkflowHandoffSchema = z.enum(["fresh", "continue"]);
 const WORKFLOW_STEPS_MAX = 24;
 export const WorkflowStepSchema = z.object({
-    id: StepIdSchema,
-    title: z.string().min(1).max(60),
-    goal: z.string().min(1).optional(),
-    prompt: z.string().min(1).optional(),
-    needs: z.array(StepIdSchema),
-    handoff: WorkflowHandoffSchema,
-    output: LoopOutputSchema,
-    checks: z.array(LoopCheckSchema),
-    context: LoopContextSchema,
-    maxSpendUsd: z.number().positive().optional(),
-    agent: AgentProviderSchema.optional(),
-    harness: AgentHarnessSchema.optional(),
-    account: z.string().optional(),
-    model: z.string().optional(),
-    actsAs: entryId.optional(),
+    id: StepIdSchema.describe("This step's own name, which other steps use to say they wait on it."),
+    title: z.string().min(1).max(60).describe("What to call it on screen. Short: the instruction below is where the detail goes."),
+    goal: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("What done means for this step, in your words. It is what the step is judged against, and a different sentence from what it is told to do."),
+    prompt: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("What the step is told to do. The goal is the suite is green; this is run the tests, take the top failure, fix it. Leaving it out hands over the run's own request untouched, which is right for a step whose whole job is do what was asked."),
+    needs: z
+        .array(StepIdSchema)
+        .describe("Which steps must finish first. Empty means it starts when the run does. Naming a step that does not exist, or a loop between steps, is refused when the workflow is saved."),
+    handoff: WorkflowHandoffSchema.describe("How it meets what came before: a fresh conversation handed the previous step's result, or the same conversation carried on."),
+    output: LoopOutputSchema.describe("What it has to produce for the step to count."),
+    checks: z.array(LoopCheckSchema).describe("What has to pass before it counts as done."),
+    context: LoopContextSchema.describe("How the step's own repeats meet each other. A long-running step wants to start clean each round; a short polish-this step wants to carry on."),
+    maxSpendUsd: z
+        .number()
+        .positive()
+        .optional()
+        .describe("A ceiling on what this step may spend. The one resource that cannot be recovered after an unattended fan-out, which is why it is here and iteration limits are not. Absent is uncapped."),
+    agent: AgentProviderSchema.optional().describe("Which provider runs it."),
+    harness: AgentHarnessSchema.optional().describe("Which agentic loop runs it."),
+    account: z.string().optional().describe("Which account pays for it."),
+    model: z.string().optional().describe("Which model runs it."),
+    actsAs: entryId
+        .optional()
+        .describe("Which persona it acts as. Unpinned, a step gets the strict unwatched default: every tool, and no signed-in accounts at all. Pinning one is how a release check gets a voice, a folder to work in, or the single account it may post from."),
 });
 export const WorkflowGateSchema = z.object({
-    step: StepIdSchema,
-    field: z.string().min(1),
-    pass: z.array(z.string().min(1)).min(1),
-    token: z.string().optional(),
-    dailyMax: z.number().int().positive().optional(),
+    step: StepIdSchema.describe("Which step's answer carries the decision. Usually a last step that weighs up the ones before it, though nothing requires that."),
+    field: z
+        .string()
+        .min(1)
+        .describe("Which of that step's declared answers to read. A declared field is the one part of a step's answer that was checked rather than fished out of prose, which is the whole rule here. Checked when the workflow is saved."),
+    pass: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("Which values mean ship it. Everything else fails. A list of what passes rather than what fails, because a step answering mostly-pass or pass-with-notes must not ship, and this gets that right without anybody having had to enumerate the ways a model can hedge."),
+    token: z
+        .string()
+        .optional()
+        .describe("The credential the calling pipeline presents. It is the only one in the exchange, because a build runner has no identity of its own here."),
+    dailyMax: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("How many runs a day, across every caller. A gate is a paid door with nobody in the loop: one wired into a push-triggered pipeline is a fan-out of conversations per commit. Absent is a small default rather than unlimited."),
 });
 export const GATE_DAILY_MAX_DEFAULT = 20;
 export const GateOutcomeSchema = z.enum(["pass", "fail", "blocked"]);
 export const GateVerdictSchema = z.object({
-    outcome: GateOutcomeSchema,
-    reason: z.string(),
-    runId: z.string(),
-    value: z.string().optional(),
+    outcome: GateOutcomeSchema.describe("Ship it, do not, or we could not tell. That third answer exists because could not reach a judgement is not the product is broken: a gate that reported its own outages as failures is one a team switches off, so it should be the honest answer far more often than the convenient one, and it means a neutral build rather than a red one."),
+    reason: z.string().describe("Why, in one line. Realistically the only part of this a build log will ever show."),
+    runId: z.string().describe("The run behind the verdict, so somebody can go and read it."),
+    value: z
+        .string()
+        .optional()
+        .describe("What the step actually answered. Absent when there was nothing to read, which is most of the could-not-tell cases."),
 });
 export const WorkflowSchema = z.object({
-    id: entryId,
-    name: z.string().min(1).max(80),
-    description: z.string().max(400).optional(),
-    steps: z.array(WorkflowStepSchema).min(1).max(WORKFLOW_STEPS_MAX),
-    gate: WorkflowGateSchema.optional(),
-    maxParallel: z.number().int().min(1).max(8),
+    id: entryId.describe("The workflow's id."),
+    name: z.string().min(1).max(80).describe("What to call it."),
+    description: z.string().max(400).optional().describe("What it is for."),
+    steps: z
+        .array(WorkflowStepSchema)
+        .min(1)
+        .max(WORKFLOW_STEPS_MAX)
+        .describe("The steps, each with what it waits on. Every one runs in its own private copy of the repos, always, because parallel steps sharing a tree collide."),
+    gate: WorkflowGateSchema.optional().describe("Present means a machine can run this design and get a ship-it answer back. Absent means an ordinary workflow, started by a person, with no outside door onto it at all."),
+    maxParallel: z
+        .number()
+        .int()
+        .min(1)
+        .max(8)
+        .describe("How many steps may run at once. Bounded, because a fan-out of twelve is twelve model sessions, twelve working copies and twelve times the burn rate, on one machine."),
 });
 export const WorkflowStepStateSchema = z.enum(["pending", "running", "done", "failed", "skipped", "stopped"]);
 export const WorkflowStepRunSchema = z.object({
-    stepId: StepIdSchema,
-    state: WorkflowStepStateSchema,
-    conversationId: z.string(),
-    startedAt: z.number().optional(),
-    endedAt: z.number().optional(),
-    iterations: z.number().int().min(0),
-    costUsd: z.number().optional(),
-    loopState: LoopStateSchema.optional(),
-    detail: z.string().optional(),
-    document: LoopDocumentSchema.optional(),
-    report: z.string().optional(),
-    reportPath: z.string().optional(),
+    stepId: StepIdSchema.describe("Which step this is."),
+    state: WorkflowStepStateSchema.describe("How it went. Skipped carries what the others cannot: it never ran, because something it was waiting on did not finish. That is why a failed run shows one red step and a trail of grey ones."),
+    conversationId: z
+        .string()
+        .describe("The conversation it ran on, and the way from a node on the graph to a real record. Shared with the step before it when they were chained, which is what makes those two one card."),
+    startedAt: z.number().optional().describe("When it began, in milliseconds."),
+    endedAt: z.number().optional().describe("When it ended, in milliseconds."),
+    iterations: z.number().int().min(0).describe("How many rounds it took."),
+    costUsd: z.number().optional().describe("What it cost, in dollars."),
+    loopState: LoopStateSchema.optional().describe("How its repeating ended. Out of rounds and stuck both come out as a failed step, and the difference between them is the difference between give it more room and more room will not help."),
+    detail: z.string().optional().describe("What went wrong, when something did."),
+    document: LoopDocumentSchema.optional().describe("What it produced, once it has produced something that passes its own declared shape. This is what the steps after it are handed."),
+    report: z
+        .string()
+        .optional()
+        .describe("The start of its closing words. Bounded, so a long answer is not silently cut down to its last few thousand characters and the record stays a sensible size."),
+    reportPath: z
+        .string()
+        .optional()
+        .describe("Where the whole answer is, as a workspace path. Every step can read it, so a long handoff need not be copied into anybody's prompt."),
 });
 export const WorkflowRunStateSchema = z.enum(["running", "done", "failed", "stopped", "overspent", "error"]);
 export const WorkflowRunSchema = z.object({
-    runId: z.string().min(1),
-    workflow: WorkflowSchema,
-    repos: z.array(RepoBaseSchema).min(1).max(50),
-    request: z.string().optional(),
-    state: WorkflowRunStateSchema,
-    startedAt: z.number(),
-    endedAt: z.number().optional(),
-    resumed: z.number().int().min(0),
-    detail: z.string().optional(),
-    steps: z.array(WorkflowStepRunSchema),
-    archivedAt: z.number().optional(),
-});
-export const WorkflowSummarySchema = WorkflowSchema.extend({ runs: z.array(WorkflowRunSchema) });
-export const WorkflowsListSchema = z.object({ workflows: z.array(WorkflowSummarySchema) });
-export const WorkflowRunsListSchema = z.object({ runs: z.array(WorkflowRunSchema) });
-export const WorkflowIdParamSchema = z.object({ id: z.string() });
-export const WorkflowRunIdParamSchema = z.object({ runId: z.string() });
-export const WorkflowRunStartSchema = WorkflowIdParamSchema.extend({ request: z.string().min(1).max(20_000).optional() });
-export const WorkflowSaveSchema = z.object({ workflow: WorkflowSchema, create: z.boolean() });
+    runId: z.string().min(1).describe("This run's id."),
+    workflow: WorkflowSchema.describe("The design as it stood when the run started, copied rather than looked up. The run has to keep showing the graph it actually ran, not the one edited twice since, and a run of a deleted workflow has to stay readable."),
+    repos: z
+        .array(RepoBaseSchema)
+        .min(1)
+        .max(50)
+        .describe("The workspace as this run began, one exact commit per repository. Every step branches from these, even if the shared tree moves while a wide fan-out is still opening its copies, so the steps can be compared with each other afterwards."),
+    request: z
+        .string()
+        .optional()
+        .describe("What this run was asked to do, handed to every step on top of its own instructions. It is what makes one saved design worth keeping: two models, one task is a shape, and the task is different every time. Absent for a run started with nowhere to type one."),
+    state: WorkflowRunStateSchema.describe("How the run is going. Finished means every step that ran got there; a run with skipped steps counts as failed, because a graph that never reached its end did not do what it was asked whatever the survivors managed."),
+    startedAt: z.number().describe("When it began, in milliseconds."),
+    endedAt: z.number().optional().describe("When it ended, in milliseconds."),
+    resumed: z.number().int().min(0).describe("How many times the sandbox restarted under it and picked it back up."),
+    detail: z.string().optional().describe("What went wrong, when something did."),
+    steps: z
+        .array(WorkflowStepRunSchema)
+        .describe("One entry per step, in the design's own order. Every one is written down as waiting when the run starts, so the picture is complete from the first frame and a missing step never has to mean two things."),
+    archivedAt: z
+        .number()
+        .optional()
+        .describe("When it was put away, in milliseconds. The record stays readable and every step's branch, transcript and counters are untouched. Its conversations are put away with it, and brought back with it. Absent means live on the board."),
+});
+export const WorkflowSummarySchema = WorkflowSchema.extend({ runs: z.array(WorkflowRunSchema).describe("Its runs, newest first.") });
+export const WorkflowsListSchema = z.object({ workflows: z.array(WorkflowSummarySchema).describe("Every saved design with its own run history.") });
+export const WorkflowRunsListSchema = z.object({
+    runs: z.array(WorkflowRunSchema).describe("Every run across every workflow, newest first, including runs of workflows since deleted."),
+});
+export const WorkflowIdParamSchema = z.object({ id: z.string().describe("Which workflow.") });
+export const WorkflowRunIdParamSchema = z.object({ runId: z.string().describe("Which run.") });
+export const WorkflowRunStartSchema = WorkflowIdParamSchema.extend({
+    request: z
+        .string()
+        .min(1)
+        .max(20_000)
+        .optional()
+        .describe("What to point it at. Optional, because a design whose steps already say what they want is complete on its own; only one written as a shape needs today's sentence."),
+});
+export const WorkflowSaveSchema = z.object({
+    workflow: WorkflowSchema.describe("The design to write."),
+    create: z
+        .boolean()
+        .describe("Whether you mean to make a new one or replace an existing one. Said outright rather than inferred, so an id that happens to collide is a refusal instead of one saved design quietly overwriting another."),
+});
 export const CiHostSchema = z.enum(["github", "gitlab"]);
 export const PipelineStatusSchema = z.enum(["running", "success", "failed", "canceled", "skipped"]);
 export const PipelineRunSchema = z.object({
-    repo: z.string(),
-    host: CiHostSchema,
-    project: z.string(),
-    runId: z.number(),
-    title: z.string().optional(),
-    authorName: z.string().optional(),
-    authorAvatarUrl: z.string().optional(),
-    trigger: z.string().optional(),
-    branch: z.string(),
-    sha: z.string(),
-    status: PipelineStatusSchema,
-    url: z.string(),
-    createdAt: z.number(),
-    durationSeconds: z.number().optional(),
-    failedJobs: z.array(z.string()).optional(),
+    repo: z.string().describe("Which workspace repository it belongs to."),
+    host: CiHostSchema.describe("Which forge is running it."),
+    project: z.string().describe("The project there, as that forge names it."),
+    runId: z.number().describe("The forge's own id for the run, which is what re-running and cancelling take."),
+    title: z
+        .string()
+        .optional()
+        .describe("The run's headline, usually the commit subject or the pull request's title. Absent means falling back to the branch and commit."),
+    authorName: z.string().optional().describe("Who the forge credits for setting it off."),
+    authorAvatarUrl: z.string().optional().describe("Their picture, hosted by the forge. Absent means drawing their initials instead."),
+    trigger: z
+        .string()
+        .optional()
+        .describe("What set it off, in the forge's own word rather than flattened into a shared vocabulary, because the forge's word is the precise one."),
+    branch: z.string().describe("Which branch."),
+    sha: z.string().describe("Which commit."),
+    status: PipelineStatusSchema.describe("How it is going. Running covers everything still moving, since the only distinction that matters is that against the three ways it can stop."),
+    url: z.string().describe("Its page on the forge."),
+    createdAt: z.number().describe("When it started, in milliseconds."),
+    durationSeconds: z.number().optional().describe("How long it took."),
+    failedJobs: z
+        .array(z.string())
+        .optional()
+        .describe("What broke, by name. Fetched only for failed runs, so that a notification or a screen can say what went wrong rather than just that something did."),
 });
 export const PipelineJobSchema = z.object({
-    name: z.string(),
-    status: PipelineStatusSchema,
-    stage: z.string().optional(),
-    needs: z.array(z.string()).optional(),
-    startedAt: z.number().optional(),
-    finishedAt: z.number().optional(),
-    durationSeconds: z.number().optional(),
-    webUrl: z.string().optional(),
+    name: z.string().describe("The job's name."),
+    status: PipelineStatusSchema.describe("How it went."),
+    stage: z.string().optional().describe("Which stage it belongs to, where the pipeline groups its jobs that way."),
+    needs: z
+        .array(z.string())
+        .optional()
+        .describe("Which jobs in this run it declared it waits on: the real shape of the pipeline. Absent means nothing could be read, which is different from an empty list, which is the claim that it waits on nothing."),
+    startedAt: z.number().optional().describe("When it began, in milliseconds. Absent while it is queued."),
+    finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
+    durationSeconds: z.number().optional().describe("How long it took."),
+    webUrl: z.string().optional().describe("Its page on the forge, which is the shortest path from this step failed to the log that says why."),
 });
 export const CiJobsResponseSchema = z.object({
-    jobs: z.array(PipelineJobSchema),
+    jobs: z.array(PipelineJobSchema).describe("The steps inside one run. Fetched separately from the run list, so that list stays cheap."),
 });
 export const CiRepoSchema = z.object({
-    repo: z.string(),
-    host: CiHostSchema,
-    project: z.string(),
-    url: z.string(),
-    hookWarning: z.string().optional(),
+    repo: z.string().describe("Which workspace repository."),
+    host: CiHostSchema.describe("Which forge it lives on."),
+    project: z.string().describe("The project there."),
+    url: z.string().describe("Its page on the forge."),
+    hookWarning: z
+        .string()
+        .optional()
+        .describe("Present when the sandbox could not register for instant notifications, with what happened and what to paste in by hand. Without them the sandbox polls instead, so this costs a couple of minutes' delay rather than the feature."),
 });
 export const CI_POLL_INTERVAL_MS = 2 * 60_000;
 export const CiRunsResponseSchema = z.object({
-    repos: z.array(CiRepoSchema),
-    runs: z.array(PipelineRunSchema),
-    seenAt: z.number().optional(),
-});
-export const CiSeenResponseSchema = z.object({ seenAt: z.number() });
-export const CiRunParamSchema = z.object({ repo: z.string(), runId: z.number() });
-export const CiFixParamSchema = CiRunParamSchema.extend({ pick: AgentRunPickSchema });
-export const CiFixResponseSchema = z.object({ conversationId: z.string() });
+    repos: z.array(CiRepoSchema).describe("Which workspace repositories are wired to a forge, and how each one's notifications are set up."),
+    runs: z.array(PipelineRunSchema).describe("Runs across all of them, newest first."),
+    seenAt: z
+        .number()
+        .optional()
+        .describe("When this was last looked at, in milliseconds, so a badge can tell new breakages from ones already read without a second call. Absent means never, so everything counts as new."),
+});
+export const CiSeenResponseSchema = z.object({
+    seenAt: z.number().describe("The timestamp that was written, handed back so a caller can update without asking again."),
+});
+export const CiRunParamSchema = z.object({
+    repo: z
+        .string()
+        .describe("Which workspace repository. The project behind it is resolved fresh each call, so a stale screen cannot act on one the workspace no longer maps to."),
+    runId: z.number().describe("Which run, by the forge's own id."),
+});
+export const CiFixParamSchema = CiRunParamSchema.extend({
+    pick: AgentRunPickSchema.describe("Which model to open the conversation on, when somebody chose one. Leave it out for the sandbox's own choice, which is the ordinary path."),
+});
+export const CiFixResponseSchema = z.object({
+    conversationId: z.string().describe("The conversation that was opened, already holding the failure. Open it to watch, or attach to its turn."),
+});
 export const PrepushStatusSchema = z.enum(["idle", "running", "passed", "failed", "error", "cancelled"]);
 export const PrepushRunSchema = z.object({
-    status: PrepushStatusSchema,
-    command: z.string(),
-    startedAt: z.number().optional(),
-    finishedAt: z.number().optional(),
-    exitCode: z.number().optional(),
-    timedOut: z.boolean().optional(),
-    session: z.string().optional(),
-    output: z.string(),
+    status: PrepushStatusSchema.describe("Where the run is. Failed and error are deliberately different: failed means the code is wrong, error means the command could not be run at all, and calling the second one a test failure would send an agent hunting a bug that is not there."),
+    command: z
+        .string()
+        .describe("What actually ran, echoed here rather than read back from the settings, so a result looked at after the setting changed still says what produced it."),
+    startedAt: z.number().optional().describe("When it began, in milliseconds."),
+    finishedAt: z.number().optional().describe("When it ended, in milliseconds."),
+    exitCode: z.number().optional().describe("How the command exited."),
+    timedOut: z.boolean().optional().describe("It was killed for taking too long rather than finishing."),
+    session: z
+        .string()
+        .optional()
+        .describe("The terminal it runs in, which is where to watch it. Absent where the sandbox has no terminals, in which case there is nothing to attach to."),
+    output: z
+        .string()
+        .describe("The end of what it printed, as plain text with the colour codes and redrawn progress lines resolved away. The end rather than the beginning, because a suite's verdict is at the end. Empty while it runs, and for one that was killed."),
 });
 export const DraftStatusSchema = z.enum(["proposed", "approved", "posting", "posted", "failed"]);
 export const DraftSchema = z.object({
-    platform: z.string().min(1),
-    actsAs: entryId.optional(),
-    content: z.string().min(1),
-    title: z.string().optional(),
-    target: z.string().optional(),
-    media: z.array(z.string()).optional(),
-    scheduledAt: z.number().optional(),
-    status: DraftStatusSchema.default("proposed"),
-    createdAt: z.number().optional(),
-    postingAt: z.number().optional(),
-    postedAt: z.number().optional(),
-    postedUrl: z.string().optional(),
-    error: z.string().optional(),
-});
-export const DraftSummarySchema = DraftSchema.extend({ id: entryId });
-export const DraftsListSchema = z.object({ drafts: z.array(DraftSummarySchema), invalid: z.array(z.string()) });
-export const DraftIdParamSchema = z.object({ id: entryId });
+    platform: z
+        .string()
+        .min(1)
+        .describe("Where it should go. A plain name, so a new site needs no change here; an unknown one simply fails when it tries to post."),
+    actsAs: entryId
+        .optional()
+        .describe("Whose name it goes out under. Needed for anywhere that requires being logged in, because an unwatched turn naming nobody is allowed no account at all. Never guessed: one site can be connected five times over, and picking for you means picking wrong in public with no undo."),
+    content: z.string().min(1).describe("The post itself."),
+    title: z.string().optional().describe("A title, where the site wants one."),
+    target: z
+        .string()
+        .optional()
+        .describe("Where on the site: a community, a channel. Or the address of the thing this replies to, in which case it is a reply, and on some sites the difference between a thread's address and one comment's is the difference between talking to the room and answering the person."),
+    media: z.array(z.string()).optional().describe("Anything to attach, as workspace paths."),
+    scheduledAt: z
+        .number()
+        .optional()
+        .describe("When it should go out, in milliseconds. An agent may propose without one and you set it when approving; an approved draft with no time goes as soon as it is picked up."),
+    status: DraftStatusSchema.default("proposed").describe("Where it is: proposed by the agent, approved by you, being sent, sent, or failed. Rejecting is deleting it; retrying is approving a failed one again."),
+    createdAt: z.number().optional().describe("When it was written, in milliseconds."),
+    postingAt: z
+        .number()
+        .optional()
+        .describe("When sending started, in milliseconds. Needed to tell a send that is under way from one whose run died mid-flight, which the scheduled time cannot: a post due last week is not a post that has been sending since last week."),
+    postedAt: z.number().optional().describe("When it went out, in milliseconds."),
+    postedUrl: z
+        .string()
+        .optional()
+        .describe("Where it landed, when the site hands back an address. The one thing a sent draft can offer that reading it cannot: the post itself, to go and look at."),
+    error: z.string().optional().describe("Why it failed, written as a sentence for a person to read rather than as a code."),
+});
+export const DraftSummarySchema = DraftSchema.extend({ id: entryId.describe("The draft's id.") });
+export const DraftsListSchema = z.object({
+    drafts: z.array(DraftSummarySchema).describe("The queue."),
+    invalid: z
+        .array(z.string())
+        .describe("Drafts that could not be read at all. Listed rather than skipped, because an agent writes these files directly and a malformed one would otherwise never post and never say why."),
+});
+export const DraftIdParamSchema = z.object({ id: entryId.describe("Which draft.") });
 export const PanelSummarySchema = z.object({
-    repo: z.string(),
-    hasPanel: z.boolean(),
-    running: z.boolean(),
-    healthy: z.boolean(),
-    port: z.number().optional(),
-    servers: z.array(z.object({ url: z.string(), dir: z.string().optional(), session: z.string().optional() })),
-    previewUrl: z.string().optional(),
-    role: z.enum(["intent", "desired-state", "app"]).optional(),
-    deployConfig: z.boolean(),
-    desiredState: z.boolean(),
-    directoryUi: z.boolean(),
-    monorepo: z.boolean(),
-    vitest: z.boolean(),
-    userStories: z.boolean(),
-    docs: z.boolean(),
-});
-export const PanelsListSchema = z.object({ panels: z.array(PanelSummarySchema) });
-export const PanelRepoParamSchema = z.object({ repo: z.string() });
+    repo: z.string().describe("Which repository."),
+    hasPanel: z.boolean().describe("Whether it has anything runnable at all."),
+    running: z.boolean().describe("Whether the sandbox has it running."),
+    healthy: z
+        .boolean()
+        .describe("Whether anything it owns is actually answering. A different question: a server still installing is running and not yet healthy, and one somebody started by hand is healthy without the sandbox running it."),
+    port: z
+        .number()
+        .optional()
+        .describe("The port the sandbox told it to use. What it actually bound is below, and for a repository that pins its own ports those are different numbers."),
+    servers: z
+        .array(z.object({
+        url: z.string().describe("Where it answers, with the right scheme: a server on its own certificate is served over https."),
+        dir: z
+            .string()
+            .optional()
+            .describe("Which part of the repository it belongs to, which for a repository whose dev command fans out is the only thing telling them apart."),
+        session: z
+            .string()
+            .optional()
+            .describe("The terminal it runs in: the sandbox's when it started it, yours when you did, and absent when nothing here owns it, which is the case worth designing for."),
+    }))
+        .describe("Every server this repository is really serving, found by looking at what is listening. Empty when nothing answers."),
+    previewUrl: z.string().optional().describe("Where to open it from outside. Absent on a sandbox with no outside address."),
+    role: z
+        .enum(["intent", "desired-state", "app"])
+        .optional()
+        .describe("Which of the workspace's three fixed roles this repository fills. Absent for one that was simply cloned in."),
+    deployConfig: z.boolean().describe("It declares infrastructure."),
+    desiredState: z.boolean().describe("That declaration has been resolved at least once."),
+    directoryUi: z.boolean().describe("It carries a small interface of its own."),
+    monorepo: z.boolean().describe("It holds several packages."),
+    vitest: z.boolean().describe("It has tests that can be run."),
+    userStories: z
+        .boolean()
+        .describe("It carries stories an agent could test the running app against. The one fact here that says nothing about the language."),
+    docs: z.boolean().describe("It carries generated architecture documentation."),
+});
+export const PanelsListSchema = z.object({
+    panels: z
+        .array(PanelSummarySchema)
+        .describe("One entry per repository, worked out in a single pass so nothing has to walk the workspace file by file."),
+});
+export const PanelRepoParamSchema = z.object({ repo: z.string().describe("Which repository.") });
 export const PortSummarySchema = z.object({
-    port: z.number(),
-    host: z.enum(["127.0.0.1", "::1"]),
-    forwardable: z.boolean(),
-    kind: z.enum(["workspace", "system"]),
-    title: z.string(),
-    purpose: z.string(),
-    origin: z.enum(["terminal", "agent", "panel", "extension", "container", "sandbox", "unknown"]),
-    pid: z.number().optional(),
-    command: z.string().optional(),
-    cwd: z.string().optional(),
-    session: z.string().optional(),
-    forwarded: z.boolean(),
-    previewUrl: z.string().optional(),
-});
-export const PortsListSchema = z.object({ ports: z.array(PortSummarySchema) });
-export const PortParamSchema = z.object({ port: z.number().int().min(1).max(65535) });
-export const PortForwardResultSchema = z.object({ previewUrl: z.string().optional() });
+    port: z.number().describe("The port number."),
+    host: z
+        .enum(["127.0.0.1", "::1"])
+        .describe("Which loopback address it actually answers on. Some tools bind only one of the two, and anything dialling it has to know which."),
+    forwardable: z
+        .boolean()
+        .describe("Whether it can be exposed at all. Some listeners answer only at their own address and nowhere else; those are listed for honesty and refused for forwarding."),
+    kind: z
+        .enum(["workspace", "system"])
+        .describe("Whether somebody's own work put it there, or the sandbox's own machinery did. Only the first kind is worth previewing."),
+    title: z
+        .string()
+        .describe("What a person would call it. Always present: a listener nothing can explain is still named, because the button beside it publishes the port to the internet."),
+    purpose: z.string().describe("One sentence about what it is for, including when the honest answer is that nothing could work it out."),
+    origin: z
+        .enum(["terminal", "agent", "panel", "extension", "container", "sandbox", "unknown"])
+        .describe("Who put it there, which is the question somebody is really asking: mine, my agent's, or the box's own."),
+    pid: z.number().optional().describe("The process holding it. Absent when nothing could be matched to the socket."),
+    command: z.string().optional().describe("The command behind it, as it was run. Absent only when nothing could be attributed at all."),
+    cwd: z.string().optional().describe("Where it is running from, which is how a port gets attributed to a repository."),
+    session: z
+        .string()
+        .optional()
+        .describe('The terminal it came from, to watch it in or stop it from. Absent when nothing in its ancestry is one, which is the honest "you cannot reach this from here".'),
+    forwarded: z.boolean().describe("Whether it is currently reachable from outside."),
+    previewUrl: z.string().optional().describe("Where to open it. Present only while forwarded, and only on a sandbox that has an outside address."),
+});
+export const PortsListSchema = z.object({
+    ports: z
+        .array(PortSummarySchema)
+        .describe("Everything listening inside the sandbox right now, read fresh each time rather than from a register the sandbox keeps."),
+});
+export const PortParamSchema = z.object({ port: z.number().int().min(1).max(65535).describe("Which port.") });
+export const PortForwardResultSchema = z.object({
+    previewUrl: z
+        .string()
+        .optional()
+        .describe("Where it can now be reached. Absent on a sandbox with no outside address, where the mapping exists but has no public name."),
+});
 export const MachineSandboxSchema = z.object({
     slug: z.string(),
     container: z.string(),
@@ -2069,99 +3342,178 @@ export const SyncStatusSchema = z.object({
     machines: z.array(MachineReportSchema).optional(),
 });
 export const PublicFileSchema = z.object({
-    path: z.string(),
-    size: z.number(),
-    modifiedAt: z.number(),
-    url: z.string().optional(),
-    blocked: z.string().optional(),
-});
-export const PublicListSchema = z.object({ url: z.string().optional(), files: z.array(PublicFileSchema) });
-export const PublishSchema = z.object({ path: z.string().min(1) });
-export const UnpublishSchema = z.object({ path: z.string().min(1) });
-export const PublishResultSchema = z.object({ path: z.string(), url: z.string().optional() });
+    path: z.string().describe("Where it sits inside the outbox."),
+    size: z.number().describe("Size in bytes."),
+    modifiedAt: z.number().describe("When it last changed, in milliseconds."),
+    url: z.string().optional().describe("Its public address. Absent when this sandbox has no outside address, or when the file is being refused."),
+    blocked: z
+        .string()
+        .optional()
+        .describe("Why a file sitting in the outbox is not being served: a hidden name, a credential-shaped name, contents that look like a token, or sheer size. Only the publisher sees this; a stranger asking for the same file gets the same nothing every other miss gets."),
+});
+export const PublicListSchema = z.object({
+    url: z.string().optional().describe("Your public address, which every file's own hangs off. Absent on a sandbox with nowhere to publish to."),
+    files: z.array(PublicFileSchema).describe("What the outbox holds."),
+});
+export const PublishSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .describe("What to publish, as a workspace path. It is copied rather than moved, so a repository does not lose its build output because somebody shared it."),
+});
+export const UnpublishSchema = z.object({
+    path: z.string().min(1).describe("What to withdraw, as a path inside the outbox rather than a workspace path."),
+});
+export const PublishResultSchema = z.object({
+    path: z.string().describe("Where it landed inside the outbox."),
+    url: z.string().optional().describe("Its public address. Absent on a sandbox with nowhere to publish to."),
+});
 export const ShareDetailSchema = z.enum(["messages", "everything"]);
 export const SharedConversationSchema = z.object({
-    id: z.string(),
-    conversationId: z.string(),
-    title: z.string(),
-    detail: ShareDetailSchema,
-    sharedAt: z.number(),
-    messages: z.number(),
-    url: z.string().optional(),
-});
-export const ShareListSchema = z.object({ shares: z.array(SharedConversationSchema) });
+    id: z
+        .string()
+        .describe("The share's own id, minted fresh each time, so sharing one conversation twice gives two links. Deliberately not the conversation's id, which is memorable by design and would make a page's address guessable."),
+    conversationId: z.string().describe("Which conversation it was taken from."),
+    title: z.string().describe("The title on the page, which is the sharer's choice rather than the conversation's own."),
+    detail: ShareDetailSchema.describe("How much travels: the two speakers' words alone, or the whole record including the agent's work and thinking, which necessarily publishes the code and command output in it."),
+    sharedAt: z
+        .number()
+        .describe("When the snapshot was taken, in milliseconds. A share is frozen, so this dates what a recipient can see rather than when the conversation happened."),
+    messages: z.number().describe("How many messages are behind the link."),
+    url: z.string().optional().describe("The page's address. Absent on a sandbox with nowhere to publish to."),
+});
+export const ShareListSchema = z.object({ shares: z.array(SharedConversationSchema).describe("Every conversation currently published as a page.") });
 export const ShareCreateSchema = z.object({
-    conversationId: z.string().min(1),
-    title: z.string().min(1).max(80),
-    detail: ShareDetailSchema,
+    conversationId: z.string().min(1).describe("Which conversation to publish."),
+    title: z.string().min(1).max(80).describe("The title for the page. The conversation's own name is only what a dialog would open with."),
+    detail: ShareDetailSchema.describe("How much to publish. Two levels rather than a set of switches, because every extra toggle is another thing to get wrong about a link that cannot be recalled."),
 });
-export const ShareUpdateSchema = z.object({ id: z.string().min(1) });
-export const ShareRemoveSchema = z.object({ id: z.string().min(1) });
+export const ShareUpdateSchema = z.object({
+    id: z.string().min(1).describe("Which share to re-take. Its link stays the same, which matters because it has already been sent."),
+});
+export const ShareRemoveSchema = z.object({ id: z.string().min(1).describe("Which share to take down.") });
 export const TerminalSessionSchema = z.object({
-    name: z.string(),
-    label: z.string().optional(),
-    kind: z.enum(["shell", "panel", "agent", "job", "process"]),
-    running: z.boolean(),
-    activityAt: z.number(),
-    exitCode: z.number().optional(),
-    command: z.string().optional(),
-    extensionId: z.string().optional(),
-    processName: z.string().optional(),
-    help: z.object({ requestId: z.string(), message: z.string(), requestedAt: z.number() }).optional(),
+    name: z.string().describe("Its id, and what the close route takes."),
+    label: z.string().optional().describe("What to call it on screen."),
+    kind: z
+        .enum(["shell", "panel", "agent", "job", "process"])
+        .describe("What sort of thing it is: a terminal somebody opened, a repository's dev server, where an agent's commands run, a job the sandbox started, or a background process that is watched rather than typed into."),
+    running: z
+        .boolean()
+        .describe("Whether it is alive. A finished one-shot job leaves a dead shell behind, which reads as false and is how it gets swept up."),
+    activityAt: z.number().describe("When it last produced output, in milliseconds. Zero means it did not say, which is unknown rather than 1970."),
+    exitCode: z.number().optional().describe("How the last thing in it ended. Absent while that pane is still alive."),
+    command: z
+        .string()
+        .optional()
+        .describe("What is running in it right now. Absent when it is sitting at a prompt. Not a second spelling of whether it is alive: this says whether anything is happening, which is what a close button should ask about before it ends something."),
+    extensionId: z.string().optional().describe("Which extension declared this process, when one did."),
+    processName: z
+        .string()
+        .optional()
+        .describe("Which of that extension's processes it is, which together with the id above addresses its start and stop routes."),
+    help: z
+        .object({
+        requestId: z.string().describe("What to send back when you answer, through the agent reply route."),
+        message: z.string().describe("What the agent needs, in its own words."),
+        requestedAt: z.number().describe("When it asked, in milliseconds."),
+    })
+        .optional()
+        .describe("The agent has stopped at something only a person can clear, and is waiting at this terminal. Present only while it is waiting."),
+});
+export const TerminalsListSchema = z.object({
+    sessions: z
+        .array(TerminalSessionSchema)
+        .describe("Every live surface the sandbox is holding, in one list, because the question they all answer is the same one."),
 });
-export const TerminalsListSchema = z.object({ sessions: z.array(TerminalSessionSchema) });
-export const TerminalNameParamSchema = z.object({ name: z.string() });
+export const TerminalNameParamSchema = z.object({ name: z.string().describe("Which terminal.") });
 export const TerminalScrollbackQuerySchema = z.object({
-    name: z.string(),
-    lines: z.coerce.number().min(1).max(100_000).default(20_000),
+    name: z.string().describe("Which terminal."),
+    lines: z.coerce.number().min(1).max(100_000).default(20_000).describe("How far back to ask for. Clamped to the history that actually exists."),
 });
 export const TerminalScrollbackSchema = z.object({
-    name: z.string(),
-    text: z.string(),
-    lines: z.number(),
-    truncated: z.boolean(),
+    name: z.string().describe("Which terminal this is from."),
+    text: z.string().describe("The history, oldest line first, with wrapped lines rejoined so a copied address or path comes back whole."),
+    lines: z.number().describe("How many lines you got."),
+    truncated: z.boolean().describe("It stopped because you asked for that many, not because the history ran out."),
 });
 export const BrowserPageSchema = z.object({
-    id: z.string(),
-    title: z.string().optional(),
-    url: z.string(),
-    active: z.boolean(),
+    id: z
+        .string()
+        .describe("Stable for the life of the page, which is what lets a tab survive a refresh of this list. Its address changes as the agent navigates and its position changes when a sibling closes."),
+    title: z.string().optional().describe("The page's title. Absent mid-navigation, which is exactly when a tab still has to be drawn."),
+    url: z.string().describe("Where it is."),
+    active: z.boolean().describe("The one the agent last touched, or for a finished session, the one it ended on. Exactly one page has this."),
 });
 export const BrowserSessionSchema = z.object({
-    name: z.string(),
-    label: z.string(),
-    server: z.string(),
-    running: z.boolean(),
-    activityAt: z.number(),
-    finishedAt: z.number().optional(),
-    help: z.object({ requestId: z.string(), message: z.string(), requestedAt: z.number() }).optional(),
-    pages: z.array(BrowserPageSchema),
+    name: z.string().describe("Its id, and what the close route takes."),
+    label: z.string().describe("What to call it on screen: the open page's title, or its site, or which browser this is."),
+    server: z
+        .string()
+        .describe("Which browser drives it: the credential-free one, or a signed-in account's. The difference between a throwaway page and one logged in as you, which is worth saying out loud."),
+    running: z
+        .boolean()
+        .describe("Whether it is still open. A closed one is listed for a while with the pages it had, as the record of where the agent went."),
+    activityAt: z.number().describe("When it last did anything, in milliseconds."),
+    finishedAt: z.number().optional().describe("When it closed, in milliseconds. Absent while it is open."),
+    help: z
+        .object({
+        requestId: z.string().describe("What to send back when you answer, through the agent reply route."),
+        message: z.string().describe("What the agent needs, in its own words."),
+        requestedAt: z.number().describe("When it asked, in milliseconds."),
+    })
+        .optional()
+        .describe("The agent has hit something only a person can clear: a captcha, a password it does not hold, a check on your phone. Present only while it is waiting."),
+    pages: z
+        .array(BrowserPageSchema)
+        .describe("Every page it has open. A browser holds several at once, which is the reason it is listed apart from the terminals."),
 });
-export const BrowsersListSchema = z.object({ sessions: z.array(BrowserSessionSchema) });
-export const BrowserNameParamSchema = z.object({ name: z.string() });
+export const BrowsersListSchema = z.object({
+    sessions: z.array(BrowserSessionSchema).describe("Every browser the agents have running, open or recently closed."),
+});
+export const BrowserNameParamSchema = z.object({ name: z.string().describe("Which browser.") });
 export const SubagentKindSchema = z.enum(["subagent", "codex", "grok"]);
 export const SubagentStatusSchema = z.enum(["pending", "running", "blocked", "completed", "failed", "killed", "paused"]);
 export const SubagentSessionSchema = z.object({
-    id: z.string(),
-    kind: SubagentKindSchema,
-    conversationId: z.string(),
-    agentType: z.string().optional(),
-    description: z.string().optional(),
-    model: z.string().optional(),
-    spawnDepth: z.number().optional(),
-    background: z.boolean().optional(),
-    status: SubagentStatusSchema,
-    startedAt: z.number(),
-    endedAt: z.number().optional(),
-    activityAt: z.number(),
-    tokens: z.number().optional(),
-    toolUses: z.number().optional(),
-    lastTool: z.string().optional(),
-    summary: z.string().optional(),
-    error: z.string().optional(),
-    terminal: z.string().optional(),
+    id: z
+        .string()
+        .describe("The id of the tool call that started it, which every side already holds, so a card links to its helper with the id it has and the helper points back the same way."),
+    kind: SubagentKindSchema.describe("What sort of helper: one the runtime spawned, or a separate tool the agent drove from a shell. It changes only how you watch it."),
+    conversationId: z.string().describe("The conversation whose turn started it, and the way back to the chat it belongs to."),
+    agentType: z.string().optional().describe("What kind of helper it is."),
+    description: z.string().optional().describe("What it was asked to do, in one line."),
+    model: z.string().optional().describe("Which model it runs on."),
+    spawnDepth: z
+        .number()
+        .optional()
+        .describe("How deep in the chain it sits, where one means the turn itself started it. A helper can start helpers, and a flat list that could not say so would read as though the turn started all of them."),
+    background: z
+        .boolean()
+        .optional()
+        .describe("The parent carried on working instead of waiting for it. This is the whole reason the list exists: such a helper used to be invisible until its result landed, sometimes minutes later."),
+    status: SubagentStatusSchema.describe("How it is going. Blocked means it needs an answer, which a parent and an operator act on differently from it simply working."),
+    startedAt: z.number().describe("When it started, in milliseconds."),
+    endedAt: z.number().optional().describe("When it finished, in milliseconds. Absent while it works."),
+    activityAt: z.number().describe("When it last did anything, in milliseconds."),
+    tokens: z
+        .number()
+        .optional()
+        .describe("What it has spent. Its own, so a parent's cost and the sum of its helpers' are two different true numbers."),
+    toolUses: z.number().optional().describe("How many tools it has used."),
+    lastTool: z.string().optional().describe("The last one it reached for."),
+    summary: z
+        .string()
+        .optional()
+        .describe("Its report: what it concluded, without opening its record. The question a finished helper gets read for."),
+    error: z.string().optional().describe("Why it failed, when it did."),
+    terminal: z
+        .string()
+        .optional()
+        .describe("The terminal its command runs in, when there is one. Absent for a helper with no process of its own, which is watched by reading its record instead."),
+});
+export const SubagentsListSchema = z.object({
+    sessions: z.array(SubagentSessionSchema).describe("Every helper this sandbox's conversations have started."),
 });
-export const SubagentsListSchema = z.object({ sessions: z.array(SubagentSessionSchema) });
 export const SubagentIdParamSchema = z.object({ id: z.string() });
 const environmentFileSchema = z.object({ content: z.string(), hash: z.string() });
 export const EnvironmentSchema = z.object({
@@ -2257,109 +3609,203 @@ export const SecretSetSchema = z.object({
     key: z
         .string()
         .regex(/^[A-Za-z_][A-Za-z0-9_]*$/)
-        .max(128),
-    value: z.string().min(1),
+        .max(128)
+        .describe("The name to store it under, which is the name a process will find it by."),
+    value: z.string().min(1).describe("The value. It goes straight to your sandbox and never through the platform."),
 });
-export const SecretKeysSchema = z.object({ keys: z.array(z.string()) });
-export const SecretKeyParamSchema = z.object({ key: z.string() });
-export const SecretRevealSchema = z.object({ value: z.string() });
+export const SecretKeysSchema = z.object({
+    keys: z.array(z.string()).describe("The names that exist here. Only the names: the values never leave the sandbox."),
+});
+export const SecretKeyParamSchema = z.object({ key: z.string().describe("Which secret, by name.") });
+export const SecretRevealSchema = z.object({ value: z.string().describe("The value itself. The only place in this API one is ever returned.") });
 export const SecretInventoryEntrySchema = z.object({
-    key: z.string(),
-    kind: z.enum(["env", "generated", "capability", "provider"]),
-    label: z.string().optional(),
-    status: z.enum(["missing", "set", "connected"]),
-    requiredBy: z.array(z.object({ resourceId: z.string(), type: z.string() })),
-    storedAt: z.string(),
-    revealable: z.boolean(),
-    ci: z.object({ synced: z.boolean(), pushedAt: z.string().optional() }).optional(),
-    lastUse: z.object({ at: z.number(), lane: z.enum(["shell", "code", "browser"]), detail: z.string().optional() }).optional(),
-});
-export const SecretInventorySchema = z.object({ entries: z.array(SecretInventoryEntrySchema) });
+    key: z.string().describe("What identifies it. Unique across the whole inventory, so several accounts of one provider each get their own entry."),
+    kind: z
+        .enum(["env", "generated", "capability", "provider"])
+        .describe("Where it came from: you set it, the sandbox generated it, a connection needs it, or it is a model account's credential."),
+    label: z.string().optional().describe("A friendlier name, for entries that have one."),
+    status: z.enum(["missing", "set", "connected"]).describe("Whether it exists and, for a connection, whether it is working."),
+    requiredBy: z
+        .array(z.object({ resourceId: z.string().describe("Which resource."), type: z.string().describe("What kind of resource it is.") }))
+        .describe("What is waiting on it. Empty for a connection's or an account's own credential."),
+    storedAt: z.string().describe("Where it actually lives, in words."),
+    revealable: z.boolean().describe("Whether its value can be shown at all. Everything except a model account's credential can be."),
+    ci: z
+        .object({
+        synced: z.boolean().describe("Whether the pipeline has it."),
+        pushedAt: z.string().optional().describe("When it was last sent there."),
+    })
+        .optional()
+        .describe("Whether a copy has been given to the build pipeline."),
+    lastUse: z
+        .object({
+        at: z.number().describe("When, in milliseconds."),
+        lane: z.enum(["shell", "code", "browser"]).describe("How it was used: a command, a script, or typed into a page."),
+        detail: z
+            .string()
+            .optional()
+            .describe("Where it went: the start of the command or script, or the site. Names and destinations only, never values."),
+    })
+        .optional()
+        .describe("The last time an agent actually spent this secret. Absent while it never has been, which most never are."),
+});
+export const SecretInventorySchema = z.object({
+    entries: z
+        .array(SecretInventoryEntrySchema)
+        .describe("One entry per secret this sandbox knows about, from every place they live. No values, ever."),
+});
 export const AdapterHealthSchema = z.object({
-    state: z.enum(["ready", "unavailable", "unknown"]),
-    detail: z.string().optional(),
-    checkedAt: z.number(),
+    state: z
+        .enum(["ready", "unavailable", "unknown"])
+        .describe("Whether this runtime can serve a turn. Unknown is a real answer rather than a soft no: a check that could not run must not grey out a provider you can in fact use."),
+    detail: z.string().optional().describe("Why it cannot, and what to do about it. Absent when it can."),
+    checkedAt: z.number().describe("When it was last checked, in milliseconds."),
 });
 export const StagedUpdateSchema = z.object({
-    version: z.string().optional(),
-    channel: z.string(),
-    at: z.number(),
+    version: z.string().optional().describe("What the downloaded build says it is. Absent means ready but unnamed, never that nothing is ready."),
+    channel: z
+        .string()
+        .describe("Which channel it was taken from. Not necessarily the one this sandbox follows: downloading a beta build is not the same as moving onto beta."),
+    at: z.number().describe("When the download finished, in milliseconds, which answers whether this is still the update being offered."),
 });
 export const InfoSchema = z.object({
-    name: z.string().optional(),
-    image: z.string().optional(),
-    version: z.string().optional(),
-    latest: z.string().optional(),
-    updateAvailable: z.boolean().optional(),
-    runtimes: z.record(z.string(), AdapterHealthSchema).optional(),
-    channel: z.string().optional(),
-    previousImage: z.string().optional(),
-    updateNotes: z.array(z.string()).optional(),
-    moreUpdateNotes: z.number().optional(),
-    breakingNotes: z.array(z.string()).optional(),
-    staged: StagedUpdateSchema.optional(),
+    name: z.string().optional().describe("What this sandbox is called."),
+    image: z.string().optional().describe("The image it is running."),
+    version: z.string().optional().describe("The version of that image."),
+    latest: z.string().optional().describe("The newest published version on its channel."),
+    updateAvailable: z.boolean().optional().describe("Whether those two differ."),
+    runtimes: z
+        .record(z.string(), AdapterHealthSchema)
+        .optional()
+        .describe("Which agent runtimes can serve a turn right now, keyed by runtime. Absent until the first check has run, which reads the same as every entry being unknown."),
+    channel: z.string().optional().describe("Which release channel this sandbox follows."),
+    previousImage: z
+        .string()
+        .optional()
+        .describe("The image the last update replaced, which is what a rollback would return to. Absent means there is nothing to go back to."),
+    updateNotes: z
+        .array(z.string())
+        .optional()
+        .describe("What is in the update, in the words of the people it is for, newest first. Absent or empty whenever there is nothing worth saying, which reads on screen exactly as it did before there were notes at all."),
+    moreUpdateNotes: z
+        .number()
+        .optional()
+        .describe("How many further notes there are beyond the ones sent, for a sandbox left alone a long time. Absent or zero means you have all of them."),
+    breakingNotes: z
+        .array(z.string())
+        .optional()
+        .describe("What the update takes away, uncapped, because a warning that fell off a shortened list is a breaking update taken unwarned. Absent for the overwhelming majority, which break nothing."),
+    staged: StagedUpdateSchema.optional().describe("An update already downloaded and built on the machine running this container, waiting only for the restart that applies it. That restart is seconds, where an unprepared update is minutes, which is a different decision entirely. Absent when nothing is waiting."),
 });
 export const ManifestProblemSchema = z.object({
-    kind: z.enum(["unreadable", "unknownKey", "invalidEntry"]),
-    detail: z.string(),
-    suggestion: z.string().optional(),
+    kind: z
+        .enum(["unreadable", "unknownKey", "invalidEntry"])
+        .describe("What to do about it. Unreadable means the whole file is being ignored and everything in it is at its default. An unknown key means only that key is ignored. An invalid entry means one item of a list was skipped and the rest is fine."),
+    detail: z.string().describe("What exactly was wrong."),
+    suggestion: z.string().optional().describe("The name it was probably meant to be, when one is close enough to guess honestly."),
+});
+export const ManifestProblemReportSchema = z.object({
+    path: z.string().describe("The file, as a workspace path. The file is the unit somebody fixes, which is why problems are grouped by it."),
+    problems: z
+        .array(ManifestProblemSchema)
+        .describe("Everything currently wrong with it. A file with nothing wrong is absent rather than present and empty."),
 });
-export const ManifestProblemReportSchema = z.object({ path: z.string(), problems: z.array(ManifestProblemSchema) });
 export const ManifestProblemsSchema = z.array(ManifestProblemReportSchema);
-export const DaemonSessionSchema = z.object({ token: z.string(), expiresAt: z.number(), email: z.string() });
+export const DaemonSessionSchema = z.object({
+    token: z.string().describe("The credential every other call carries. Present it as a bearer token."),
+    expiresAt: z.number().describe("When it stops working, in milliseconds, so a caller can renew ahead of it without reading the token."),
+    email: z.string().describe("Who the sandbox verified you as."),
+});
 export const ActivityEventSchema = z.object({
-    id: z.string(),
-    at: z.number(),
-    provider: z.string().optional(),
-    account: z.string().optional(),
-    direction: z.enum(["in", "out", "system"]),
-    type: z.string(),
-    channelId: z.string().optional(),
-    author: z.string().optional(),
-    content: z.string().optional(),
-    method: z.string().optional(),
-    endpoint: z.string().optional(),
-    sessionId: z.string().optional(),
-    turnId: z.string().optional(),
-    conversationId: z.string().optional(),
-    title: z.string().optional(),
-    origin: AgentOriginSchema.optional(),
-    automationIds: z.array(z.string()).optional(),
-    outcome: z.enum(["ok", "error"]).optional(),
-    error: z.string().optional(),
-    extra: z.record(z.string(), z.unknown()).optional(),
+    id: z.string().describe("The entry's own id."),
+    at: z.number().describe("When it happened, in milliseconds. Also what you page by."),
+    provider: z.string().optional().describe("Which outside service, when one was involved. Absent for the sandbox's own events."),
+    account: z
+        .string()
+        .optional()
+        .describe("Which account handled it. Absent for the sandbox's own events and for work run on a provider's default."),
+    direction: z.enum(["in", "out", "system"]).describe("Whether something arrived, something went out, or the sandbox did it to itself."),
+    type: z
+        .string()
+        .describe("Exactly what happened: a message received or sent, a reaction, a turn starting or ending, a rule doing something. A rule that ran and passed says nothing here, because a feed of green ticks is one the eye learns to skip."),
+    channelId: z.string().optional().describe("Which channel or thread it happened in."),
+    author: z.string().optional().describe("Who sent it, for something that arrived."),
+    content: z.string().optional().describe("The message, in full, whichever direction it went."),
+    method: z.string().optional().describe("The verb of an outgoing call."),
+    endpoint: z.string().optional().describe("The address of an outgoing call. Credentials travel in headers, so they are never here."),
+    sessionId: z.string().optional().describe("The provider session behind it."),
+    turnId: z
+        .string()
+        .optional()
+        .describe("Ties one turn's entries together. A turn writes several, and read as separate rows they say one thing several times, so a feed groups on this."),
+    conversationId: z
+        .string()
+        .optional()
+        .describe("Which conversation. This, rather than the provider session, is what the same agent means across a feed, because a session is retired whenever the model changes."),
+    title: z
+        .string()
+        .optional()
+        .describe("What that conversation was called at the time. Copied in rather than looked up, because an audit entry must still read as words years later, after the conversation has been renamed or pruned."),
+    origin: AgentOriginSchema.optional().describe("What woke the conversation from outside, when something did. It is how a turn gets filed under the chat service that caused it rather than under the model that served it."),
+    automationIds: z.array(z.string()).optional().describe("Which automations were involved."),
+    outcome: z.enum(["ok", "error"]).optional().describe("How it ended."),
+    error: z.string().optional().describe("What went wrong, when something did."),
+    extra: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("Whatever else the source had to say: attachments, participants, a recording's path. Shape varies by source."),
 });
 export const ActivityQuerySchema = z.object({
-    provider: z.string().optional(),
-    limit: z.coerce.number().min(1).max(500).default(100),
-    before: z.coerce.number().optional(),
+    provider: z.string().optional().describe("Narrow it to one outside service."),
+    limit: z.coerce.number().min(1).max(500).default(100).describe("How many entries to return."),
+    before: z.coerce.number().optional().describe("Only entries older than this timestamp, so paging walks backwards through the feed."),
 });
-export const ActivityListSchema = z.object({ events: z.array(ActivityEventSchema) });
+export const ActivityListSchema = z.object({ events: z.array(ActivityEventSchema).describe("The audit entries, newest first.") });
 export const ActivityConnectionSchema = z.object({
-    capabilityId: z.string(),
-    provider: z.string(),
-    gateway: z.enum(["ready", "connecting", "pairing", "disconnected", "idle"]),
-    lastError: z.string().optional(),
+    capabilityId: z.string().describe("Which connection."),
+    provider: z.string().describe("Which service it is."),
+    gateway: z
+        .enum(["ready", "connecting", "pairing", "disconnected", "idle"])
+        .describe("Idle means it is up but has nothing to listen for, which is different from a connection that should be up and is not. Pairing means somebody started a sign-in and never finished it, which no amount of waiting will fix."),
+    lastError: z.string().optional().describe("The most recent thing that went wrong on it."),
 });
 export const ActivityStatusSchema = z.object({
-    connections: z.array(ActivityConnectionSchema),
-    voice: z.object({ channelId: z.string(), channelName: z.string(), startedAt: z.number(), participants: z.array(z.string()) }).optional(),
+    connections: z
+        .array(ActivityConnectionSchema)
+        .describe("Each source feeding the record, and whether it is working. Probed now rather than remembered."),
+    voice: z
+        .object({
+        channelId: z.string().describe("Which channel."),
+        channelName: z.string().describe("What it is called."),
+        startedAt: z.number().describe("When it joined, in milliseconds."),
+        participants: z.array(z.string()).describe("Who else is in it."),
+    })
+        .optional()
+        .describe("A voice call the sandbox is currently in, when it is in one."),
 });
 export const UsageTurnSchema = z.object({
-    at: z.number(),
-    day: z.string(),
-    provider: z.string(),
-    account: z.string().optional(),
-    model: z.string().optional(),
-    harness: z.string(),
-    conversationId: z.string().optional(),
-    turns: z.number(),
-    inputTokens: z.number(),
-    outputTokens: z.number(),
-    cacheReadTokens: z.number(),
-    cacheCreationTokens: z.number(),
-    costUsd: z.number(),
-    durationMs: z.number(),
+    at: z.number().describe("When the turn ended, in milliseconds."),
+    day: z.string().describe("The day it fell in, as YYYY-MM-DD in UTC, worked out once so nothing downstream has to do timezone arithmetic."),
+    provider: z.string().describe("Which model provider served it."),
+    account: z.string().optional().describe("Which account paid. Absent for a turn run on a plain key, which belongs to no account."),
+    model: z
+        .string()
+        .optional()
+        .describe("The model that actually ran, past whatever was asked for and every default. Absent only when the provider's own default served it without being named."),
+    harness: z.string().describe("Which agentic loop it ran on."),
+    conversationId: z
+        .string()
+        .optional()
+        .describe("Which conversation it belonged to, so spending can be traced to a card. Absent only for an internal one-off with no conversation at all."),
+    turns: z
+        .number()
+        .describe("The provider's own count for the request, since one exchange can be several under the hood. One when it reported none."),
+    inputTokens: z.number().describe("Tokens sent."),
+    outputTokens: z.number().describe("Tokens received."),
+    cacheReadTokens: z.number().describe("Tokens served from cache, which cost less."),
+    cacheCreationTokens: z.number().describe("Tokens written to cache, which cost more up front and less afterwards."),
+    costUsd: z.number().describe("What it cost, in dollars."),
+    durationMs: z.number().describe("How long it took, in milliseconds."),
     terse: z.boolean().optional(),
     iqSearchArm: z.boolean().optional(),
     iqSearchCohort: z.string().optional(),
@@ -2371,25 +3817,32 @@ export const UsageTurnSchema = z.object({
     tierRouted: z.boolean().optional(),
 });
 export const UsageRollupRowSchema = z.object({
-    day: z.string(),
-    provider: z.string(),
-    account: z.string().optional(),
-    model: z.string().optional(),
-    harness: z.string(),
-    conversationId: z.string().optional(),
-    turns: z.number(),
-    inputTokens: z.number(),
-    outputTokens: z.number(),
-    cacheReadTokens: z.number(),
-    cacheCreationTokens: z.number(),
-    costUsd: z.number(),
-    durationMs: z.number(),
+    day: z.string().describe("The day, as YYYY-MM-DD in UTC."),
+    provider: z.string().describe("Which model provider."),
+    account: z.string().optional().describe("Which account. Absent for work run on a plain key."),
+    model: z.string().optional().describe("Which model."),
+    harness: z.string().describe("Which agentic loop."),
+    conversationId: z.string().optional().describe("Which conversation."),
+    turns: z.number().describe("Turns in this group."),
+    inputTokens: z.number().describe("Tokens sent."),
+    outputTokens: z.number().describe("Tokens received."),
+    cacheReadTokens: z.number().describe("Tokens served from cache."),
+    cacheCreationTokens: z.number().describe("Tokens written to cache."),
+    costUsd: z.number().describe("What the group cost, in dollars."),
+    durationMs: z.number().describe("Time spent, in milliseconds."),
 });
 export const DayWindowQuerySchema = z.object({
-    from: z.string().optional(),
-    to: z.string().optional(),
+    from: z.string().optional().describe("First day to include, as YYYY-MM-DD in UTC. Leave it out for everything up to the end day."),
+    to: z
+        .string()
+        .optional()
+        .describe("Last day to include, as YYYY-MM-DD in UTC, and it is included rather than excluded. Leave it out for everything from the start day onwards."),
+});
+export const UsageRollupSchema = z.object({
+    rows: z
+        .array(UsageRollupRowSchema)
+        .describe("Spending grouped by day, provider, account, model and conversation. Everything a cost screen shows is a rearrangement of these rows, which is why there is no second call for any of it."),
 });
-export const UsageRollupSchema = z.object({ rows: z.array(UsageRollupRowSchema) });
 export const UsageAccountSchema = z.object({
     provider: z.string(),
     account: z.string(),
@@ -2402,94 +3855,178 @@ export const UsageAccountSchema = z.object({
 });
 export const UsageSummarySchema = z.object({ accounts: z.array(UsageAccountSchema) });
 export const LogFileEntrySchema = z.object({
-    name: z.string(),
-    sizeBytes: z.number(),
-    modifiedAt: z.number(),
+    name: z.string().describe("Its name, which is what the read route takes."),
+    sizeBytes: z.number().describe("Size in bytes."),
+    modifiedAt: z.number().describe("When it last changed, in milliseconds."),
+});
+export const LogsListSchema = z.object({
+    files: z.array(LogFileEntrySchema).describe("Every log the sandbox keeps: captured terminal output, command runs, and its own log."),
 });
-export const LogsListSchema = z.object({ files: z.array(LogFileEntrySchema) });
 export const LogReadQuerySchema = z.object({
-    name: z.string().min(1),
-    bytes: z.coerce.number().min(1).max(1_048_576).default(65_536),
+    name: z.string().min(1).describe("Which log. It travels in the query rather than the address, because log names contain slashes."),
+    bytes: z.coerce
+        .number()
+        .min(1)
+        .max(1_048_576)
+        .default(65_536)
+        .describe("How much of the end to read. The newest bytes win when the file is larger."),
 });
 export const LogReadSchema = z.object({
-    name: z.string(),
-    sizeBytes: z.number(),
-    text: z.string(),
-    truncated: z.boolean(),
+    name: z.string().describe("Which log this is from."),
+    sizeBytes: z.number().describe("How large the whole file is."),
+    text: z.string().describe("The end of it, as text."),
+    truncated: z.boolean().describe("There is more before what you got."),
 });
 export const PresenceReportSchema = z.object({
-    clientId: z.string(),
-    idle: z.boolean(),
-    view: z.string().optional(),
-    sessionId: z.string().optional(),
-    path: z.string().optional(),
+    clientId: z.string().describe("This connection's own id, the same one it gave the event stream."),
+    idle: z.boolean().describe("Whether the person has stopped doing anything."),
+    view: z.string().optional().describe("Which view they are on."),
+    sessionId: z.string().optional().describe("Which conversation they have open."),
+    path: z
+        .string()
+        .optional()
+        .describe("Which file they are looking at. Sent whole rather than merged: leaving a field out clears it, so a tab that closes a file drops the path in the same report."),
 });
 export const WebPushChannelSchema = z.object({
-    kind: z.literal("webpush"),
-    endpoint: z.url(),
-    keys: z.object({
-        p256dh: z.string().min(1),
-        auth: z.string().min(1),
-    }),
+    kind: z.literal("webpush").describe("A browser, which the sandbox can reach directly and encrypt end to end."),
+    endpoint: z.url().describe("Where that browser's push service accepts sends. It also identifies the device everywhere else in this group."),
+    keys: z
+        .object({
+        p256dh: z.string().min(1).describe("The browser's public key, for encrypting what is sent."),
+        auth: z.string().min(1).describe("The browser's secret, for the same."),
+    })
+        .describe("What the browser handed you when it subscribed. Post it back exactly as it came; nothing reshapes it."),
 });
 export const RelayChannelSchema = z.object({
-    kind: z.literal("relay"),
-    url: z.url(),
-    deviceId: z.string().min(1),
-    secret: z.string().min(1),
+    kind: z
+        .literal("relay")
+        .describe("A native app, whose operating system only accepts sends from the app's publisher, so the sandbox posts through a relay instead. The message passes through that relay readable, which is the price of the publisher having to be in the loop."),
+    url: z.url().describe("Where to post a send. Recorded rather than assumed, so the sandbox need not know any platform by name."),
+    deviceId: z.string().min(1).describe("The device's id, which also identifies this registration everywhere else in this group."),
+    secret: z.string().min(1).describe("Proof that this sandbox may notify this device. The relay never learns which sandbox is calling."),
 });
 export const PushChannelSchema = z.discriminatedUnion("kind", [WebPushChannelSchema, RelayChannelSchema]);
 export const channelId = (channel) => (channel.kind === "webpush" ? channel.endpoint : channel.deviceId);
 export const PushNotificationSchema = z.object({
-    title: z.string().min(1),
-    body: z.string(),
-    url: z.string().optional(),
-    tag: z.string().optional(),
-    requireInteraction: z.boolean().optional(),
-});
-export const PushConfigSchema = z.object({ publicKey: z.string(), subscribed: z.boolean() });
-export const PushChannelIdSchema = z.object({ id: z.string().min(1) });
-export const PushConfigQuerySchema = z.object({ id: z.string().min(1).optional() });
-export const PushTestSchema = z.object({ delivered: z.number().int().nonnegative() });
+    title: z.string().min(1).describe("The headline."),
+    body: z
+        .string()
+        .describe("The line under it. Push services cap the whole payload at a few kilobytes, which is why nothing here carries a transcript or a diff: a notification is a pointer back, not a delivery."),
+    url: z.string().optional().describe("Where tapping it goes. An existing tab is focused rather than a new one opened."),
+    tag: z
+        .string()
+        .optional()
+        .describe("Collapses repeats: a second notification with the same tag replaces the first instead of stacking beside it."),
+    requireInteraction: z
+        .boolean()
+        .optional()
+        .describe("Keep it on screen until it is dismissed. Used when the agent is waiting for you, where one that fades away is a question that went unanswered in silence."),
+});
+export const PushConfigSchema = z.object({
+    publicKey: z.string().describe("The key a browser needs in order to subscribe. Native apps ignore it."),
+    subscribed: z
+        .boolean()
+        .describe("Whether the asking device is already registered, so a toggle can show its real state instead of trusting the device's own permission, which can be granted with nothing behind it."),
+});
+export const PushChannelIdSchema = z.object({
+    id: z.string().min(1).describe("Which device: a browser's push address, or a native install's device id."),
+});
+export const PushConfigQuerySchema = z.object({
+    id: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Which device is asking. Without it the answer can only speak for the sandbox as a whole, which is rarely the question."),
+});
+export const PushTestSchema = z.object({
+    delivered: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("How many devices actually accepted it. A count rather than a yes, because this button exists to prove a chain nobody can inspect, and the sandbox having accepted the request is not the question being asked."),
+});
 export const PROBE_IDS = ["outdated", "audit", "knip", "jscpd", "ui", "bundle"];
 export const ProbeIdSchema = z.enum(PROBE_IDS);
 export const OutdatedPackageSchema = z.object({
-    name: z.string(),
-    current: z.string(),
-    latest: z.string(),
-    kind: z.enum(["major", "minor", "patch"]),
-    section: z.string(),
+    name: z.string().describe("The dependency."),
+    current: z.string().describe("What you are on."),
+    latest: z.string().describe("What is published."),
+    kind: z
+        .enum(["major", "minor", "patch"])
+        .describe("How far apart those are. This is not one number because forty patch releases behind is a morning's work and one major version is a project."),
+    section: z
+        .string()
+        .describe("Which part of the manifest declares it. A major version behind on a build-time tool is a different risk from one that ships."),
 });
 export const AdvisorySchema = z.object({
-    name: z.string(),
-    severity: z.enum(["critical", "high", "moderate", "low", "info"]),
-    title: z.string(),
-    patched: z.string().optional(),
-    dev: z.boolean(),
+    name: z.string().describe("The dependency it concerns."),
+    severity: z.enum(["critical", "high", "moderate", "low", "info"]).describe("How bad it is said to be."),
+    title: z
+        .string()
+        .describe("What it is, in one line. No scoring vector and no reference list: those are for reading on the advisory's own page, and carrying them would put a kilobyte of prose per finding on every poll."),
+    patched: z
+        .string()
+        .optional()
+        .describe("Which versions fix it. Absent means no fix has been published, which is exactly when nothing should offer to upgrade and something should say so instead."),
+    dev: z.boolean().describe("Whether it only reaches build-time tooling, which is a different problem from one that reaches what you ship."),
 });
 export const DeadCodeSchema = z.object({
-    files: z.number().int().nonnegative(),
-    exports: z.number().int().nonnegative(),
-    types: z.number().int().nonnegative(),
-    dependencies: z.number().int().nonnegative(),
-    devDependencies: z.number().int().nonnegative(),
-    sample: z.array(z.string()),
+    files: z.number().int().nonnegative().describe("Files nothing reaches."),
+    exports: z.number().int().nonnegative().describe("Exported things nothing uses."),
+    types: z.number().int().nonnegative().describe("Types nothing uses."),
+    dependencies: z.number().int().nonnegative().describe("Declared dependencies nothing imports."),
+    devDependencies: z.number().int().nonnegative().describe("The same, for build-time ones."),
+    sample: z
+        .array(z.string())
+        .describe("A handful of the files, so a reader need not take the count on faith. Counts and a sample rather than the whole list, because an agent re-measures against the live tree anyway."),
 });
 export const DuplicationSchema = z.object({
-    percentage: z.number(),
-    clones: z.number().int().nonnegative(),
-    top: z.array(z.object({ lines: z.number().int().nonnegative(), first: z.string(), second: z.string() })),
+    percentage: z
+        .number()
+        .describe("How much of the scanned code is duplicated. A share rather than a count, because a count grows with the repository and would mean something different every quarter."),
+    clones: z.number().int().nonnegative().describe("How many duplicated stretches were found."),
+    top: z
+        .array(z.object({
+        lines: z.number().int().nonnegative().describe("How long the duplicated stretch is."),
+        first: z.string().describe("One of the two places."),
+        second: z.string().describe("The other."),
+    }))
+        .describe("The largest of them."),
 });
 export const UiScanSchema = z.object({
-    components: z.array(z.string()),
-    bypasses: z.array(z.object({ path: z.string(), count: z.number().int().positive() })),
-    idioms: z.array(z.object({ id: z.string(), files: z.array(z.string()) })),
+    components: z.array(z.string()).describe("The interface's own source files, with tests, stories and generated output left out."),
+    bypasses: z
+        .array(z.object({
+        path: z.string().describe("The file."),
+        count: z.number().int().positive().describe("How many times, in that file."),
+    }))
+        .describe("Where the design system was routed around and a value hard-coded instead. Counted per file, because a reader deciding what to open is served by a file and a number, not by eleven snippets."),
+    idioms: z
+        .array(z.object({
+        id: z
+            .string()
+            .describe("Which outdated idiom. Looked up rather than listed here, so a sandbox one version behind can still report one this list has never heard of."),
+        files: z.array(z.string()).describe("The files still on it."),
+    }))
+        .describe("Files still written the way their framework has since replaced."),
 });
 export const BundleSchema = z.object({
-    dir: z.string(),
-    totalBytes: z.number().int().nonnegative(),
-    totalGzip: z.number().int().nonnegative(),
-    assets: z.array(z.object({ path: z.string(), bytes: z.number().int().nonnegative(), gzip: z.number().int().nonnegative() })),
+    dir: z
+        .string()
+        .describe("Which folder was measured. Read from build output already on disk rather than by building, so this is sometimes a commit behind and never leaves anything in your working tree."),
+    totalBytes: z.number().int().nonnegative().describe("The whole thing, raw."),
+    totalGzip: z
+        .number()
+        .int()
+        .nonnegative()
+        .describe("The whole thing, compressed. The ratio between the two is the difference between big and big-and-incompressible, which are different problems."),
+    assets: z
+        .array(z.object({
+        path: z.string().describe("The file."),
+        bytes: z.number().int().nonnegative().describe("Its raw size."),
+        gzip: z.number().int().nonnegative().describe("Its compressed size."),
+    }))
+        .describe("What is in it, piece by piece."),
 });
 export const ProbeStateSchema = z.enum(["ok", "unavailable", "failed"]);
 export const ProbeFactsSchema = z.discriminatedUnion("id", [
@@ -2501,66 +4038,109 @@ export const ProbeFactsSchema = z.discriminatedUnion("id", [
     z.object({ id: z.literal("bundle"), bundle: BundleSchema }),
 ]);
 export const ProbeResultSchema = z.object({
-    id: ProbeIdSchema,
-    state: ProbeStateSchema,
-    ranAt: z.number(),
-    tookMs: z.number().int().nonnegative(),
-    facts: ProbeFactsSchema.optional(),
-    reason: z.string().optional(),
+    id: ProbeIdSchema.describe("Which measurement this is."),
+    state: ProbeStateSchema.describe("Whether the tool ran and reported, is not part of this repository at all, or broke. The middle one is not evidence of health: the check simply cannot be made here."),
+    ranAt: z.number().describe("When it last finished, in milliseconds, which is what its age is measured from."),
+    tookMs: z.number().int().nonnegative().describe("How long it took. Worth knowing before asking for it again: some of these run for minutes."),
+    facts: ProbeFactsSchema.optional().describe("What it found, including finding nothing, which is a real answer and the one that keeps a chore quiet."),
+    reason: z
+        .string()
+        .optional()
+        .describe("Why it broke, quoted from the tool rather than summarised, or, when it never ran, what is missing. Never a sentence built from the check's own name, which would have an unmeasured check claiming there is nothing to measure."),
 });
 export const ChorePackageSchema = z.object({
-    dir: z.string(),
-    name: z.string(),
-    engines: z.record(z.string(), z.string()).optional(),
-    dependencies: z.array(z.string()),
-    devDependencies: z.array(z.string()),
-    documented: z.boolean(),
+    dir: z.string().describe("Where the package lives."),
+    name: z.string().describe("What it declares itself as."),
+    engines: z.record(z.string(), z.string()).optional().describe("Which runtime versions it says it needs, verbatim."),
+    dependencies: z.array(z.string()).describe("What it depends on."),
+    devDependencies: z.array(z.string()).describe("What it needs only to build."),
+    documented: z.boolean().describe("Whether it has a README, which in this workspace is what a package's own documentation is."),
 });
 export const ChoreShapeSchema = z.object({
-    docs: z.array(z.string()),
-    dockerfiles: z.array(z.string()),
-    ci: z.array(z.string()),
-    lockfile: z.boolean(),
-    packageManifest: z.boolean(),
-    deps: z.array(z.string()),
+    docs: z
+        .array(z.string())
+        .describe("The repository's own architecture documents, when it has any. Their existence is the question: a repository with none has never been through the documentation flow at all."),
+    dockerfiles: z.array(z.string()).describe("Container definitions in it."),
+    ci: z.array(z.string()).describe("Pipeline definitions in it."),
+    lockfile: z.boolean().describe("Whether dependencies are pinned to exact versions, which is what makes a security audit mean anything."),
+    packageManifest: z
+        .boolean()
+        .describe("Whether it is a JavaScript project at all. A Rust or Go repository has no majors to be behind on, and offering it those checks would be this surface guessing at what it is looking at."),
+    deps: z
+        .array(z.string())
+        .describe("Every dependency name declared anywhere in the repository. Names rather than a verdict about which framework this is, because that judgement belongs to whatever reads this, not to a sandbox baked months ago."),
 });
 export const ChoreSignalsSchema = z.object({
-    packages: z.array(ChorePackageSchema),
-    shape: ChoreShapeSchema,
-    hotspots: z.array(WorkspaceHotspotSchema),
-    keyModules: z.array(WorkspaceKeyModuleSchema),
-    totals: z.object({ files: z.number(), symbols: z.number(), complexity: z.number(), hotspots: z.number() }),
-    indexed: z.boolean(),
+    packages: z.array(ChorePackageSchema).describe("Each package in the repository, as its own manifest declares it."),
+    shape: ChoreShapeSchema.describe("What the repository is made of, which decides whether a given chore is even a sensible question to ask of it."),
+    hotspots: z
+        .array(WorkspaceHotspotSchema)
+        .describe("Files that change often and are complicated at once, capped tight: a chore only asks whether something has entered the top of the ranking."),
+    keyModules: z.array(WorkspaceKeyModuleSchema).describe("The parts the rest of the code leans on most, capped the same way."),
+    totals: z
+        .object({
+        files: z.number().describe("Files counted."),
+        symbols: z.number().describe("Named things they export."),
+        complexity: z.number().describe("Branch points added up."),
+        hotspots: z.number().describe("How many files qualify as hotspots at all."),
+    })
+        .describe("The repository in numbers."),
+    indexed: z.boolean().describe("Whether the index these rankings came from is finished. Nothing should act on a half-built one."),
 });
 export const ChoreOutcomeSchema = z.enum(["acted", "reported", "clean"]);
 export const ChoreLedgerEntrySchema = z.object({
-    repo: z.string(),
-    chore: z.string(),
-    ranAt: z.number(),
-    runId: z.string(),
-    outcome: ChoreOutcomeSchema,
-    digest: z.string(),
-    snoozedUntil: z.number().optional(),
+    repo: z.string().describe("Which repository."),
+    chore: z.string().describe("Which chore."),
+    ranAt: z.number().describe("When it ran, in milliseconds."),
+    runId: z.string().describe("The conversation that ran it, so its whole record can be opened."),
+    outcome: ChoreOutcomeSchema.describe("What it concluded: it did something, it wrote something down, or it looked and found the finding to be false. That last one matters most, or the same turn starts again for ever."),
+    digest: z
+        .string()
+        .describe("A fingerprint of the evidence standing at the time. A chore whose evidence has since changed is due again on its own merits; one whose evidence has not stays quiet."),
+    snoozedUntil: z
+        .number()
+        .optional()
+        .describe("Not until then, in milliseconds. The chore stays visible and stays out of the badge. Different from switching it off, which is a setting."),
 });
 export const RunningProbeSchema = z.object({
-    repo: z.string(),
-    id: ProbeIdSchema,
-    askedAt: z.number(),
-    startedAt: z.number().optional(),
+    repo: z.string().describe("Which repository."),
+    id: ProbeIdSchema.describe("Which measurement."),
+    askedAt: z.number().describe("When it was asked for, in milliseconds, so one still waiting can say how long it has waited."),
+    startedAt: z
+        .number()
+        .optional()
+        .describe("When it actually began. Absent while it is queued behind another, which is a real and common state: there is one lane for the whole sandbox."),
 });
 export const ChoresReportSchema = z.object({
-    repos: z.array(z.object({ repo: z.string(), probes: z.array(ProbeResultSchema), signals: ChoreSignalsSchema })),
-    ledger: z.array(ChoreLedgerEntrySchema),
-    running: z.array(RunningProbeSchema),
-    node: z.string(),
+    repos: z
+        .array(z.object({
+        repo: z.string().describe("Which repository."),
+        probes: z
+            .array(ProbeResultSchema)
+            .describe("The expensive measurements, served from a cache with an age on each rather than run on demand."),
+        signals: ChoreSignalsSchema.describe("The cheap facts, worked out fresh every time."),
+    }))
+        .describe("Every repository's standing evidence. One answer for all of them, because a badge polls this on a timer and one request per repository is the kind of poll that shows up in a battery graph."),
+    ledger: z.array(ChoreLedgerEntrySchema).describe("What has already been done about all of it."),
+    running: z
+        .array(RunningProbeSchema)
+        .describe("What is being measured right now and what is waiting behind it. Part of this read rather than a route of its own, because a screen that had to ask twice would show the two halves disagreeing."),
+    node: z
+        .string()
+        .describe("The runtime version this sandbox is actually running, read off the process rather than off a manifest, because what is installed is the fact that matters and a declared range is a wish."),
+});
+export const ChoreProbeRequestSchema = z.object({
+    repo: z.string().min(1).describe("Which repository."),
+    id: ProbeIdSchema.describe("Which measurement to retake, ahead of its usual schedule."),
 });
-export const ChoreProbeRequestSchema = z.object({ repo: z.string().min(1), id: ProbeIdSchema });
 export const ChoreLedgerWriteSchema = ChoreLedgerEntrySchema;
 export const ReadinessCheckSchema = z.object({
-    id: z.string(),
-    label: z.string(),
-    status: z.enum(["pass", "warn", "fail"]),
-    detail: z.string(),
+    id: z.string().describe("Which check."),
+    label: z.string().describe("What it is called."),
+    status: z.enum(["pass", "warn", "fail"]).describe("How it went. A warning is a real third answer rather than a soft failure."),
+    detail: z.string().describe("What it found."),
+});
+export const ExtensionReadinessSchema = z.object({
+    checks: z.array(ReadinessCheckSchema).describe("Everything that can be checked from the extension's own files, for an author about to publish."),
 });
-export const ExtensionReadinessSchema = z.object({ checks: z.array(ReadinessCheckSchema) });
 //# sourceMappingURL=schemas.js.map