diff --git a/apps/web/src/action-command-dispatch-race.test.tsx b/apps/web/src/action-command-dispatch-race.test.tsx
index 55a7f45d7..e20fd447a 100644
--- a/apps/web/src/action-command-dispatch-race.test.tsx
+++ b/apps/web/src/action-command-dispatch-race.test.tsx
@@ -1,14 +1,6 @@
-// Regression test for the off-route create-dialog race: firing a palette
-// action command ("New skill") from a page other than its target route used
-// to dispatch the shared "create" event synchronously, then navigate — but
-// the target page's window-event listener only registers once it mounts,
-// which happens on the next render after navigate's setState. The event
-// fired and was gone before anyone was listening.
-//
-// runActionCommand now goes through a pending-flag (pending-dialog-request.ts,
-// the same pattern library-upload.ts already used for "Upload artifact"):
-// off-route, it records the flag and navigates; the target page consumes it
-// on mount instead of relying on a same-tick dispatch.
+// Regression: firing a palette action off-route used to dispatch a "create"
+// event before the target page's listener mounted. Now it goes through a
+// pending-flag (pending-dialog-request.ts) the target page consumes on mount.
 
 import { afterEach, describe, expect, test } from "bun:test";
 import { act } from "react";
@@ -50,11 +42,8 @@ describe("runActionCommand off-route dispatch ordering", () => {
     });
     expect(navigated).toEqual(["/skills"]);
 
-    // Only now (mirroring main.tsx's setState-based navigate re-rendering
-    // the route switch on the next tick) does the section actually mount.
-    // The section reads the stock skill-asset list on mount; serve it an
-    // empty one so the test exercises the pending-flag path, not a
-    // network failure.
+    // Serve an empty skill-asset list so the test exercises the
+    // pending-flag path, not a network failure.
     globalThis.fetch = (async () =>
       new Response(JSON.stringify([]), {
         status: 200,
diff --git a/apps/web/src/activatable-row.test.ts b/apps/web/src/activatable-row.test.ts
index 54bcbadcc..8e64967ac 100644
--- a/apps/web/src/activatable-row.test.ts
+++ b/apps/web/src/activatable-row.test.ts
@@ -2,11 +2,8 @@ import { afterEach, describe, expect, test } from "bun:test";
 
 import { isAdditiveSelectClick, isRowActivationKey, rowActivationProps } from "./activatable-row";
 
-// `isAdditiveSelectClick`'s Mac/non-Mac branch reads `navigator.platform`,
-// which happy-dom's `GlobalRegistrator` reports as whatever the *host* OS
-// is — Darwin-flavored on a Mac, something else on Linux CI. Each test
-// below pins the platform it means to exercise instead of inheriting the
-// host's, so both branches are deterministic on any OS.
+// happy-dom reports `navigator.platform` as the host OS, so each test pins
+// the platform it means to exercise to stay deterministic on any OS.
 const originalPlatform = Object.getOwnPropertyDescriptor(navigator, "platform");
 
 function stubPlatform(platform: string): void {
diff --git a/apps/web/src/activatable-row.ts b/apps/web/src/activatable-row.ts
index 420618714..3c2f2802f 100644
--- a/apps/web/src/activatable-row.ts
+++ b/apps/web/src/activatable-row.ts
@@ -1,22 +1,13 @@
-// A clickable `TableRow` (library, agents, skills) needs the same three
-// things to be keyboard-operable: an accessible role, a tab stop, and
-// Enter/Space activation. Pure so the "which keys activate a row" rule is
-// testable without rendering a table.
+// Pure so "which keys activate a row" is testable without a table render.
 import type { KeyboardEvent } from "react";
 
 export function isRowActivationKey(key: string): boolean {
   return key === "Enter" || key === " ";
 }
 
-/**
- * Whether a click's modifiers mean "add this row to the selection" rather
- * than "activate/replace". Cmd-click is the additive gesture on every
- * platform; Ctrl-click only joins in on non-Mac, because on Mac Ctrl-click
- * is the native context-menu gesture — the browser can fire `click` and
- * `contextmenu` from the same physical click, and treating Ctrl as additive
- * there would silently toggle the very row the context menu is about to
- * act on.
- */
+// Ctrl-click is additive only on non-Mac; on Mac it's the context-menu
+// gesture, and treating it as additive there would toggle the row the
+// context menu is about to act on.
 export function isAdditiveSelectClick(event: {
   readonly metaKey: boolean;
   readonly ctrlKey: boolean;
diff --git a/apps/web/src/agent-deploy.ts b/apps/web/src/agent-deploy.ts
index fb55a3cfa..afdc20ade 100644
--- a/apps/web/src/agent-deploy.ts
+++ b/apps/web/src/agent-deploy.ts
@@ -1,9 +1,5 @@
 // Deploys a hand-authored agent the same way Myra deploys herself
-// (`myra-deploy.ts`): a `workflow`-kind asset holding a rendered source
-// tree, pushed over the stock git smart-HTTP route, then deployed through
-// the stock `POST /workflows/deployments`. Generalized over {name,
-// displayName, systemPrompt} so the create-agent panel can deploy any
-// agent through the one path the platform actually backs.
+// (`myra-deploy.ts`), generalized over {name, displayName, systemPrompt}.
 import { renderBundledWorkflowSourceTree } from "@corbits/workflows/client";
 import { type } from "arktype";
 import { WorkflowDeploymentResponse } from "@intx/types";
@@ -156,10 +152,8 @@ async function withPushToken<T>(
   }
 }
 
-/** Renders this agent's built definition as the same bundled source tree
- * Myra deploys (`pushMyraSource`) — the bundle's `buildMyraWorkflow` is
- * generic over which agent it builds — and pushes it to the asset's `main`.
- * Returns the commit sha the deploy pins to. */
+// The bundle's `buildMyraWorkflow` is generic over which agent it builds.
+// Returns the commit sha the deploy pins to.
 export async function pushAgentSource(
   tenantId: string,
   assetId: string,
@@ -219,11 +213,8 @@ export function isAgentDeploySourceAssetName(name: string): boolean {
   return AGENT_DEPLOY_SOURCE_ASSET_NAME.test(name);
 }
 
-/** The inverse of `agentDeploySourceAssetName`: recovers the slug this
- * pipeline deployed an asset under, so a caller re-deploying an existing
- * agent can reuse its slug instead of re-deriving one from its display
- * name. Null when the name isn't this pipeline's `agent-<slug>-source`
- * shape. */
+/** Lets a caller re-deploying an existing agent reuse its slug instead of
+ * re-deriving one from its display name. */
 export function agentSlugFromSourceAssetName(assetName: string): string | null {
   const match = AGENT_DEPLOY_SOURCE_ASSET_NAME.exec(assetName);
   return match?.[1] ?? null;
@@ -257,12 +248,8 @@ export function buildScheduledRunBody(deployerAddress?: string): string {
   return `This is your scheduled run. ${task} Mail the result to ${deployerAddress} (pass it as a single-item \`to\` list) with a short, descriptive subject.`;
 }
 
-/** The deploying person's mailbox address — same source `session.ts`'s
- * `fetchSession` reads, same shape `threads-api.ts` builds a person
- * participant's address from (`<refId>@<tenantDomain>`). Best-effort: a
- * session probe that fails or comes back signed-out just means the
- * scheduled run's body falls back to naming nobody, never a failed
- * deploy over it. */
+// Best-effort: a failed or signed-out session probe just means the
+// scheduled run's body falls back to naming nobody, never a failed deploy.
 async function resolveDeployerAddress(
   tenantDomain: string,
   fetchImpl: typeof fetch,
@@ -316,13 +303,8 @@ async function scheduleAgentRun(
 
 export type DeployedAgent = typeof WorkflowDeploymentResponse.infer;
 
-/**
- * Deploys a hand-authored agent: ensures its source asset, pushes its
- * rendered definition, resolves the tenant's existing inference offering
- * (the same one Myra's own deploy resolves through), and deploys through
- * the stock `POST /workflows/deployments`. Fails closed when no provider is
- * connected yet — there is no offering to deploy against.
- */
+// Fails closed when no provider is connected yet — there is no offering
+// to deploy against.
 export async function deployAgentSource(
   args: { readonly tenantId: string; readonly input: NewAgentInput },
   fetchImpl: typeof fetch = fetch,
diff --git a/apps/web/src/agent-source-read.ts b/apps/web/src/agent-source-read.ts
index 39698771c..76ebbe074 100644
--- a/apps/web/src/agent-source-read.ts
+++ b/apps/web/src/agent-source-read.ts
@@ -1,7 +1,4 @@
-// Reads an existing agent's deploy source back out of its workflow asset,
-// so the new-workbench picker can re-push the same definition into a
-// child tenant (agent-deploy.ts already generalizes that push+deploy).
-// There is no stock file-read route for a workflow asset (only
+// No stock file-read route exists for a workflow asset (only
 // package-registry tarballs get one), so this fetches `main` over the
 // asset's smart-HTTP git remote with a short-lived read-only token.
 import {
@@ -44,10 +41,8 @@ export type AgentToolPackagePin = { readonly name: string; readonly version: str
 
 type AgentWorkflowStep = (typeof AgentWorkflowJsonShape.infer)["steps"][string];
 
-/** Mints a read-only token, fetches the asset's `main` over its smart-HTTP
- * git remote, and parses `definition.json` out of it. Shared by every
- * reader below so each mints and revokes its own short-lived token rather
- * than holding one open across a batch of assets. */
+// Each reader mints and revokes its own short-lived token rather than
+// holding one open across a batch of assets.
 async function readAgentWorkflowStep(
   tenantId: string,
   assetId: string,
@@ -101,11 +96,8 @@ export async function readAgentSource(
   };
 }
 
-/** The tool packages an agent's own step pins in `definition.json`. Empty
- * for an agent whose tools ride bundled into its `workflow.js` closure
- * instead (Myra's mail/posix factories never surface here — see
- * `deployed-tool-packages.ts`'s `MYRA_TOOL_PACKAGES`, derived from
- * `@corbits/myra/package.json`'s own dependencies). */
+/** Empty for an agent whose tools ride bundled into its `workflow.js`
+ * closure instead — see `deployed-tool-packages.ts`'s `MYRA_TOOL_PACKAGES`. */
 export async function readAgentToolPackagePins(
   tenantId: string,
   assetId: string,
diff --git a/apps/web/src/agents-api.ts b/apps/web/src/agents-api.ts
index a31c4cdba..f47b22b7a 100644
--- a/apps/web/src/agents-api.ts
+++ b/apps/web/src/agents-api.ts
@@ -1,9 +1,5 @@
-// The hub seams this app still needs for agents: definitions (for the
-// sidebar's own-agent-DM listing in `shell/bench-activity.ts`), top-level
-// runs (for `chat/threads-api.ts`'s live-address resolution), and the
-// create-agent deploy mutation. The Agents page itself now reads through
-// `chat/threads-api.ts`'s `listChatAgents` — the same chat-partner listing
-// — so this file no longer carries a roster/detail data model of its own.
+// The Agents page reads through `chat/threads-api.ts`'s `listChatAgents`;
+// this file carries no roster/detail data model of its own.
 
 import { WorkflowDefinitionResponse, WorkflowRunResponse, paginatedSchema } from "@intx/types";
 import { type } from "arktype";
@@ -21,10 +17,8 @@ export type AgentInstance = typeof WorkflowRunResponse.infer;
 const DefinitionsPage = paginatedSchema(WorkflowDefinitionResponse);
 const InstancesPage = paginatedSchema(WorkflowRunResponse);
 
-// The REST pagination ceiling (see `vendor/intx/hub-api/src/pagination.ts`).
-// A bench with more agents or instances than this needs real pagination on
-// this page, not raised here — tracked as a known limit, not silently
-// worked around.
+// The REST pagination ceiling; a bench past this needs real pagination,
+// not a raised limit here.
 const PAGE_LIMIT = 100;
 
 type Validator<T> = (data: unknown) => T | ArkErrors;
@@ -60,28 +54,16 @@ export function listAgentDefinitions(tenantId: string): Promise<readonly AgentDe
   ).then((page) => page.data);
 }
 
-/**
- * The tenant's genuine top-level deployment runs — every non-top-level
- * run (workbench host, invited agent, task) excluded server-side by the
- * native `GET /workflows/runs` listing's own predicate (`address IS NOT
- * NULL AND anchorRunId = id`), the same one `isTopLevelRun` uses.
- * Single-tenant (accepted loss): the deleted route expanded the
- * requested tenant to its whole descendant subtree via
- * `getDescendantTenants`; the native listing filters one tenant, so a
- * workspace parent sees only its own runs, not its child workbenches'.
- */
+// Single-tenant (accepted loss): the native listing filters one tenant, so
+// a workspace parent sees only its own runs, not its child workbenches'.
 export function listTopLevelRuns(tenantId: string): Promise<readonly AgentInstance[]> {
   return getJSON(`/api/tenants/${tenantId}/workflows/runs?limit=${PAGE_LIMIT}`, InstancesPage).then(
     (page) => page.data,
   );
 }
 
-/**
- * Deploys a hand-authored agent through the stock workflow-deploy path
- * (`agent-deploy.ts`), then invalidates the bench's agent directory and
- * chat-agent roster so both pick up the new deployment without a manual
- * refetch.
- */
+// Invalidates the bench's agent directory and chat-agent roster so both
+// pick up the new deployment without a manual refetch.
 export function useDeployAgentMutation(tenantId: string) {
   const queryClient = useQueryClient();
   return useMutation({
diff --git a/apps/web/src/api.ts b/apps/web/src/api.ts
index 328a326e6..5a506a4cb 100644
--- a/apps/web/src/api.ts
+++ b/apps/web/src/api.ts
@@ -1,7 +1,5 @@
-// The interface's one seam to the hub: relative /api paths on the origin the
-// bundle was served from, validated at the boundary with the platform's own
-// response schemas so a shape change surfaces as an error state, never as
-// undefined leaking into a page.
+// Every response is validated at the boundary with the platform's own
+// schemas, so a shape change surfaces as an error state, never `undefined`.
 
 import {
   ApprovalResponse,
@@ -25,11 +23,8 @@ export const PrincipalsSchema = paginatedSchema(PrincipalSummary);
 export const TenantApprovalsSchema = paginatedSchema(ApprovalResponse);
 export const TenantDetailSchema = TenantResponse;
 
-// `GET /api/tenants/:tenantId/assets` returns a bare array of
-// `AssetWithOriginResponse` rows (not the paginated envelope), so the schema
-// validates the array directly. These tenant assets — workflows, skills,
-// package registries, agent state — are the real, listable store the Library
-// page renders as artifacts.
+// Returns a bare array, not the paginated envelope, so this validates the
+// array directly.
 export const AssetsSchema = AssetWithOriginResponse.array();
 
 // Real Library plane: paginated list from GET /api/tenants/:id/artifacts.
@@ -83,26 +78,17 @@ export type ArtifactListItem = typeof ArtifactListItemSchema.infer;
 export type ArtifactListPage = typeof ArtifactListPageSchema.infer;
 export type ArtifactDetail = typeof ArtifactRowSchema.infer;
 export type ArtifactCounts = typeof ArtifactCountsSchema.infer;
-/**
- * The envelope paginatedSchema validates, stated structurally: the generic
- * schema's inferred type carries an arktype inference artifact that rejects
- * plain literals, so pages and tests use this equivalent shape instead.
- */
+// Stated structurally because the generic schema's inferred type rejects
+// plain literals.
 type Paginated<T> = { data: T[]; nextCursor: string | null };
 export type PrincipalsPage = Paginated<Principal>;
 
 /** An arktype schema, seen as the validating call every `Type` provides. */
 type Validator<T> = (data: unknown) => T | ArkErrors;
 
-/**
- * Fetches one hub endpoint and reports exactly what happened: loading, no
- * session (401), a failure, or validated data. Pass a module-level schema so
- * identity stays stable; the schema never enters the query key.
- *
- * Empty paths are disabled and never fetch — the boundary owns the gate so
- * call sites that still pass `""` when a tenant is unresolved cannot hit
- * the network with a broken URL.
- */
+// Pass a module-level schema so identity stays stable. Empty paths are
+// disabled and never fetch, so a call site with an unresolved tenant
+// can't hit the network with a broken URL.
 export function useAPIQuery<T>(
   path: string,
   schema: Validator<T>,
@@ -133,11 +119,7 @@ export function useAPIQuery<T>(
   return toAPIQuery(result);
 }
 
-/**
- * A one-shot POST against a hub route, parsed the same way `useAPIQuery`
- * parses its GETs: loud on a non-2xx status and on a response shape that
- * doesn't match the schema, never a silent fallback.
- */
+// Loud on a non-2xx status or a shape mismatch, never a silent fallback.
 async function postJSON<T>(path: string, schema: Validator<T>, body: unknown): Promise<T> {
   let response: Response;
   try {
@@ -184,13 +166,8 @@ export function rejectApproval(
   );
 }
 
-/**
- * One-shot fetch of `GET /api/tenants/:id` — the only place `parentId`
- * comes from. A bench is a top-level tenant (`parentId === null`); a workbench
- * is a named child tenant, so the raw-id/name heuristic can never tell them
- * apart. `bench-context.tsx` fans this out per membership with
- * `useQueries` to decide which memberships are benches.
- */
+// The only place `parentId` comes from — a bench is a top-level tenant,
+// so a raw-id/name heuristic can never tell it apart from a workbench.
 export async function fetchTenantDetail(tenantId: string): Promise<TenantDetail> {
   const response = await fetch(`/api/tenants/${encodeURIComponent(tenantId)}`, {
     headers: { accept: "application/json" },
@@ -209,24 +186,13 @@ export async function fetchTenantDetail(tenantId: string): Promise<TenantDetail>
   return parsed;
 }
 
-/**
- * Sandboxed HTML preview URL for a Library artifact — the same
- * path an `<iframe sandbox>` in the canvas or Library detail pane loads,
- * and the "Open in new tab" affordance's `href`. Server-side (`GET
- * .../artifacts/:id/preview` in `@corbits/artifacts-hub`) answers 415 for
- * a non-HTML artifact.
- */
+// The server answers 415 for a non-HTML artifact.
 export function artifactPreviewPath(tenantId: string, artifactId: string): string {
   return `/api/tenants/${tenantId}/artifacts/${encodeURIComponent(artifactId)}/preview`;
 }
 
-/**
- * One-shot fetch of a Library artifact's detail — the same
- * `GET /api/tenants/:id/artifacts/:artifactId` read `LibraryRoute` uses via
- * `useAPIQuery`, but as a plain promise for callers that aren't a mounted
- * component (a chat artifact chip's open handler). Never falls back to
- * blob bytes: an `artifactId` always resolves through this Library read.
- */
+// A plain promise for callers that aren't a mounted component. Never
+// falls back to blob bytes: an `artifactId` always resolves through here.
 export async function fetchArtifactDetail(
   tenantId: string,
   artifactId: string,
diff --git a/apps/web/src/app-error-boundary.tsx b/apps/web/src/app-error-boundary.tsx
index b544d644b..1e591ef66 100644
--- a/apps/web/src/app-error-boundary.tsx
+++ b/apps/web/src/app-error-boundary.tsx
@@ -1,7 +1,5 @@
-// The last line of defence: a render error anywhere in the tree
-// used to leave the reader staring at a blank white page. React only offers
-// this as a class component (no hook equivalent exists), so it's the one
-// class in an otherwise function-component codebase.
+// React offers error boundaries only as a class component (no hook
+// equivalent exists), so this is the one class in the codebase.
 
 import { reportError } from "@corbits/error-sink";
 import { Button, EmptyState } from "@corbits/react-ui";
diff --git a/apps/web/src/app.tsx b/apps/web/src/app.tsx
index 18527fcc4..03d861e27 100644
--- a/apps/web/src/app.tsx
+++ b/apps/web/src/app.tsx
@@ -1,7 +1,6 @@
-// The whole interface as a pure function of the current path and session
-// state. The entry point owns the browser history and the one session probe;
-// screens that talk to the hub only mount once the session is confirmed, so
-// a signed-out browser fires no authenticated request anywhere.
+// The entry point owns the browser history and the one session probe;
+// screens mount only once the session is confirmed, so a signed-out
+// browser fires no authenticated request anywhere.
 
 import { Button, EmptyState } from "@corbits/react-ui";
 import { WorkbenchLoadingState } from "@/chat";
@@ -25,12 +24,8 @@ import { AppShell } from "./shell/app-shell";
 import { ComposerInsertionProvider } from "./shell/composer-insertion";
 import { ShellChromeProvider } from "./shell/shell-chrome-provider";
 
-/**
- * Onboarding renders above the shell entirely — no rail, no col2, no bench
- * dock, nothing that implies a workbench already exists. An account the
- * hub reports as setup-required must never see "Select a workbench"; the
- * setup screen is the only thing on screen until it hands off to `/`.
- */
+// Renders above the shell entirely — no rail, no dock, nothing that
+// implies a workbench already exists, until it hands off to `/`.
 function OnboardingGate({
   navigate,
   user,
@@ -56,13 +51,9 @@ function Shell({
   readonly user: SessionUser;
   readonly onSignOut: () => void;
 }) {
-  // One client per signed-in shell mount — above BenchProvider so principals
-  // and every tenant-scoped page share the same cache. Wired to the same
-  // `onSignOut` the account menu uses: any query or mutation that
-  // discovers the session is no longer valid (a hub restarted on an empty
-  // DB, a cookie for a deleted user, an expired session) routes the whole
-  // shell back to login instead of leaving one panel stuck showing "sign
-  // in required" beside chrome that still renders as if signed in.
+  // One client per shell mount so every tenant-scoped page shares the same
+  // cache; wired to `onSignOut` so a session going invalid anywhere routes
+  // the whole shell back to login, not just one stuck panel.
   const queryClient = useMemo(() => createAppQueryClient(onSignOut), [onSignOut]);
   const route = APP_ROUTES.find((candidate) => matchesRoute(candidate.path, path));
   return (
@@ -84,12 +75,6 @@ function Shell({
   );
 }
 
-/**
- * The whole interface as a pure function of the current path and session
- * state. The entry point owns the browser history and the one session probe;
- * screens that talk to the hub only mount once the session is confirmed, so
- * a signed-out browser fires no authenticated request anywhere.
- */
 export function App({
   path,
   navigate,
diff --git a/apps/web/src/approval-actions.ts b/apps/web/src/approval-actions.ts
index 075935071..4fee9e67c 100644
--- a/apps/web/src/approval-actions.ts
+++ b/apps/web/src/approval-actions.ts
@@ -1,11 +1,5 @@
-// Builds the `ApprovalActions` port `ChatWorkspace` (`@/chat`)
-// calls for its in-chat approve card. Reuses the exact reads and writes
-// every other approval surface uses -- `getApprovalDetail` in
-// `pending-approvals.ts`, `approveApproval`/`rejectApproval` in `api.ts` --
-// and invalidates the same query keys they invalidate, so approving in chat
-// updates the shell's pending count live, and vice versa. This is the one place that logic belongs: chat-ui
-// owns no `QueryClient`, so the invalidation the design calls for can only
-// run here.
+// chat-ui owns no `QueryClient`, so this is the one place that can
+// invalidate the same query keys every approval surface shares.
 
 import type { QueryClient } from "@tanstack/react-query";
 import type { ApprovalActions, ApprovalDecisionResult } from "@/chat";
@@ -25,9 +19,8 @@ export function createChatApprovalActions(
     void queryClient.invalidateQueries({
       queryKey: tenantKeys.pendingApprovals(tenantId),
     });
-    // Any cached query keyed under this tenant's inbox API paths (list,
-    // detail, counts) — the tasks backend still owns these routes even
-    // though the Inbox page that used to read them is gone.
+    // The tasks backend still owns these inbox routes even though the
+    // Inbox page that used to read them is gone.
     void queryClient.invalidateQueries({
       predicate: (query) => {
         const key = query.queryKey;
@@ -39,14 +32,8 @@ export function createChatApprovalActions(
     });
   }
 
-  /**
-   * Both `approveApproval`/`rejectApproval` hit the same native resolve
-   * route and fail the same way, so both decisions share this mapping. A
-   * 409 (already resolved, run no longer running, or deployment
-   * unavailable -- see `vendor/intx/hub-api/src/routes/approvals.ts`) is
-   * kept distinct from a generic error: it's never something a retry
-   * fixes, only something the card's next status read explains.
-   */
+  // A 409 (already resolved, run no longer running) is kept distinct from
+  // a generic error: never something a retry fixes.
   async function resolve(
     call: () => Promise<Approval>,
     status: "approved" | "rejected",
@@ -55,9 +42,7 @@ export function createChatApprovalActions(
   ): Promise<ApprovalDecisionResult> {
     try {
       // The native route only ever returns 200 with the exact terminal
-      // status this call asked for -- see `resolveApproval` in
-      // `vendor/intx/hub-api/src/routes/approvals.ts` -- so `status` here
-      // is not a guess.
+      // status asked for, so `status` here is not a guess.
       await call();
       invalidate();
       return { kind: "resolved", status };
diff --git a/apps/web/src/auth/auth-layout.tsx b/apps/web/src/auth/auth-layout.tsx
index 49228ee93..aa7ae3c04 100644
--- a/apps/web/src/auth/auth-layout.tsx
+++ b/apps/web/src/auth/auth-layout.tsx
@@ -4,16 +4,9 @@ import type { ReactNode } from "react";
 import { DitherBackground } from "./dither-background";
 import { QuoteCard } from "./quote-card";
 
-/**
- * Two-column auth shell modeled on the corbits.dev sign-in page: a centered
- * form column on the left and a brand panel with a quote card on the right
- * (hidden on small screens). Pure presentation.
- *
- * This is a local shell rather than react-ui's `blocks/login/auth-layout`
- * because that block hardcodes its own procedural `DitherCanvas` in the brand
- * panel; the signature visual here is an image-driven dither that needs the
- * hero `<img>` painted underneath as the no-JS fallback.
- */
+// Local shell rather than react-ui's `blocks/login/auth-layout`, since that
+// block hardcodes its own procedural `DitherCanvas` — this one needs the
+// image-driven dither's hero `<img>` as a no-JS fallback underneath.
 export function AuthLayout({ children }: { readonly children: ReactNode }) {
   return (
     <div className="auth-shell">
diff --git a/apps/web/src/auth/dither-background.tsx b/apps/web/src/auth/dither-background.tsx
index d05deb457..40d9c7e82 100644
--- a/apps/web/src/auth/dither-background.tsx
+++ b/apps/web/src/auth/dither-background.tsx
@@ -22,20 +22,8 @@ const STRENGTH_LERP = 0.08; // cursor influence easing per frame
 const FRAME_MS = 1000 / 30; // animation cap (~30fps) to spare the CPU
 const ASSET = "/images/hero-dither.png"; // same-origin source image
 
-/**
- * Animated ordered-dither over a source image, rendered on a 2D canvas. A
- * downscaled buffer is dithered each frame with a slow ambient sine warp plus a
- * cursor-driven displacement, then upscaled with `image-rendering: pixelated`.
- *
- * This replaces the original WebGL port: a WebGL canvas promoted the auth
- * panel to a GPU-composited layer that failed to paint (blank/white). A 2D
- * canvas is CPU-rasterized, composites reliably, and retains its last frame
- * when requestAnimationFrame is paused on a hidden tab.
- *
- * The loop is paused whenever the canvas is offscreen or the tab is hidden, is
- * capped to ~30fps, and honours `prefers-reduced-motion` reactively (a single
- * static frame, re-evaluated when the OS setting toggles).
- */
+// Renders on a plain 2D canvas, not WebGL — see
+// docs/auth-dither-background.md for why.
 export function DitherBackground({ className }: { className?: string }) {
   // The animation belongs to the canvas element, so it starts and stops with
   // it: a ref callback with a cleanup, never an effect reaching for a ref.
@@ -111,9 +99,7 @@ export function DitherBackground({ className }: { className?: string }) {
       tStr = inside ? 1 : 0;
     };
     // Listen on window, not the canvas: the canvas is painted behind the
-    // QuoteCard overlay, so canvas-scoped pointermove never fires. onMove
-    // already maps coordinates to the canvas rect and zeroes strength when
-    // the cursor is outside the panel, so the global listener is cheap.
+    // QuoteCard overlay, so canvas-scoped pointermove never fires.
     window.addEventListener("pointermove", onMove, { passive: true });
 
     const reduceQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
diff --git a/apps/web/src/auth/quote-card.tsx b/apps/web/src/auth/quote-card.tsx
index 7071938ad..f3fe7936a 100644
--- a/apps/web/src/auth/quote-card.tsx
+++ b/apps/web/src/auth/quote-card.tsx
@@ -49,10 +49,8 @@ function nextIndex(): number {
   return (lastIndex() + 1) % QUOTES.length;
 }
 
-/**
- * Brand quote card. Advances to the next quote once per page load (persisted in
- * localStorage) — it does not cycle while the page is open.
- */
+// Advances to the next quote once per page load; does not cycle while
+// the page is open.
 export function QuoteCard() {
   // Picked and persisted once, as the card mounts — the rotation advances
   // per page load, never while the page is open.
diff --git a/apps/web/src/auto-workbench-title.ts b/apps/web/src/auto-workbench-title.ts
index ab08374ea..93346b49f 100644
--- a/apps/web/src/auto-workbench-title.ts
+++ b/apps/web/src/auto-workbench-title.ts
@@ -1,10 +1,6 @@
-// ad-hoc ("Just start talking") benches mint as "New Workbench" and
-// used to stay that way in the sidebar. Prefab templates already name the
-// workbench after the template title; this helper turns the person's first message
-// into a short sidebar title so blank benches get the same treatment once
-// that message is known (at create) — without inventing a second rename API.
-// Callers apply the result through `patchWorkbenchSettings` the same way the
-// sidebar rename does (`chat/name`).
+// Turns the first message into a short sidebar title so an ad-hoc bench
+// gets the same naming treatment as a prefab template, via the existing
+// `patchWorkbenchSettings` rename path — no second rename API.
 
 /** Placeholder title for an untitled / blank mint — never a prefab name. */
 export const NEW_WORKBENCH_TITLE = "New Workbench";
@@ -12,12 +8,8 @@ export const NEW_WORKBENCH_TITLE = "New Workbench";
 /** Sidebar-friendly cap — long enough for a goal phrase, short enough to scan. */
 export const AUTO_WORKBENCH_TITLE_MAX = 48;
 
-/**
- * Collapse a first user message into a short workbench title.
- * Returns `undefined` when there is nothing worth naming with (blank /
- * whitespace-only). Truncates at a word boundary when the cut would land
- * mid-word past halfway, and appends an ellipsis when truncated.
- */
+// Truncates at a word boundary when the cut would land mid-word past
+// halfway, appending an ellipsis.
 export function titleFromFirstMessage(
   message: string,
   maxLength: number = AUTO_WORKBENCH_TITLE_MAX,
@@ -32,11 +24,8 @@ export function titleFromFirstMessage(
   return `${cut.replace(/[.,;:!?]+$/u, "")}…`;
 }
 
-/**
- * What an ad-hoc auto-name should PATCH as `chat/name`: the derived title when
- * the workbench is still the generic "New Workbench" placeholder, otherwise
- * `undefined` so callers leave prefab (and already-renamed) titles alone.
- */
+// `undefined` unless the workbench is still the generic placeholder, so
+// callers leave prefab (and already-renamed) titles alone.
 export function autoNameFromFirstMessage(
   currentTitle: string,
   firstMessage: string,
diff --git a/apps/web/src/bench-context-value.ts b/apps/web/src/bench-context-value.ts
index 9fdc44238..61d50dd14 100644
--- a/apps/web/src/bench-context-value.ts
+++ b/apps/web/src/bench-context-value.ts
@@ -1,10 +1,6 @@
-// The context object itself, apart from the provider that fills it.
-// `createContext` mints a fresh object every time its module runs, and a
-// module that also exports a component is a React Refresh boundary that a
-// hot update re-executes without re-executing its importers — the provider
-// would then publish one context while `useBench` still reads the previous
-// one. Holding it in a component-free module keeps a single identity for
-// every reader.
+// Held in a component-free module, since a module with a component is a
+// React Refresh boundary — a hot re-execution would mint a new context the
+// provider publishes while `useBench` still reads the old one.
 
 import type { APIQuery } from "@/lib/api-query";
 import { createContext } from "react";
@@ -13,11 +9,8 @@ import type { Principal, PrincipalsPage } from "./api";
 
 export type BenchState = {
   readonly memberships: APIQuery<PrincipalsPage>;
-  /** The subset of `memberships` this account may treat as a bench: a
-   * top-level tenant (`parentId === null`, per `GET /api/tenants/:id`).
-   * Empty while any membership's tenant detail is still loading — every
-   * consumer that used to filter `memberships` with `isBenchMembership`
-   * reads this instead, so a workbench can never sneak into a bench list. */
+  /** Top-level tenants only; every consumer reads this instead of filtering
+   * `memberships` itself, so a workbench can't sneak into a bench list. */
   readonly benchMemberships: readonly Principal[];
   readonly selectedTenantId: string | null;
   readonly selectedPrincipalId: string | null;
diff --git a/apps/web/src/bench-context.tsx b/apps/web/src/bench-context.tsx
index 3fa92952d..2a965e637 100644
--- a/apps/web/src/bench-context.tsx
+++ b/apps/web/src/bench-context.tsx
@@ -1,8 +1,5 @@
-// The one place this app decides which bench is "current": a single fetch of
-// `/api/me/principals`, and a selected-tenant id persisted to localStorage so
-// the choice survives a reload. Every page that needs to know the current
-// bench (the chat page, the benches page, the header switcher) reads this
-// context instead of re-deriving "membership[0]" on its own.
+// The one place this app decides which bench is "current" — every page
+// reads this context instead of re-deriving "membership[0]" on its own.
 
 import { useQueries, useQueryClient } from "@tanstack/react-query";
 import { useContext, useMemo, useState } from "react";
@@ -36,13 +33,9 @@ function writeStoredTenantId(tenantId: string): void {
   }
 }
 
-/** True for a membership the shell may treat as a bench: a top-level
- * tenant, i.e. one whose `GET /api/tenants/:id` reports `parentId: null`.
- * Workbenches are named child tenants (`needs-converge.ts`'s `POST /api/tenants
- * { parentId }`), so a name-based heuristic can never tell a workbench from a
- * bench — only the tenant's own parent can. `parentByTenantId` holds
- * `undefined` for a tenant whose detail hasn't loaded yet, which this
- * treats as "not (yet known to be) a bench" rather than guessing. */
+/** True only for a top-level tenant (`parentId: null`) — a name-based
+ * heuristic can never tell a workbench from a bench. Unloaded detail
+ * (`undefined`) reads as "not yet known to be a bench" rather than a guess. */
 export function isBenchMembership(
   membership: Principal,
   parentByTenantId: ReadonlyMap<string, string | null>,
diff --git a/apps/web/src/bench/tenancy-contracts.ts b/apps/web/src/bench/tenancy-contracts.ts
index 73b38dca4..6076dea00 100644
--- a/apps/web/src/bench/tenancy-contracts.ts
+++ b/apps/web/src/bench/tenancy-contracts.ts
@@ -22,19 +22,14 @@ export const DmWorkbenchFlag = type({
 });
 export type DmWorkbenchFlag = typeof DmWorkbenchFlag.infer;
 
-/**
- * Build the auto-name for a DM from the counterparty's display name.
- * Never invents a third-party name — caller supplies the resolved label.
- */
+// Never invents a third-party name — caller supplies the resolved label.
 export function dmWorkbenchName(counterpartyDisplayName: string): string {
   const trimmed = counterpartyDisplayName.trim();
   return trimmed.length > 0 ? trimmed : "Direct message";
 }
 
-/**
- * Spec for creating a DM workbench. The workbench runtime still lives in the
- * owning tenant; this is the product shape the create path must honor.
- */
+// The workbench runtime still lives in the owning tenant; this is the
+// product shape the create path must honor.
 export function createDmWorkbenchSpec(args: {
   readonly counterpartyDisplayName: string;
   readonly memberUserIds: readonly [string, string];
@@ -65,11 +60,8 @@ export type ParentValidationResult =
   | { readonly ok: true }
   | { readonly ok: false; readonly code: string; readonly message: string };
 
-/**
- * Validate parentId for sub-workbench creation. Cycle-safe for create
- * (new id does not exist yet). Rejects unknown parents. Does not grant-
- * check — caller must verify owner (or create-child) separately.
- */
+// Cycle-safe for create (new id doesn't exist yet). Does not grant-check
+// — caller must verify owner separately.
 export async function validateParentId(
   parentId: string | null | undefined,
   lookup: TenantParentLookup,
@@ -87,12 +79,8 @@ export async function validateParentId(
   return { ok: true };
 }
 
-/**
- * Detect whether setting `childId`'s parent to `newParentId` would create
- * a cycle. Walks ancestors of newParentId; if childId appears, reject.
- * Used for any future reparent path; create paths pass a not-yet-existing
- * childId and always pass.
- */
+// For any future reparent path; create paths pass a not-yet-existing
+// childId and always pass.
 export async function wouldCreateParentCycle(
   childId: string,
   newParentId: string,
@@ -110,18 +98,13 @@ export async function wouldCreateParentCycle(
   return false;
 }
 
-/**
- * Roles the product may assign or display. Rejects invented roles so UI
- * never drifts from Interchange.
- */
+// Rejects invented roles so UI never drifts from Interchange.
 export function isInterchangeRole(value: string): value is InterchangeRole {
   return (INTERCHANGE_ROLES as readonly string[]).includes(value);
 }
 
-/**
- * Same-parent shared-workbench projection: both tenants must share a parent
- * (or one is the parent of the other). External cross-org is out of scope.
- */
+// Both tenants must share a parent (or one is the parent of the other).
+// External cross-org is out of scope.
 export async function canShareWorkbenchWithinParent(
   tenantA: string,
   tenantB: string,
diff --git a/apps/web/src/chat-artifact-open.ts b/apps/web/src/chat-artifact-open.ts
index fd14dad3c..e9d7dfdd1 100644
--- a/apps/web/src/chat-artifact-open.ts
+++ b/apps/web/src/chat-artifact-open.ts
@@ -1,11 +1,6 @@
-// Turns a chat `FilePart` into the canvas's typed artifact content —
-// `ChatPage`'s glue between the chip-open callback and either of two reads:
-// `artifactId` resolves through the Library artifacts surface (the same
-// `GET /api/tenants/:id/artifacts/:id` `LibraryRoute` reads —
-// `artifactContentFromDetail`), never raw blob bytes. Only a part with no
-// `artifactId` — a plain human upload that never got a Library row — falls
-// back to `chat-ui`'s blob route (see `packages/chat/src/routes.ts`
-// `GET /workbenches/:id/blobs/:blobId`, `artifactContentFromBlob`).
+// A part with an `artifactId` resolves through the Library artifacts
+// surface, never raw blob bytes; only a plain human upload with no
+// Library row falls back to the blob route.
 
 import {
   isTextDecodableMediaType,
@@ -16,10 +11,8 @@ import { artifactPreviewPath, type ArtifactDetail } from "./api";
 import { base64ToUtf8 } from "./chat/threads-api";
 import type { CanvasArtifactContent } from "./shell/canvas-availability";
 
-/** Decodes a Library artifact detail into the canvas's typed content — the
- * same renderer-kind resolution `LibraryPage`'s preview pane uses, so a
- * chip opened from chat and the same artifact opened from Library render
- * identically. */
+/** Same renderer-kind resolution `LibraryPage`'s preview pane uses, so a
+ * chip opened from chat renders identically to Library. */
 export function artifactContentFromDetail(
   tenantId: string,
   detail: ArtifactDetail,
@@ -54,10 +47,8 @@ export function artifactContentFromDetailError(
   };
 }
 
-/** Decodes a base64 blob body into the canvas artifact content for a
- * `FilePart`, given its already-known `name`/`mediaType`. Binary content
- * (a MIME type this UI can't decode as text) renders through the
- * "unsupported" pane with an honest reason rather than raw bytes. */
+/** Binary content this UI can't decode as text renders through the
+ * "unsupported" pane with an honest reason, rather than raw bytes. */
 export function artifactContentFromBlob(
   part: { readonly name: string; readonly mediaType: string },
   blobId: string,
diff --git a/apps/web/src/chat/agent-part-adapter.ts b/apps/web/src/chat/agent-part-adapter.ts
index d29757eab..c61edb9c9 100644
--- a/apps/web/src/chat/agent-part-adapter.ts
+++ b/apps/web/src/chat/agent-part-adapter.ts
@@ -1,11 +1,5 @@
-// Adapting the chat wire's parts (`./wire/parts`) to the shapes `@corbits/react-ui`
-// renders.
-//
-// Only reasoning crosses this boundary now. Tool calls used to as well,
-// but the conversation renders them through `tool-activity.tsx` instead:
-// react-ui's `ToolBlock` shows one call at a time with its arguments and
-// its result as `JSON.stringify` output, and the chat surface groups a
-// turn's calls into rounds and never shows a reader JSON at all.
+// Only reasoning crosses this boundary now — tool calls render through
+// `tool-activity.tsx` instead, since react-ui's `ToolBlock` shows raw JSON.
 
 import type { PartReasoning } from "@corbits/react-ui";
 import type { ReasoningPart } from "./wire/parts";
diff --git a/apps/web/src/chat/avatar.tsx b/apps/web/src/chat/avatar.tsx
index e7beb4af5..8af3de600 100644
--- a/apps/web/src/chat/avatar.tsx
+++ b/apps/web/src/chat/avatar.tsx
@@ -2,12 +2,7 @@ import type { CSSProperties } from "react";
 
 import { agentInitials } from "@/chat/threads-api";
 
-/* Avatar identity pastels. The palette is token references, not
-   hex: --avatar-1 through --avatar-4 are defined once in this package's
-   stylesheet :root (the proposed upstream contract for @corbits/react-ui's
-   theme) and consumed here by reference, so no product code hardcodes a
-   color value. Numbered like react-ui's --chart-1..5 series — slot order is
-   the deterministic resolution order, not a ranking. */
+// Token references, not hex, so no product code hardcodes a color value.
 export const AVATAR_COLORS = ["--avatar-1", "--avatar-2", "--avatar-3", "--avatar-4"] as const;
 
 export type AvatarColor = (typeof AVATAR_COLORS)[number];
@@ -128,10 +123,8 @@ export function CorbitAvatar({
   );
 }
 
-/** The one avatar element for a `.shell-ch-avatar` slot: a Corbit avatar for
- * an agent, a pastel initials chip (hashed off the person's own principal
- * id, never their name) for a person — visually distinct per DESIGN.md's
- * avatar identity rule. */
+// Person chip color hashes off principal id, never name — DESIGN.md's
+// avatar identity rule.
 export function IdentityAvatar({
   kind,
   name,
diff --git a/apps/web/src/chat/blocks/approval-actions.ts b/apps/web/src/chat/blocks/approval-actions.ts
index 387a00e54..5db723655 100644
--- a/apps/web/src/chat/blocks/approval-actions.ts
+++ b/apps/web/src/chat/blocks/approval-actions.ts
@@ -1,38 +1,16 @@
-// The in-chat approve card's one seam to the platform approval it
-// references. `@/chat` owns no session and no query cache, so it
-// never fetches or mutates approvals itself -- the host (the same app that
-// already resolves `tenantId` for `ChatWorkspace`) supplies this port,
-// mirroring how `onOpenArtifact`/`onOpenProfile` thread host callbacks
-// through the timeline. The host's implementation is expected to call the
-// same Interchange-native approve/reject routes Inbox uses and to invalidate
-// the same query keys, so the card, Inbox, and the Activity band stay one
-// source of truth.
+// See docs/chat-wire-contract.md for why this is a host-supplied port.
 
-/** The platform's own status vocabulary for an approval (`ApprovalResponse.status`
- * in `@intx/types/src/approvals.ts`) -- never invented here. */
+// Never invented here — mirrors `ApprovalResponse.status`.
 export type ApprovalLiveStatus = "pending" | "approved" | "rejected" | "timeout" | "expired";
 
-/**
- * A standing-consent offer the platform is willing to take for this
- * approval's tool/resource pair -- present only when the host's read can
- * name both (see `ApproveAction.scope` and its `hub-api` handler, which
- * today rejects `scope: "always"` with `unsupported_scope` because the
- * suspend path doesn't yet capture tool identity). Absence of this field
- * means "not offerable here," never "offerable but hidden."
- */
+// Absent means "not offerable here," never "offerable but hidden."
 export type StandingConsentOffer = {
   readonly verb: string;
   readonly resource: string;
 };
 
-/**
- * The platform's own account of what is being asked -- who, what tool, with
- * which arguments. This is the authoritative "what am I approving" a human
- * decides against; the block's own `title`/`body` is the *agent's* framing
- * and is never a substitute for it (a confused-deputy card that shows only
- * agent-authored text next to live buttons is exactly the failure mode this
- * type exists to close off).
- */
+// The authoritative "what am I approving" — the block's own title/body is
+// the agent's framing and never a substitute for it.
 export type PlatformApprovalDetail = {
   readonly agentName: string;
   readonly headline: string;
@@ -41,31 +19,14 @@ export type PlatformApprovalDetail = {
    * it"). Falls back to the generic "Approve" when the host's read doesn't
    * carry one. */
   readonly actionVerb?: string;
-  /** One-line, platform-authored consequence of taking the action (e.g.
-   * "Merging goes further than posting a review -- it puts the change
-   * live."). Replaces a risk-level badge, which only ever repeated the
-   * agent's own framing back at the human deciding against it. */
+  // Replaces a risk-level badge, which only repeated the agent's own
+  // framing back at the human deciding against it.
   readonly consequence?: string;
   readonly standingConsent?: StandingConsentOffer;
 };
 
-/**
- * What the host's status read told the card. `canAct` is a fact the host
- * establishes from its own authorization read (e.g. whether the approval
- * showed up in a grant-scoped "needs you" read) -- the card never infers it
- * from the block's own data. A `"ready"` result always carries `detail`:
- * there is no code path where a card may show live buttons without the
- * platform's own description of the request alongside them.
- *
- * `forbidden` is distinct from `canAct: false`: it means the host's *read*
- * itself was refused, so actionability -- and the platform detail -- could
- * not be determined at all. The card's honest answer in that case is to
- * show the Approve/Deny buttons (never the agent's framing standing in for
- * a description) and let the real approve/reject call's own authorization
- * decide, surfacing a 403 inline if it also refuses -- never guessing a
- * spectator verdict, and never rendering unverified agent text as if it
- * were the platform's account of the request.
- */
+// See docs/chat-wire-contract.md for why `forbidden` is distinct from
+// `canAct: false`.
 export type ApprovalStatusQuery =
   | { readonly kind: "loading" }
   | {
@@ -81,11 +42,8 @@ export type ApprovalStatusQuery =
 export type ApprovalDecisionResult =
   | { readonly kind: "resolved"; readonly status: "approved" | "rejected" }
   | { readonly kind: "forbidden"; readonly message: string }
-  /** The approval was no longer pending by the time this decision reached
-   * the platform (HTTP 409: already resolved, run no longer running, or
-   * deployment unavailable) -- distinct from a transient `error` because
-   * the right response is never "let the user retry," it's "re-sync and
-   * show what actually happened." */
+  // HTTP 409, no longer pending: distinct from `error` because the right
+  // response is "re-sync and show what happened," never "let it retry."
   | { readonly kind: "conflict"; readonly message: string }
   | { readonly kind: "error"; readonly message: string };
 
@@ -98,13 +56,7 @@ export type ApprovalActions = {
   readonly approve: (approvalId: string) => Promise<ApprovalDecisionResult>;
   /** Calls the same native `/reject` route Inbox calls. */
   readonly reject: (approvalId: string) => Promise<ApprovalDecisionResult>;
-  /**
-   * Turns this one decision into a standing grant for the same tool/resource
-   * pair. Optional: the native route this would call (`POST .../approve`
-   * with `scope: "always"`) is defined in `@intx/types` but `hub-api`
-   * rejects it today (`unsupported_scope` -- the suspend path doesn't yet
-   * capture tool identity). Omit this until a host can wire it to something
-   * real; the card never shows the standing-consent link without it.
-   */
+  // Optional: `hub-api` rejects `scope: "always"` today, so omit until a
+  // host can wire it to something real.
   readonly allowStanding?: (approvalId: string) => Promise<ApprovalDecisionResult>;
 };
diff --git a/apps/web/src/chat/blocks/approve-block.tsx b/apps/web/src/chat/blocks/approve-block.tsx
index 2ea790544..d32971691 100644
--- a/apps/web/src/chat/blocks/approve-block.tsx
+++ b/apps/web/src/chat/blocks/approve-block.tsx
@@ -1,15 +1,6 @@
-// The approve card renders the PLATFORM's own account of what is being
-// asked -- who, what, with which arguments, read live from the host -- as
-// the authoritative description next to any live Approve/Deny buttons. The
-// agent's own framing (`data.title`/`body`/`risk`) is demoted to
-// contextual color: it renders alongside the platform detail, never in
-// place of it, and never at all when live buttons show with no platform
-// detail available (the "undetermined" 403 fallback -- see
-// `approve-card-state.ts`). Nothing here is a decision: resolved state is
-// always re-rendered from the host's status read, never from the block's
-// own data or from a decision response the card just made. When the host
-// gives no `ApprovalActions` port, the card falls back to its
-// pre-round-trip framing: fixed disabled buttons, no fetch.
+// See docs/chat-wire-contract.md for why the platform's own detail is
+// authoritative. No `ApprovalActions` port: falls back to pre-round-trip
+// framing, fixed disabled buttons, no fetch.
 
 import { Button, toast } from "@corbits/react-ui";
 import type { ApproveBlockData } from "../wire/blocks";
diff --git a/apps/web/src/chat/blocks/approve-card-state.test.ts b/apps/web/src/chat/blocks/approve-card-state.test.ts
index 596487bfa..47df134e7 100644
--- a/apps/web/src/chat/blocks/approve-card-state.test.ts
+++ b/apps/web/src/chat/blocks/approve-card-state.test.ts
@@ -137,10 +137,7 @@ describe("deriveApproveCardView", () => {
   });
 
   test("a forbidden status read keeps the buttons, never demotes to spectator", () => {
-    // A refused status read leaves the card with no platform detail to
-    // show. It still renders buttons: the refusal a person can act on is
-    // the one their own decision returns, surfaced inline, not a silently
-    // disabled card (`forbidden` → `undetermined`, never `spectator`).
+    // `forbidden` -> `undetermined`, never `spectator`.
     const view = deriveApproveCardView({
       wired: true,
       live: { kind: "forbidden" },
diff --git a/apps/web/src/chat/blocks/approve-card-state.ts b/apps/web/src/chat/blocks/approve-card-state.ts
index 7b490b50e..1a987173c 100644
--- a/apps/web/src/chat/blocks/approve-card-state.ts
+++ b/apps/web/src/chat/blocks/approve-card-state.ts
@@ -1,7 +1,4 @@
-// Pure state mapping for the approve card: turns the live status read plus
-// any in-flight decision into exactly what the view renders. Kept free of
-// React so the branch logic (actable vs. spectator vs. resolved vs. the
-// forbidden-read branch) is unit-testable without a DOM.
+// Kept free of React so the branch logic is unit-testable without a DOM.
 
 import type {
   ApprovalLiveStatus,
@@ -20,22 +17,16 @@ export type ApproveCardView =
       readonly deciding: DecisionInFlight;
       readonly error: string | null;
     }
-  /** The read succeeded but couldn't establish the viewer may act (or the
-   * read never returned a live status at all, e.g. hosts that only carry
-   * the fixed disabled framing) -- status and the platform's own detail
-   * shown, no buttons. */
+  // Read succeeded but couldn't establish the viewer may act: status and
+  // detail shown, no buttons.
   | {
       readonly kind: "spectator";
       readonly status: ApprovalLiveStatus;
       readonly detail: PlatformApprovalDetail;
     }
-  /** The read itself was forbidden, so the platform's own detail never
-   * arrived. Buttons render anyway: the refusal a person needs to see is
-   * the one their own decision earns, surfaced inline from approve/reject,
-   * not a disabled card they cannot ask about. There is deliberately no
-   * `detail` here: this is the one case where buttons show without it, so
-   * the view must never let the block's agent-authored `body`/`title`
-   * stand in as if it were that detail. */
+  // Read was forbidden; buttons render anyway so the refusal a person
+  // needs to see is the one their own decision earns. No `detail`: the
+  // view must never substitute the agent-authored body/title for it.
   | {
       readonly kind: "undetermined";
       readonly deciding: DecisionInFlight;
@@ -45,10 +36,8 @@ export type ApproveCardView =
       readonly kind: "resolved";
       readonly status: ApprovalLiveStatus;
       readonly detail: PlatformApprovalDetail;
-      /** Set when this render followed a decision call that came back
-       * `"conflict"` (HTTP 409): the card re-synced and found the approval
-       * already resolved by someone/something else, rather than by this
-       * click -- worth a calmer, more specific note than the bare status. */
+      // Set on an HTTP 409 conflict: resolved by someone/something else,
+      // not this click.
       readonly resolvedElsewhere: boolean;
     }
   | { readonly kind: "not-found" }
@@ -65,16 +54,9 @@ export function isTerminalStatus(status: ApprovalLiveStatus): boolean {
   return TERMINAL_STATUSES.includes(status);
 }
 
-/**
- * Derives what the card shows. `wired` is false when the host gave no
- * `ApprovalActions` port at all -- the pre-round-trip fallback: static
- * framing, fixed disabled buttons, no fetch ever attempted.
- *
- * `resolvedElsewhere` only ever marks a genuinely resolved render: it has
- * no effect unless `live` is itself `"ready"` with a terminal status, so a
- * stale flag left over from an earlier decision can never fabricate a
- * resolution.
- */
+// `resolvedElsewhere` has no effect unless `live` is already `"ready"`
+// with a terminal status, so a stale flag can never fabricate a
+// resolution.
 export function deriveApproveCardView(args: {
   readonly wired: boolean;
   readonly live: ApprovalStatusQuery;
diff --git a/apps/web/src/chat/blocks/connect-service-actions.ts b/apps/web/src/chat/blocks/connect-service-actions.ts
index 6ce58c058..3df4b82da 100644
--- a/apps/web/src/chat/blocks/connect-service-actions.ts
+++ b/apps/web/src/chat/blocks/connect-service-actions.ts
@@ -1,11 +1,5 @@
-// The host port behind the generic service connect card —
-// the `ConnectGithubActions` shape generalized to any connector or MCP
-// preset. The block's data carries only agent-authored framing; every
-// live fact — connected or not, and which connect affordance the
-// deployment actually supports (hosted OAuth, one-click keyless, or a
-// pasted key) — is resolved here by the host against the tenant's real
-// connections, so an agent can never author a verdict or steer the
-// auth mode.
+// Every live fact — connected or not, which auth mode applies — is
+// resolved by the host, never authored by the agent.
 
 export type ConnectAffordance = "oauth" | "keyless" | "api-key";
 
@@ -31,12 +25,8 @@ export interface ConnectServiceActions {
     connectorId: string,
     listener: (query: ConnectServiceQuery) => void,
   ): () => void;
-  /**
-   * Re-reads live connect state for every subscribed connector and fans
-   * it to those listeners. ChatWorkspace calls this when a parsed
-   * `chat.settings` event lands so a mounted card flips without
-   * remounting.
-   */
+  // Called on a `chat.settings` event so a mounted card flips without
+  // remounting.
   notifySettingsChanged(): Promise<void>;
   /** One-click connect: starts the hosted OAuth hand-off (navigating
    * away and back) or completes a keyless preset in place. */
diff --git a/apps/web/src/chat/blocks/connect-service-block-container.tsx b/apps/web/src/chat/blocks/connect-service-block-container.tsx
index 10bbb3b16..615059144 100644
--- a/apps/web/src/chat/blocks/connect-service-block-container.tsx
+++ b/apps/web/src/chat/blocks/connect-service-block-container.tsx
@@ -1,12 +1,5 @@
-// Wires the presentational `ConnectServiceBlockView` to a live
-// `ConnectServiceActions` port — the `ConnectGithubBlockContainer`
-// shape: one `getConnectState` read on mount, then live
-// `subscribeConnectState` folds, keyed by the block's `connectorId`
-// rather than the message id since the state is the tenant's, not the
-// workbench's. With no port (or while loading), the card renders the
-// disconnected key-paste-free framing with a disabled-by-inaction
-// connect that goes nowhere, matching the "no port, no feature"
-// fallback every other block uses.
+// Keyed by `connectorId`, not the message id, since the state is the
+// tenant's, not the workbench's. No port: "no port, no feature" fallback.
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useEffect } from "react";
 import type { ConnectServiceBlockData } from "../wire/blocks";
diff --git a/apps/web/src/chat/blocks/connect-service-block.tsx b/apps/web/src/chat/blocks/connect-service-block.tsx
index e61427d16..47c7636e8 100644
--- a/apps/web/src/chat/blocks/connect-service-block.tsx
+++ b/apps/web/src/chat/blocks/connect-service-block.tsx
@@ -1,11 +1,5 @@
-// The generic service connect card — `connect-github`'s
-// first-run card generalized to every connector and MCP preset, in the
-// same `BlockCard` frame. Pure and props-driven like
-// `ConnectGithubBlockView`: the disconnected arm renders one of three
-// affordances the host resolved (one-click OAuth, one-click keyless,
-// key-paste), the connected arm is a plain confirmation, and
-// `./connect-service-block-container.tsx` wires the callbacks to a live
-// `ConnectServiceActions` port.
+// Pure and props-driven; `./connect-service-block-container.tsx` wires
+// the callbacks to a live port.
 
 import { useState } from "react";
 import { Button, Input } from "@corbits/react-ui";
diff --git a/apps/web/src/chat/blocks/registry.tsx b/apps/web/src/chat/blocks/registry.tsx
index e0c01ca15..2f3a38f07 100644
--- a/apps/web/src/chat/blocks/registry.tsx
+++ b/apps/web/src/chat/blocks/registry.tsx
@@ -1,7 +1,5 @@
-// The closed, curated block registry: agents author data, this client owns
-// the code. `BlockPartView` parses the wire envelope at the render boundary
-// and routes each known type to its view; anything unknown or malformed
-// renders a labeled fallback card instead of raw JSON or a crash.
+// Closed and curated: agents author data, this client owns the code.
+// Unknown or malformed renders a labeled fallback, never raw JSON.
 
 import type { Block } from "../wire/blocks";
 import { parseBlock } from "../wire/blocks";
diff --git a/apps/web/src/chat/clock.ts b/apps/web/src/chat/clock.ts
index 13b879a12..f076335ac 100644
--- a/apps/web/src/chat/clock.ts
+++ b/apps/web/src/chat/clock.ts
@@ -1,8 +1,5 @@
-// The one seam `streaming-reply.ts` and `turn-activity.tsx` read wall-clock
-// time and arm backstop timers through, so a test can swap in a fake that
-// advances synchronously instead of sleeping on the real clock — real-timer
-// waits on these hooks' 30ms/60ms backstops are exactly what made them flake
-// under CI's sharded, CPU-contended `bun run test`.
+// A test seam so a fake clock can advance synchronously instead of
+// sleeping — real-timer waits on these backstops flaked under CI.
 export type Clock = {
   readonly now: () => number;
   readonly setTimeout: (callback: () => void, ms: number) => unknown;
diff --git a/apps/web/src/chat/composer.tsx b/apps/web/src/chat/composer.tsx
index c3bed8dec..720843fff 100644
--- a/apps/web/src/chat/composer.tsx
+++ b/apps/web/src/chat/composer.tsx
@@ -1,8 +1,5 @@
-// The one composer surface for a chat thread and a workbench workbench alike:
-// Enter sends, Shift+Enter inserts a newline, and a right-hand action rail
-// carries Send. There is no Stop action — neither `threads-api.ts` nor the
-// hub API expose a way to cancel a running turn, so cancellation is not
-// wired up here; add it to this rail once that capability exists upstream.
+// No Stop action: neither `threads-api.ts` nor the hub API expose a way to
+// cancel a running turn yet.
 import { ArrowUp, CircleNotch } from "@/lib/icons";
 import { useState } from "react";
 
diff --git a/apps/web/src/chat/deployable-package.ts b/apps/web/src/chat/deployable-package.ts
index 99073884c..1d1ac08cf 100644
--- a/apps/web/src/chat/deployable-package.ts
+++ b/apps/web/src/chat/deployable-package.ts
@@ -1,11 +1,5 @@
-// The one contract between an agent that writes a package and the client
-// that deploys it: a reply carrying `package.json` plus a
-// `definition.json` of {name, systemPrompt, description?, schedule?} —
-// either as mail attachments, or (since `@intx/tools-mail`'s `mail_send`
-// has no attachments parameter) as two labelled fenced code blocks in the
-// message body. The client renders the source tree itself
-// (`agent-deploy.ts`), so the agent never has to know the deploy
-// pipeline's shape.
+// Either mail attachments, or — since `@intx/tools-mail`'s `mail_send` has
+// no attachments parameter — two labelled fenced code blocks in the body.
 
 import { type } from "arktype";
 import { reportError } from "@corbits/error-sink";
@@ -40,12 +34,7 @@ export interface DeployablePackage {
 export const PACKAGE_MANIFEST_NAME = "package.json";
 export const AGENT_DEFINITION_NAME = "definition.json";
 
-/**
- * What a message's attachments (or fenced blocks) resolve to: a parsed
- * package, a named rejection when the message attempted a package but
- * got a field wrong, or `null` when the message isn't a package attempt
- * at all.
- */
+// `null` when the message isn't a package attempt at all.
 export type PackageOutcome = DeployablePackage | { readonly reason: string } | null;
 
 export function isPackageRejection(
@@ -111,10 +100,7 @@ function parsePackageFiles(
   };
 }
 
-/** The agent package a message's attachments describe: a parsed package,
- * a rejection naming what's wrong, or `null` when the attachments aren't
- * a package attempt at all (no package.json or no definition.json).
- * Untrusted input: parsed, never cast. */
+// Untrusted input: parsed, never cast.
 export function deployablePackage(attachments: readonly MailAttachment[]): PackageOutcome {
   const manifest = attachments.find((attachment) => attachment.name === PACKAGE_MANIFEST_NAME);
   if (manifest === undefined) return null;
@@ -211,11 +197,8 @@ function findNamedFencedBlocks(lines: readonly string[]): Map<string, FencedBloc
   return found;
 }
 
-/** The agent package a message body carries as fenced code blocks, plus
- * the body with those blocks removed. Used when attachments are absent —
- * `@intx/tools-mail`'s `mail_send` has no attachments parameter, so this is
- * the mailed-package contract's actual delivery path today. `null` when
- * the body isn't a package attempt (neither file is present). */
+// Used when attachments are absent — the actual delivery path today,
+// since `mail_send` has no attachments parameter.
 export function deployablePackageFromBody(body: string): {
   readonly outcome: DeployablePackage | { readonly reason: string };
   readonly strippedBody: string;
@@ -243,10 +226,8 @@ export function deployablePackageFromBody(body: string): {
   return { outcome, strippedBody };
 }
 
-/** The package outcome a message describes and the body to render for it —
- * attachments win when present (the intended path once `mail_send` grows
- * attachments support), otherwise the body's fenced blocks are read and
- * stripped from the rendered text. */
+// Attachments win when present (the intended path once `mail_send` grows
+// attachments support), otherwise the body's fenced blocks are used.
 export function resolveMessagePackage(
   attachments: readonly MailAttachment[],
   body: string,
diff --git a/apps/web/src/chat/failed-turn-models.ts b/apps/web/src/chat/failed-turn-models.ts
index 7b1fcc903..79b239e9f 100644
--- a/apps/web/src/chat/failed-turn-models.ts
+++ b/apps/web/src/chat/failed-turn-models.ts
@@ -44,11 +44,7 @@ function toChoices(models: readonly ModelInfo[], limit: number): readonly Failed
     });
 }
 
-/**
- * Two-to-four tenant-available chat models for the failed-turn strip
- * picker — the same connected, chat-capable filter Settings' agent
- * model select uses, capped so the strip stays a quiet inline row.
- */
+// Capped so the strip stays a quiet inline row.
 export function failedTurnModelChoices(
   models: readonly ModelInfo[],
   limit = FAILED_TURN_MODEL_PICKER_LIMIT,
@@ -56,11 +52,7 @@ export function failedTurnModelChoices(
   return toChoices(chatCapableModels(models), limit);
 }
 
-/**
- * Same picker as {@link failedTurnModelChoices}, restricted to offerings
- * that advertise function-calling — the recovery set when the failure
- * was that the current model cannot use tools.
- */
+// The recovery set when the failure was that the model can't use tools.
 export function failedTurnToolCapableModelChoices(
   models: readonly ModelInfo[],
   limit = FAILED_TURN_MODEL_PICKER_LIMIT,
diff --git a/apps/web/src/chat/inference-failure.ts b/apps/web/src/chat/inference-failure.ts
index eed223d1b..1bc0708c0 100644
--- a/apps/web/src/chat/inference-failure.ts
+++ b/apps/web/src/chat/inference-failure.ts
@@ -1,29 +1,5 @@
-// Recognizes a classified inference failure's reply prose — the
-// one place `chat-ui` matches against the exact preambles
-// `@intx/inference/src/default-director.ts`'s `formatInferenceError`
-// writes for `"credential_failure"` and `"quota_exhausted"`
-// (`InferenceError.category`, `@intx/types/runtime`). This is a prose
-// match, not a structured read: by the time a reply reaches the chat
-// timeline it is a plain `text` part with no metadata (see
-// `vendor/intx/hub-sessions/src/event-collector.ts`'s `connector.reply`
-// case, which persists the formatted string with `null` metadata) — the
-// classification itself IS structured further upstream
-// (`packages/chat/src/chat-orchestrator.ts`'s `postProviderHealthSignal`
-// reads `TurnFinalized.errors[].category` directly, no parsing involved),
-// but nothing carries that category down to this render layer.
-//
-// Conservative and narrow on purpose: matches only the two preambles a
-// credential or quota failure gets, anchored at the start of the string
-// (never a substring match, so an agent's own reply that happens to
-// quote or discuss one of these phrases mid-sentence does not
-// false-positive) and never the "temporary error"/"context limit"/
-// "aborted" preambles those other categories get — a false match here
-// would offer "Fix this connection" on a turn that was never a
-// connection problem.
-// Exported so `test/inference-preamble-drift.test.ts` can assert these
-// stay byte-for-byte identical to the vendored source they're copied
-// from, rather than each preamble living only as an inline literal no
-// test can reach.
+// Reply-prose match against classified failures (see
+// docs/chat-wire-contract.md for why this can't be a structured read).
 export const CLASSIFIED_INFERENCE_FAILURE_PREAMBLES: readonly string[] = [
   "This agent could not complete your request due to a credential error",
   "This agent could not complete your request because the API quota has been exhausted",
diff --git a/apps/web/src/chat/loading-state.tsx b/apps/web/src/chat/loading-state.tsx
index 3fed134a4..86c4f1774 100644
--- a/apps/web/src/chat/loading-state.tsx
+++ b/apps/web/src/chat/loading-state.tsx
@@ -1,13 +1,5 @@
-// The one warm loader every page/workbench-level wait in this app renders —
-// a bare skeleton/spinner/grey
-// slab is never the right answer for "we don't know how long this takes":
-// one honest headline plus a small rotating tip reads as useful rather than
-// stalled, and it's the same shape everywhere so a reader learns it once.
-//
-// `delayMs` (default 200) holds the loader itself back: a wait that
-// resolves before the delay elapses never gets an intermediate frame at
-// all, which is what keeps a fast round-trip from flashing chrome the
-// reader has no time to read.
+// `delayMs` (default 200) holds the loader back so a fast round-trip
+// never flashes chrome the reader has no time to read.
 
 import { CorbitsMark } from "@corbits/react-ui";
 import { useEffect, useState } from "react";
@@ -17,11 +9,8 @@ import { CHAT_STRINGS } from "./strings";
 const WORKBENCH_LOADING_TIP_INTERVAL_MS = 4000;
 const DEFAULT_LOADING_DELAY_MS = 200;
 
-/** A small, honest product tip under the loading headline — rotates on a
- * timer regardless of motion preference; the fade between tips is the
- * only thing `prefers-reduced-motion` turns off (the CSS keyframe is
- * scoped to `no-preference`, so a reduced-motion reader still sees each
- * tip in turn, just without the crossfade). */
+// Rotates regardless of motion preference; only the crossfade is scoped
+// to `no-preference` and turns off under `prefers-reduced-motion`.
 function WorkbenchLoadingTip() {
   const tips = CHAT_STRINGS.workbenchLoadingTips;
   const [index, setIndex] = useState(0);
@@ -40,13 +29,7 @@ function WorkbenchLoadingTip() {
   );
 }
 
-/**
- * The shared page/workbench-level loading treatment: one honest headline (never
- * an internal stage name — "Starting the runtime…" tells the reader
- * nothing they can act on) plus a rotating tip. Delays its own mount by
- * `delayMs` so a wait that resolves quickly never flashes an intermediate
- * frame — see this file's doc.
- */
+// Headline is always one honest sentence, never an internal stage name.
 export function WorkbenchLoadingState({
   delayMs = DEFAULT_LOADING_DELAY_MS,
   title = CHAT_STRINGS.workbenchLoadingTitle,
@@ -62,12 +45,9 @@ export function WorkbenchLoadingState({
   const [visible, setVisible] = useState(delayMs <= 0);
 
   useEffect(() => {
-    // A surface that swaps its own `delayMs` — a route that starts out
-    // "still reading" (delayed) and becomes "known to be waiting"
-    // (immediate) — reconciles onto this same element rather than
-    // remounting it, so dropping to 0 has to show the loader outright.
-    // Returning early here instead left the loader hidden for good and
-    // rendered the wait as a blank page.
+    // A route swapping `delayMs` to 0 reconciles onto this same element;
+    // returning early here instead left the loader hidden and the wait
+    // rendered as a blank page.
     if (delayMs <= 0) {
       setVisible(true);
       return;
diff --git a/apps/web/src/chat/markdown.tsx b/apps/web/src/chat/markdown.tsx
index 7613dcfdb..98ae9b336 100644
--- a/apps/web/src/chat/markdown.tsx
+++ b/apps/web/src/chat/markdown.tsx
@@ -1,10 +1,5 @@
-// A minimal, dependency-free renderer for the safe markdown subset chat
-// messages use: bold, italic, inline code, fenced code blocks, ordered and
-// unordered lists, links, and headings (rendered as bold lines rather than
-// distinct heading elements, since a chat bubble has no heading hierarchy
-// to preserve). Never uses `dangerouslySetInnerHTML` — every character of
-// message text passes through React as text content, so raw HTML in a
-// message can never execute or render as markup.
+// Never uses `dangerouslySetInnerHTML` — every character passes through
+// React as text content, so raw HTML in a message can't execute.
 
 import type { ReactNode } from "react";
 
@@ -133,12 +128,7 @@ function parseBlocks(source: string): Block[] {
   return blocks;
 }
 
-/**
- * Renders the safe markdown subset (bold/italic/inline code/code
- * blocks/lists/links/headings-as-bold) message text uses. Plain text with
- * no markdown syntax renders exactly as before — a single paragraph of its
- * own text.
- */
+// Plain text with no markdown syntax renders exactly as before.
 export function Markdown({ text }: { readonly text: string }) {
   const blocks = parseBlocks(text);
 
diff --git a/apps/web/src/chat/no-usable-model-banner.tsx b/apps/web/src/chat/no-usable-model-banner.tsx
index 6c8334531..2ac3f0048 100644
--- a/apps/web/src/chat/no-usable-model-banner.tsx
+++ b/apps/web/src/chat/no-usable-model-banner.tsx
@@ -1,10 +1,5 @@
-// The pre-send half of the fix. A tenant whose one seeded
-// `model_provider` row carries no credential (the shape seeding always
-// leaves behind) can't run inference — the composer stays live (a person
-// may still want to leave a note), but this banner says so before they
-// invest a long message in a reply that was never coming, and leads
-// straight into the connect flow that already works
-// (`@/settings`'s `ConnectionsSection`).
+// Says so before a person invests a long message in a reply that was
+// never coming; the composer stays live since they may still want a note.
 import { Button } from "@corbits/react-ui";
 import { WarningCircle } from "@/lib/icons";
 import { CHAT_STRINGS } from "./strings";
diff --git a/apps/web/src/chat/relative-time.ts b/apps/web/src/chat/relative-time.ts
index d0096efdd..cee1257ba 100644
--- a/apps/web/src/chat/relative-time.ts
+++ b/apps/web/src/chat/relative-time.ts
@@ -1,7 +1,5 @@
-/** How long ago a timestamp was, in the compact form the chat surfaces
- * use for activity: "just now", "12m ago", "3h ago", "5d ago". An
- * absent or unparseable timestamp renders as nothing rather than a
- * placeholder date. */
+// An absent or unparseable timestamp renders as nothing, never a
+// placeholder date.
 export function formatRelativeActivity(iso: string | null): string {
   if (iso === null) return "";
   const date = new Date(iso);
diff --git a/apps/web/src/chat/resume-failed-banner.tsx b/apps/web/src/chat/resume-failed-banner.tsx
index 017b15aa5..e699b275b 100644
--- a/apps/web/src/chat/resume-failed-banner.tsx
+++ b/apps/web/src/chat/resume-failed-banner.tsx
@@ -1,7 +1,5 @@
-// Mid-turn reopen whose catch-up fetch (`fetchRunningTurn`) fails
-// must not leave the workbench looking idle. This soft banner names the gap,
-// quotes a `reportError` ref id, and offers Retry — never a silent
-// `.catch(() => undefined)`.
+// A failed catch-up fetch must not leave the workbench looking idle —
+// never a silent `.catch(() => undefined)`.
 import { Button } from "@corbits/react-ui";
 import { WarningCircle } from "@/lib/icons";
 import { CHAT_STRINGS } from "./strings";
diff --git a/apps/web/src/chat/strings.ts b/apps/web/src/chat/strings.ts
index 4b2dad1c6..e12239635 100644
--- a/apps/web/src/chat/strings.ts
+++ b/apps/web/src/chat/strings.ts
@@ -1,11 +1,5 @@
-// Every user-facing word the conversation surface prints, in one place.
-// The package underneath calls everything a "workbench" — a `kind` string of
-// "workbench" or "chat" — but the app decides what a human reads: a
-// "workbench" is the product word for a conversation with an agent (each
-// one its own tenancy). Nothing in the chat/* components inlines its own
-// copy; it imports from here. There is no in-package new-workbench dialog
-// any more: the one creation verb mints and navigates directly —
-// see `apps/web/src/instant-agent-create.ts`.
+// Every user-facing word the conversation surface prints, in one place —
+// no chat/* component inlines its own copy.
 
 function joinWithAnd(names: readonly string[]): string {
   if (names.length <= 1) return names[0] ?? "";
@@ -348,10 +342,8 @@ export const CHAT_STRINGS = {
   workbenchSettingsAgentDetailLoadError: "Couldn't load this agent's instructions",
   workbenchSettingsAgentDetailSaveError: "Couldn't save these changes — try again.",
   workbenchSettingsAgentDetailSavedToast: "Instructions saved",
-  // Scoped rather than a bare "Save" — the top-bar Save
-  // right above it in the same view saves the conversation's own General
-  // fields, a different scope entirely; this one only ever writes this
-  // agent's instructions.
+  // Scoped, not a bare "Save": the top-bar Save above it saves General
+  // fields, a different scope.
   workbenchSettingsAgentDetailSave: "Save instructions",
   workbenchSettingsAgentDetailSaving: "Saving…",
   workbenchSettingsAgentDetailCancel: "Cancel",
diff --git a/apps/web/src/chat/threads-api.ts b/apps/web/src/chat/threads-api.ts
index b86d8f9ce..9634e2351 100644
--- a/apps/web/src/chat/threads-api.ts
+++ b/apps/web/src/chat/threads-api.ts
@@ -1,16 +1,6 @@
-// Chats are mail threads. One chat has exactly one agent, and both sides
-// of it are durable mail: the person sends from their own mailbox
-// (`POST /mailbox/me/inbox/send`), which keeps a Sent copy and hands the
-// frame to the hub, and the agent's reply lands in the same mailbox's
-// INBOX. This file is the only seam between the chat UI and that surface —
-// nothing here touches a chat-specific hub route, because none exist.
-//
-// A chat is identified by its agent's definition asset id, not a run id —
-// every hub restart releases the old run and redeploys under a new one, so
-// keying on a run id would 409 the moment it turns terminal. An agent's
-// address set spans every run it has ever had (releases included), which is
-// what keeps a chat's history intact across a redeploy; sends resolve the
-// current live run's address at send time.
+// Chats are mail threads (see docs/chat-mail-threading.md). Keyed by the
+// agent's definition asset id, not a run id, since a redeploy retires the
+// run id and would 409 a keyed-on-run chat.
 
 import { type } from "arktype";
 import { WorkflowDeploymentResponse } from "@intx/types";
@@ -44,17 +34,13 @@ export type ChatAgent = {
   /** The address of the agent's currently live run, or null when none is
    * live (mid-redeploy). */
   readonly liveAddress: string | null;
-  /** The newest deployment's status for this agent's asset — `undefined`
-   * when it has never been deployed. `"pending"`/`"recovering"` mean a run
-   * is on the way up; a terminal status (`released`, `failed`,
-   * `destroy_failed`, `stopped`) means nothing is running and nothing is
-   * coming unless someone restarts it. */
+  // A terminal status means nothing is running and nothing is coming
+  // unless someone restarts it.
   readonly latestStatus: string | undefined;
 };
 
 const LIVE_DEPLOYMENT_STATUSES = new Set(["deployed", "pending", "recovering"]);
-/** A deployment status that means a run is on the way up but not live yet
- * — distinct from a terminal status, which means nothing is running. */
+// On the way up but not live yet, distinct from a terminal status.
 export const STARTING_DEPLOYMENT_STATUSES = new Set(["pending", "recovering"]);
 
 const DeploymentsSchema = WorkflowDeploymentResponse.array();
@@ -91,10 +77,8 @@ export type ChatSummary = {
   readonly lastMessageId: string;
 };
 
-/** Myra is the one default agent; her deploy asset name is not a display
- * name anyone should have to read. Any other agent's deploy asset name
- * encodes its slug (`agent-<slug>-source`), which renders title-cased with
- * hyphens as spaces ("echo-bot" -> "Echo Bot"). */
+// Myra's deploy asset name is not a display name anyone should read;
+// every other agent's slug renders title-cased ("echo-bot" -> "Echo Bot").
 export function displayAgentName(definitionName: string): string {
   if (definitionName === MYRA_SOURCE_CONFIG.assetName) return MYRA_SOURCE_CONFIG.displayName;
   const slug = agentSlugFromSourceAssetName(definitionName);
@@ -125,11 +109,8 @@ function workflowAssetsPath(tenantId: string): string {
   return `/api/tenants/${encodeURIComponent(tenantId)}/assets?kind=workflow&inherited=false`;
 }
 
-/** Every agent the person has ever had a deployment of, keyed by its
- * definition asset id. Deployments list every anchor run ever created for
- * an asset (releases included, most recent first), joined here against the
- * run listing for each run's address and against the workflow assets for a
- * display name. */
+// Deployments list every anchor run ever created (releases included, newest
+// first), joined against runs for addresses and assets for a display name.
 export async function listChatAgents(tenantId: string): Promise<readonly ChatAgent[]> {
   const [deployments, assets, runs] = await Promise.all([
     getJson(deploymentsPath(tenantId), DeploymentsSchema),
@@ -174,10 +155,7 @@ export async function listChatAgents(tenantId: string): Promise<readonly ChatAge
   });
 }
 
-/** True once an agent's latest deployment has gone terminal (or it has
- * never been deployed) — nothing is running and nothing is coming up on
- * its own; a restart is the only way forward. False while a run is live or
- * still on its way up (`pending`/`recovering`). */
+// True once terminal (or never deployed): nothing is coming up on its own.
 export function isAgentNotRunning(agent: Pick<ChatAgent, "liveAddress" | "latestStatus">): boolean {
   if (agent.liveAddress !== null) return false;
   return agent.latestStatus === undefined || !STARTING_DEPLOYMENT_STATUSES.has(agent.latestStatus);
@@ -474,12 +452,8 @@ export type ChatThread = {
   readonly messages: readonly ChatMessage[];
 };
 
-/** A chat is always titled by its agent's display name — never by mail
- * metadata, which can be a run address or other addressing detail nobody
- * should have to read. `agentName` is `undefined` only when the agent
- * couldn't be resolved at all, in which case the title falls back to the
- * person's own opening turn (never an agent reply, so a chat never titles
- * itself off what the agent said). */
+// Falls back to the person's own opening turn (never an agent reply) only
+// when the agent couldn't be resolved at all.
 export function chatTitle(turns: readonly MailTurn[], agentName: string | undefined): string {
   if (agentName !== undefined) return agentName;
   const first = turns.find((turn) => turn.author === "me");
@@ -525,11 +499,8 @@ export async function listChats(tenantId: string): Promise<readonly ChatSummary[
     .sort((a, b) => Date.parse(b.lastActivityAt) - Date.parse(a.lastActivityAt));
 }
 
-// ---------------------------------------------------------------------
-// Reply-ready: a chat is unread until it has been opened at its newest
-// message. Tracked per-viewer in localStorage — a convenience, not data of
-// record, so a missing/blocked store just falls back to "ready".
-// ---------------------------------------------------------------------
+// Reply-ready: tracked per-viewer in localStorage, a convenience not data
+// of record, so a missing/blocked store just falls back to "ready".
 
 const CHAT_SEEN_KEY_PREFIX = "workbench:chat-seen:";
 
@@ -598,12 +569,7 @@ export function subscribeToInbox(tenantId: string, onChange: () => void): () =>
   };
 }
 
-// ---------------------------------------------------------------------
-// Workbenches: a workbench is a child tenant, and its workbench conversation is that
-// tenant's mailbox. Reads are the same stock mailbox routes as a chat,
-// scoped to the child tenant id; participants are the child tenant's
-// principals.
-// ---------------------------------------------------------------------
+// Workbenches: see docs/chat-mail-threading.md.
 
 export type WorkbenchParticipant = {
   readonly id: string;
@@ -629,14 +595,8 @@ const PrincipalPage = type({
   nextCursor: "string | null",
 });
 
-/** Everyone in the workbench: the child tenant's principals plus its live
- * deployments' run addresses. A deployment's workflow principal only
- * appears after its first run, so the run listing is what makes an agent
- * addressable from the moment it is deployed into the workbench. `tenantDomain`
- * is the workbench tenant's own domain (already fetched by the caller) — a
- * person's routable mailbox address is `<refId>@<tenantDomain>`, exactly
- * what the hub builds and the mailbox delivers to; their email and refId
- * alone are never routable. */
+// A deployment's workflow principal only appears after its first run, so
+// the run listing is what makes an agent addressable from deploy time.
 export async function listWorkbenchParticipants(
   tenantId: string,
   tenantDomain: string,
@@ -687,10 +647,8 @@ function authorName(address: string): string {
   return local.length > 0 ? local : address;
 }
 
-/** Case-insensitive whole-address match: the mailbox lowercases local parts
- * on the wire, so a sent message's header `from` (mixed case) and envelope
- * `from` (lowercase) both name the same participant. Never lowercases
- * stored data — comparison only. */
+// Case-insensitive: the mailbox lowercases local parts on the wire, so a
+// header `from` (mixed case) and envelope `from` (lowercase) still match.
 export function sameAddress(a: string, b: string): boolean {
   return a.toLowerCase() === b.toLowerCase();
 }
@@ -708,10 +666,7 @@ export function resolveParticipantName(
   );
 }
 
-/** A turn's avatar name: the matching participant's real name, including
- * the person's own — never the "You" transcript label, which stays for the
- * row's own text elsewhere. Falls back to `resolveParticipantName` when no
- * participant matches the turn's address. */
+// Never the "You" transcript label, which stays for the row's own text.
 export function resolveAvatarName(
   message: Pick<WorkbenchMessage, "author" | "authorName" | "address">,
   participants: readonly WorkbenchParticipant[],
@@ -755,10 +710,8 @@ async function readWorkbenchFolder(
   }));
 }
 
-/** The workbench timeline: every turn oldest first, flat — no turn is ever
- * dropped from the main list. A turn whose in-reply-to names a known
- * message keeps that as `parentMessageId`, metadata for the sub-thread
- * panel to walk the ancestor chain of whichever turn the person opened. */
+// Flat, oldest first — no turn is ever dropped from the main list.
+// `parentMessageId` is metadata for the sub-thread panel only.
 export async function readWorkbench(tenantId: string): Promise<readonly WorkbenchMessage[]> {
   const [inbox, sent] = await Promise.all([
     readWorkbenchFolder(tenantId, "INBOX"),
@@ -799,14 +752,8 @@ export function ancestorChain(
   return chain;
 }
 
-/** The one send seam for a workbench: a single mailbox send addressed to every
- * agent in it. The hub triggers each addressed run and keeps the Sent
- * copy, so the person's own turn comes back out of the mailbox like any
- * other. The body carries a trailing roster of every agent's name and
- * run address plus the person's own (the same rows the Participants panel
- * reads), so an agent can hand a task to another agent in the workbench — the
- * hub only delivers to a run address, which only the client otherwise
- * knows — and can copy the person on that handoff so they can follow it. */
+// The one send seam for a workbench (see docs/chat-mail-threading.md for
+// the roster mechanism).
 export async function sendToWorkbench(input: {
   readonly workbenchTenantId: string;
   readonly participants: readonly WorkbenchParticipant[];
diff --git a/apps/web/src/chat/tool-activity-view.tsx b/apps/web/src/chat/tool-activity-view.tsx
index f5fd94e87..421b95b7f 100644
--- a/apps/web/src/chat/tool-activity-view.tsx
+++ b/apps/web/src/chat/tool-activity-view.tsx
@@ -1,12 +1,5 @@
-// How a turn's tool calls sit in the conversation.
-//
-// One presentation serves both the live strip (`turn-activity.tsx`) and the
-// persisted transcript (`timeline.tsx`), so a call that reads one way while
-// it runs doesn't restyle itself the moment the turn ends. Chips, not
-// collapsibles: a glyph, one sentence, a status icon, and — only when there
-// is something to show — a disclosure onto plain-text detail. Calls stack
-// one per call; nothing here ever folds several into a count. The sentences
-// come from `tool-activity.ts`; nothing here formats a tool's own data.
+// One presentation serves both the live strip and the persisted
+// transcript, so a call doesn't restyle itself when the turn ends.
 
 import {
   BookBookmark,
@@ -158,12 +151,8 @@ function ToolActivityLine({
   );
 }
 
-/**
- * A run of consecutive tool calls, stacked one chip per call — never
- * folded into a summary line (§12.3: chips are not collapsibles). Each
- * chip keeps its own disclosure onto its detail; there is no group-level
- * trigger and no count of how many calls happened.
- */
+// Never folded into a summary line (DESIGN.md §12.3: chips, not
+// collapsibles) — no group-level trigger, no count.
 export function ToolActivityGroup({ rows }: { readonly rows: readonly ToolActivityRow[] }) {
   if (rows.length === 0) return null;
   return (
@@ -175,10 +164,8 @@ export function ToolActivityGroup({ rows }: { readonly rows: readonly ToolActivi
   );
 }
 
-/**
- * The mid-turn strip: the same rows, plus the two things that only exist
- * while a turn is open — the model thinking, and a retried request.
- */
+// Plus the two things that only exist while a turn is open: thinking and
+// a retried request.
 export function LiveToolActivity({
   rows,
   thinking,
diff --git a/apps/web/src/chat/tool-activity.ts b/apps/web/src/chat/tool-activity.ts
index fbaf948e5..695c2491c 100644
--- a/apps/web/src/chat/tool-activity.ts
+++ b/apps/web/src/chat/tool-activity.ts
@@ -1,24 +1,6 @@
-// Turning a turn's tool calls into something a person can read.
-//
-// The wire carries a tool call as an identifier plus an argument bag plus
-// whatever the tool handed back (`ToolTracePart` in `@/chat/wire/parts`,
-// assembled by the chat orchestrator from `inferenceDoneBlocks` /
-// `toolDoneResult`). None of those three is fit to show anyone: the
-// identifier is a symbol (`slack__post_message`, or an Interchange qualified
-// id `@scope/package/export:tool`), the arguments are JSON, and the result
-// is usually a content-block array. This module is the one place that
-// translates all three into plain sentences — "Posted a message in Slack",
-// "Searched memory for "outbound"" — so no surface downstream ever has to
-// reach for `JSON.stringify` to say what happened. The phrase uses the
-// segment after the last colon (the end tool name); a leftover path is a
-// provider only when it maps onto a known brand, never `@corbits` or a
-// package stem like `memory-tools`.
-//
-// Both the live strip (`turn-activity.tsx`, mid-turn) and the persisted
-// transcript (`timeline.tsx`) render through here, which is why a phrase
-// comes in two tenses: the same call reads "Searching the web for
-// "pricing"" while it runs and "Searched the web for "pricing"" once it
-// settles.
+// Translates a tool call into a plain sentence, so no downstream surface
+// reaches for `JSON.stringify`. Two tenses since both the live strip and
+// the persisted transcript render through here.
 
 import type { Part, ToolTracePart } from "./wire/parts";
 
@@ -120,10 +102,8 @@ export type ProviderTile = {
   readonly color: string;
 };
 
-/** Brand mark for the chip's leading tile — two letters and the provider's
- * own color, the way the mock's `[Li #5E6AD2]` / `[GH #24292f]` read. Only
- * providers a person would recognise on sight get a fixed brand color;
- * anything else is not a brand — the chip uses an action glyph. */
+// Only providers a person would recognise on sight get a fixed brand
+// color; anything else uses an action glyph.
 const PROVIDER_TILES: Record<string, ProviderTile> = {
   github: { initials: "GH", color: "#24292f" },
   gitlab: { initials: "GL", color: "#fc6d26" },
@@ -244,21 +224,9 @@ function splitQualifiedName(name: string): {
   return { leftover: undefined, toolName: name };
 }
 
-/**
- * Splits a tool identifier into the provider it belongs to and the words
- * describing what it does.
- *
- * `mcp_read`/`mcp_call` are the generic MCP dispatch tools
- * (`tools/mcp/src/tool.ts`): every downstream call arrives under
- * one of those two names, with the tool it actually invoked sitting in its
- * `{server, tool}` arguments — so those are read first, or a whole
- * conversation's worth of calls would all read alike.
- *
- * Interchange qualified ids (`@scope/package/export:tool`) take the
- * segment after the last `:`. A leftover path is a provider only when a
- * segment or `-tools` stem is a known brand; `memory`, `ad`, and
- * `ask-user` never are.
- */
+// `mcp_read`/`mcp_call` are generic MCP dispatch tools: the tool actually
+// invoked sits in `{server, tool}` args, so those are read first — or a
+// whole conversation's calls would all read alike.
 export function resolveToolIdentity(name: string, input: unknown): ToolIdentity {
   const args = asRecord(input);
   if (name === "mcp_read" || name === "mcp_call") {
@@ -305,11 +273,8 @@ function hostname(url: string): string | undefined {
   return host.replace(/^www\./, "");
 }
 
-/**
- * The one argument worth putting in the sentence, as the clause that
- * carries it. Precedence is explicit and ordered — a search tool given
- * both a query and a path is describing the query.
- */
+// Precedence is explicit and ordered — a search tool given both a query
+// and a path is describing the query.
 function argumentClause(input: unknown): string | undefined {
   const args = asRecord(input);
   if (args === undefined) return undefined;
@@ -429,11 +394,8 @@ function domainHead(words: readonly string[], verb: string, tense: Tense): strin
   return undefined;
 }
 
-/**
- * What this tool call did, as a sentence — in the tense its status calls
- * for. Never contains the tool's identifier, its argument JSON, or an
- * internal id.
- */
+// Never contains the tool's identifier, its argument JSON, or an internal
+// id.
 export function describeToolCall(name: string, input: unknown, tense: Tense): string {
   const identity = resolveToolIdentity(name, input);
   const clause = argumentClause(input);
@@ -481,12 +443,8 @@ function decodeOutput(output: unknown): unknown {
   }
 }
 
-/**
- * Pulls readable prose out of whatever a tool handed back. Tool results
- * arrive as a string, as MCP content blocks, or as an arbitrary object;
- * only the first two carry anything worth showing a person, and this
- * returns undefined rather than stringifying the third.
- */
+// Returns undefined for an arbitrary-object result rather than
+// stringifying it.
 export function plainTextOfOutput(output: unknown): string | undefined {
   const decoded = decodeOutput(output);
   if (typeof decoded === "string") {
@@ -536,11 +494,8 @@ function looksLikeContentBlocks(output: unknown): boolean {
   });
 }
 
-/**
- * The detail a row opens onto: plain text, always. A failure keeps its
- * first line — the reason, said plainly — and never goes silent: a tool
- * that fails without saying why still says that much.
- */
+// A failure keeps its first line and never goes silent, even when the
+// tool didn't say why.
 export function summarizeToolOutput(
   status: ToolActivityStatus,
   output: unknown,
@@ -614,13 +569,8 @@ export type TimelinePartGroup =
       readonly key: string;
     };
 
-/**
- * Splits a message's parts into render groups, clustering every run of
- * consecutive tool calls together. The cluster renders as a stack of
- * chips, one per call — never folded into a summary line — so this is
- * purely about keeping tool calls next to each other in the flow, not
- * about hiding them.
- */
+// Clusters consecutive tool calls into a stack of chips, never folded
+// into a summary line.
 export function groupTimelineParts(
   parts: readonly Part[],
   keyPrefix: string,
diff --git a/apps/web/src/chat/turn-activity.tsx b/apps/web/src/chat/turn-activity.tsx
index 1c380ecfa..c1c5dde64 100644
--- a/apps/web/src/chat/turn-activity.tsx
+++ b/apps/web/src/chat/turn-activity.tsx
@@ -1,17 +1,5 @@
-// The live "what is the agent doing right now" strip for an in-flight
-// turn: `chat.agent` events already carry the vendored Interchange
-// `InferenceEvent` union verbatim (see `streaming-reply.ts`'s header for
-// the wire path), but that module only ever reads `inference.text.delta`
-// and the turn-boundary events — every tool call, thinking delta, and
-// retry is dropped on the floor. This module is the trust boundary that
-// narrows those other event shapes (`inference.tool_call.*`, `tool.*`,
-// `inference.thinking.delta`, `inference.retry` — see
-// `@intx/types/src/runtime.ts`'s `InferenceEvent`) and the pure
-// state machine that turns them into one turn's activity list, plus the
-// hook and presentational strip that render it. v1 is live-only: the
-// strip disappears the moment the turn ends (`nextTurnActivityState`
-// returns `null`), same as `streaming-reply.ts`'s reply text — no
-// persisted trace yet.
+// v1 is live-only: the strip disappears the moment the turn ends, same as
+// `streaming-reply.ts`'s reply text — no persisted trace yet.
 
 import { useEffect, useState } from "react";
 
@@ -110,15 +98,9 @@ function parseToolDone(data: unknown): { callId: string; isError: boolean } | nu
   return { callId, isError: result.isError === true };
 }
 
-/**
- * `inference.thinking.delta`'s `data.partial.thinking` is cumulative, same
- * as `partial.text` (see `PartialMessage` in
- * `@intx/types/src/runtime.ts`) — so the ordinary case replaces the
- * char count outright. `thinking` is typed optional on `PartialMessage`;
- * if a future adapter omits it on the delta event, falling back to the
- * per-delta `token`'s length keeps the counter moving (as an increment,
- * not a replacement, since `token` is only ever the new fragment).
- */
+// `partial.thinking` is cumulative, so the ordinary case replaces the char
+// count outright; a future adapter omitting it falls back to `token`'s
+// length as an increment instead.
 function parseThinkingDelta(
   data: unknown,
 ): { kind: "cumulative" | "increment"; charCount: number } | null {
@@ -143,11 +125,8 @@ function parseRetry(data: unknown): { attempt: number } | null {
   return typeof attempt === "number" ? { attempt } : null;
 }
 
-/** Records (or refines) one tool call, opening a new running row if
- * `callId` hasn't been seen yet this turn. Never touches `startedAtMs`,
- * `status`, or `doneAtMs` on an existing entry — `inference.tool_call.end`
- * and `tool.start` only ever add the arguments a row already opened by an
- * earlier event was missing. */
+// Never touches `startedAtMs`/`status`/`doneAtMs` on an existing entry —
+// a later event only ever fills in arguments an earlier one was missing.
 function upsertToolCall(
   toolCalls: readonly ToolCallActivity[],
   call: {
@@ -195,18 +174,9 @@ function settleToolCall(
   );
 }
 
-/**
- * The current turn's whole activity state machine, pure: `reactor.start`
- * clears it (a fresh turn owns none of the previous turn's chips),
- * `reactor.done`/`reactor.error`/`inference.done`/`inference.error`
- * finalize it to `null` (the turn is over), and every tool-call,
- * thinking, and retry event in between updates the open state — opening
- * one implicitly if none exists yet, so activity that arrives before a
- * `reactor.start` (or in a test driving events directly) is never
- * silently dropped. Kept separate from the `useState` that holds it in
- * `useTurnActivity`, matching `nextStreamingReplyState`'s split in
- * `streaming-reply.ts`.
- */
+// Opens the activity implicitly if none exists yet, so an event arriving
+// before `reactor.start` is never silently dropped. Kept pure and separate
+// from the `useState` that holds it, matching `nextStreamingReplyState`.
 export function nextTurnActivityState(
   current: TurnActivityState,
   event: { readonly eventType: string; readonly data: unknown },
@@ -309,25 +279,13 @@ export function nextTurnActivityState(
   return { ...base, thinking };
 }
 
-/** How long an open turn may sit with no consumed event before the strip
- * clears itself — the backstop for a turn whose `reactor.done`/
- * `inference.done` (or `.error`) never arrives (agent down, SSE dropped
- * mid-reconnect), mirroring `streaming-reply.ts`'s
- * `PENDING_REPLY_CLEAR_MS`. */
+// Backstop for a turn whose done/error event never arrives (agent down,
+// SSE dropped mid-reconnect), mirroring `streaming-reply.ts`.
 const TURN_ACTIVITY_STALE_MS = 120_000;
 
-/**
- * Owns the turn-activity state end to end, mirroring
- * `useStreamingReply`'s shape exactly: feed it every stream event and it
- * tracks the active turn's tool calls, thinking, and retries, clearing
- * the moment the turn ends. `workbenchId` resets it immediately on a
- * workbench switch — activity from the workbench just left belongs to that
- * workbench, not the new one. `staleMs` (default `TURN_ACTIVITY_STALE_MS`)
- * is a test seam, mirroring `useTypingIndicator`'s own configurable
- * timeout. `clock` (default `REAL_CLOCK`) is the same kind of seam for the
- * wall-clock reads and the backstop timer itself — a test drives both
- * synchronously with a fake clock instead of sleeping on the real one.
- */
+// `workbenchId` resets state immediately on a workbench switch — activity
+// from the one just left doesn't belong to the new one. `staleMs`/`clock`
+// are test seams so a test can drive time synchronously.
 export function useTurnActivity(
   workbenchId: string | null,
   staleMs: number = TURN_ACTIVITY_STALE_MS,
@@ -346,11 +304,8 @@ export function useTurnActivity(
     setActivity(null);
   }
 
-  // Reset (clear + re-arm) on every event that actually changes the
-  // activity object — an ignored event never resets the clock, since
-  // nothing about the open turn changed. A dropped stream leaves
-  // `activity` referentially stable forever, so this timer is the only
-  // thing that ever clears it in that case.
+  // This timer is the only thing that clears `activity` if the stream
+  // drops and leaves it referentially stable forever.
   useEffect(() => {
     if (activity === null) return;
     const timer = clock.setTimeout(() => {
@@ -370,12 +325,8 @@ function elapsedSeconds(startedAtMs: number, endMs: number): number {
   return Math.max(0, Math.round((endMs - startedAtMs) / 1000));
 }
 
-/**
- * This turn's tool calls as the rows the conversation renders everywhere
- * else — same sentences, same statuses. A call still running says so in
- * the present tense and carries how long it has been going; a settled one
- * drops the timer, since a finished step's duration is noise.
- */
+// A running call carries how long it's been going; a settled one drops
+// the timer, since a finished step's duration is noise.
 export function toolActivityRows(
   activity: NonNullable<TurnActivityState>,
   nowMs: number,
@@ -397,12 +348,7 @@ export function toolActivityRows(
   });
 }
 
-/**
- * The live strip: one row per tool call this turn, a "Thinking…" row while
- * thinking deltas are flowing, and a retry note if the model's own request
- * needed one. Renders nothing once the turn ends — the persisted message
- * takes over from there, in the same row idiom.
- */
+// Renders nothing once the turn ends — the persisted message takes over.
 export function TurnActivityStrip({ activity }: { readonly activity: TurnActivityState }) {
   const hasRunningToolCall = activity?.toolCalls.some((call) => call.status === "running") ?? false;
   const [, forceTick] = useState(0);
diff --git a/apps/web/src/chat/wire/agent-address.ts b/apps/web/src/chat/wire/agent-address.ts
index 06d4699c2..0e655ef7f 100644
--- a/apps/web/src/chat/wire/agent-address.ts
+++ b/apps/web/src/chat/wire/agent-address.ts
@@ -1,18 +1,7 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md).
 
-// Agent-address helpers shared by this package's own fan-out
-// (`routes.ts`) and by `@/chat`'s composer: splitting an
-// address into its local part and domain. Mirrors the split
-// `@intx/types/src/agent-address.ts`'s `parseAgentAddress` does,
-// but stays permissive about the left-hand side on purpose — the
-// mention rule (see `mentions.ts`) only ever needs the substring before
-// the first "@", never a validated `ins_`-prefixed instance id, so it
-// tolerates any participant string rather than rejecting non-address
-// ones the way `parseAgentAddress` does.
+// Deliberately permissive, unlike `@intx/types`'s `parseAgentAddress`: the
+// mention rule only needs the substring before "@", not a validated id.
 
 export function localPartOf(address: string): string {
   const at = address.indexOf("@");
diff --git a/apps/web/src/chat/wire/blocks.ts b/apps/web/src/chat/wire/blocks.ts
index 5acf5bb42..92e4923d5 100644
--- a/apps/web/src/chat/wire/blocks.ts
+++ b/apps/web/src/chat/wire/blocks.ts
@@ -1,26 +1,15 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md) — apps/web
+// must not import @corbits/chat, a server-only package.
 
 import { type } from "arktype";
 
 import type { BlockPart } from "./parts";
 
-// The typed vocabulary for `BlockPart.block` payloads. `BlockPart` stays
-// `{ type: string, data: unknown }` on the wire so unknown types degrade to
-// a labeled fallback instead of failing the whole message; `parseBlock` is
-// the render-boundary parse that turns that envelope into a typed block.
-// Every schema strips undeclared keys deeply: agent-authored extras (say, a
-// hostile `tally` object on a poll) must never ride along on the parsed
-// object a renderer trusts.
+// Every schema strips undeclared keys deeply so agent-authored extras (a
+// hostile `tally` on a poll) never reach a renderer that trusts them.
 
-// An approve block carries only a reference to a platform approval plus the
-// agent's framing. It deliberately has no action labels and no resolved
-// state: free-form button text on an approval card is a spoofing surface,
-// and the decision's status lives on the approval record, never in the
-// message.
+// No action labels or resolved state: those live on the approval record,
+// never in the message, so an agent can't spoof a decision.
 export const ApproveBlockData = type({
   approvalId: "string",
   title: "string",
@@ -65,16 +54,9 @@ export const StreamBlockData = type({
 }).onDeepUndeclaredKey("delete");
 export type StreamBlockData = typeof StreamBlockData.infer;
 
-// An agent-authored "connect this service" card, the
-// generalization of `connect-github` to every connector and MCP preset:
-// `request_connection` posts one of these instead of a prose deep link.
-// It carries only the framing the agent decided — which service, and the
-// consumer-language reason it would unlock — never an auth mode or a
-// connected/disconnected verdict: an agent that could author "connected"
-// (or steer OAuth vs key-paste) would be spoofing live state next to a
-// live button. The card's real state and connect affordance come from a
-// host-supplied actions port resolved against the tenant's actual
-// connections at render time.
+// No auth mode or connected/disconnected verdict: an agent that could author
+// "connected" would be spoofing live state next to a live button. Real
+// state and the connect affordance come from the host at render time.
 export const ConnectServiceBlockData = type({
   connectorId: "string > 0",
   displayName: "string > 0",
@@ -96,12 +78,7 @@ export type BlockParseResult =
   | { readonly ok: true; readonly block: Block }
   | { readonly ok: false; readonly type: string; readonly summary: string };
 
-/**
- * Parse a `BlockPart` envelope into a typed block at the render boundary.
- * An unknown type or invalid data yields an `ok: false` result for the
- * caller's fallback card — never a throw, so one malformed block can't take
- * down a timeline.
- */
+// Never throws, so one malformed block can't take down a timeline.
 export function parseBlock(envelope: BlockPart["block"]): BlockParseResult {
   switch (envelope.type) {
     case "approve": {
diff --git a/apps/web/src/chat/wire/consumer-inference-text.ts b/apps/web/src/chat/wire/consumer-inference-text.ts
index 3f2431018..7a6c57ef1 100644
--- a/apps/web/src/chat/wire/consumer-inference-text.ts
+++ b/apps/web/src/chat/wire/consumer-inference-text.ts
@@ -1,14 +1,7 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md).
 
-/**
- * Person-facing inference copy. HTTP status, raw provider dumps, and
- * JSON error objects never belong on the timeline, in a sidebar preview,
- * or next to the composer — DESIGN.md Honesty is one consumer sentence.
- */
+// HTTP status, raw provider dumps, and JSON error objects never belong on
+// the timeline — DESIGN.md Honesty is one consumer sentence.
 
 import {
   TOOLS_UNSUPPORTED_CONSUMER_MESSAGE,
@@ -21,13 +14,8 @@ const TRAILING_HTTP_DUMP = /\s*\[HTTP\s+\d+\]:[\s\S]*$/i;
 export const CONSUMER_INFERENCE_FAILURE_NOTICE =
   "This didn't go through. Try again, or check the connection in Settings.";
 
-/**
- * Byte-for-byte copies of the two preambles `@intx/inference`'s
- * `formatInferenceError` writes for `credential_failure` and
- * `quota_exhausted`. Kept here so the bench-list preview path
- * can refuse them without depending on `@/chat`. The chat-ui
- * drift guard still owns matching these against the published director.
- */
+// Byte-for-byte copies of `@intx/inference`'s preambles, kept here so the
+// bench-list preview path can match them without depending on `@/chat`.
 export const CLASSIFIED_INFERENCE_FAILURE_PREAMBLES: readonly string[] = [
   "This agent could not complete your request due to a credential error",
   "This agent could not complete your request because the API quota has been exhausted",
@@ -67,11 +55,7 @@ export function isClassifiedInferenceFailureText(text: string): boolean {
   return CLASSIFIED_INFERENCE_FAILURE_PREAMBLES.some((preamble) => text.startsWith(preamble));
 }
 
-/**
- * Bench-list / sidebar preview copy: never the full failure
- * paragraph, never HTTP/raw provider dumps — a short consumer sentence
- * when the text is a classified failure.
- */
+// Never the full failure paragraph or raw provider dumps.
 export function activityPreviewText(raw: string): string {
   const facing = consumerFacingInferenceText(raw);
   return facing;
diff --git a/apps/web/src/chat/wire/display-name.ts b/apps/web/src/chat/wire/display-name.ts
index d73fbaa12..426964d7b 100644
--- a/apps/web/src/chat/wire/display-name.ts
+++ b/apps/web/src/chat/wire/display-name.ts
@@ -1,17 +1,7 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md).
 
-// A workflow definition's person-facing display name, derived once here
-// so every caller that decides "what does this agent look like to a
-// person" reads it the same way — never a scattered `description ?? name`
-// (or worse, a raw address/run id) reimplemented per call site.
-//
-// Lives in `@/chat/wire` (mirrored from `@corbits/chat`'s
-// `workbench-host-naming`) so this browser-facing surface never needs a
-// server-only chat import.
+// One derivation for "what does this agent look like to a person", never a
+// scattered `description ?? name` reimplemented per call site.
 import { type } from "arktype";
 import { ID_LEAK_PATTERN } from "./id-leak-guard";
 
@@ -20,13 +10,8 @@ const DisplayNameSource = type({
   "description?": "string | null",
 });
 
-/** kebab-case identifier -> Title Case words: `"research-analyst"` ->
- * `"Research Analyst"`. Words that aren't hyphen-separated (a name that
- * already reads as prose) pass through with only their case fixed up, so
- * this is safe to run over a definition's raw `name` unconditionally —
- * PROVIDED that `name` is never an internal id in disguise; see
- * `deriveDisplayName`'s own guard for why the raw run-id case never
- * reaches this function at all. */
+// Safe to run over a raw `name` only because `deriveDisplayName` already
+// guards against an internal id reaching this function.
 export function humanizeSlug(slug: string): string {
   return slug
     .split(/[-_\s]+/)
@@ -35,21 +20,9 @@ export function humanizeSlug(slug: string): string {
     .join(" ");
 }
 
-/**
- * The display name a definition should render as: its own description
- * when one was set at creation, otherwise a humanized reading of its
- * immutable slug. A whitespace-only description reads as absent — never
- * a blank display name — since it carries nothing a person actually
- * typed. Throws on a shape that isn't at least `{ name }` — this is a
- * trust boundary, not a formatting helper, so a malformed record fails
- * loudly rather than rendering "undefined".
- *
- * Also throws when `name` is itself an internal-id shape (`run_…`,
- * `wfd_…`, …, see `./id-leak-guard`) — the product rule is that a person
- * never sees an internal identifier, so a caller that reaches this
- * function with a run id where a definition's slug belongs gets a loud
- * failure instead of a Title-Cased leak like "Run 737a058d…".
- */
+// A trust boundary, not a formatter: throws on a malformed record and on a
+// `name` that is itself an internal id, rather than leaking one into a
+// rendered display name.
 export function deriveDisplayName(definition: {
   readonly name: string;
   readonly description?: string | null;
@@ -87,9 +60,8 @@ export type UserFacingAgentDefinition = {
 
 export type WithDisplayName<T> = T & { readonly displayName: string };
 
-/** Projects `deriveDisplayName` onto a definition, keeping every other
- * field untouched — the read-boundary derivation done once here rather
- * than as scattered `??` fallbacks in UI code. */
+// Read-boundary derivation, done once rather than as scattered `??`
+// fallbacks in UI code.
 export function withDisplayName<T extends UserFacingAgentDefinition>(
   definition: T,
 ): WithDisplayName<T> {
diff --git a/apps/web/src/chat/wire/id-leak-guard.ts b/apps/web/src/chat/wire/id-leak-guard.ts
index fb0b1c5b9..a211c119d 100644
--- a/apps/web/src/chat/wire/id-leak-guard.ts
+++ b/apps/web/src/chat/wire/id-leak-guard.ts
@@ -1,28 +1,8 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md, which
+// also covers this file's rationale).
 
-// The guard: a person never sees an internal
-// identifier — not as a participant's name, not in a join/system line,
-// not in a greeting, not in a chat title. This has recurred repeatedly
-// (a raw definitionId/runId in insights, a `writing_systems` id in a
-// Myra reply, and the "Run 737a058d…" / "I'm run_737a…") each
-// time as a one-off display-time patch; this module is the one place
-// every id-generating prefix is named, so a new leak is a missed test
-// run rather than a missed grep.
-//
-// Prefix words mirror `@intx/hub-common`'s `generateId` (vendored;
-// upstream source: `packages/hub-common/src/ids.ts`'s `PREFIXES`) for
-// the six kinds named explicitly — a workflow run, a workflow
-// definition, a tenant, a principal, an asset, and a git token — each
-// normally followed by `_` and 32 lowercase hex characters (`run_737a…`).
-//
-// Matched with either `_`, a space, or `-` as the separator, not just
-// `_`: `humanizeSlug`'s Title Case reading of a leaked id (its own
-// "Run 737a058d48006e2bde12559576f422e0") replaces the underscore with a
-// space, so the raw and the humanized-leak forms both need to trip this.
+// Matches `_`, space, or `-` as separator so both the raw id and
+// `humanizeSlug`'s Title-Cased reading of one ("Run 737a058d…") trip it.
 const ID_PREFIX_WORDS = ["run", "wfd", "tnt", "prn", "ast", "gtk"] as const;
 
 export const ID_LEAK_PATTERN = new RegExp(
@@ -30,15 +10,8 @@ export const ID_LEAK_PATTERN = new RegExp(
   "i",
 );
 
-/**
- * Throws when `value` carries an internal identifier — a raw id, or a
- * humanized reading of one (`"Run 737a058d…"`, produced by title-casing
- * `run_737a058d…`'s underscore split). The humanized case is why this
- * checks the ORIGINAL prefixes case-insensitively rather than requiring
- * the literal lowercase prefix: `humanizeSlug` capitalizes the first
- * letter of the leading word, so a leaked run id renders as "Run …", not
- * "run …", by the time it would reach a person.
- */
+// Case-insensitive because `humanizeSlug` capitalizes the leading word
+// ("Run …") before this would ever see it.
 export function assertNoLeakedInternalId(value: string, context: string): void {
   if (ID_LEAK_PATTERN.test(value)) {
     throw new Error(
diff --git a/apps/web/src/chat/wire/mentions.ts b/apps/web/src/chat/wire/mentions.ts
index cd682057f..ff36c43c1 100644
--- a/apps/web/src/chat/wire/mentions.ts
+++ b/apps/web/src/chat/wire/mentions.ts
@@ -1,28 +1,14 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md).
 
-// The "@ + handle" mention rule: the single wire-level contract between
-// the composer (`@/chat`'s `mentions.ts`, which derives
-// candidates from a workbench's participant records and splices the
-// picked handle into the draft) and this package's own fan-out
-// (`routes.ts`'s `POST /workbenches/:id/messages`). Both sides work off
-// the same `ParticipantRecord[]` (see `participants.ts`), so a message
-// the composer thinks mentions a participant is always exactly the set
-// the server fans a copy to — the handle is the friendly, settings-held
-// mention name, never the instance-id local part.
+// The composer and the server fan-out both derive mentions from the same
+// `ParticipantRecord[]`, so what the composer highlights is always exactly
+// who gets a copy.
 
 import type { Part as PartType } from "./parts";
 import type { ParticipantRecord } from "./participants";
 
-/**
- * A participant is an agent address (mention-fannable) when it has the
- * `local@domain` shape every agent address has and is not a principal.
- * Humans are `prn_…` — bare or `prn_…@tenant.domain` — and read the
- * workbench's own timeline directly, so they are never fanned a copy.
- */
+// Humans (`prn_…`) read the workbench timeline directly and are never
+// fanned a copy; only agent addresses are.
 export function isAgentAddress(participant: string): boolean {
   return participant.includes("@") && !participant.startsWith("prn_");
 }
@@ -31,14 +17,8 @@ function escapeForRegExp(text: string): string {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
-/**
- * The participants an ordinary message @mentions, restricted to agent
- * addresses: the fan-out set for `POST /workbenches/:id/messages`. A
- * mention is structural — `@` followed by the participant's own handle
- * at a word boundary, appearing in any `TextPart` of the message — not
- * a full parse of mention syntax; kept minimal per the anchor-mailbox
- * rework's scope.
- */
+// Structural match only (`@handle` at a word boundary) — not a full mention
+// syntax parse.
 export function mentionedParticipants(
   parts: readonly PartType[],
   participants: readonly ParticipantRecord[],
diff --git a/apps/web/src/chat/wire/participants.ts b/apps/web/src/chat/wire/participants.ts
index f9f4d989b..7c2e85a0a 100644
--- a/apps/web/src/chat/wire/participants.ts
+++ b/apps/web/src/chat/wire/participants.ts
@@ -1,19 +1,7 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md).
 
-// Workbench participant records: the settings-backed source of mention
-// handles. `chat/participants` (see `routes.ts`'s `ChatNamespaceSchemas`)
-// holds `ParticipantRecord[]` — an address plus the short,
-// unique-within-workbench handle a mention actually types (`@echo`), never
-// the unusable instance-id local part (`@ins_cd03d8e3...`). Reading
-// tolerates a bare address string too — a participant seeded before this
-// record shape existed, or a caller PATCHing `chat/participants` with
-// plain addresses — always upgrading it to a record on the way out (its
-// handle defaults to the address's own local part); writing always
-// produces records, never bare strings.
+// Reading tolerates a bare address string (pre-rollout data) and upgrades it
+// to a record; writing always produces records, never bare strings.
 
 import { type } from "arktype";
 import { localPartOf } from "./agent-address";
@@ -46,24 +34,14 @@ function parseParticipantEntry(entry: unknown): ParticipantRecord {
   return result;
 }
 
-/**
- * Parses a whole `chat/participants` setting value into records,
- * tolerant of the mixed shape a workbench written before and after this
- * rollout might carry: some entries bare strings, some already records.
- * Anything other than an array is treated as no participants at all.
- */
+// Tolerant of a workbench with a mix of pre- and post-rollout entries.
 export function parseParticipants(raw: unknown): ParticipantRecord[] {
   if (!Array.isArray(raw)) return [];
   return raw.map(parseParticipantEntry);
 }
 
-/**
- * A short, word-safe handle derived from a workflow definition's name —
- * e.g. "Echo Bot" -> "echo-bot" — lowercased, non-alphanumeric runs
- * collapsed to a single hyphen, and leading/trailing hyphens trimmed.
- * Falls back to the given address's own local part when the name yields
- * nothing usable (e.g. a name of all punctuation, or empty).
- */
+// Falls back to the address's local part when the name yields nothing
+// usable (e.g. all punctuation).
 export function handleFromName(name: string, fallbackAddress: string): string {
   const slug = name
     .trim()
@@ -73,11 +51,7 @@ export function handleFromName(name: string, fallbackAddress: string): string {
   return slug.length > 0 ? slug : localPartOf(fallbackAddress);
 }
 
-/**
- * De-duplicates a candidate handle against the handles already in use in
- * a workbench: "echo" becomes "echo-2", then "echo-3", etc. — the first
- * suffix not already taken.
- */
+// "echo" becomes "echo-2", then "echo-3" — the first suffix not taken.
 export function dedupeHandle(handle: string, taken: ReadonlySet<string>): string {
   if (!taken.has(handle)) return handle;
   let suffix = 2;
@@ -85,12 +59,8 @@ export function dedupeHandle(handle: string, taken: ReadonlySet<string>): string
   return `${handle}-${suffix}`;
 }
 
-/**
- * Appends a new participant to an existing record list, de-duplicating
- * the desired handle against every handle already in the workbench.
- * Same-address retries return the existing list by identity so a caller
- * can tell "already present" apart from "appended a row".
- */
+// Returns the existing list by identity on a same-address retry, so a
+// caller can tell "already present" from "appended".
 export function addParticipant(
   existing: readonly ParticipantRecord[],
   address: string,
@@ -104,12 +74,8 @@ export function addParticipant(
   return [...existing, { address, handle }];
 }
 
-/**
- * Drops a participant from an existing record list by address — the
- * inverse of `addParticipant`. Returns the same array reference when
- * the address names no participant, so a caller can tell "nothing
- * changed" apart from "removed the last matching entry" by identity.
- */
+// Returns the same array reference when the address names no participant,
+// so a caller can tell "nothing changed" by identity.
 export function removeParticipant(
   existing: readonly ParticipantRecord[],
   address: string,
diff --git a/apps/web/src/chat/wire/parts.ts b/apps/web/src/chat/wire/parts.ts
index 83d20a519..47efb9008 100644
--- a/apps/web/src/chat/wire/parts.ts
+++ b/apps/web/src/chat/wire/parts.ts
@@ -1,36 +1,18 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md).
 
 import { type } from "arktype";
 
-// The wire contract for chat message content. Every message a thread
-// carries is a `Part[]`; each part is a structural arktype schema with a
-// `kind` discriminant, parsed at the trust boundary rather than cast.
-
 export const TextPart = type({
   kind: "'text'",
   text: "string",
-  /** Set only on the undelivered-turn notice `postUndeliveredNotice`
-   * posts in an unreachable agent's own voice — the client's
-   * one signal that this particular text bubble is a failed turn's
-   * notice, not an ordinary reply, so it renders the failed-turn strip
-   * (`PrFailedTurnStrip`) instead of a plain bubble. Absent on every
-   * other text part. */
+  // Marks the undelivered-turn notice so it renders the failed-turn strip,
+  // not a plain bubble.
   "turnFailed?": "boolean",
-  /** Set with `turnFailed` when the cause is a missing/unresolvable
-   * model (`InferenceResolutionError`) or a model that cannot use tools
-   * — the failed-turn strip renders named recovery (picker + Settings
-   * hop) instead of Retry. Absent on every other text part. */
+  // Set with `turnFailed` for a missing/unresolvable model or one that
+  // can't use tools, to render named recovery instead of Retry.
   "turnFailedReason?": "'model_unavailable' | 'tools_unsupported'",
-  /** Set only on the cancelled-turn notice `postCancelledNotice`
-   * (`./workbench-service.ts`) posts in the cancelled agent's own voice
-   * — distinct from `turnFailed`: a user cancelling a turn is
-   * not a failure, and the frontend renders it with its own honest copy
-   * rather than `FailedTurnStrip`'s "didn't reply" framing. Absent on
-   * every other text part. */
+  // Marks a user-cancelled turn — distinct from `turnFailed` since
+  // cancelling isn't a failure and gets its own copy.
   "turnCancelled?": "boolean",
 });
 export type TextPart = typeof TextPart.infer;
@@ -59,14 +41,9 @@ export const BlockPart = type({
 });
 export type BlockPart = typeof BlockPart.infer;
 
-// A file rides either as a reference into platform blob storage (`blobId`,
-// for content already persisted) or as inline base64 bytes (`data`, for
-// content the codec is encoding fresh). Exactly one of those two must be
-// present. `artifactId` is an orthogonal, optional link back to a Library
-// artifact (see `@corbits/artifacts`) — set when this file is also a
-// persisted Library row (e.g. a workflow finalize tool's output),
-// independent of whether the bytes themselves also live in chat's own blob
-// store.
+// Exactly one of `blobId` (already persisted) or `data` (inline base64)
+// must be present, unless `artifactId` links this file to a Library row
+// instead (see @corbits/artifacts).
 export const FilePart = type({
   kind: "'file'",
   name: "string",
@@ -77,10 +54,8 @@ export const FilePart = type({
 }).narrow((part, ctx) => {
   const hasBlobId = part.blobId !== undefined;
   const hasData = part.data !== undefined;
-  // An artifact-backed file needs neither: its bytes live in the Library
-  // artifact row `artifactId` names, not in chat's own blob store, so
-  // `blobId`/`data` stay optional (but still mutually exclusive) once
-  // `artifactId` is set.
+  // An artifact-backed file's bytes live in the Library row, so blobId/data
+  // stay optional (still mutually exclusive) once artifactId is set.
   if (part.artifactId !== undefined) {
     if (hasBlobId && hasData) {
       return ctx.reject("`blobId` and `data` cannot both be set on a FilePart");
@@ -108,11 +83,7 @@ export const Part = TextPart.or(ReasoningPart)
   .or(EventPart);
 export type Part = typeof Part.infer;
 
-/**
- * Parse untrusted data as a `Part`, throwing a precise error rather than
- * returning malformed or partially-trusted data. The only supported way
- * to bring external JSON into the `Part` type.
- */
+// The only supported way to bring external JSON into the `Part` type.
 export function parsePart(data: unknown): Part {
   const result = Part(data);
   if (result instanceof type.errors) {
diff --git a/apps/web/src/chat/wire/stream-events.ts b/apps/web/src/chat/wire/stream-events.ts
index dac88c850..90ca8eb54 100644
--- a/apps/web/src/chat/wire/stream-events.ts
+++ b/apps/web/src/chat/wire/stream-events.ts
@@ -1,24 +1,5 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
-
-// The wire contract for every event a workbench's `/stream` SSE
-// connection carries — arktype schemas so a payload is validated at the
-// one boundary that matters (about to leave the process on the wire),
-// rather than trusted by convention the way a plain TS interface would
-// leave it. `chat-ui`'s subscriber types are meant to mirror these
-// `.infer` types exactly: this file is the contract, not a description
-// of one.
-//
-// The organizing rule every event here follows: a subscriber must be
-// able to render (or update its own state) from the event alone, with
-// no follow-up GET. `chat.message` carries the full rendered row: a
-// `GET /workbenches/:id/messages` page item and a freshly published
-// `chat.message` are structurally the same shape, minus the fields
-// (`reactions`, `pinned`, `clientId`) that are always absent on a
-// message nobody has reacted to, pinned, or reconciled yet.
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md, which
+// also covers this file's organizing rule).
 import { type } from "arktype";
 import { Part } from "./parts";
 
@@ -27,16 +8,8 @@ const WorkbenchMessageSender = type({
   address: "string",
 });
 
-/**
- * The full rendered timeline row a `chat.message` event carries —
- * everything `postWorkbenchMessage`'s caller already has in hand from the
- * insert it just did, so a subscriber never needs to refetch the
- * message it was just told about. `ref` names the workbench the row
- * lives on; the mail headers ride along only when the row was actually
- * mailed (a human send through the mailbox fan-out) — Message-ID always,
- * In-Reply-To and References when the row answers a thread — and are
- * absent, never invented, for a row nobody mailed.
- */
+// Mail headers ride along only when the row was actually mailed; absent,
+// never invented, otherwise.
 export const ChatMessageEventData = type({
   id: "string",
   workbenchId: "string",
@@ -64,15 +37,8 @@ export const ChatTypingEventData = type({
 });
 export type ChatTypingEventData = typeof ChatTypingEventData.infer;
 
-/**
- * A presence delta: one principal either just became reachable on this
- * stream (`"online"`, fired the moment its SSE connection opens, and
- * again on an explicit `POST .../presence` ping) or just stopped being
- * reachable (`"offline"`, fired once its *last* open connection for
- * this workbench closes — a second open tab never fires it). Never
- * persisted and never the answer to a poll: a subscriber folds this
- * into the roster it already holds from `chat.presence.snapshot`.
- */
+// "offline" fires only once a principal's *last* open connection closes —
+// a second open tab never fires it.
 export const ChatPresenceEventData = type({
   principalId: "string",
   state: "'online' | 'offline'",
@@ -80,12 +46,7 @@ export const ChatPresenceEventData = type({
 });
 export type ChatPresenceEventData = typeof ChatPresenceEventData.infer;
 
-/**
- * The one-time roster a freshly opened stream is handed before any
- * delta — what lets a subscriber render "who's here" immediately on
- * connect without a separate fetch. Sent only to the connecting
- * stream itself, never broadcast.
- */
+// Sent only to the connecting stream itself, never broadcast.
 export const ChatPresenceSnapshotEventData = type({
   members: type({
     principalId: "string",
diff --git a/apps/web/src/chat/wire/tools-unsupported.ts b/apps/web/src/chat/wire/tools-unsupported.ts
index 6611c5886..586c3b2b5 100644
--- a/apps/web/src/chat/wire/tools-unsupported.ts
+++ b/apps/web/src/chat/wire/tools-unsupported.ts
@@ -1,26 +1,10 @@
-// Mirrored from packages/chat/src: apps/web and @/chat
-// must not import @corbits/chat, a server-only package. This is the browser-
-// facing half of the same wire contract the hub's chat routes still speak;
-// once the hub moves onto native mail threads (T5a/T5c) this file becomes
-// the one source of truth and packages/chat's copy goes away.
-
-/**
- * Named consumer copy for an inference failure whose real cause is that
- * the agent's model cannot use tools. Provider dumps, HTTP status, and
- * catalog/registry capability strings never belong on the timeline.
- */
+// Mirrored from packages/chat/src (see docs/chat-wire-contract.md).
 
 export const TOOLS_UNSUPPORTED_CONSUMER_MESSAGE = "This agent's model can't use tools.";
 
-/**
- * Conservative match: provider/inference errors about tools /
- * function-calling plus unsupported / not supported / a missing required
- * capability. An unrelated HTTP 400, an embedding model's "does not
- * support generate", an ordinary reply that happens to mention tools,
- * or connector prose like "The grep tool is not supported in this
- * sandbox" must not match. Singular "tool" next to "not supported" is
- * ordinary tool-availability copy, not a model-capability failure.
- */
+// Conservative on purpose: must not match an unrelated HTTP 400, an
+// embedding model's "does not support generate", or connector prose like
+// "The grep tool is not supported in this sandbox".
 const TOOLS_UNSUPPORTED_RE =
   /\b(?:tools|tool use)\b[^.]{0,80}\b(?:is |are |use is )?not supported\b|\b(?:is |are )?not supported\b[^.]{0,80}\b(?:tools\b|tool use)\b|\bdoes(?: not|n't) support (?:tools?|tool use|function[\s-]?calling)\b|\bfunction[\s-]?calling\b[^.]{0,80}\b(?:not supported|unsupported|required|missing)\b|\b(?:not supported|unsupported|required|missing)\b[^.]{0,80}\bfunction[\s-]?calling\b/i;
 
diff --git a/apps/web/src/chat/workbench-roster.ts b/apps/web/src/chat/workbench-roster.ts
index fab2cc386..2f18d3640 100644
--- a/apps/web/src/chat/workbench-roster.ts
+++ b/apps/web/src/chat/workbench-roster.ts
@@ -1,14 +1,6 @@
-// A workbench mail send has no way to hand off between agents: the hub only
-// delivers to run addresses, which only the client knows (a workbench's
-// Participants panel already reads them off the deployment/run listing).
-// Appending them as a trailing block on every workbench send gives every agent
-// in the workbench everyone else's address, so one agent can mail another
-// directly. Agent-to-agent mail goes run to run and never lands in the
-// person's mailbox on its own, so the block also carries the person's own
-// address and a line telling agents to copy it on any handoff — the mail
-// tools have no `cc` field, so that means naming it as another `to`
-// recipient. `stripRoster` is the inverse, used only to keep the block out
-// of what a person sees echoed back as their own sent message.
+// See docs/chat-mail-threading.md for the roster mechanism. `stripRoster`
+// is the inverse, used to keep the block out of a person's echoed-back sent
+// message.
 
 const ROSTER_HEADING = "Participants:";
 
diff --git a/apps/web/src/chat/workbench-tenants.ts b/apps/web/src/chat/workbench-tenants.ts
index a2f17d0a9..645bb69f1 100644
--- a/apps/web/src/chat/workbench-tenants.ts
+++ b/apps/web/src/chat/workbench-tenants.ts
@@ -1,7 +1,5 @@
-// A workbench is a child tenant, so listing workbenches is listing the
-// bench's children over the stock tenant routes. This is the whole
-// workbench-listing surface the rest of the app reads — the workbench itself
-// lives in the child tenant's mailbox (`threads-api.ts`).
+// A workbench is a child tenant, so listing workbenches lists children
+// over the stock tenant routes.
 
 import { createFetchStockHub, findOwnedTenants } from "../needs-converge";
 import { listChats } from "./threads-api";
diff --git a/apps/web/src/client-bootstrap.ts b/apps/web/src/client-bootstrap.ts
index 4bb7b3cbd..3879db2db 100644
--- a/apps/web/src/client-bootstrap.ts
+++ b/apps/web/src/client-bootstrap.ts
@@ -1,15 +1,5 @@
-// The portable client bootstrap: one call that drives the client's
-// needs-list against a stock Interchange hub using only stock routes — no
-// workbench server proxies, tables, or mounts. Auth owns the primary
-// tenant; this lane converges everything beneath it (top-level Myra,
-// workbench child tenants plus each workbench's primary thread) and
-// persists the child tenant ids it created in client storage scoped by
-// hub origin and account, so a reinstall reclaims by id, never by slug.
-// DMs are participant-filtered threads derived client-side, never tenants.
-// Myra's definition refId resolves from the client workflow catalog, and
-// deployment source/offering ids only ever come from explicit caller
-// config — this module never guesses them. When stock Interchange lacks a
-// capability the result carries the typed gap instead of throwing.
+// Uses only stock routes — no workbench server proxies, tables, or mounts.
+// Persisted child tenant ids let a reinstall reclaim by id, never by slug.
 
 import { WORKFLOW_CATALOG } from "@corbits/workflows/catalog";
 
@@ -44,12 +34,8 @@ function primaryTenantSlug(account: ClientBootstrapAccount): string {
   return base !== undefined && base.length > 0 ? base : `home-${account.id}`;
 }
 
-/** First-signup installer step: mints the account's primary
- * tenant over the stock `POST /api/tenants` route (no `parentId`, so the
- * caller becomes its owner) when it does not already own one. This is
- * the "0→1" ruling's execution — never hub boot, never a CLI — and it
- * never mints a second root: an account that already owns a top-level
- * tenant is left alone. */
+/** The "0→1" ruling's execution — never hub boot, never a CLI. Never
+ * mints a second root: an account that already owns one is left alone. */
 export async function ensurePrimaryTenant(
   account: ClientBootstrapAccount,
   hub: StockHub,
@@ -62,10 +48,7 @@ export async function ensurePrimaryTenant(
   });
 }
 
-/** The seeded assistant asset, productized as Myra — the same wire
- * identifier the hub seed deploys under and the catalog resolves to the
- * "Myra" display name. Resolved from the catalog at runtime, never
- * hardcoded at the call site. */
+// Resolved from the catalog at runtime, never hardcoded at the call site.
 export function resolveMyraDefinitionRefId(): string | undefined {
   return WORKFLOW_CATALOG.find((entry) => entry.displayName === "Myra")?.assetName;
 }
@@ -154,10 +137,8 @@ export async function bootstrapClientSession(
   });
   const store = childTenantStore(deps.storage, deps.hubScope, account.id);
   try {
-    // The common case (an account that already owns its primary tenant)
-    // never pays for a primary-tenant existence probe: convergence is
-    // attempted directly, and only a "primary-tenant-bootstrap" gap — the
-    // first-signup case — triggers the one-time mint-then-retry below.
+    // The common case never pays for a primary-tenant existence probe;
+    // only the first-signup gap triggers the mint-then-retry below.
     const report = await convergeNeedsList(manifest, deps.hub, store).catch(
       async (cause: unknown) => {
         if (
@@ -199,10 +180,8 @@ export async function bootstrapClientSession(
   }
 }
 
-/** One shared landing for the bootstrap outcome at both entry points
- * (first-open in main, signup in the onboarding page): a converged lane
- * logs at info, a stock gap or any other failure logs at warn — never
- * shown, never gating the shell. */
+// A converged lane logs at info, any failure at warn — never shown,
+// never gating the shell.
 export function logBootstrapResult(log: ClientLogger, result: ClientBootstrapResult): void {
   if (result.kind === "ready") {
     log.info("Portable client bootstrap converged", {
@@ -229,10 +208,8 @@ export function logBootstrapThrown(log: ClientLogger, error: unknown): void {
   });
 }
 
-/** The bootstrap with its production ports already attached: stock fetch
- * hub, browser localStorage, current origin as hub scope. Both bootstrap
- * entry points (first-open in main, signup in the onboarding page) call
- * this one helper so the ports can never drift between them. */
+// Both bootstrap entry points call this one helper so production ports
+// can never drift between them.
 export function runPortableClientBootstrap(
   account: ClientBootstrapAccount,
   overrides?: {
diff --git a/apps/web/src/command-palette-actions.ts b/apps/web/src/command-palette-actions.ts
index c2df3b060..979d05dcb 100644
--- a/apps/web/src/command-palette-actions.ts
+++ b/apps/web/src/command-palette-actions.ts
@@ -1,22 +1,5 @@
-// The command palette's `>` action commands: everything the shell mock's
-// `buildCmdkEntries` lists under "Commands" that this app can actually wire
-// today. Skills still use the off-route-safe pending-flag pattern
-// `library-upload.ts` established: the palette can fire from any page,
-// before the target page (and its window-event listener) has mounted, so
-// a same-tick `dispatchEvent` would be a race the listener always loses.
-// `pending-dialog-request.ts` generalizes that pattern; the target page
-// (skills-page.tsx) consumes the pending flag on mount. Skills moved from
-// its own route into a Settings section and back out to its own
-// rail destination — "New skill" lands on `/skills`. "New task"
-// and the Inbox page it used to open are gone (owner decision):
-// tasks are dispatched by Myra from inside a workbench now.
-//
-// Workbench creation is not one of those — there is no dialog to race, no
-// page to mount first: "new-workbench" navigates straight to the template
-// picker (`/new`, — superseding its direct mint), the same
-// hop the sidebar's own "+" control uses. A second "new-agent" row that
-// said and did the same thing was dropped. "New thread" is out
-// of scope (killed by owner decision).
+// "New skill" uses the pending-flag pattern from `pending-dialog-request.ts`
+// since the palette can fire before the target page's listener mounts.
 
 import { createPendingDialogRequest } from "@/shell/layout";
 import { CHAT_STRINGS } from "@/chat";
@@ -54,10 +37,8 @@ export type ActionCommand = {
   readonly subtitle: string;
 };
 
-/** Static catalog: id, title, subtitle. Matches the mock's action-command
- * titles, with "Install skill" relabeled "New skill" to match the shell's
- * current skills model: a person authors a skill into the workbench's own
- * registry (`skills-api.ts`) rather than installing one from a catalog. */
+// "Install skill" relabeled "New skill": a person authors a skill into
+// the workbench's own registry rather than installing from a catalog.
 export const ACTION_COMMANDS: readonly ActionCommand[] = [
   {
     id: "new-workbench",
@@ -101,13 +82,8 @@ export type ActionCommandContext = {
   readonly closeCanvas: () => void;
 };
 
-/**
- * Runs one action command. "new-workbench" opens the template picker (see
- * the module doc); "new-skill" still goes through a pending flag when the
- * palette fires it off-route (see the module doc), so the target page's
- * own mount effect opens the dialog instead of a dispatch racing against
- * that page's not-yet-mounted listener.
- */
+// "new-skill" goes through a pending flag off-route, so the target page's
+// mount effect opens the dialog instead of racing a dispatch.
 export async function runActionCommand(
   id: ActionCommandId,
   ctx: ActionCommandContext,
diff --git a/apps/web/src/command-palette-open-store.ts b/apps/web/src/command-palette-open-store.ts
index 634e79132..0ec02c80c 100644
--- a/apps/web/src/command-palette-open-store.ts
+++ b/apps/web/src/command-palette-open-store.ts
@@ -1,15 +1,6 @@
-// The state of the global command palette (DECISIONS.md → Search) — a
-// separate surface from the stage top bar's per-page filter, which owns no
-// state here at all. Held outside the React tree because the things that
-// open it are siblings, not ancestors: `CommandPaletteProvider` renders the
-// palette itself, `Cmd+K` opens it from anywhere via `useCommandShortcut`,
-// and a context menu item opens it too. One store, so all three ways in can
-// never disagree about whether the palette is open.
-//
-// Module state outlives a React remount, so search is scoped explicitly:
-// `CommandPaletteProvider` closes it on a route change (a Back out of a
-// result must not leave the overlay standing) and on a bench switch (whose
-// results and query belonged to the bench being left).
+// Held outside the React tree because the things that open it (Cmd+K, a
+// context menu item, the provider) are siblings, not ancestors — one
+// store so all three ways in can never disagree.
 
 import { useSyncExternalStore } from "react";
 
diff --git a/apps/web/src/command-palette-provider.tsx b/apps/web/src/command-palette-provider.tsx
index d29a4cd67..7991d0dab 100644
--- a/apps/web/src/command-palette-provider.tsx
+++ b/apps/web/src/command-palette-provider.tsx
@@ -43,23 +43,9 @@ const STATIC_COMMANDS = buildStaticCommands(
   NAV_ROUTES.map((route) => ({ path: route.path, label: route.label })),
 );
 
-/**
- * Wires the data-driven react-ui command palette into the app shell, and
- * renders it — the global surface `Cmd+K` (and a context-menu item) opens,
- * as its own modal dialog (`CommandPalette`), never anchored to the stage
- * top bar's per-page filter magnifier. Mounted once in `app.tsx`'s `Shell`,
- * above `AppShell`, so it works from every route — including one that
- * matches no page and renders no stage top bar of its own.
- *
- * Grouping, `#`/`@`/`>`/`/` scope parsing, and the Recents rule live in
- * `@/command-palette` (`buildCommandPaletteGroups`) — this file only
- * assembles the app's own sources (routes, workbenches, agents, routines,
- * skills, library artifacts) and maps a selection back to a real route or
- * action. Entity results for workbenches/runs/agents still come off the same
- * `useEntitySearch` paging this provider already used; routines, skills and
- * library artifacts are small per-bench catalogs fetched once and filtered
- * client-side, the same way the static route list already is.
- */
+// Mounted once above `AppShell` so it works from every route, including
+// one that matches no page. Grouping/scope-parsing lives in
+// `@/command-palette`; this file only assembles the app's own sources.
 export function CommandPaletteProvider({
   path,
   navigate,
@@ -109,11 +95,8 @@ export function CommandPaletteProvider({
     [recentsStore],
   );
 
-  // A workbench-level 404 (`chat-page.tsx`, via `ChatWorkspace`'s
-  // `onWorkbenchNotFound`) means a Recents entry outlived the workbench it
-  // points at — drop it so re-opening the palette never offers a dead end
-  // again. See `workbench-not-found-event.ts` for why this is an event
-  // rather than a prop: the chat route and this provider are siblings.
+  // A workbench-level 404 means a Recents entry outlived the workbench it
+  // points at — drop it so re-opening never offers a dead end again.
   useEffect(() => {
     function onWorkbenchNotFound(event: Event) {
       const workbenchId = (event as CustomEvent<string>).detail;
@@ -128,11 +111,8 @@ export function CommandPaletteProvider({
     };
   }, [removeRecent]);
 
-  // Reads through `queryClient` at the shared `tenantKeys.workbenches` key
-  // (rather than calling `listWorkbenches` directly) so a re-search — every
-  // debounced keystroke re-invokes this — and the bare `#` scope view below
-  // both reuse one cached fetch with every other workbench-listing surface in
-  // the shell, instead of each one issuing its own request.
+  // Reads through the shared query key, not `listWorkbenches` directly,
+  // so every re-search reuses one cached fetch instead of its own request.
   const listWorkbenchesForSearch = useCallback(async () => {
     if (selectedTenantId === null) return [];
     const result = await queryClient.ensureQueryData({
@@ -174,10 +154,8 @@ export function CommandPaletteProvider({
     sources: entitySearchSources,
   });
 
-  // A bare `#` or `@` strips to an empty query, which useEntitySearch never
-  // fetches for (by design — the unscoped default view should not dump
-  // every entity on open). The mock shows every item in an active scope for
-  // this input, so fetch that scope's raw list directly instead.
+  // A bare `#`/`@` strips to an empty query, which useEntitySearch never
+  // fetches for by design — so fetch that scope's raw list directly.
   const bareWorkbenchesQuery = useQuery({
     queryKey: [...tenantKeys.workbenches(selectedTenantId ?? "", "workbench"), "bare-scope"],
     enabled: bareScopeKind === "workbenches" && open && selectedTenantId !== null,
@@ -213,15 +191,9 @@ export function CommandPaletteProvider({
     ArtifactListPageSchema,
   );
 
-  // its hidden escape hatch: the sidebar dropped its bench switcher
-  // (a workbench IS a conversation now, one per account in the common
-  // case), but a multi-bench install still needs a way in. Plainly
-  // labeled, cycling to the next workbench in membership order — the
-  // simplest honest thing a single command-palette entry can do without
-  // reinventing a picker. Absent entirely for the common one-workbench
-  // account, same principle the old dock used to hide itself by. Benches
-  // are top-level memberships (`useBench`'s `benchMemberships`) — a workbench
-  // (a named child tenant) can never be cycled to.
+  // The sidebar dropped its bench switcher, so this is the hidden escape
+  // hatch: cycles to the next workbench in membership order, absent
+  // entirely for the common one-workbench account.
   const workbenchMemberships = benchMemberships;
   const nextWorkbench =
     workbenchMemberships.length > 1
@@ -239,11 +211,9 @@ export function CommandPaletteProvider({
   // the overlay are the ways back out.
   useCommandShortcut(openCommandPalette);
 
-  // Search is scoped to where it was opened from. A route change (including
-  // browser Back out of a result) closes it, so the overlay never stands over
-  // content it was not opened from; a bench switch closes it too, dropping a
-  // query whose results belonged to the bench being left. A tenant resolving
-  // for the first time (null → a real bench, at boot) is not a switch.
+  // A route change or bench switch closes the palette, so it never stands
+  // over content it wasn't opened from. A tenant resolving for the first
+  // time (boot) is not a switch.
   const [searchScope, setSearchScope] = useState({ path, tenantId: selectedTenantId });
   if (searchScope.path !== path || searchScope.tenantId !== selectedTenantId) {
     const benchSwitched =
@@ -346,10 +316,7 @@ export function CommandPaletteProvider({
     [artifactsQuery],
   );
 
-  // Order matches the mock's buildCmdkEntries: Commands, Agents &
-  // Channels, Pages, then the unscoped catalogs (Runs, Workflows,
-  // Skills, Artifacts), with People & agents last among the palette's
-  // groups.
+  // Order matches the mock's buildCmdkEntries.
   const sources = useMemo<readonly PaletteSource[]>(
     () => [
       {
diff --git a/apps/web/src/command-palette-recents.ts b/apps/web/src/command-palette-recents.ts
index c3789d151..4d7b4ee1d 100644
--- a/apps/web/src/command-palette-recents.ts
+++ b/apps/web/src/command-palette-recents.ts
@@ -1,8 +1,5 @@
-// A localStorage-backed Recents store per bench, built on
-// `@/command-palette`'s generic `createRecentsStore`. Mirrors the
-// defensive try/catch localStorage access `bench-context.tsx` already uses —
-// a private-browsing tab with storage disabled loses persistence, not
-// function.
+// Defensive try/catch localStorage access: a private-browsing tab with
+// storage disabled loses persistence, not function.
 
 import { createRecentsStore, type RecentsStorage, type RecentsStore } from "@/command-palette";
 
diff --git a/apps/web/src/command-palette/command-groups.ts b/apps/web/src/command-palette/command-groups.ts
index fbe23d7cf..111dd1060 100644
--- a/apps/web/src/command-palette/command-groups.ts
+++ b/apps/web/src/command-palette/command-groups.ts
@@ -19,11 +19,8 @@ export type PaletteResultGroup = {
   readonly items: readonly PaletteResultItem[];
 };
 
-/** One group of results, in the order it should appear among its siblings.
- * `kind` gates it to a prefix scope (`#`, `@`, `>`, `/`): visible when no
- * scope is active, or when the active scope matches. Omitting `kind` makes
- * it an unscoped-only group — the mock's Routines, Skills, Library and
- * Threads groups — visible only in the default (no scope) view. */
+// Omitting `kind` makes it an unscoped-only group, visible only in the
+// default (no scope) view.
 export type PaletteSource = {
   readonly id: string;
   readonly heading: string;
@@ -37,10 +34,8 @@ export type BuildCommandPaletteGroupsInput = {
   /** Already-ordered, already-capped Recents rows; shown only when the
    * query is empty and no scope prefix is active. */
   readonly recents: readonly PaletteResultItem[];
-  /** Every other group, already in the exact order they should render in —
-   * scoped and unscoped groups may be interleaved, matching the mock's
-   * Commands/Workbenches/Pages/Settings/Artifacts/Routines/Threads/People
-   * order (People last). */
+  // Already in the exact order they should render in; scoped and
+  // unscoped groups may be interleaved.
   readonly sources: readonly PaletteSource[];
 };
 
@@ -54,13 +49,8 @@ function filterItems(
   );
 }
 
-/**
- * Builds the palette's grouped, ordered result list from already-fetched
- * data: parses the `#`/`@`/`>`/`/` scope prefix, applies it to each scoped
- * source, folds in unscoped sources only in the default view, and shows
- * `recents` only on the empty, unscoped view — the same rules
- * `buildCmdkEntries` in the shell mock encodes. Pure: no fetch, no state.
- */
+// Pure: no fetch, no state. `recents` shows only on the empty, unscoped
+// view.
 export function buildCommandPaletteGroups(
   input: BuildCommandPaletteGroupsInput,
 ): readonly PaletteResultGroup[] {
diff --git a/apps/web/src/command-palette/detail-paths.ts b/apps/web/src/command-palette/detail-paths.ts
index a68e57d5e..6d5d5862a 100644
--- a/apps/web/src/command-palette/detail-paths.ts
+++ b/apps/web/src/command-palette/detail-paths.ts
@@ -1,14 +1,6 @@
-// Where a palette result lands. DESIGN.md's Detail Pages section addresses
-// every browsable entity by slug (`/agents/<slug>`), so a result row has to
-// resolve to that route when the entity carries a real slug.
-//
-// The slug is never derived here. A slug is minted once, at creation, and is
-// immutable; guessing one from a display name produces a URL that 404s the
-// moment the two disagree (an accent folded differently, a rename, a name
-// that was never sluggable). An entity whose slug is not a slug — an import
-// race, an external id, a handle minted before the rule tightened — falls
-// back to its own opaque id, which every roster still resolves as a deep
-// link into that row.
+// The slug is never derived here: guessing one from a display name
+// produces a URL that 404s the moment the two disagree. An entity with no
+// real slug falls back to its own opaque id instead.
 
 import { isValidSlug } from "@/lib/slug";
 
diff --git a/apps/web/src/command-palette/entity-search.ts b/apps/web/src/command-palette/entity-search.ts
index ddbf8437d..7be704555 100644
--- a/apps/web/src/command-palette/entity-search.ts
+++ b/apps/web/src/command-palette/entity-search.ts
@@ -1,15 +1,12 @@
 import { matchesQuery } from "./static-commands";
 
-/** One entity result. Only `title` is ever shown — never the id it carries
- * for selection, so a consumer wiring this into a UI can never regress the
- * "no raw identifier on screen" floor by accident. */
+// Only `title` is ever shown, never the id, so a consumer can't regress
+// the "no raw identifier on screen" floor by accident.
 export type EntitySearchResult = {
   readonly id: string;
   readonly title: string;
-  /** Which source the result came from — a free-form label the consumer
-   * defines (e.g. `"workbenches"`, `"routines"`, `"agents"`). The package
-   * never interprets it; it only carries it through so the app shell can
-   * group results and map a selection back to the right route. */
+  // The package never interprets this — only carries it through so the
+  // app shell can group results and map a selection to a route.
   readonly category: string;
 };
 
@@ -18,18 +15,15 @@ export type EntitySearchPage = {
   readonly hasMore: boolean;
 };
 
-/** The bare shape entity search needs from an already-fetched, already-typed
- * list — workbenches, routines, agents, etc. all already come off
- * arktype-validated API responses before they reach here, so this module
- * trusts the shape it is handed. */
+// Already-typed data from arktype-validated API responses — this module
+// trusts the shape it's handed.
 export type SearchableEntity = {
   readonly id: string;
   readonly name: string;
 };
 
-/** A named bundle of entities the search core matches against. The
- * `category` label flows through to every result so the consumer can group
- * and route them without re-deriving provenance. */
+// `category` flows through to every result so the consumer can group and
+// route them without re-deriving provenance.
 export type EntitySource = {
   readonly category: string;
   readonly entities: readonly SearchableEntity[];
@@ -42,20 +36,9 @@ export type SearchEntitiesInput = {
   readonly offset: number;
 };
 
-/**
- * Client-side search over entities the app has already fetched for its own
- * pages — workbenches, routines, agents, whatever the consumer hands in. There
- * is no cross-tenant search endpoint yet, so every source is an
- * already-fetched list matched here.
- *
- * An empty query returns nothing rather than everything: the palette's own
- * "type to search" state covers that case, and dumping every entity into
- * the list the instant the palette opens would make the static commands
- * compete with noise for the first keystroke.
- *
- * Results preserve source order: if the consumer passes workbenches before
- * routines, workbench matches appear first within a page.
- */
+// There's no cross-tenant search endpoint yet, so every source is an
+// already-fetched list. An empty query returns nothing rather than
+// dumping every entity in, competing with static commands on open.
 export function searchEntities({
   query,
   sources,
diff --git a/apps/web/src/command-palette/index.ts b/apps/web/src/command-palette/index.ts
index 2aca0d9f4..9428cc281 100644
--- a/apps/web/src/command-palette/index.ts
+++ b/apps/web/src/command-palette/index.ts
@@ -1,14 +1,5 @@
-// `@/command-palette`: what the global command palette can show.
-// `buildStaticCommands` turns the app shell's own route table into commands.
-// `searchEntities` is the pure match/paginate core over already-fetched
-// entity lists (workbenches, routines, agents — any source the consumer wires);
-// `useEntitySearch` is the one piece of React this package owns — debouncing
-// a typed query and fetching those lists, because that timing and caching is
-// inseparable from the pagination it resets. `parsePaletteQuery` and
-// `buildCommandPaletteGroups` are the prefix-scope and grouping rules the
-// shell mock's `buildCmdkEntries` encodes; `recents` is the small Recents
-// store. Rendering — the overlay, the keyboard contract, the
-// grouped/loading/empty/load-more states — stays a react-ui concern.
+// Rendering — the overlay, keyboard contract, grouped/loading/empty
+// states — stays a react-ui concern; this package owns only the data.
 export { buildStaticCommands, matchesQuery } from "./static-commands";
 export type { StaticCommand, StaticRoute } from "./static-commands";
 
diff --git a/apps/web/src/command-palette/recents.ts b/apps/web/src/command-palette/recents.ts
index 27bc7e399..69313c634 100644
--- a/apps/web/src/command-palette/recents.ts
+++ b/apps/web/src/command-palette/recents.ts
@@ -59,12 +59,8 @@ function isRecentEntry(value: unknown): value is RecentEntry {
   );
 }
 
-/**
- * A small localStorage-backed Recents list, keyed by `storageKey` so each
- * bench keeps its own history. Malformed or missing stored data is treated
- * as an empty list rather than thrown — a corrupt entry never breaks the
- * palette.
- */
+// Malformed or missing stored data is treated as an empty list rather
+// than thrown — a corrupt entry never breaks the palette.
 export function createRecentsStore(
   storage: RecentsStorage,
   storageKey: string,
diff --git a/apps/web/src/command-palette/scope.ts b/apps/web/src/command-palette/scope.ts
index 013f4fee3..1e712f6ac 100644
--- a/apps/web/src/command-palette/scope.ts
+++ b/apps/web/src/command-palette/scope.ts
@@ -31,14 +31,9 @@ export function parsePaletteQuery(raw: string): ParsedPaletteQuery {
   return { scope, query };
 }
 
-/**
- * True for a bare scope prefix with nothing typed after it (`"#"`, `"@ "`)
- * — the mock shows every item in that scope for this input, which a
- * debounced entity search that skips fetching on an empty query cannot
- * produce on its own. A consumer backed by such a search should use this to
- * decide when to fetch the scope's unfiltered list directly instead of
- * routing the empty string through its normal search path.
- */
+// True for a bare scope prefix (`"#"`, `"@ "`) — a consumer should use
+// this to fetch the scope's unfiltered list directly, since a debounced
+// search that skips empty queries can't produce it.
 export function isBareScopeQuery(raw: string): boolean {
   const { scope, query } = parsePaletteQuery(raw);
   return scope !== null && query === "";
diff --git a/apps/web/src/command-palette/use-entity-search.ts b/apps/web/src/command-palette/use-entity-search.ts
index e307435b4..e983ec590 100644
--- a/apps/web/src/command-palette/use-entity-search.ts
+++ b/apps/web/src/command-palette/use-entity-search.ts
@@ -31,24 +31,8 @@ export type UseEntitySearchResult = {
   readonly loadMore: () => void;
 };
 
-/**
- * Debounces a typed query, fetches every source once per search (cached
- * across pages of the same search), and matches/paginates them via
- * `searchEntities`. Debouncing lives here rather than in the app shell
- * because it is inseparable from the pagination it resets: a keystroke
- * that arrives mid-debounce must restart the timer *and* the offset
- * together, or a stale page from the previous query would leak into the
- * new one.
- *
- * `loading` is derived, not just set in an effect: the moment a keystroke
- * makes `query` outrun the debounce-committed `debouncedQuery`, the hook is
- * `pending`, and that is visible on the very render the keystroke caused —
- * no waiting for a passive effect to flush. It stays true through the fetch
- * (`fetching`) and only drops once that query's results are ready.
- *
- * All sources are fetched in parallel via `Promise.all`; a failure in any
- * one surfaces as `error: true` rather than a partial result set.
- */
+// Debouncing lives here, inseparable from the pagination it resets: a
+// keystroke mid-debounce must restart the timer and offset together.
 export function useEntitySearch({
   query,
   enabled,
diff --git a/apps/web/src/dom-environment.ts b/apps/web/src/dom-environment.ts
index 771a6f45a..3f8ce295b 100644
--- a/apps/web/src/dom-environment.ts
+++ b/apps/web/src/dom-environment.ts
@@ -1,8 +1,5 @@
-// A DOM for the tests that need one. Without it every UI test in this app is
-// limited to `renderToStaticMarkup`, which never runs an effect — so hooks,
-// listeners and focus behaviour could only be reasoned about, not asserted.
-// Registered through `bunfig.toml`'s preload so it is in place before any
-// test module imports React.
+// Without a real DOM, tests are limited to `renderToStaticMarkup`, which
+// never runs an effect. Registered via `bunfig.toml`'s preload.
 
 import { GlobalRegistrator } from "@happy-dom/global-registrator";
 
diff --git a/apps/web/src/git-fetch.ts b/apps/web/src/git-fetch.ts
index 7ecf6487f..45443fd36 100644
--- a/apps/web/src/git-fetch.ts
+++ b/apps/web/src/git-fetch.ts
@@ -1,7 +1,6 @@
-// Reads one file out of a hub asset repo from the browser, mirroring
-// `git-push.ts`'s in-memory clone but for the read side: isomorphic-git's
-// own upload-pack wire (unlike its receive-pack) parses the hub's
-// pkt-lines fine, so no hand-rolled wire code is needed here.
+// Mirrors `git-push.ts`'s in-memory clone for the read side; isomorphic-git's
+// own upload-pack wire parses the hub's pkt-lines fine, so no hand-rolled
+// wire code is needed here.
 import LightningFS from "@isomorphic-git/lightning-fs";
 import { Buffer } from "buffer";
 import git, { Errors } from "isomorphic-git";
@@ -58,10 +57,8 @@ export async function fetchSourceFile(args: {
   }
 }
 
-/** Fetches `main` and returns `filepath`'s contents as text, or `""` when
- * the branch has no commits yet or the file isn't in it — the two shapes
- * a freshly created, still-empty asset takes. Any other failure (auth,
- * network, a malformed repo) still throws. */
+/** Returns `""` for a freshly created, still-empty asset (no commits, or
+ * file not in it); any other failure still throws. */
 export async function fetchSourceFileOrEmpty(args: {
   url: string;
   token: string;
diff --git a/apps/web/src/git-push.ts b/apps/web/src/git-push.ts
index 203b0ab43..58fd6aada 100644
--- a/apps/web/src/git-push.ts
+++ b/apps/web/src/git-push.ts
@@ -1,7 +1,5 @@
-// Pushes a small flat file tree into a hub asset repo from the browser.
-// isomorphic-git builds the objects and the pack; the receive-pack wire
-// exchange is spoken directly because the hub answers `report-status`
-// as raw pkt-lines, which isomorphic-git's own push cannot read.
+// The receive-pack wire exchange is spoken directly because the hub
+// answers `report-status` as raw pkt-lines isomorphic-git's push can't read.
 import LightningFS from "@isomorphic-git/lightning-fs";
 import { Buffer } from "buffer";
 import git from "isomorphic-git";
diff --git a/apps/web/src/git-token.ts b/apps/web/src/git-token.ts
index cc91cb133..30148e3fe 100644
--- a/apps/web/src/git-token.ts
+++ b/apps/web/src/git-token.ts
@@ -1,8 +1,5 @@
-// Short-lived git tokens scoped to one asset — the mint/use/revoke shape
-// every reader and pusher of an asset's smart-HTTP git remote needs.
-// Pulled out of `agent-source-read.ts` and `agent-deploy.ts`'s copies so a
-// new caller (skill content) mints and revokes through the same helper
-// rather than a third copy of this dance.
+// The mint/use/revoke shape every reader/pusher of an asset's git remote
+// needs, pulled out of duplicate copies so a new caller shares this one.
 import { type } from "arktype";
 
 export class GitTokenError extends Error {}
diff --git a/apps/web/src/insights-api.test.ts b/apps/web/src/insights-api.test.ts
index bb8aaf316..311b3dc15 100644
--- a/apps/web/src/insights-api.test.ts
+++ b/apps/web/src/insights-api.test.ts
@@ -3,10 +3,7 @@ import { describe, expect, test } from "bun:test";
 import { insightsTopLevelRunsPath } from "./insights-api";
 
 describe("insightsTopLevelRunsPath", () => {
-  // the native tenant-scoped top-level listing, not the deleted
-  // `/top-level-runs` route (or its `feed=fires` variant) and not the dead
-  // `/me/workflows/runs`. deleted `packages/insights` and its
-  // usage/activity/tools/latency/scope routes entirely.
+  // Not the deleted `/top-level-runs` or `/me/workflows/runs` routes.
   test("hits the native tenant-scoped GET /workflows/runs listing", () => {
     const path = insightsTopLevelRunsPath("tenant-1");
     expect(path.startsWith("/api/tenants/tenant-1/workflows/runs?")).toBe(true);
diff --git a/apps/web/src/insights-api.ts b/apps/web/src/insights-api.ts
index 1adebbdf4..6abdb4a62 100644
--- a/apps/web/src/insights-api.ts
+++ b/apps/web/src/insights-api.ts
@@ -1,14 +1,6 @@
-// This app's fetch/query plumbing over the native tenant-scoped
-// `GET /workflows/runs` top-level listing →
-// Paginated<WorkflowRunResponse>. deleted `@corbits/run-scope`'s
-// `/top-level-runs?feed=fires`, which used to attribute each fire to its
-// routine server-side; deleted `packages/insights` itself — the
-// hub mounts nothing Workbench-specific any more. The four stock
-// observability routes (`vendor/intx/hub-api/src/routes/observability.ts`)
-// are unimplemented stubs (each returns 501), so usage/cost/activity,
-// tool-call, latency, run-trace, and cross-workbench scope all lost their
-// only data source and are dropped rather than faked — see the PR
-// description for the full accounting.
+// Fetch/query plumbing over the native tenant-scoped `GET /workflows/runs`
+// listing. See docs/insights-native-runs.md for the cutover from the
+// deleted run-scope/insights packages and what was dropped.
 
 import { type } from "arktype";
 import { WorkflowRunResponse, paginatedSchema } from "@intx/types";
@@ -18,20 +10,8 @@ export const ListingTurnSchema = type({
   "endedAt?": "string | null",
 });
 
-/**
- * `WorkflowRunResponse` plus the two routine-attribution fields the deleted
- * `feed=fires` mode of `/top-level-runs` used to report: the
- * routine that fired this run, when it has one. The native
- * `GET /workflows/runs` listing has no routine attribution, so both are
- * absent there — callers fall back to `definitionId`/`definitionName`
- * (`groupRunsByDefinition`, `runDisplayName` in `./insights-stats.ts`)
- * instead of inventing a routine. Both stay `null` (when present) for a
- * run with no routine/task parent — a directly launched workflow.
- * `turns` / `hasInFlightTurn` are this build's listing of in-flight
- * inference turns for the run (not Interchange fields) so a live
- * tool-loop can stay running past the abandoned-fire window. Omitting
- * them is not "no in-flight turn".
- */
+// `routineId`/`routineName` and `turns`/`hasInFlightTurn` are this app's
+// own additions, absent on the native feed — see docs/insights-native-runs.md.
 export const InsightsRunSchema = WorkflowRunResponse.and(
   type({
     "routineId?": "string | null",
@@ -45,43 +25,18 @@ export type InsightsRun = typeof InsightsRunSchema.infer;
 /** Native `GET /workflows/runs` envelope. */
 export const TopLevelRunsSchema = paginatedSchema(InsightsRunSchema);
 
-// The REST pagination ceiling (see `vendor/intx/hub-api/src/pagination.ts`) —
-// same limit `agents-api.ts`'s `listTopLevelRuns` uses for this route.
+// The REST pagination ceiling — same limit `agents-api.ts`'s
+// `listTopLevelRuns` uses for this route.
 const TOP_LEVEL_RUNS_LIMIT = 100;
 
-/**
- * Insights' run feed (; repointed to native in): the
- * tenant's top-level runs from `GET /workflows/runs` — the native
- * listing's own predicate (`address IS NOT NULL AND anchorRunId = id`,
- * see `vendor/intx/hub-api/src/routes/runs.ts`) already excludes every
- * non-top-level run (workbench host, invited agent), so this page never
- * derives that exclusion itself. Four differences from the deleted
- * `feed=fires` feed, all recorded as accepted loss in: a
- * routine's fire (not a top-level run) is no longer included, so
- * Insights no longer sees routine executions; there is no routine
- * attribution, so history groups by definition; the resident,
- * never-triggered deployment placeholder (`status: "deployed"`) is now
- * included — `computeInsightsStats` counts it as deployed rather than
- * hiding it; and the feed is single-tenant — the deleted route expanded
- * the requested tenant to its whole descendant subtree via
- * `getDescendantTenants` (the same rollup `resolveScope` used to give
- * `/usage`, `/activity`, and `/tools` before deleted them), while
- * the native listing filters `tenantId = requested tenant` only, so a
- * workspace parent's runs feed no longer rolls up its child workbenches
- * and now sits mismatched against its own usage aggregate (moot now that
- * usage itself is gone). Used in place of the dead `/me/workflows/runs`
- * — its `anchorRunId IS NULL` filter never matched anything, because
- * every addressed run self-anchors at creation, so that feed always came
- * back empty.
- */
+// The native listing already excludes every non-top-level run. See
+// docs/insights-native-runs.md for the accepted-loss differences.
 export function insightsTopLevelRunsPath(tenantId: string): string {
   return `/api/tenants/${tenantId}/workflows/runs?limit=${TOP_LEVEL_RUNS_LIMIT}`;
 }
 
-/** One run's event log, from the stock
- * `GET /workflows/runs/:runId/events` route. `body` is left unparsed
- * (`unknown`) since its shape varies by event type — `runFailureMessage`
- * below is the one place that reaches into it. */
+// `body` is left unparsed since its shape varies by event type —
+// `runFailureMessage` below is the one place that reaches into it.
 export const RunEventSchema = type({
   seq: "number",
   type: "string",
@@ -99,10 +54,8 @@ export function insightsRunEventsPath(tenantId: string, runId: string): string {
   return `/api/tenants/${tenantId}/workflows/runs/${encodeURIComponent(runId)}/events`;
 }
 
-/** The failed run's own explanation: the last `RunFailed`/`StepFailed`
- * event's `error.message`, read defensively since `body` is unparsed. Null
- * when no failure event carries a message — the caller falls back to a
- * generic notice rather than showing nothing. */
+// Null when no failure event carries a message — the caller falls back
+// to a generic notice rather than showing nothing.
 export function runFailureMessage(events: readonly RunEvent[]): string | null {
   for (let i = events.length - 1; i >= 0; i--) {
     const event = events[i];
diff --git a/apps/web/src/insights-deeplinks.ts b/apps/web/src/insights-deeplinks.ts
index 14c48e8fe..b71cf68ad 100644
--- a/apps/web/src/insights-deeplinks.ts
+++ b/apps/web/src/insights-deeplinks.ts
@@ -15,11 +15,8 @@ export function runDeepLinkTarget(run: { readonly id: string }): string {
   return runDetailPath(run.id);
 }
 
-/** Insights scoped to one workbench — the target for the
- * conversation action bar's "Insights" entry point. The route resolves the
- * workbench's own workbench tenant itself (see `../insights-workbench-scope.ts`)
- * rather than trusting a tenant id from the caller, since the caller here
- * only ever has the workbench id at hand. */
+/** The route resolves the tenant itself (see `insights-workbench-scope.ts`)
+ * since the caller here only ever has the workbench id. */
 export function workbenchInsightsPath(workbenchId: string): string {
   return `${INSIGHTS_PATH_PREFIX}/workbench/${encodeURIComponent(workbenchId)}`;
 }
diff --git a/apps/web/src/insights-path.ts b/apps/web/src/insights-path.ts
index 18b999613..cfc1e2c88 100644
--- a/apps/web/src/insights-path.ts
+++ b/apps/web/src/insights-path.ts
@@ -6,22 +6,9 @@ import { decodedOrNull } from "@corbits/url-path";
 
 import { INSIGHTS_PATH_PREFIX, INSIGHTS_RUNS_PATH } from "./path-ids";
 
-/**
- * `/insights/workbench/:workbenchId` is its own dedicated route — a
- * conversation's own scoped view, resolved by `InsightsWorkbenchPage`, never
- * a sub-mode of the landing. Every other path stays the cross-workbench
- * default landing: no per-mode branch needed there, since scoping happens
- * in InsightsRoute (which tenantId every query below targets), not here.
- * A stale `/insights/workbench/:tenantId` link (that route is retired,
- * hard cut) falls through to the plain landing default below rather than
- * matching anything.
- *
- * A malformed percent-escape in the id segment reads as the plain landing
- * default too, never as a detail mode with no entity to show — `mode:
- * "workbench"` (or `"run"`) with a `null` id would otherwise render that
- * mode's own scoped, permanently-empty dashboard instead of falling back
- * to the landing view any other unresolvable path already gets.
- */
+// A malformed percent-escape or stale/retired path falls through to the
+// plain landing default, never to a detail mode with a `null` id that
+// would render a permanently-empty dashboard.
 export function parseInsightsPath(path: string): {
   mode: "landing" | "runs" | "run" | "workbench";
   runId: string | null;
diff --git a/apps/web/src/insights-stats.ts b/apps/web/src/insights-stats.ts
index c715e14b9..662f76174 100644
--- a/apps/web/src/insights-stats.ts
+++ b/apps/web/src/insights-stats.ts
@@ -36,58 +36,32 @@ export type InsightsStats = {
 /** Cap recent-run table rows so the page stays scannable. */
 export const INSIGHTS_RECENT_LIMIT = 12;
 
-/**
- * Purpose runs only. `insights-page.tsx` sources `runs` from
- * `insightsTopLevelRunsPath` (see `./insights-api.ts`), the native `GET
- * /workflows/runs` top-level listing whose own predicate already
- * excludes every non-top-level run — no workbench-host anchors exist to
- * filter post-cutover, so this is now an identity pass kept for
- * callers that still name it explicitly.
- */
+// Identity pass: the native `GET /workflows/runs` feed already excludes
+// non-top-level runs, kept only for callers that still name it explicitly.
 export function purposeRunsForInsights(runs: readonly InsightsRun[]): readonly InsightsRun[] {
   return runs;
 }
 
-/**
- * A run's human-facing name: its routine's name when the feed
- * attributed one, honestly falling back to the definition name for a run
- * with no routine attribution — e.g. every row of the native
- * `GET /workflows/runs` listing, which carries no
- * `routineName`, or a directly launched workflow. Never mapped from a
- * client-side lookup table.
- */
+// Falls back to definition name since the native feed carries no
+// `routineName`; never mapped from a client-side lookup table.
 export function runDisplayName(run: InsightsRun): string {
   return run.routineName ?? run.definitionName;
 }
 
-/**
- * Keep runs whose `createdAt` falls inside `[fromIso, toIso]` (inclusive).
- * Invalid timestamps are dropped so KPIs never invent rows.
- */
+// Keeps runs whose `createdAt` falls inside `[fromIso, toIso]`; invalid
+// timestamps are dropped so KPIs never invent rows.
 export type DefinitionRunGroup = {
-  /** `routineId` when the newest run in the group fired from one,
-   * else `definitionId` — two different routines sharing one
-   * definition (e.g. two workbench-digest schedules) never merge into
-   * one group. The native `GET /workflows/runs` feed carries
-   * no routine attribution, so in practice this is always `definitionId`
-   * until a fires equivalent exists — the `routineId` branch is kept for
-   * that feed, not removed. */
+  /** `routineId` when set, else `definitionId` — kept distinct so two
+   * routines sharing one definition never merge into one group. */
   readonly groupKey: string;
   readonly displayName: string;
   /** Newest run first. */
   readonly runs: readonly InsightsRun[];
 };
 
-/**
- * "Run history" grouping for the Insights runs page: the same feed already
- * fetched for the flat list, bucketed by routine (falling back to
- * definition, for a run with no routine parent) and sorted newest-run
- * first — a client-side grouping of already-fetched data, no new endpoint.
- * With the native feed every row lacks routine attribution, so every
- * group is definition-keyed today; the routine branch rejoins once a
- * fires equivalent exists. Group order follows each group's own newest
- * run, newest overall first.
- */
+// Client-side grouping of already-fetched runs, no new endpoint. Every
+// group is definition-keyed today since the native feed lacks routine
+// attribution; the routine branch rejoins once a fires equivalent exists.
 export function groupRunsByDefinition(runs: readonly InsightsRun[]): readonly DefinitionRunGroup[] {
   const byGroupKey = new Map<string, InsightsRun[]>();
   for (const run of runs) {
diff --git a/apps/web/src/insights-timeline.ts b/apps/web/src/insights-timeline.ts
index 5ffbe2f16..2a3f7c613 100644
--- a/apps/web/src/insights-timeline.ts
+++ b/apps/web/src/insights-timeline.ts
@@ -18,11 +18,8 @@ export const INSIGHTS_TIMELINE_DAYS = 14;
 
 const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
 
-/**
- * Buckets `runs` into the last `days` UTC days ending on `now`'s day, oldest
- * first. Runs outside the window are dropped; days with no runs still appear
- * as zero-count buckets so the strip never collapses.
- */
+// Days with no runs still appear as zero-count buckets so the strip
+// never collapses.
 export function bucketRunsByDay(
   runs: readonly WorkflowRun[],
   days: number = INSIGHTS_TIMELINE_DAYS,
diff --git a/apps/web/src/insights-workbench-scope.ts b/apps/web/src/insights-workbench-scope.ts
index 53d17e01b..686c4b11c 100644
--- a/apps/web/src/insights-workbench-scope.ts
+++ b/apps/web/src/insights-workbench-scope.ts
@@ -1,13 +1,6 @@
-// Insights is scoped per workbench: `/insights/workbench/:workbenchId`
-// resolves to that workbench's OWN workbench tenant — every workbench minted
-// through POST /workbenches carries a tenancy link (see `WorkbenchWire.tenancy`
-// in @/chat) — never the workbench id itself and never the bench's
-// root tenant. That lookup goes through this one pure function over the SAME
-// cached workbench rows the shell's sidebar already fetches, rather than a
-// bespoke endpoint. deleted the reverse lookup
-// (`workbenchIdForWorkbenchTenant`): it only served the cross-workbench
-// "activity by workbench" chart and scope switcher, both dropped along with
-// packages/insights.
+// Resolves to the workbench's own tenant (`WorkbenchWire.tenancy`), reusing
+// the same cached workbench rows the sidebar already fetches, rather than a
+// bespoke endpoint.
 
 import type { Workbench } from "@/chat";
 
@@ -20,12 +13,8 @@ export type WorkbenchInsightsResolution =
       readonly title: string;
     };
 
-/** `workbenchId` → this workbench's own workbench tenant, or an honest reason
- * there isn't one: absent from the bench's workbench list at all ("not-found"
- * — the only path a stale `/insights/workbench/:tenantId` link or a
- * mis-typed id can take now that route is retired), or a true legacy
- * workbench minted before workbench tenancy existed ("legacy", `tenancy` is
- * `null`). */
+/** "not-found" for a stale/mis-typed link; "legacy" for a workbench minted
+ * before workbench tenancy existed (`tenancy` is `null`). */
 export function resolveWorkbenchInsightsScope(
   workbenches: readonly Workbench[],
   workbenchId: string,
diff --git a/apps/web/src/last-workbench.ts b/apps/web/src/last-workbench.ts
index a4b4c5969..07cc79fae 100644
--- a/apps/web/src/last-workbench.ts
+++ b/apps/web/src/last-workbench.ts
@@ -1,9 +1,5 @@
-// Files' workbench-first lens needs to know which workbench, if
-// any, the user was just inside — a signal `/artifacts` can't carry itself,
-// since it's reached from the sidebar footer, not a workbench sub-route.
-// Recorded per bench (a switch to a different bench must not default to a
-// foreign bench's workbench) and read back once on mount — never a live
-// subscription, so a workbench visited after Files is already open doesn't
+// Recorded per bench and read back once on mount, never a live
+// subscription, so a workbench visited after Files is open doesn't
 // yank the lens out from under the user.
 
 const KEY_PREFIX = "workbench.lastWorkbenchId.";
diff --git a/apps/web/src/lib/api-query/envelope.ts b/apps/web/src/lib/api-query/envelope.ts
index 545613eb9..00665b885 100644
--- a/apps/web/src/lib/api-query/envelope.ts
+++ b/apps/web/src/lib/api-query/envelope.ts
@@ -1,10 +1,6 @@
-// The hub-query envelope: every page's data fetch reports exactly one of
-// these four outcomes, so a page never has to invent its own notion of
-// "still loading" vs. "no session" vs. "failed". `toAPIQuery` adapts any
-// TanStack-Query-shaped result onto it; `QueryView` (./query-view) renders
-// it. Both halves are framework-agnostic about the fetch itself — neither
-// imports `@tanstack/react-query` — so a host wires its own query hook to
-// this contract instead of the package assuming one.
+// Neither this file nor `QueryView` imports `@tanstack/react-query`, so a
+// host wires its own query hook to this contract instead of one being
+// assumed.
 
 export type APIQuery<T> =
   | { readonly kind: "loading" }
@@ -13,16 +9,14 @@ export type APIQuery<T> =
       readonly kind: "error";
       readonly message: string;
       readonly retry: () => void;
-      /** The response status when the failure was an HTTP error (absent for
-       * network failures) — lets a caller tell "404, genuinely not found"
-       * apart from "500, something is actually broken" instead of
-       * collapsing every failure into the same generic error state. */
+      // Lets a caller tell "404, not found" from "500, broken" instead of
+      // one generic error state.
       readonly status?: number;
     }
   | { readonly kind: "ready"; readonly data: T };
 
-/** Thrown from a queryFn on HTTP 401 so a host's retry policy can stop
- * retrying and `toAPIQuery` can map the failure to `kind: "unauthenticated"`. */
+// Thrown on HTTP 401 so a retry policy can stop retrying and `toAPIQuery`
+// can map it to `kind: "unauthenticated"`.
 export class UnauthenticatedError extends Error {
   constructor(message = "unauthenticated") {
     super(message);
@@ -30,10 +24,7 @@ export class UnauthenticatedError extends Error {
   }
 }
 
-/** The one HTTP-query error shape every hub request throws: a human message
- * plus the response status when one exists (absent for network failures),
- * plus the request path for logs — never surfaced in user-facing copy —
- * plus the envelope `refId` when the hub answered through the sink. */
+// `path` is for logs only, never surfaced in user-facing copy.
 export class ApiQueryError extends Error {
   constructor(
     message: string,
@@ -45,11 +36,8 @@ export class ApiQueryError extends Error {
   }
 }
 
-/**
- * Human copy for a failed query, kept plain and actionable — the technical
- * detail (status codes, hub URLs, schema mismatches) stays in `console` /
- * devtools for debugging, never in the primary line a person reads.
- */
+// Technical detail stays in console/devtools, never the primary line a
+// person reads.
 export function describeQueryError(error: unknown): string {
   if (error instanceof TypeError) {
     return "Can't reach the server. Check your connection.";
@@ -57,14 +45,8 @@ export function describeQueryError(error: unknown): string {
   return "Something went wrong. Try again.";
 }
 
-/**
- * Human copy for a failed request, one sentence per status class, named
- * around what the caller was trying to do ("loading your benches",
- * "uploading this file"). Reads only `error.status` (any error-like value
- * carrying one, not just `ApiQueryError`) — never `error.message`, so a
- * request path, tenant id, or raw status text baked into a thrown message
- * can never reach this return value.
- */
+// Reads only `error.status`, never `error.message`, so a request path or
+// raw status text baked into a thrown message can never leak through.
 export function describeApiError(error: unknown, doing: string): string {
   const status =
     typeof error === "object" &&
@@ -82,11 +64,8 @@ export function describeApiError(error: unknown, doing: string): string {
   return `Something went wrong ${doing}. Try again.`;
 }
 
-/**
- * Map a TanStack-Query-shaped result onto `APIQuery`. `isLoading` (pending +
- * fetching) is the loading state — bare `isPending` would flash skeletons
- * when cached data exists.
- */
+// `isLoading` (pending + fetching), not bare `isPending`, since the
+// latter would flash skeletons when cached data exists.
 export function toAPIQuery<T>(result: {
   readonly isLoading: boolean;
   readonly isError: boolean;
diff --git a/apps/web/src/lib/api-query/query-view.test.tsx b/apps/web/src/lib/api-query/query-view.test.tsx
index 19761ab69..84ca79840 100644
--- a/apps/web/src/lib/api-query/query-view.test.tsx
+++ b/apps/web/src/lib/api-query/query-view.test.tsx
@@ -1,7 +1,5 @@
-// QueryView is the shared translation of loading/unauthenticated/error/
-// ready — every host page's failure copy and recovery affordance flow
-// through here, so this suite is the one place asserting a failed query
-// never strands a person with raw error text and nothing to do about it.
+// Asserts a failed query never strands a person with raw error text and
+// nothing to do about it.
 
 import { describe, expect, test } from "bun:test";
 import { renderToStaticMarkup } from "react-dom/server";
diff --git a/apps/web/src/lib/api-query/query-view.tsx b/apps/web/src/lib/api-query/query-view.tsx
index 54cf38310..215d14d04 100644
--- a/apps/web/src/lib/api-query/query-view.tsx
+++ b/apps/web/src/lib/api-query/query-view.tsx
@@ -9,11 +9,8 @@ import type { ReactNode } from "react";
 import type { APIQuery } from "./envelope";
 import { describeApiError } from "./envelope";
 
-/** Which shape a loading `QueryView` should hint at, close enough to the
- * real content's footprint to keep layout shift small — not a skeleton
- * framework, just the handful of shapes host pages actually need. `"block"`
- * (the default) is a fixed placeholder for surfaces that are neither a list
- * nor a single record. */
+// Not a skeleton framework — just the handful of shapes host pages
+// actually need.
 export type QuerySkeletonVariant = "block" | "rows" | "detail";
 
 /** A handful of list-row placeholders, sized near a real row. */
@@ -80,12 +77,8 @@ export function QueryView<T>({
    * real content so it doesn't jump when data lands. Ignored when
    * `loadingContent` is set. */
   readonly skeleton?: QuerySkeletonVariant;
-  /** Overrides the loading render entirely — a page-level wait (a whole
-   * stage or panel's primary content, not a row hint) should pass its own
-   * warm loader here rather than take the `"block"` skeleton slab, which
-   * this package can't render itself: `@/chat`'s
-   * `WorkbenchLoadingState` depends on this package, so `QueryView` can
-   * never import it back without a cycle. */
+  // `@/chat`'s `WorkbenchLoadingState` depends on this package, so
+  // `QueryView` can never import it back without a cycle.
   readonly loadingContent?: ReactNode;
   readonly children: (data: T) => ReactNode;
 }) {
diff --git a/apps/web/src/lib/client-log/index.ts b/apps/web/src/lib/client-log/index.ts
index f89cc1585..a33675379 100644
--- a/apps/web/src/lib/client-log/index.ts
+++ b/apps/web/src/lib/client-log/index.ts
@@ -1,14 +1,5 @@
-// The one browser-side logger: every ad-hoc `console.*` call in
-// apps/web and chat-ui routes through this instead, so a user's actions
-// are traceable end-to-end through one category+level shape instead of
-// scattered, differently-worded console lines. Two jobs: an in-memory
-// ring buffer any surface can flush (a devtools panel, a future
-// diagnostics beacon), and a console mirror gated by level so a
-// production console isn't flooded with routine debug/info trace lines.
-//
-// This module is the sanctioned exception to the `no-console` lint rule
-// — every other file under `src/` calls `getLogger` instead of
-// `console.*` directly.
+// The sanctioned exception to the `no-console` lint rule — every other
+// file calls `getLogger` instead of `console.*` directly.
 
 export type LogLevel = "debug" | "info" | "warn" | "error";
 
diff --git a/apps/web/src/lib/icons/index.test.tsx b/apps/web/src/lib/icons/index.test.tsx
index 961dea872..ca1ed374c 100644
--- a/apps/web/src/lib/icons/index.test.tsx
+++ b/apps/web/src/lib/icons/index.test.tsx
@@ -13,13 +13,8 @@ describe("@/lib/icons", () => {
     expect(typeof icons.BoldIconProvider).toBe("function");
   });
 
-  // Regression for the oversized right-click menu / search bar: Phosphor's
-  // IconContext.Provider fully replaces the context value rather than
-  // merging with it, so a bare `{ weight: "bold" }` silently drops the
-  // library's own `size: "1em"` default. Any glyph mounted without an
-  // ancestor CSS rule or an explicit `size=` prop then renders as a bare
-  // <svg> with no width/height, which the browser falls back to sizing as
-  // a 300x150 replaced element.
+  // Regression: a bare `{ weight: "bold" }` silently drops Phosphor's own
+  // `size` default, since the context value is replaced, not merged.
   test("BoldIconProvider preserves Phosphor's size default alongside bold weight", () => {
     expect(icons.boldIconContextValue).toEqual({
       size: "1em",
diff --git a/apps/web/src/lib/icons/index.tsx b/apps/web/src/lib/icons/index.tsx
index 6153fa313..e1389589c 100644
--- a/apps/web/src/lib/icons/index.tsx
+++ b/apps/web/src/lib/icons/index.tsx
@@ -1,16 +1,6 @@
-// The one icon surface every app/package imports glyphs through — owner
-// ruling (CL-icons-phosphor): Phosphor replaces lucide-react everywhere,
-// bold is the only weight, and the Sparkle/Sparkles glyph is banned outright
-// (it read as a generic "AI" cliché; every former sparkle spot now carries a
-// glyph that means something specific to what it marks). This module is a
-// curated re-export, not a full pass-through of `@phosphor-icons/react` —
-// only the glyphs the product actually uses are named here, so a stray
-// import can't reach for an off-list icon or tiptoe around the weight rule.
-//
-// Extraction-ready: this is deliberately just re-exports plus one context
-// provider, no app-specific logic. If `@corbits/react-ui` grows its own
-// icon surface, this file becomes the shim that re-points at it instead of
-// every call site changing again.
+// Sparkle/Sparkles is banned outright — it read as a generic "AI" cliché.
+// A curated re-export, not a full pass-through, so a stray import can't
+// reach for an off-list icon or tiptoe around the bold-weight rule.
 import { IconContext, type Icon, type IconProps } from "@phosphor-icons/react";
 import type { ReactNode } from "react";
 
@@ -85,12 +75,9 @@ export {
   X,
 } from "@phosphor-icons/react";
 
-/** `IconContext.Provider` replaces Phosphor's whole context value rather than
- * merging with it, so this must restate every default the library ships
- * (`size: "1em"`) alongside the one we're overriding (`weight: "bold"`) —
- * dropping `size` silently un-sizes every glyph that has no ancestor CSS
- * rule and no explicit `size=` prop, which is why the right-click menu and
- * the search bar rendered at the browsers' unsized-<svg> fallback. */
+// `IconContext.Provider` replaces Phosphor's whole context value rather
+// than merging it, so every library default (`size`) must be restated
+// alongside the override — dropping it silently un-sizes bare glyphs.
 export const boldIconContextValue = { size: "1em", weight: "bold" } as const;
 
 /** Wraps a subtree so every Phosphor icon under it defaults to bold weight
diff --git a/apps/web/src/lib/slug/slug.ts b/apps/web/src/lib/slug/slug.ts
index e92c249b4..aaa47b38f 100644
--- a/apps/web/src/lib/slug/slug.ts
+++ b/apps/web/src/lib/slug/slug.ts
@@ -5,14 +5,8 @@ export const SLUG_MAX_LENGTH = 64;
 
 const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
-/**
- * Derive a slug from a display name: accents folded to ASCII, everything
- * that is not a letter or digit collapsed into a single hyphen, and the
- * result capped at `SLUG_MAX_LENGTH` without leaving a trailing hyphen. A
- * name with nothing sluggable in it (punctuation, emoji, a non-Latin
- * script) yields the empty string — the caller decides what to do with a
- * name that cannot name a URL.
- */
+// A name with nothing sluggable (punctuation, emoji, non-Latin script)
+// yields the empty string — the caller decides what to do with it.
 export function slugify(name: string): string {
   const ascii = name
     .normalize("NFKD")
diff --git a/apps/web/src/lib/text-diff/line-diff.ts b/apps/web/src/lib/text-diff/line-diff.ts
index 386a1fb72..445802545 100644
--- a/apps/web/src/lib/text-diff/line-diff.ts
+++ b/apps/web/src/lib/text-diff/line-diff.ts
@@ -1,22 +1,5 @@
-// A line-level diff over two revisions of the same document, shaped the way
-// a review surface renders it: one row per line, in reading order, each row
-// knowing whether it was kept, added, or removed and which line number it
-// carries on each side.
-//
-// Three things keep it cheap enough to run in a dialog:
-//
-//   1. Newlines are normalized first, so a CRLF document never reads as
-//      "every line changed" — and callers can write back exactly the text
-//      they diffed (`normalizeNewlines` is exported for that).
-//   2. The identical head and tail are trimmed before any table is built,
-//      so a one-line edit in a 20k-line document costs a linear scan.
-//   3. What remains is diffed with a longest-common-subsequence walk, whose
-//      table is quadratic — so a hard cap refuses the walk instead of
-//      allocating gigabytes, and the caller shows a summary instead.
-//
-// Long runs of unchanged lines between edits are collapsed into a single
-// "skipped" row: a reader needs the neighbourhood of a change, not the
-// thousands of lines that did not move.
+// Head/tail trim before the quadratic LCS walk, with a hard cap, keeps
+// this cheap enough for a dialog on a huge diff.
 
 export type DiffLineKind = "context" | "added" | "removed" | "skipped";
 
@@ -89,12 +72,7 @@ function characterCount(lines: readonly string[]): number {
   return total;
 }
 
-/**
- * Lengths of the longest common subsequence for every suffix pair, so the
- * walk below can always take the branch that keeps more lines in common.
- * One Int32Array per row: the table is the expensive part of a diff, and a
- * typed array keeps it to four bytes a cell.
- */
+// A typed array keeps the expensive table to four bytes a cell.
 function commonSuffixLengths(
   before: readonly string[],
   after: readonly string[],
@@ -241,11 +219,8 @@ export function diffTotals(lines: readonly DiffLine[]): DiffTotals {
   return { added, removed };
 }
 
-/**
- * The one entry point: a diff of two revisions, or an honest refusal when
- * the changed region is too large to diff inline. Callers render whichever
- * status comes back rather than computing the script a second time.
- */
+// Callers render whichever status comes back rather than computing the
+// script a second time.
 export function diffText(
   beforeRevision: string,
   afterRevision: string,
diff --git a/apps/web/src/library-upload.ts b/apps/web/src/library-upload.ts
index df04418e7..97cf13f67 100644
--- a/apps/web/src/library-upload.ts
+++ b/apps/web/src/library-upload.ts
@@ -1,17 +1,11 @@
-// Library pageBand Upload is a cross-route action: the shell may fire it from
-// another path before LibraryPage is mounted. When already on /artifacts, open
-// the picker immediately; otherwise record a one-shot pending flag the page
-// consumes on mount. Keeps shell ↔ page coupling to this tiny module.
+// The shell may fire this before LibraryPage is mounted; off-route it
+// records a one-shot pending flag the page consumes on mount.
 
 export const LIBRARY_UPLOAD_EVENT = "workbench:library:upload";
 
 let pendingUpload = false;
 
-/**
- * Request the Library file picker. On-route: dispatch the window event the
- * mounted page listens for. Off-route: set a pending flag and navigate so the
- * page opens the picker after mount — no setTimeout race.
- */
+// Off-route sets a pending flag and navigates, avoiding a setTimeout race.
 export function requestLibraryUpload(args: {
   readonly alreadyOnLibrary: boolean;
   readonly navigateToLibrary: () => void;
diff --git a/apps/web/src/library-workbench-scope.ts b/apps/web/src/library-workbench-scope.ts
index 6f5a13a10..b0af6ab45 100644
--- a/apps/web/src/library-workbench-scope.ts
+++ b/apps/web/src/library-workbench-scope.ts
@@ -1,7 +1,5 @@
-// Files' workbench-first lens: resolves the "current workbench"
-// pill to that workbench's own tenant, the same `tenancy.tenantId`
-// `insights-workbench-scope.ts` scopes Insights on — never the workbench id
-// itself and never the bench's root tenant.
+// Resolves to the workbench's own tenant id, same as
+// `insights-workbench-scope.ts` — never the bench's root tenant.
 
 import type { Workbench } from "@/chat";
 
diff --git a/apps/web/src/library/artifact-renderer.tsx b/apps/web/src/library/artifact-renderer.tsx
index ec4fb9c19..f0a0e36bb 100644
--- a/apps/web/src/library/artifact-renderer.tsx
+++ b/apps/web/src/library/artifact-renderer.tsx
@@ -1,11 +1,5 @@
-// Typed, read-only renderers for artifact content — one per
-// `ArtifactRendererKind` (see `renderer-kind.ts`), dispatched by
-// `ArtifactRenderer`. Every host (canvas pane, Library detail preview, an
-// opened chat blob) renders through this one component so a kind's shape
-// only has one implementation.
-//
-// Read-only phase: no editing affordances here at all — the
-// multiplayer-editing half is substrate to build on top of this.
+// Every host renders through this one component so a kind's shape only
+// has one implementation. Read-only phase: no editing affordances here.
 
 import { CsvTable } from "@corbits/react-ui";
 import { FileDashed } from "@/lib/icons";
@@ -14,32 +8,17 @@ import type { ArtifactRendererKind } from "./renderer-kind";
 export type ArtifactRenderProps = {
   readonly rendererKind: ArtifactRendererKind;
   readonly title: string;
-  /** Empty string is a legitimate, honestly-rendered "nothing here" —
-   * never distinguished from "not fetched yet" (the host's own loading
-   * state handles that before this component ever mounts). */
+  // Empty string is a legitimate "nothing here" — never distinguished
+  // from "not fetched yet", which the host's loading state handles first.
   readonly content: string;
-  /**
-   * True when `content` is empty NOT because the artifact is genuinely
-   * blank, but because its real bytes are stored out-of-band (a file
-   * upload) in a format this renderer can't decode as text — a binary
-   * `.docx`/`.xlsx`, an image, a real PDF. Empty `content` alone can't
-   * carry that distinction, so the host that fetched the artifact passes
-   * it explicitly. Swaps the per-kind "no content yet" copy for an honest
-   * "couldn't read this file" message — the artifact was NOT uploaded
-   * empty, its contents just can't be shown here.
-   */
+  // True when `content` is empty because the real bytes are out-of-band
+  // and undecodable, not because the artifact is genuinely blank — swaps
+  // in an honest "couldn't read this file" message instead.
   readonly contentUnavailable?: boolean;
-  /** Overrides the default "unsupported" copy with something specific to
-   * why this content can't be shown (e.g. a binary MIME type). */
   readonly unavailableReason?: string;
-  /**
-   * The sandboxed preview route (`GET .../artifacts/:id/preview`) for a
-   * `"html"`-kind artifact — the `<iframe sandbox="allow-scripts">`'s
-   * `src`. Absent when the host has no server-backed preview for this
-   * content (e.g. a chat blob that was never diverted into a Library
-   * artifact), in which case the pane falls back to an honest
-   * "unsupported" message rather than rendering raw markup unsandboxed.
-   */
+  // Absent when the host has no server-backed preview, in which case the
+  // pane falls back to "unsupported" rather than rendering raw markup
+  // unsandboxed.
   readonly previewSrc?: string;
 };
 
@@ -52,10 +31,8 @@ type DocLine =
   | { readonly kind: "bullet"; readonly text: string }
   | { readonly kind: "paragraph"; readonly text: string };
 
-/** Minimal, dependency-free markdown-lite: headings and bullet lists read
- * as structure, everything else is a paragraph. Not a markdown compiler —
- * inline emphasis/links pass through as literal text, which is honest
- * given no markdown-parser dependency is in scope for this phase. */
+// Not a markdown compiler — inline emphasis/links pass through as
+// literal text.
 function parseDocLines(content: string): readonly DocLine[] {
   return content
     .split("\n")
@@ -143,10 +120,8 @@ function SheetRenderer({
   return <CsvTable text={content} caption="Sheet contents" />;
 }
 
-/** No PDF-rendering dependency is in scope for this phase — a page-styled
- * frame around the artifact's stored text is the honest read: it shows
- * whatever text content exists (e.g. an extracted body) without claiming
- * to be a real paginated PDF viewer. */
+// No PDF-rendering dependency in scope — shows the stored text honestly
+// without claiming to be a real paginated viewer.
 function PdfRenderer({
   title,
   content,
@@ -175,14 +150,9 @@ function PdfRenderer({
   );
 }
 
-/**
- * Live sandboxed preview of a self-contained HTML artifact. `allow-scripts`
- * with NO `allow-same-origin` puts the framed document in an opaque unique
- * origin: it can run inline script, but it cannot read this app's cookies
- * or storage, call back into the hub API, or navigate the parent — the
- * server's own `Content-Security-Policy: sandbox allow-scripts` header
- * enforces the same posture even if an attribute got stripped somewhere.
- */
+// `allow-scripts` with NO `allow-same-origin`: the framed document runs
+// inline script but can't read this app's cookies/storage or call the hub
+// API. The server's CSP header enforces the same posture as a backstop.
 function HtmlPreviewRenderer({
   title,
   previewSrc,
diff --git a/apps/web/src/library/artifact-text-editor.tsx b/apps/web/src/library/artifact-text-editor.tsx
index f8c0818b4..7d3bde752 100644
--- a/apps/web/src/library/artifact-text-editor.tsx
+++ b/apps/web/src/library/artifact-text-editor.tsx
@@ -1,13 +1,6 @@
-// The editable half of a text-kind artifact's canvas pane. Built on top of
-// `ArtifactRenderer`'s read-only surface rather than replacing it:
-// `ArtifactRenderer` still owns every other kind, and a viewer with no
-// write access still renders through it read-only. This component only
-// ever mounts for a "doc"-kind artifact once the host has already decided
-// the viewer can edit — it never makes that call itself.
-//
-// This is a plain controlled textarea, debounced-saved through `onSave`
-// (the host wires that to the artifacts HTTP route's PUT). Single-user
-// editing only; no live co-viewer cursors, no shared doc, no awareness.
+// Only mounts once the host has already decided the viewer can edit — it
+// never makes that call itself. Single-user only: no co-viewer cursors,
+// no shared doc, no awareness.
 import { useRef, useState } from "react";
 
 import { formatSaveStateLine, type ArtifactSaveState } from "./save-state";
@@ -25,13 +18,9 @@ export interface ArtifactTextEditorProps {
   readonly onSave: (content: string) => void;
 }
 
-/**
- * The host must remount this component (`key={artifact.id}`) when the open
- * artifact changes — the same convention `ArtifactRenderer` doesn't need
- * because it's stateless, but this component's local `value` buffer is not:
- * without a remount, switching artifacts while one has unsaved keystrokes
- * would carry them onto the new artifact's content.
- */
+// The host must remount this (`key={artifact.id}`) on artifact change:
+// unlike stateless `ArtifactRenderer`, this has a local `value` buffer
+// that would otherwise carry unsaved keystrokes onto the new content.
 export function ArtifactTextEditor({
   content,
   title,
diff --git a/apps/web/src/library/kind-filter.ts b/apps/web/src/library/kind-filter.ts
index 224bda89d..dae7e539f 100644
--- a/apps/web/src/library/kind-filter.ts
+++ b/apps/web/src/library/kind-filter.ts
@@ -1,9 +1,5 @@
-// Pure helpers for the Artifacts kind nav (`/artifacts`,
-// `/artifacts/document`, …) — this module's own names keep the "library"
-// vocabulary (it's the internal name for the artifact store), but
-// `LIBRARY_PATH` tracks the app's real mount point: `/library` and
-// `/files` both stay routable only as redirects to `/artifacts` — see
-// `legacy-settings-redirects.tsx`.
+// Names here keep the "library" vocabulary (the internal name for the
+// artifact store), but `LIBRARY_PATH` tracks the app's real mount point.
 
 import { decodedOrNull } from "@corbits/url-path";
 
@@ -46,16 +42,8 @@ export function libraryArtifactIdFromPath(path: string): string | null {
   return decodedOrNull(rest);
 }
 
-/**
- * Whether an artifact belongs under a library kind nav segment
- * (`document` | `sheet` | `pdf` | `routine`). Empty segment matches all.
- *
- * Mapping:
- * - document → kind `document`, or kind `file` with .doc/.txt/.md title
- * - sheet → kind `csv-export` | `sheet`, or kind `file` with .xls/.csv title
- * - pdf → kind `pdf`, or kind `file` with .pdf title
- * - routine → kind `routine` only
- */
+// Empty segment matches all; see `resolveArtifactRendererKind` for the
+// same kind/extension mapping this reuses.
 export function artifactMatchesLibraryKindSegment(
   artifact: Pick<ArtifactSummary, "kind" | "title">,
   segment: string,
diff --git a/apps/web/src/library/provenance.ts b/apps/web/src/library/provenance.ts
index b7993e8c4..49ac2b79e 100644
--- a/apps/web/src/library/provenance.ts
+++ b/apps/web/src/library/provenance.ts
@@ -1,9 +1,5 @@
-// The one cheap provenance fact Library detail is worth showing: the
-// workflow run that produced an artifact, when its `source` says so
-// (`@corbits/artifacts`' `normalizeSource` — `{ origin: "workflow", runId }`
-// written by `packages/artifacts-hub`'s workflow finalize route). This is a
-// link, not a lineage system — every other origin, or a `source` shaped any
-// other way, reads as "nothing to show" rather than guessed at.
+// A link, not a lineage system — every other `source` shape reads as
+// "nothing to show" rather than guessed at.
 
 /** The workflow run id behind an artifact, or null when its `source` isn't
  * a recognized workflow origin. */
diff --git a/apps/web/src/library/renderer-kind.ts b/apps/web/src/library/renderer-kind.ts
index 985b3aec5..ee753ce61 100644
--- a/apps/web/src/library/renderer-kind.ts
+++ b/apps/web/src/library/renderer-kind.ts
@@ -1,8 +1,5 @@
-// Which typed renderer an artifact's content plays through — the canvas
-// pane, the Library detail preview, and a chat artifact chip's opened blob
-// all resolve to one of these before `ArtifactRenderer` ever sees them, so
-// the renderer itself never has to know whether it was picked by a Library
-// `kind` string or a chat `Part`'s MIME type.
+// Resolved before `ArtifactRenderer` ever sees it, so the renderer never
+// has to know whether it was picked by a Library `kind` or a MIME type.
 
 import { titleExtension } from "./title-extension";
 
@@ -10,13 +7,8 @@ export const ARTIFACT_RENDERER_KINDS = ["doc", "sheet", "pdf", "html", "unsuppor
 
 export type ArtifactRendererKind = (typeof ARTIFACT_RENDERER_KINDS)[number];
 
-/**
- * Renderer selection for a Library artifact — reuses the same
- * kind/extension mapping as the Library kind nav (`kind-filter.ts`), so a
- * card that files under "Sheet" always previews through the sheet
- * renderer. Routines have no typed renderer in this phase — they fall
- * back honestly to "unsupported" rather than guessing at a shape.
- */
+// Reuses the same mapping as the Library kind nav, so a card filed under
+// "Sheet" always previews through the sheet renderer.
 export function resolveArtifactRendererKind(artifact: {
   readonly kind: string;
   readonly title: string;
@@ -46,12 +38,8 @@ const SHEET_MEDIA_TYPES = new Set([
 ]);
 const PDF_MEDIA_TYPES = new Set(["application/pdf"]);
 
-/**
- * Renderer selection for a chat `Part`'s file attachment — no Library
- * `kind` exists for a blob that was never diverted into an artifact, so
- * this reads the MIME type first and falls back to the filename
- * extension exactly like the Library mapping does for a bare "file" kind.
- */
+// No Library `kind` exists for a blob never diverted into an artifact, so
+// this reads MIME type first, falling back to extension.
 export function resolveRendererKindFromMediaType(
   mediaType: string,
   filename: string,
@@ -68,11 +56,8 @@ export function resolveRendererKindFromMediaType(
   return "unsupported";
 }
 
-/** Whether a chat blob's bytes can be shown as text at all — gates whether
- * `chat-artifact-open.ts` even attempts to decode them. `.xls`/`.xlsx`
- * are binary spreadsheet formats, not CSV, so they resolve to the sheet
- * renderer by extension but are excluded here — decoding their bytes as
- * UTF-8 text would just show binary noise. */
+// `.xls`/`.xlsx` resolve to the sheet renderer by extension but are
+// excluded here: decoding their binary bytes as UTF-8 shows only noise.
 export function isTextDecodableMediaType(mediaType: string): boolean {
   const mime = mediaType.trim().toLowerCase();
   if (mime === "application/vnd.ms-excel") return false;
diff --git a/apps/web/src/library/save-state.ts b/apps/web/src/library/save-state.ts
index 972fb1b34..0eaf53ff9 100644
--- a/apps/web/src/library/save-state.ts
+++ b/apps/web/src/library/save-state.ts
@@ -1,8 +1,5 @@
-// The canvas artifact pane's save-state line — never a fake autosave claim.
-// "Saved · v12" is only ever rendered once the artifact's PUT route has
-// actually answered with that version; until then the host renders "Saving…" or "Unsaved
-// changes" honestly instead of guessing that a debounced write already
-// landed.
+// Never a fake autosave claim: "Saved · v12" renders only once the PUT
+// route has actually answered with that version.
 
 export type ArtifactSaveState =
   | { readonly kind: "read-only" }
diff --git a/apps/web/src/login-next.ts b/apps/web/src/login-next.ts
index d7987dab6..977a857bc 100644
--- a/apps/web/src/login-next.ts
+++ b/apps/web/src/login-next.ts
@@ -1,7 +1,5 @@
-// URLs tell the truth. The `next` query param carries where a
-// signed-out visit was headed so a successful sign-in returns there — but
-// it's attacker-controllable (a crafted `/login?next=...` link), so it must
-// resolve to an in-app path or nowhere at all. Never an open redirect.
+// `next` is attacker-controllable (a crafted `/login?next=...` link), so
+// it must resolve to an in-app path or nowhere — never an open redirect.
 
 import { LOGIN_PATH } from "./routes";
 
@@ -9,10 +7,8 @@ export function buildLoginRedirect(path: string): string {
   return `${LOGIN_PATH}?next=${encodeURIComponent(path)}`;
 }
 
-/** Same-origin in-app path only. Rejects absolute URLs, protocol-relative
- * paths (`//host/...`), backslash tricks browsers treat as
- * protocol-relative (`/\host/...`), and a loop back to `/login` itself —
- * falling back to `/` in every rejected case. */
+/** Same-origin in-app path only — rejects absolute/protocol-relative URLs
+ * and a loop back to `/login`, falling back to `/`. */
 export function validatedNextPath(search: string): string {
   const next = new URLSearchParams(search).get("next");
   if (next === null) return "/";
diff --git a/apps/web/src/login-routing.test.tsx b/apps/web/src/login-routing.test.tsx
index d0ce7f776..8da64811f 100644
--- a/apps/web/src/login-routing.test.tsx
+++ b/apps/web/src/login-routing.test.tsx
@@ -1,8 +1,5 @@
-// the URL bar is the source of truth for where you are.
-// `TestRoot` mirrors `main.tsx`'s `Root` history wiring (same pattern as
-// `test/auth.test.tsx`'s `ProbedApp`) so these tests drive real
-// `pushState`/`popstate` traffic instead of asserting against a bare
-// `navigate` prop.
+// `TestRoot` mirrors `main.tsx`'s `Root` history wiring so these tests
+// drive real `pushState`/`popstate` traffic, not a bare `navigate` prop.
 
 import { ThemeProvider } from "@corbits/react-ui";
 import { afterEach, describe, expect, test } from "bun:test";
@@ -36,10 +33,8 @@ const user: SessionUser = {
   email: "ada@example.com",
 };
 
-/** Set by `TestRoot` on every render so a test can drive the exact
- * `handleSignedIn` wiring `main.tsx`'s `Root` gives `AuthScreen` — reading
- * `next=` off the live URL at call time — without simulating a real
- * `LoginForm` submission end to end. */
+// Lets a test drive the exact `handleSignedIn` wiring `Root` gives
+// `AuthScreen` without simulating a real `LoginForm` submission.
 let capturedHandleSignedIn: ((user: SessionUser) => void) | null = null;
 
 function TestRoot({ initialSession }: { readonly initialSession: SessionState }) {
diff --git a/apps/web/src/main.tsx b/apps/web/src/main.tsx
index 3a10ee147..88601c491 100644
--- a/apps/web/src/main.tsx
+++ b/apps/web/src/main.tsx
@@ -1,9 +1,6 @@
-// The mount, and nothing else. This module declares no component on
-// purpose: a module that declares one becomes a React Refresh boundary,
-// and a hot update then re-executes it in place — calling `createRoot` on
-// `#root` a second time and leaving two reconcilers committing into one
-// container. The root itself is kept on the HMR data slot so even a
-// re-execution reuses the single root it already created.
+// No component declared here on purpose: that would make this module a
+// React Refresh boundary, whose hot re-execution would call `createRoot`
+// twice. The root is kept on the HMR data slot to survive re-execution.
 
 import "@corbits/react-ui/styles.css";
 import "./app.css";
diff --git a/apps/web/src/myra-deploy.ts b/apps/web/src/myra-deploy.ts
index 50a7fabb0..7719c7e82 100644
--- a/apps/web/src/myra-deploy.ts
+++ b/apps/web/src/myra-deploy.ts
@@ -1,7 +1,5 @@
 // Builds and publishes Myra's deployable definition entirely over stock
-// routes: ensure the `workflow`-kind asset exists, mint a short-lived push
-// token, push the rendered source tree into the asset's git repo, revoke
-// the token, and hand back the `WorkflowDeployInput` pinned to that commit.
+// routes, ending with a `WorkflowDeployInput` pinned to the pushed commit.
 import { ASSISTANT_SYSTEM_PROMPT } from "@corbits/myra/prompt";
 import { ASSISTANT_STEP_ID, ASSISTANT_WORKFLOW_ID } from "@corbits/myra/workflow-ids";
 import { renderBundledWorkflowSourceTree } from "@corbits/workflows/client";
@@ -75,23 +73,9 @@ export async function ensureMyraSourceAsset(
   return existing.id;
 }
 
-/**
- * The function-free projection of what `@corbits/myra`'s `buildMyraWorkflow`
- * produces, written to the asset's `definition.json` for readers — the entry
- * itself is a bundle no reader can slice apart. Hand-built here rather than
- * by calling that function, because it goes through `@intx/workflow`'s
- * `defineWorkflow`/`step`, which pull in `@intx/agent`'s Node-bound runtime
- * (file locking) that a browser bundle cannot resolve.
- *
- * It mirrors `defineWorkflow`'s own normalization
- * (`vendor/intx/workflow/src/definition/workflow.ts`'s `normalize`/
- * `applyDefaultInputStep`, and `primitives.ts`'s `step`): a single step with
- * no `after` gets `input: { from: "trigger.payload" }`; `triggers:
- * "unbounded"` (not the numeric default) gets `drainBehavior: "wait"`; a
- * bare `trigger` becomes a one-element `triggers` array. `toolFactories` is
- * empty and `toolPackagePins` is empty on purpose: the real factories ride
- * the bundle, and JSON cannot carry a function.
- */
+// Hand-built rather than calling `buildMyraWorkflow` directly, since that
+// pulls in a Node-bound runtime a browser bundle can't resolve. See
+// docs/myra-definition-json.md.
 export function buildMyraDefinitionJson(
   triggerAddress: string,
   declaredSources: readonly DeclaredSource[],
diff --git a/apps/web/src/myra-source.ts b/apps/web/src/myra-source.ts
index d5205b094..fb48b14ea 100644
--- a/apps/web/src/myra-source.ts
+++ b/apps/web/src/myra-source.ts
@@ -1,9 +1,6 @@
-// Myra's deploy source: a `workflow`-kind asset holding the three-file
-// codebase `renderBundledWorkflowSourceTree` emits, pushed over the stock
-// git smart-HTTP route and deployed as a source tree at that commit. That is
-// the one variant the stock deploy route can anchor from a browser: it
-// requires a `workflow`-kind asset, and a `workflow` asset only takes its
-// code by git push.
+// The stock deploy route requires a `workflow`-kind asset, and a
+// `workflow` asset only takes its code by git push — the one variant it
+// can anchor from a browser.
 import { type } from "arktype";
 
 export const MyraSourceConfig = type({
diff --git a/apps/web/src/navigation-context.ts b/apps/web/src/navigation-context.ts
index 7849d6ef3..3ff5af410 100644
--- a/apps/web/src/navigation-context.ts
+++ b/apps/web/src/navigation-context.ts
@@ -12,11 +12,8 @@ export const NavigateContext = createContext<Navigate>(() => {
   throw new Error("navigation used outside NavigationProvider");
 });
 
-/** Absent outside a signed-in shell (the onboarding wizard has no account
- * menu, no settings surface) — `undefined` rather than a throwing default,
- * so a reader like `AccountSection` (mounted in package tests with no
- * provider at all) can simply omit the Sign out action instead of
- * crashing. */
+// `undefined` rather than a throwing default so a reader mounted without a
+// provider (e.g. in package tests) can omit Sign out instead of crashing.
 export const SignOutContext = createContext<(() => void) | undefined>(undefined);
 
 /** Same availability rule as `SignOutContext`: present in the signed-in
diff --git a/apps/web/src/navigation.tsx b/apps/web/src/navigation.tsx
index bebdafff0..7ffb3e091 100644
--- a/apps/web/src/navigation.tsx
+++ b/apps/web/src/navigation.tsx
@@ -1,8 +1,6 @@
-// Client-side navigation, sized to what six flat routes need: a navigate
-// function provided by the entry point, anchors that intercept plain left
-// clicks, and nothing else. Deep links and modified clicks fall through to the
-// browser — the hub serves index.html for every non-/api path, so a full page
-// load lands on the same route.
+// Deep links and modified clicks fall through to the browser — the hub
+// serves index.html for every non-/api path, so a full page load still
+// lands on the same route.
 
 import { useContext } from "react";
 import type { ComponentProps, MouseEvent, ReactNode } from "react";
@@ -49,11 +47,8 @@ export function useSessionUser(): SessionUser | undefined {
   return useContext(SessionUserContext);
 }
 
-/**
- * Intercepts a plain left click on an in-app anchor. Modified clicks (new
- * tab, download) and clicks a handler already cancelled keep their native
- * behavior.
- */
+// Modified clicks (new tab, download) and already-cancelled clicks keep
+// their native behavior.
 export function handleLinkClick(
   event: MouseEvent<HTMLAnchorElement>,
   to: string,
diff --git a/apps/web/src/needs-converge.ts b/apps/web/src/needs-converge.ts
index 7cdb41f60..cedd64f4f 100644
--- a/apps/web/src/needs-converge.ts
+++ b/apps/web/src/needs-converge.ts
@@ -1,18 +1,5 @@
-// Convergence for the portable client manifest: stock writes only, after
-// gap checks. Group workbench creation sequence per workbench: stock
-// `POST /api/tenants { parentId }` → send the primary-thread first message
-// (the workbench's chat, only when the caller supplied its exact content)
-// → fork sub-threads as needed via `forkSubThread`. DMs are never created
-// here — they derive from participant-filtered threads over stock mail
-// snapshots the caller supplies, via `deriveDmThreads` in threads.ts.
-//
-// Creation idempotency rides native Message-IDs the hub stamps and returns:
-// the primary thread id is recorded on the child-tenant row and fork links
-// in the thread store, beside created ids — never a custom key. Reads stay
-// stock routes (mailbox list); writes stay stock routes (tenant create,
-// member invite, workflow deploy, run-mail send). Per-agent mailbox search
-// and full thread reads stay typed upstream gaps until the hub exposes
-// stock routes for them.
+// Stock writes only, after gap checks. DMs are never created here; they
+// derive from participant-filtered threads via `deriveDmThreads`.
 
 import { type } from "arktype";
 
@@ -90,18 +77,11 @@ export type StockHub = {
   listMyPrincipals(): Promise<MyMembership[]>;
   getTenant(id: string): Promise<HubTenant | null>;
   listPrincipals(tenantId: string): Promise<HubPrincipal[]>;
-  /** Omitting `parentId` mints a top-level tenant with the caller as its
-   * owner — the stock route the first-signup installer step uses to
-   * create the primary tenant; a workbench child tenant always supplies
-   * it. */
+  // Omitting `parentId` mints a top-level tenant with the caller as
+  // owner; a workbench child tenant always supplies it.
   createTenant(input: { name: string; slug: string; parentId?: string }): Promise<HubTenant>;
-  /**
-   * Invites by email and assigns `role` (a system role name, e.g.
-   * "member") in the same op — the stock invite route's `roleId` is the
-   * only way an invited principal gets any grant at all; without it the
-   * principal lands with zero roles and every subsequent read 403s
-   * (/ fix).
-   */
+  // `roleId` is the only way an invited principal gets any grant at all;
+  // without it every subsequent read 403s.
   inviteMember(tenantId: string, input: { email: string; role: string }): Promise<void>;
   deployWorkflow(tenantId: string, input: WorkflowDeployInput): Promise<void>;
   /** Whether a live (non-released, non-failed) deployment is anchored to
@@ -165,10 +145,8 @@ export class StockHubRequestError extends Error {
   }
 }
 
-/** Every tenant the signed-in user owns (active `owner` role), regardless
- * of whether it is a top-level home or a workbench child — the shared
- * read behind both the primary-tenant gap check and the first-signup
- * installer's "does a primary tenant already exist" probe. */
+/** Shared read behind the primary-tenant gap check and the first-signup
+ * "does a primary tenant already exist" probe. */
 export async function findOwnedTenants(hub: StockHub): Promise<HubTenant[]> {
   const memberships = await hub.listMyPrincipals();
   const activeOwned = memberships.filter(
@@ -221,10 +199,8 @@ export type ConvergeReport = {
   primaryThreads: PrimaryThread[];
 };
 
-/** Ensures the group workbench child tenant exists (stock `POST
- * /api/tenants { parentId }` when the stored id no longer resolves) and
- * invites its email members. Returns the converged tenant id, whether it
- * was just created, and its stored record. */
+/** Re-resolves the stored tenant id before creating one — the store can
+ * point at a tenant the hub no longer has. */
 async function convergeWorkbenchTenant(
   hub: StockHub,
   store: ChildTenantStore,
@@ -258,10 +234,8 @@ async function convergeWorkbenchTenant(
   return { tenantId: created.id, created: true };
 }
 
-/** Sends the workbench's primary-thread first message — the workbench's
- * chat — exactly when the caller supplied its content and no native
- * Message-ID is recorded yet. A recorded id means the send already
- * happened: never resend, never mint a custom key. */
+/** A recorded Message-ID means the send already happened — never resend,
+ * never mint a custom key. */
 async function convergePrimaryThread(
   hub: StockHub,
   store: ChildTenantStore,
@@ -351,13 +325,8 @@ export async function convergeNeedsList(
     if (stored === undefined) continue;
     const mail = await hub.listRunMail({ tenantId: stored.tenantId });
     const grouped = deriveThreads(mail);
-    // Ordering assumption: the stock mailbox list returns rows oldest-first,
-    // so mail[0] is the primary-thread first message. The recorded
-    // primaryThreadMessageId (written at send time) is authoritative and this
-    // fallback only covers mail sent before the id was recorded; if the hub
-    // ever returns newest-first or unordered rows, the root mistargets and
-    // the real sub-threads misclassify — until the hub documents ordering,
-    // prefer the recorded id.
+    // The recorded id is authoritative; mail[0] is only a fallback for mail
+    // sent before it was recorded (see docs/chat-mail-threading.md).
     const rootMessageId = stored.primaryThreadMessageId ?? mail[0]?.messageId;
     if (rootMessageId === undefined) continue;
     primaryThreads.push({
@@ -388,14 +357,9 @@ export type ForkSubThreadInput = {
   body: string;
 };
 
-/** Forks a sub-thread off a primary-thread message: the fork ancestry
- * (parent as In-Reply-To closing the References chain) rides the sent
- * first message natively, and the linkage is recorded in the client-held
- * thread store beside created ids. A fork already recorded for the same
- * parent + subject + recipients + body returns its native Message-ID
- * instead of resending; any of those differing (including an edited body)
- * sends anew. Rows recorded before recipients/body were stored match on
- * parent + subject only, preserving their exactly-once replay. */
+/** Replays by native Message-ID when parent + subject + recipients + body
+ * match an already-recorded fork; any difference sends anew. See
+ * docs/chat-mail-threading.md. */
 export async function forkSubThread(
   storage: StringStorage,
   hub: StockHub,
@@ -492,13 +456,8 @@ const RolePageShape = type({
   nextCursor: "string | null",
 });
 
-/**
- * Resolves a system role name (e.g. "member") to its per-tenant role id
- * over the stock roles route. A tenant's system roles are seeded by
- * `createTenant` itself, so this never needs to page past the first
- * roles listing in practice — the route is still cursor-shaped, so this
- * follows it rather than assuming a single page.
- */
+// Resolves a system role name (e.g. "member") to its per-tenant role id;
+// still pages the cursor-shaped route rather than assuming a single page.
 async function resolveRoleId(
   fetchImpl: typeof fetch,
   tenantId: string,
@@ -564,9 +523,8 @@ function parseBoundary<T>(
   return parsed;
 }
 
-/** Follows every page of a `{ data, nextCursor }` stock listing — the hub
- * caps pages at its own limit, so reading only the first page would
- * silently mistarget accounts past ~100 principals or memberships. */
+// The hub caps pages at its own limit, so stopping at page one would
+// silently mistarget accounts past ~100 rows.
 async function fetchAllPages<T>(
   fetchImpl: typeof fetch,
   basePath: string,
@@ -587,10 +545,8 @@ async function fetchAllPages<T>(
   }
 }
 
-/** Builds the StockHub port over stock routes only: tenant bootstrap,
- * member invite, workflow deploy, and run-mail send/list under the tenant
- * mailbox surface. Per-agent mailbox search and full thread reads stay
- * typed upstream gaps until the hub exposes stock routes for them. */
+// Per-agent mailbox search and full thread reads stay typed upstream gaps
+// until the hub exposes stock routes for them.
 export function createFetchStockHub(fetchImpl: typeof fetch = fetch): StockHub {
   return {
     async listMyPrincipals() {
diff --git a/apps/web/src/needs-list.ts b/apps/web/src/needs-list.ts
index e125d84f1..9bf2d82b5 100644
--- a/apps/web/src/needs-list.ts
+++ b/apps/web/src/needs-list.ts
@@ -130,11 +130,8 @@ const ChildTenantRecordSchema = type({
   localId: "string > 0",
   tenantId: "string > 0",
   kind: "'workbench'",
-  // The workbench's primary thread: the native Message-ID of the first
-  // conversation.message sent in the child tenant. Recorded beside the
-  // created id so a retry never resends — idempotency rides this id.
-  // Workbench metadata beyond Subject/List-ID (icon, prefs) lives here
-  // too: client-held, never a server table.
+  // Recorded so a retry never resends — idempotency rides this id.
+  // Workbench metadata beyond Subject/List-ID lives here too, client-held.
   "primaryThreadMessageId?": "string > 0",
   "icon?": "string > 0",
   "prefs?": "Record<string, unknown>",
@@ -192,11 +189,8 @@ const ThreadLinkSchema = type({
   // submission route accepts threading headers.
   "inReplyTo?": "string > 0",
   "references?": type("string > 0").array(),
-  // The forked subject, recipients, and body, so a retry of the same fork
-  // replays its recorded Message-ID while a different subject, recipient
-  // set, or edited body off the same parent sends anew. Rows written before
-  // recipients/body were recorded carry neither and match on parent+subject
-  // only, preserving their exactly-once replay.
+  // A retry of the same fork replays its recorded Message-ID; a different
+  // subject/recipients/body off the same parent sends anew.
   "subject?": "string > 0",
   "to?": type("string").array(),
   "body?": "string",
diff --git a/apps/web/src/onboarding.ts b/apps/web/src/onboarding.ts
index ae29730db..ddd367686 100644
--- a/apps/web/src/onboarding.ts
+++ b/apps/web/src/onboarding.ts
@@ -1,5 +1,4 @@
-// The browser side of the first-login hook: a read-only probe that never
-// mints anything. Setup counts as done only once the primary tenant has
+// A read-only probe: setup counts as done only once the primary tenant has
 // Myra live, so an install that failed midway resumes instead of landing
 // in an empty shell.
 
@@ -8,30 +7,21 @@ import { reportError } from "@corbits/error-sink";
 import { MYRA_SOURCE_CONFIG } from "./myra-source";
 import { createFetchStockHub, findOwnedTenants, type StockHub } from "./needs-converge";
 
-/** Any credential row this bench actually has stored — the cheap
- * pre-skip read the home page's first-workbench flow uses to tell "no
- * credential yet" apart from "still coming online". */
+// The cheap pre-skip read to tell "no credential yet" apart from "still
+// coming online".
 const CredentialsPage = type({
   data: type({ status: "string" }).array(),
 });
 
-/**
- * Outcome of the cheap credentials read used before trusting a
- * `seeded: true` hard-skip. A probe that cannot complete is never
- * collapsed into `none`: that would open paste-a-key as if no
- * key exists when one may already be connected.
- */
+// A probe that can't complete is never collapsed into `none`: that would
+// open paste-a-key as if no key exists when one may already be connected.
 export type ActiveCredentialProbe =
   | { readonly kind: "active" }
   | { readonly kind: "none" }
   | { readonly kind: "error" };
 
-/**
- * Whether `tenantId` has at least one credential in the `active`
- * status. A cheap, single read — no provider/catalog chain resolution —
- * so the caller treats it as the weaker check it is: only a confirmed
- * miss means "no key", never a probe failure.
- */
+// A cheap, single read, no chain resolution — only a confirmed miss
+// means "no key", never a probe failure.
 export async function hasActiveCredential(tenantId: string): Promise<ActiveCredentialProbe> {
   try {
     const response = await fetch(`/api/tenants/${tenantId}/credentials`);
@@ -45,10 +35,8 @@ export async function hasActiveCredential(tenantId: string): Promise<ActiveCrede
   }
 }
 
-// The hub's user-facing error envelope: `userMessage` is
-// consumer language, safe to render as-is; `refId` is what a person can
-// quote back for support. Never a raw `message`/stack/file-path field —
-// those stay in the hub's own logger.
+// `userMessage` is safe to render as-is; never a raw `message`/stack/
+// file-path field — those stay in the hub's own logger.
 const ErrorEnvelope = type({
   error: { code: "string", userMessage: "string", refId: "string" },
 });
@@ -56,12 +44,8 @@ const ErrorEnvelope = type({
 const FALLBACK_ERROR_MESSAGE =
   "Setting up your workbench hit a snag — we're on it. Try again in a moment.";
 
-/** What the first-login hook can conclude from the native status read:
- * the account either lands on an already-set-up hub (`existing-member`)
- * or on one that still needs setup (`needs-onboarding`). The hub's own
- * counts ride along in the status payload but the hook needs only the
- * verdict — seed/credential detail belongs to the setup flow (T6/T7),
- * not to this routing decision. */
+// Seed/credential detail belongs to the setup flow, not this routing
+// decision — the hook needs only the verdict.
 export type ProvisionOutcome =
   | { readonly kind: "existing-member" }
   | { readonly kind: "needs-onboarding" }
@@ -86,38 +70,16 @@ export async function triggerFirstLoginProvisioning(
   }
 }
 
-/* cut the rest of this module's provisioning surface: the
- * credential-submit, one-click OAuth connect, and complete-setup helpers
- * all spoke to the deleted `/api/onboarding/*` routes, so they went with
- * the hub mount. What remains is the first-login status read above plus
- * the agent-readiness tombstone below. Live callers (the home page's
- * first-workbench flow, the picker) no longer use it — they read Myra's
- * native agent definition directly — so this helper exists only to keep
- * the deleted route's absence explicit: a 404/410 is `route-gone`, never
- * a generic agent error. The setup flow itself is T6/T7's to build.
- * TODO(T6/T7): replace this tombstone with native readiness once
- * T6/T7 builds it — no new `/api/onboarding/*` client calls until then. */
+// The agent-readiness tombstone below exists only to keep the deleted
+// `/api/onboarding/*` route's absence explicit — a 404/410 is
+// `route-gone`, never a generic agent error.
 const ProvisioningStatus = type({
   kind: "'ready' | 'provisioning'",
   setupAgentReady: "boolean",
 });
 
-/**
- * Whether this account can start a conversation yet, and whether
- * anything is still coming online behind it. Deliberately not
- * a count: how many workflows a bench seeds is an implementation detail,
- * and a person watching "0 of 5" learns nothing they can act on.
- *
- * - `ready` — everything this bench seeds is live.
- * - `chat-ready` — Myra is live, so the person can start now; the rest
- *   converge in the background.
- * - `preparing` — Myra is not live yet; this is the only state worth
- *   holding someone on a loader for.
- * - `route-gone` — the legacy `/api/onboarding/provisioning-status`
- * route is gone (deleted it with the hub mount). Explicit on
- *   purpose: a deleted route must never read as "your agent is broken".
- * - `error` — readiness could not be checked; show the message and allow retry.
- */
+// Deliberately not a count: how many workflows a bench seeds is an
+// implementation detail a person watching "0 of 5" can't act on.
 export type AgentReadiness =
   | { readonly kind: "ready" }
   | { readonly kind: "chat-ready" }
@@ -125,14 +87,8 @@ export type AgentReadiness =
   | { readonly kind: "route-gone" }
   | { readonly kind: "error"; readonly message: string };
 
-/**
- * Legacy agent-readiness read against the deleted
- * `/api/onboarding/provisioning-status` route. No live caller uses this
- * (T1): the home page's first-workbench flow and the picker read
- * Myra's native agent definition directly instead. Kept so the route's
- * absence stays an explicit, testable outcome — a 404/410 answers
- * `route-gone`, never the generic agent error below.
- */
+// No live caller uses this — kept so the deleted route's absence stays
+// an explicit, testable outcome.
 export async function fetchAgentReadiness(tenantId: string): Promise<AgentReadiness> {
   try {
     const response = await fetch(
diff --git a/apps/web/src/pages/agents-page.tsx b/apps/web/src/pages/agents-page.tsx
index e7147e481..d4be89a27 100644
--- a/apps/web/src/pages/agents-page.tsx
+++ b/apps/web/src/pages/agents-page.tsx
@@ -1,9 +1,5 @@
-// Agents: a roster and nothing else — display name, live/starting status,
-// and a Chat action per agent. Everything this page used to carry (a
-// detail panel, run health/events/approvals, bulk archive) leaned on hub
-// routes or state no longer worth a whole screen; a chat with the agent is
-// the one action anyone actually used. Create-agent lives in the sidebar's
-// "+" menu, not here.
+// A roster and nothing else — a chat with the agent is the one action
+// anyone actually used. Create-agent lives in the sidebar's "+" menu.
 
 import {
   Badge,
@@ -32,13 +28,9 @@ import { Link } from "../navigation";
 import { useTenantQuery } from "../routines-api";
 import { StageTopBar } from "../shell/stage-top-bar";
 
-/**
- * One agent's roster row: `Live` once it has a live run address, `starting`
- * while a deploy is still landing one (mid-first-deploy or mid-redeploy),
- * `not-running` once its latest deployment has gone terminal (a hub
- * restart releases every prior allocation) — a restart is then the only
- * way forward.
- */
+// `not-running` once the latest deployment has gone terminal (a hub
+// restart releases every prior allocation) — restart is the only way
+// forward.
 export function agentRosterStatus(
   agent: Pick<ChatAgent, "liveAddress" | "latestStatus">,
 ): "live" | "starting" | "not-running" {
diff --git a/apps/web/src/pages/chat-thread-page.tsx b/apps/web/src/pages/chat-thread-page.tsx
index 38cbf5282..eacb4a5c9 100644
--- a/apps/web/src/pages/chat-thread-page.tsx
+++ b/apps/web/src/pages/chat-thread-page.tsx
@@ -171,10 +171,9 @@ function ChatTranscript({
   // data, not a fetch of its own.
   if (chat !== undefined) markChatSeen(chatId, chat.lastMessageId);
 
-  // The inbox stream is the only signal that an agent has answered; it
-  // carries no chat identity, so it invalidates rather than patches. An
-  // agent that parks on an ask sends no mail, but the same stream ticks
-  // over its turn, so the approvals read is refreshed alongside.
+  // Invalidates rather than patches: the inbox stream carries no chat
+  // identity. Also refreshes approvals, since a parked ask sends no mail
+  // but still ticks the same stream.
   useEffect(
     () =>
       subscribeToInbox(tenantId, () => {
@@ -184,11 +183,9 @@ function ChatTranscript({
     [tenantId, queryClient],
   );
 
-  // Only this agent's asks belong in this transcript; the bench-wide list
-  // is filtered down to the run address this chat talks to. Polling only
-  // covers the same "agent still starting" window `chatQuery` polls for —
-  // once live, the inbox subscription's invalidation above is the only
-  // trigger, so a single mailbox event issues one read, not two.
+  // Polling only covers the same "agent still starting" window `chatQuery`
+  // polls for — once live, the inbox subscription's invalidation is the
+  // only trigger.
   const liveAddress = chat?.agent.liveAddress ?? null;
   const approvalsQuery = usePendingApprovals(tenantId, {
     refetchInterval: liveAddress === null ? 3000 : false,
diff --git a/apps/web/src/pages/create-agent-panel.tsx b/apps/web/src/pages/create-agent-panel.tsx
index 99b6abc81..0b6606aca 100644
--- a/apps/web/src/pages/create-agent-panel.tsx
+++ b/apps/web/src/pages/create-agent-panel.tsx
@@ -1,9 +1,5 @@
-// The agent-create panel: name + system prompt, deployed through the stock
-// workflow-deploy path (`../agent-deploy.ts`) the same way Myra deploys
-// herself. There is no drafting assist and no per-agent model/skills pin
-// here — the routes that backed those were removed from the hub; the
-// agent's model resolves from the tenant's existing inference offering,
-// exactly as Myra's own deploy does.
+// No drafting assist or per-agent model/skills pin: the routes that backed
+// those were removed from the hub.
 
 import {
   Button,
diff --git a/apps/web/src/pages/create-skill-dialog.tsx b/apps/web/src/pages/create-skill-dialog.tsx
index b114d566c..da9690602 100644
--- a/apps/web/src/pages/create-skill-dialog.tsx
+++ b/apps/web/src/pages/create-skill-dialog.tsx
@@ -1,14 +1,6 @@
-// The create-skill dialog.
-//
-// this used to hand a full SKILL.md (name/description/body, or
-// an uploaded file) to the workbench's own skill registry, which parsed
-// and stored it. That registry is gone — skills are native `kind:"skill"`
-// hub assets now, and the stock asset routes (`@intx/hub-api`'s
-// `routes/assets.ts`) accept only a bare `{ kind, name, displayName }` on
-// create: there is no stock route yet to write a skill's SKILL.md content
-// in the same call. This dialog is scoped down to match: it names the
-// asset only, and hands off; writing the skill's actual instructions
-// happens through whatever surface eventually covers skill content.
+// Scoped down to naming the asset only: the stock asset routes accept a
+// bare `{ kind, name, displayName }`, with no stock route yet to write a
+// skill's SKILL.md content in the same call.
 import {
   Button,
   Dialog,
diff --git a/apps/web/src/pages/diff-view.tsx b/apps/web/src/pages/diff-view.tsx
index 3cba1b817..d407824eb 100644
--- a/apps/web/src/pages/diff-view.tsx
+++ b/apps/web/src/pages/diff-view.tsx
@@ -1,9 +1,5 @@
-// One diff renderer for every surface that shows "what changed": the
-// save-confirmation step and the version comparison on a detail page both
-// mount this, so a diff always reads the same way. The line script comes
-// from `@/lib/text-diff`; this file is only its presentation, and it
-// computes the script exactly once per render — the change summary is read
-// off the same result the rows come from.
+// Computes the diff script exactly once per render — the change summary
+// reads off the same result the rows come from.
 
 import { Badge, Table, TableBody, TableCell, TableRow } from "@corbits/react-ui";
 import { diffText } from "@/lib/text-diff";
diff --git a/apps/web/src/pages/insights-page-render.test.tsx b/apps/web/src/pages/insights-page-render.test.tsx
index db05feb8f..30b3a9828 100644
--- a/apps/web/src/pages/insights-page-render.test.tsx
+++ b/apps/web/src/pages/insights-page-render.test.tsx
@@ -1,12 +1,5 @@
-// A malformed percent-escape on an Insights deep link (`/insights/runs/%`)
-// must render the same landing dashboard any other unrecognized Insights
-// path gets — never a blank page (see `insights-path.ts`'s
-// `parseInsightsPath`, which InsightsPage calls with the exact same `path`
-// prop this test passes). deleted the usage/activity/tools/latency/
-// scope-switcher props `InsightsPage` used to take along with
-// `packages/insights` itself — `InsightsWorkbenchPage`'s workbench-scoped
-// mode now lives entirely in `InsightsRoute`, so a `/insights/workbench/...`
-// path is out of scope for this component-level test.
+// A malformed percent-escape on a deep link must render the same landing
+// dashboard any other unrecognized path gets — never a blank page.
 
 import { afterEach, describe, expect, test } from "bun:test";
 import { act } from "react";
@@ -112,11 +105,8 @@ describe("InsightsPage 'Running now' strip", () => {
     expect(el.textContent).toContain("Weekly digest");
   });
 
-  // Liveness is not a windowed property: a run that started long ago and is
-  // still running must not disappear from the strip or read 0 in the
-  // "Running now" KPI just because it started long before this page's
-  // recent-runs slice. Persist has not settled (`endedAt` absent), so the
-  // fire is live — not remapped to completed by the abandoned-fire window.
+  // Liveness is not a windowed property: a run started long ago must not
+  // disappear from the strip or the "Running now" KPI.
   test("a run started 8 days ago that is still running stays in the strip and the KPI", () => {
     const eightDaysAgo = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000).toISOString();
     const el = render("/insights", {
diff --git a/apps/web/src/pages/insights-page.test.ts b/apps/web/src/pages/insights-page.test.ts
index c1eac7a18..7f133a15a 100644
--- a/apps/web/src/pages/insights-page.test.ts
+++ b/apps/web/src/pages/insights-page.test.ts
@@ -66,10 +66,8 @@ describe("isRunningNow", () => {
     ).toBe(false);
   });
 
-  // Warm-keep: a routine's delivery agent stays deployed
-  // after it replies, so workflow_run.status lingers on `running`. Past the
-  // fire window that is not an in-flight job — Insights must not keep it in
-  // "Running now" forever.
+  // Warm-keep: status lingers on `running` after a reply, but past the
+  // fire window it's not in-flight — must not stay "Running now" forever.
   test("endedAt drops in-flight immediately, even while status is still running inside the window", () => {
     expect(
       isRunningNow(
diff --git a/apps/web/src/pages/insights-page.tsx b/apps/web/src/pages/insights-page.tsx
index 8d5308d9b..a88ab0527 100644
--- a/apps/web/src/pages/insights-page.tsx
+++ b/apps/web/src/pages/insights-page.tsx
@@ -1,11 +1,5 @@
-// Insights over the native `GET /workflows/runs` top-level listing: KPI
-// row, "running now" strip, recent purpose runs, and runs history grouped
-// by definition. The stock observability routes
-// (`vendor/intx/hub-api/src/routes/observability.ts`'s four GET routes)
-// are unimplemented stubs — each returns 501 — so this page is entirely
-// native `WorkflowRunResponse` data, already fetched the same way
-// `mission-control-page.tsx` and `routines-api.ts` read runs elsewhere in
-// this app.
+// The stock observability routes are unimplemented 501 stubs, so this
+// page is entirely native `WorkflowRunResponse` data.
 
 import {
   Badge,
@@ -76,11 +70,8 @@ export function formatWhen(iso: string): string {
   });
 }
 
-/** A platform workflow run's status (`WorkflowRunStatus`) doesn't spell
- * react-ui's `RunStatus` vocabulary the same way — normalize onto it here
- * so the badge tone always comes from `RUN_STATUS_TONE`, the one source
- * every run-status tone reads from, rather than a second opinion invented
- * on this page. */
+// Normalizes onto react-ui's `RunStatus` vocabulary so the tone always
+// comes from `RUN_STATUS_TONE`, never a second opinion invented here.
 const WORKFLOW_RUN_STATUS_ALIAS: Readonly<Record<WorkflowRunStatus, RunStatus>> = {
   deployed: "completed",
   running: "running",
@@ -174,10 +165,8 @@ function runsDetailLabel(stats: { readonly running: number; readonly errored: nu
 
 const ELAPSED_TICK_MS = 1_000;
 
-/** Ticks once a second while `enabled` — the clock the elapsed label next to
- * the pulsing `StatusDot` reads from, so it counts up like the live indicator
- * beside it instead of freezing at whatever instant this component mounted
- * or last re-rendered for an unrelated reason. */
+// So the elapsed label counts up like the live indicator, instead of
+// freezing at whatever instant this component last rendered.
 function useTickingNow(enabled: boolean): number {
   const [now, setNow] = useState(() => Date.now());
   useEffect(() => {
@@ -188,13 +177,9 @@ function useTickingNow(enabled: boolean): number {
   return now;
 }
 
-/** A run actually in flight right now (`status: running | updating`) —
- * liveness is not a windowed property, so this filters the full run set,
- * never the range-filtered one. A persisted `endedAt` means the fire
- * already finished, even if `status` still reads `running`. A live fire
- * with an in-flight turn stays in flight however old it is; without an
- * explicit no-in-flight signal, missing `turns` is not abandonment.
- */
+// Liveness is not a windowed property, so this filters the full run set,
+// never the range-filtered one. A persisted `endedAt` means the fire
+// already finished, even if `status` still reads `running`.
 export function isRunningNow(run: InsightsRun, now: number = Date.now()): boolean {
   const outcome = runOutcomeStatus(withListingAbandoned(run, now), now);
   return outcome === "running" || outcome === "updating";
@@ -204,22 +189,16 @@ function insightsRunStatus(run: InsightsRun, now: number = Date.now()): string {
   return runOutcomeStatus(withListingAbandoned(run, now), now) ?? run.status;
 }
 
-/** Wall-clock time since a run started, in the same "2m 12s" form as the
- * rest of this page (`durationLabel`) — never a fabricated live counter. */
+// Wall-clock time since start, never a fabricated live counter.
 export function elapsedLabel(createdAt: string, now: number): string {
   const startMs = Date.parse(createdAt);
   if (Number.isNaN(startMs)) return "—";
   return durationLabel(Math.max(0, now - startMs));
 }
 
-/**
- * "Running now" — a horizontally scrolling strip of the runs actually in
- * flight this instant (`status: running | updating`), not a fabricated
- * live-metrics ticker. Renders nothing when nothing is running, same
- * convention as react-ui's `WorkflowDock`: an empty "nothing running" strip
- * is a permanent fixture reporting the normal case, not an empty state worth
- * showing.
- */
+// Renders nothing when nothing is running — same convention as react-ui's
+// `WorkflowDock`: an empty strip reports the normal case, not an empty
+// state worth showing.
 function RunningNowStrip({
   runs,
   onOpenRun,
@@ -312,10 +291,8 @@ function InsightsLanding({
   onOpenRuns,
 }: {
   readonly runs: readonly InsightsRun[];
-  /** The feed's own `nextCursor` (`limit=100` fetch, see
-   * `insightsTopLevelRunsPath`) — non-null means more runs exist than the
-   * 100 fetched, so the KPIs below disclose the cap instead of silently
-   * presenting a truncated series as complete. */
+  // Non-null means more runs exist than fetched, so KPIs disclose the cap
+  // instead of presenting a truncated series as complete.
   readonly runsNextCursor: string | null;
   readonly routines: readonly ScheduledWorkflowDefinition[];
   readonly loading: boolean;
@@ -700,16 +677,8 @@ export function InsightsPage({
   );
 }
 
-/**
- * Insights scoped to one workbench — `/insights/workbench/:workbenchId`
- * resolves the workbench's own workbench tenant (see
- * `../insights-workbench-scope.ts`) and titles the page by the WORKBENCH name,
- * never the tenant's. A true legacy workbench (tenancy `null`) and an id
- * absent from the bench's own workbench list (a stale
- * `/insights/workbench/:tenantId` link, or any other mis-wired id — that
- * route is retired) both get an honest empty state instead of a doomed
- * tenant-scoped fetch.
- */
+// Titles the page by the workbench name, never the tenant's. A legacy or
+// mis-wired id gets an honest empty state instead of a doomed fetch.
 function InsightsWorkbenchPage({
   workbenchesLoading,
   resolution,
diff --git a/apps/web/src/pages/library-page.tsx b/apps/web/src/pages/library-page.tsx
index 376ae469a..3d20ad912 100644
--- a/apps/web/src/pages/library-page.tsx
+++ b/apps/web/src/pages/library-page.tsx
@@ -91,10 +91,8 @@ function ArtifactRows({
   const allSelected = artifacts.length > 0 && selection.selectedCount === artifacts.length;
   const headerChecked: SelectionCheckboxState =
     selection.selectedCount === 0 ? false : allSelected ? true : "indeterminate";
-  // `useListSelection` hands back ids in toggle/insertion order, not row
-  // order — a bottom-up shift-select would otherwise join/copy links out of
-  // visible order. Sort against this row order before handing ids to any
-  // bulk operation (copy links here, the context menu's `ids` below).
+  // `useListSelection` hands back ids in toggle order, not row order — a
+  // bottom-up shift-select would otherwise copy links out of visible order.
   const visibleOrder = useMemo(
     () => new Map(artifacts.map((artifact, index) => [artifact.id, index])),
     [artifacts],
@@ -171,13 +169,8 @@ function ArtifactRows({
   );
 }
 
-/**
- * The one cheap provenance fact worth surfacing: a link to the
- * workflow run that produced this artifact, when `source` says so
- * (`workflowRunIdFromSource`). Not a lineage system — every other origin
- * (manual, agent, imported, unknown) renders nothing here rather than
- * guessing.
- */
+// Not a lineage system — every other origin renders nothing rather than
+// guessing.
 function ProvenanceLine({ source }: { readonly source: Record<string, unknown> }) {
   const runId = workflowRunIdFromSource(source);
   if (runId === null) return null;
@@ -211,12 +204,9 @@ function PreviewPane({
     detail !== null && rendererKind === "html" && tenantId !== null
       ? artifactPreviewPath(tenantId, detail.id)
       : undefined;
-  // Empty `content` on a file artifact is ambiguous on its own: it's the
-  // honest "nothing here" for an inline-content artifact, but it's also
-  // what a real upload's row carries when its bytes live out-of-band and
-  // aren't text-decodable (an image, a real PDF, a legacy `.docx`/`.xlsx`).
-  // `source.upload.mimeType` disambiguates — present only when this
-  // artifact really does have stored bytes behind it.
+  // Empty `content` is ambiguous alone (honest "nothing here" vs. a real
+  // upload whose bytes aren't text-decodable); `uploadMimeType`
+  // disambiguates.
   const uploadMimeType = detail !== null ? uploadMimeTypeFromSource(detail.source) : null;
   const contentUnavailable =
     detail !== null &&
@@ -277,18 +267,8 @@ function PreviewPane({
   );
 }
 
-/**
- * The Artifacts stage: a row list of everything this workbench owns, with an
- * in-stage preview when a row is selected. Real data only.
- *
- * Every control the page owns — the workbench lens, the name filter, sort,
- * the rows/grid toggle, Upload — lives in `StageTopBar`'s action slot
- * (DESIGN.md → Pages & Routing: the top nav owns the page's actions, and a
- * page body never floats its own). The name filter drives the stage top
- * bar's own magnifier (`filter` prop) rather than a second input — the
- * magnifier IS this page's filter, never the global palette (DECISIONS.md
- * → Search).
- */
+// Every control lives in `StageTopBar`'s action slot (DESIGN.md -> Pages
+// & Routing) — a page body never floats its own.
 export function LibraryPage({
   artifacts,
   now,
@@ -354,18 +334,12 @@ export function LibraryPage({
   );
 
   const visibleIds = useMemo(() => visible.map((artifact) => artifact.id), [visible]);
-  // A row filtered out of `visibleIds` drops out of `selection.selectedIds`
-  // immediately (the hook reconciles against `ids` on every read) but
-  // `useListSelection` keeps it in its own internal state, so the row comes
-  // back selected if the filter that hid it is cleared. Deliberate: it
-  // matches Finder/Sheets ("clearing a filter doesn't lose your picks") and
-  // needs no bookkeeping here.
+  // Deliberate: matches Finder/Sheets — clearing a filter doesn't lose
+  // your picks, since `useListSelection` keeps them in internal state.
   const selection = useListSelection({ ids: visibleIds });
 
-  // Rows and cards render selection differently — only rows has checkboxes
-  // — so a selection made in one view has nothing to anchor to in the
-  // other. Clearing on view change is simpler than teaching the card view
-  // its own checkboxes for a selection UI it doesn't otherwise need.
+  // Only rows has checkboxes, so a selection has nothing to anchor to in
+  // cards — clearing on view change is simpler than adding card checkboxes.
   const [selectionViewMode, setSelectionViewMode] = useState(viewMode);
   if (selectionViewMode !== viewMode) {
     setSelectionViewMode(viewMode);
@@ -419,21 +393,15 @@ export function LibraryPage({
         actions={
           <>
             {selectedSummary !== null ? (
-              // This clears the open file and returns to the list — an
-              // action, not a filter. It used to say bare "All", which read
-              // as a third option in the scope group right beside it ("All"
-              // vs. "All workbenches"); this label can't be mistaken for
-              // that.
+              // An action, not a filter. Used to say bare "All", which read
+              // as a third scope option next to "All workbenches".
               <Button variant="ghost" size="sm" onClick={() => select(null)}>
                 Back to artifacts
               </Button>
             ) : null}
             {workbenchScope !== null && onScopeChange !== undefined ? (
-              // One control, two states — answers exactly one question
-              // ("whose files"). At lg the bordered segmented group matches
-              // `ViewToggle` in this bar; below lg that group is hidden and
-              // the overflow menu in this same slot is the way to reach
-              // All workbenches.
+              // Below lg the segmented group is hidden; the overflow menu
+              // in this same slot is the way to reach All workbenches.
               <>
                 <div
                   role="group"
@@ -612,11 +580,8 @@ export function LibraryRoute({ path }: { readonly path: string }) {
   const [uploading, setUploading] = useState(false);
   const [uploadError, setUploadError] = useState<string | null>(null);
   const [searchQuery, setSearchQuery] = useState("");
-  // `/artifacts/a/:id` — a chat artifact chip's "Open in Artifacts"
-  // deep link, distinct from the kind-nav segments below. It only ever
-  // sets the initial selection; the user's own clicks stay local state,
-  // the same way kind-nav selection already worked before this route
-  // existed.
+  // Only sets the initial selection; the user's own clicks stay local
+  // state, as kind-nav selection already worked before this route existed.
   const deepLinkedArtifactId = libraryArtifactIdFromPath(path);
   const [selectedId, setSelectedId] = useState<string | null>(deepLinkedArtifactId);
   const [appliedDeepLink, setAppliedDeepLink] = useState(deepLinkedArtifactId);
@@ -626,10 +591,9 @@ export function LibraryRoute({ path }: { readonly path: string }) {
   }
   const kindSegment = deepLinkedArtifactId === null ? libraryKindSegmentFromPath(path) : "";
 
-  // Artifacts' workbench-first lens: the workbench the person just
-  // came from, if `last-workbench.ts` recorded one for this bench, resolved
-  // to its own tenant via the same sidebar-backed activity listing every
-  // other bench-scoped surface already fetches.
+  // The workbench the person just came from, if `last-workbench.ts`
+  // recorded one — resolved via the same activity listing other
+  // bench-scoped surfaces already fetch.
   const activity = useBenchActivity(selectedTenantId);
   const lastWorkbenchId = selectedTenantId === null ? null : readLastWorkbenchId(selectedTenantId);
   const workbenchScope =
@@ -750,11 +714,9 @@ export function LibraryRoute({ path }: { readonly path: string }) {
                   await queryClient.invalidateQueries({
                     queryKey: tenantKeys.artifacts(selectedTenantId),
                   });
-                  // The confirmation names what the server actually stored
-                  // (its own titles), never the local `File` picked — the
-                  // two can differ (e.g. a collision rename), and a sibling
-                  // fix for empty content read-back means this toast must
-                  // only ever repeat the upload response, not assume it.
+                  // Names what the server actually stored, never the local
+                  // `File` picked — the two can differ (e.g. a collision
+                  // rename).
                   toast(artifactUploadToast(uploaded.map((artifact) => artifact.title)));
                 } catch (err) {
                   setUploadError(describeApiError(err, "uploading those files"));
diff --git a/apps/web/src/pages/onboarding-page.tsx b/apps/web/src/pages/onboarding-page.tsx
index 112bd7248..02846b3ac 100644
--- a/apps/web/src/pages/onboarding-page.tsx
+++ b/apps/web/src/pages/onboarding-page.tsx
@@ -1,23 +1,5 @@
-// The setup gate: the screen a signed-in
-// session lands on when the hub reports setup-required. It reads the
-// hub's native setup-status route, and a hub that already has tenants
-// bounces straight into the shell (`/`). An empty hub drives the
-// browser installer itself, as one converge loop over stock routes,
-// asking the operator only where a human input is genuinely required:
-//
-//   1. mint the account's primary tenant (stock `POST /api/tenants`) if
-//      it does not already own one;
-//   2. resolve a catalog offering to deploy Myra against — if the
-//      tenant already resolves one (inherited, or a previous run of
-//      this step), skip straight past; otherwise ask the operator to
-//      connect exactly one provider credential (`ProviderConnectStep`);
-//   3. push Myra's source tree and build its deploy input for that offering
-//      (`deployMyraSource`) and hand it to `bootstrapClientSession` as
-//      `myraDeploy`.
-//
-// A converged install lands on `/`; a stock capability gap this loop did
-// not anticipate, or a hard failure at any step, renders here with a
-// retry — a gap is not "ready".
+// A gap the install loop can't cross renders here with a retry, never a
+// silent "ready".
 import { Button, EmptyState } from "@corbits/react-ui";
 import { WarningCircle } from "@/lib/icons";
 import { WorkbenchLoadingState } from "@/chat";
@@ -86,11 +68,8 @@ export function OnboardingPage({ user }: { readonly user: SessionUser }) {
     checkStatus();
   }, [checkStatus]);
 
-  // Step 1: mint the primary tenant if this account does not already
-  // own one, then move to the offering-resolution step. Stays a
-  // separate phase from "installing" (which still runs the full
-  // `bootstrapClientSession` converge for the rest of the needs list)
-  // because a credential connect needs a tenant id to write against.
+  // A separate phase from "installing" because a credential connect
+  // needs a tenant id to write against.
   useEffect(() => {
     if (state.phase !== "resolving-tenant") return;
     let cancelled = false;
@@ -144,10 +123,8 @@ export function OnboardingPage({ user }: { readonly user: SessionUser }) {
     // out of this effect's dependency list.
   }, [state.phase, user]);
 
-  // Step 3: publish Myra's deploy input for the resolved offering, then
-  // hand off to the installing phase. Shared by both the
-  // already-resolved-offering path (above) and the operator-connected
-  // path (`ProviderConnectStep`'s `onConnected` below).
+  // Shared by both the already-resolved-offering path and the
+  // operator-connected path.
   function publishAndInstall(
     tenantId: string,
     tenantDomain: string,
diff --git a/apps/web/src/pages/provisioning-error-page.tsx b/apps/web/src/pages/provisioning-error-page.tsx
index 7d448618d..fd84c4bed 100644
--- a/apps/web/src/pages/provisioning-error-page.tsx
+++ b/apps/web/src/pages/provisioning-error-page.tsx
@@ -1,7 +1,5 @@
-// Shown when the first-login hook's provisioning call fails outright.
-// A signed-in user with zero benches and a failed provisioning attempt has
-// nothing useful to do anywhere else in the app, so this replaces the
-// whole shell rather than a toast a user could miss or dismiss past.
+// Replaces the whole shell, not a toast — a user with zero benches and a
+// failed provisioning attempt has nothing useful to do elsewhere.
 
 import { Button, EmptyState, PageShell } from "@corbits/react-ui";
 import { WarningCircle } from "@/lib/icons";
diff --git a/apps/web/src/pages/routine-detail-page.tsx b/apps/web/src/pages/routine-detail-page.tsx
index 69c8a100b..4db35bc25 100644
--- a/apps/web/src/pages/routine-detail-page.tsx
+++ b/apps/web/src/pages/routine-detail-page.tsx
@@ -1,8 +1,3 @@
-// `/workflows/<definitionId>` — a deployed definition's own page: name,
-// pause, run now, and its runs (with expandable event logs, from stock's
-// `GET /workflows/runs?definitionId=` and `GET
-// /workflows/runs/:runId/events` — `vendor/intx/hub-api/src/routes/runs.ts`).
-// The id is the definition id.
 import {
   Badge,
   Button,
diff --git a/apps/web/src/pages/run-status-tone-parity.test.ts b/apps/web/src/pages/run-status-tone-parity.test.ts
index 238319b5d..9a844e660 100644
--- a/apps/web/src/pages/run-status-tone-parity.test.ts
+++ b/apps/web/src/pages/run-status-tone-parity.test.ts
@@ -1,19 +1,5 @@
-// Guards against the exact bug this file was added for (design
-// review): a page grows its own run-status → tone map/function instead of
-// reading react-ui's `RUN_STATUS_TONE` (`workflow-run.ts`), and it quietly
-// disagrees — a cancelled run reading neutral grey on Routines and amber
-// warning on Insights, the same status meaning two different things in one
-// product. `RUN_STATUS_TONE` is the one place a run-status tone is allowed
-// to be decided; every surface below must normalize its own status
-// vocabulary onto react-ui's `RunStatus` and read the tone from there.
-//
-// A static scan can't verify this: the divergence this catches was a
-// `case "stopped": return "warning"` inside a switch, not an object
-// literal, and re-deriving "is this tone value equal to canonical" from
-// source text would mean parsing arbitrary JS — the general-purpose lint
-// framework this ticket explicitly says not to build. Calling the real
-// exported code and comparing its output to `RUN_STATUS_TONE` catches both
-// shapes (switch or map) with no parser.
+// Calls the real exported code and compares output, since a static scan
+// can't tell a switch's tone from an object literal's without parsing.
 import { describe, expect, test } from "bun:test";
 
 import { RUN_STATUS_TONE } from "@corbits/react-ui";
diff --git a/apps/web/src/pages/settings-nav.tsx b/apps/web/src/pages/settings-nav.tsx
index 6747d9f47..bf5773de3 100644
--- a/apps/web/src/pages/settings-nav.tsx
+++ b/apps/web/src/pages/settings-nav.tsx
@@ -1,9 +1,5 @@
-// Settings section nav: the master list of the settings surface, rendered
-// inside the stage beside the active section (master-detail — the list is
-// never repeated in the section panel). Grouping, gating, and icons come
-// from `@/settings`'s section registry
-// (`resolveSettingsSectionGroups`); this component only adapts the app's
-// scope context and router around it.
+// Grouping, gating, and icons come from `@/settings`'s section registry;
+// this component only adapts the app's scope context and router.
 
 import { SidebarItemRow } from "@corbits/react-ui";
 import { SETTINGS_STRINGS } from "@/settings";
diff --git a/apps/web/src/pages/settings-page.tsx b/apps/web/src/pages/settings-page.tsx
index 60cedc178..b31f9219c 100644
--- a/apps/web/src/pages/settings-page.tsx
+++ b/apps/web/src/pages/settings-page.tsx
@@ -1,11 +1,5 @@
-// Thin mount of `@/settings`'s shell: the package owns the section
-// registry (Account / Everyone groups, icons, tenancy gates — see
-// `resolveSettingsSectionGroups`); this file only adapts the app's
-// bench-selection state (see ../bench-context.tsx) and the URL into the
-// shape the package expects. `/settings` defaults to the first allowed
-// section; `/settings/:section` deep-links directly to it. The section nav
-// renders here in the stage, beside the active section (`settings-nav.tsx`)
-// — master-detail, the list is never repeated in the section panel.
+// Thin mount: this file only adapts the app's bench-selection state and
+// the URL into the shape `@/settings`'s shell expects.
 
 import { flattenSettingsSections, resolveActiveSection, SettingsShell } from "@/settings";
 import { PageShell } from "@corbits/react-ui";
@@ -41,13 +35,8 @@ export function SettingsRoute({
     activeSection === undefined ? null : settingsEntityIdFromPath(path, activeSection.id);
   const requestedSectionExists =
     requestedId !== null && sections.some((section) => section.id === requestedId);
-  // A gated section (People/Roles/Grants/Credentials) is absent from
-  // `sections` while its probe is still resolving, same as when it's
-  // genuinely denied — wait for every gate to settle before treating a
-  // miss as final, or a deep link to an about-to-be-allowed section would
-  // bounce away before its probe finishes. `error` is settled: the
-  // registry withholds the section and the nav shows a couldn't-check
-  // state rather than pretending the principal is unauthorized.
+  // Wait for every gate to settle before treating a miss as final, or a
+  // deep link to an about-to-be-allowed section would bounce away early.
   const accessSettled =
     access.people !== "loading" &&
     access.roles !== "loading" &&
diff --git a/apps/web/src/pages/skill-detail-page.tsx b/apps/web/src/pages/skill-detail-page.tsx
index 58410c2b4..a1798b28b 100644
--- a/apps/web/src/pages/skill-detail-page.tsx
+++ b/apps/web/src/pages/skill-detail-page.tsx
@@ -1,17 +1,6 @@
-// The skill detail page at `/skills/<name>`.
-//
-// this used to be a full editor over `@corbits/skills`' own registry —
-// description/body editing with diff review, restore-by-version off that
-// asset's git history, a "pinned by" list, and a private/shared visibility
-// toggle. That registry (and the workflow routes it served) was deleted:
-// skills are native `kind:"skill"` hub assets now, and the stock asset
-// routes (`@intx/hub-api`'s `routes/assets.ts`) carry only metadata — id,
-// name, displayName, creator, timestamps. There is still no stock route
-// for a skill's version history, pinned-by list, or scope/visibility
-// flag, so those stay out of this page. Its `SKILL.md` content, though,
-// is readable and writable the same way agent source is: over the
-// asset's own smart-HTTP git remote with a short-lived token (see
-// `skill-source.ts`).
+// No stock route for version history, pinned-by list, or visibility flag,
+// so those stay out of this page. SKILL.md content, though, is readable
+// and writable the same way agent source is (see `skill-source.ts`).
 import {
   Button,
   PageShell,
@@ -232,10 +221,8 @@ function SkillDraftEditor({
   );
 }
 
-/**
- * Mount at `/skills/:name`: resolves the workbench this skill is read from
- * and the name the route carries. The page owns its own stage chrome.
- */
+// Resolves the workbench this skill is read from and the name the route
+// carries.
 export function SkillDetailRoute({ path }: { readonly path: string }) {
   const { selectedTenantId } = useBench();
   const name = skillIdFromPath(path);
diff --git a/apps/web/src/pages/skills-page.tsx b/apps/web/src/pages/skills-page.tsx
index 0f0cdeeb7..30732b95f 100644
--- a/apps/web/src/pages/skills-page.tsx
+++ b/apps/web/src/pages/skills-page.tsx
@@ -1,19 +1,6 @@
-// Skills: a standalone rail destination, over the workbench's
-// real skill registry (`@corbits/skills`, via `../skills-api.ts`). Used to
-// be a Settings section; the owner moved it back out to its own
-// page — this is the only surface left, there is no Settings duplicate.
-// This replaced the session-local store shipped before that: a
-// skill now lives in a native `kind:"skill"` hub asset the moment it is
-// created, and its version history is that asset's git history.
-//
-// Two states a skill can be in, both visible in the "Who can see it"
-// column:
-//   private  — visible only to the person who wrote it (the default)
-//   shared   — visible to the whole workbench
-//
-// There is no external catalog: skills are authored in this workbench.
-// This page lists them; a single skill — its editor, its versions, its
-// visibility toggle — lives on its own page (`skill-detail-page.tsx`).
+// A skill lives in a native `kind:"skill"` hub asset the moment it's
+// created; its version history is that asset's git history. No external
+// catalog — skills are authored here, private by default or shared.
 
 import {
   PageShell,
@@ -55,14 +42,8 @@ function messageOf(cause: unknown): string {
   return cause instanceof Error ? cause.message : String(cause);
 }
 
-/**
- * The Skills roster over one workbench's skill registry, with its own
- * top-nav contract: the trail says where the reader is and the
- * top bar's action slot is the only home for "New skill". `tenantId` is the
- * registry every read is scoped to; opening a row navigates to that skill's
- * own page at `/skills/<name>`, which is where editing, versions,
- * and diffs live — this page never renders a skill inline.
- */
+// Opening a row navigates to `/skills/<name>`: editing, versions, and
+// diffs live there, never rendered inline here.
 export function SkillsPage({
   tenantId,
   navigate,
@@ -238,12 +219,7 @@ export function SkillsPage({
   );
 }
 
-/**
- * Skills roster mount at `/skills`: a thin adapter that resolves
- * which workbench's registry is listed. The stage chrome (breadcrumb trail,
- * action slot) belongs to `SkillsPage`; a single skill has its own route
- * (`/skills/<name>`, `skill-detail-page.tsx`).
- */
+// A thin adapter that resolves which workbench's registry is listed.
 export function SkillsRoute({ navigate }: { readonly navigate: (to: string) => void }) {
   const { selectedTenantId } = useBench();
 
diff --git a/apps/web/src/pages/tools-page.tsx b/apps/web/src/pages/tools-page.tsx
index 923a822bf..bb3fb7bac 100644
--- a/apps/web/src/pages/tools-page.tsx
+++ b/apps/web/src/pages/tools-page.tsx
@@ -1,8 +1,5 @@
-// Tools: a standalone rail destination listing the tool packages the
-// tenant's live agent deployments actually carry — read off each agent's
-// deployed `definition.json` (plus Myra's bundled mail/posix, which never
-// lands in that file). No stock route lists a tenant's MCP servers yet, so
-// this page has nothing to show for those until one exists.
+// No stock route lists a tenant's MCP servers yet, so this page has
+// nothing to show for those until one exists.
 
 import {
   PageShell,
@@ -21,10 +18,7 @@ import { useDeployedToolPackages } from "../tools/deployed-tool-packages";
 import { useBench } from "../bench-context";
 import { StageTopBar } from "../shell/stage-top-bar";
 
-/**
- * The tool packages the tenant's live agent deployments carry.
- * `tenantId` is the tenant every read is scoped to.
- */
+// `tenantId` is the tenant every read is scoped to.
 export function ToolsPage({ tenantId }: { readonly tenantId: string | null }) {
   const query = useDeployedToolPackages(tenantId);
   const crumbs = [{ label: "Tools" }];
@@ -89,10 +83,7 @@ export function ToolsPage({ tenantId }: { readonly tenantId: string | null }) {
   );
 }
 
-/**
- * Tools roster mount at `/tools`: a thin adapter that resolves which
- * workbench's registry is listed. The stage chrome lives on `ToolsPage`.
- */
+// A thin adapter that resolves which workbench's registry is listed.
 export function ToolsRoute() {
   const { selectedTenantId } = useBench();
 
diff --git a/apps/web/src/pages/workbench-page.tsx b/apps/web/src/pages/workbench-page.tsx
index 9128187e8..e6c956fca 100644
--- a/apps/web/src/pages/workbench-page.tsx
+++ b/apps/web/src/pages/workbench-page.tsx
@@ -1,10 +1,5 @@
-// A workbench is a child tenant, and its workbench is that tenant's mailbox:
-// the timeline is the tenant's mail threads, participants are its
-// principals, and a message is addressed to every agent in the workbench. The
-// left info column folds in what Mission Control used to show for a
-// bench overall — here scoped to this one workbench: latest activity,
-// relevant artifacts, and pending approvals with approve/deny. Sub-threads
-// are native in-reply-to chains, shown in a side panel.
+// See docs/chat-mail-threading.md. The left info column folds in what
+// Mission Control used to show, scoped to this one workbench.
 
 import {
   Button,
@@ -137,10 +132,8 @@ function WorkbenchInfoColumn({
   readonly latestMessage: WorkbenchMessage | undefined;
   readonly participants: readonly WorkbenchParticipant[];
 }) {
-  // Poll only while an agent in this workbench is still starting (released,
-  // no live address yet) — the same window `participants` itself polls for.
-  // Once every agent is live, the inbox subscription's invalidation is the
-  // only trigger, so one mailbox event issues one read, not two.
+  // Poll only while an agent is still starting; once live, the inbox
+  // subscription's invalidation is the only trigger.
   const anyAgentStarting = participants.some((p) => p.kind === "agent" && p.address === "");
   const approvalsQuery = usePendingApprovals(workbenchTenantId, {
     refetchInterval: anyAgentStarting ? 3000 : false,
@@ -221,12 +214,8 @@ function WorkbenchInfoColumn({
   );
 }
 
-/** Redeploys one released agent (asset present, no live run — a hub
- * restart releases every process-provisioned deployment). Renders nothing;
- * one instance per released agent, keyed by asset id, so a mount's own ref
- * plus the mutation's `isPending`/`isSuccess` keep StrictMode's double
- * render (and any refetch that finds the same agent still released) from
- * firing it twice. */
+// Renders nothing; a mount's own ref plus the mutation's `isPending`/
+// `isSuccess` keep StrictMode's double render from firing it twice.
 function AgentRedeployer({
   workbenchTenantId,
   agent,
@@ -273,11 +262,9 @@ function Workbench({ workbenchTenantId }: { readonly workbenchTenantId: string }
     queryFn: () => readWorkbench(workbenchTenantId),
   });
 
-  // The workbench mailbox stream is the only signal that an agent answered; it
-  // carries no thread identity, so it invalidates rather than patches. An
-  // agent that parks on an ask sends no mail, but the same stream ticks over
-  // its turn, so the approvals read invalidates here too instead of the info
-  // column polling it continuously while any agent is simply live.
+  // Invalidates rather than patches: the stream carries no thread
+  // identity. Also invalidates approvals, since a parked ask sends no
+  // mail but still ticks the stream.
   useEffect(
     () =>
       subscribeToInbox(workbenchTenantId, () => {
diff --git a/apps/web/src/path-ids.ts b/apps/web/src/path-ids.ts
index cc7bad3e3..6e01257b6 100644
--- a/apps/web/src/path-ids.ts
+++ b/apps/web/src/path-ids.ts
@@ -1,11 +1,5 @@
-// Path-id helpers for settings and top-level roster deep links. Shared by
-// the shell (col2 section nav) and the settings sections (stage detail) so
-// neither layer owns the other. Same pattern as workbench-path.ts. Agents
-// and Skills were Settings sections for a stretch at
-// `/settings/agents/:id` and `/settings/skills/:id`; //
-// moved both back out to their own top-level rail destinations —
-// `/agents/:id` and `/skills/:id`, via `agentIdFromPath`/`skillIdFromPath`
-// below.
+// Agents and Skills were Settings sections for a stretch; both moved back
+// out to their own top-level rail destinations (`/agents/:id`, `/skills/:id`).
 
 import { isValidSlug, type Slug } from "@/lib/slug";
 import { decodedOrNull } from "@corbits/url-path";
@@ -19,13 +13,9 @@ export const WORKFLOWS_PATH_PREFIX = "/workflows";
 export const INSIGHTS_PATH_PREFIX = "/insights";
 export const INSIGHTS_RUNS_PATH = `${INSIGHTS_PATH_PREFIX}/runs`;
 
-/** The slug a detail path carries — `null` unless the path is exactly
- * `<prefix>/<slug>`. Validation reads the raw segment: a slug carries no
- * percent-escape and no character that needs one, so decoding could only
- * turn a malformed URL into a `URIError` mid-render. An id-shaped segment
- * (`wfd_1`, `skill_1`) is not a slug either, so id deep links keep
- * resolving to their roster rather than to a slug-addressed detail
- * screen. */
+/** `null` unless the path is exactly `<prefix>/<slug>`. Reads the raw
+ * segment — decoding a slug could only turn a malformed URL into a
+ * `URIError` mid-render, and an id-shaped segment isn't a slug either. */
 export function detailSlugFromPath(path: string, prefix: string): Slug | null {
   const segment = rawSegmentFromTopLevelPath(path, prefix);
   if (segment === null) return null;
@@ -52,10 +42,8 @@ export function skillIdFromPath(path: string): string | null {
   return entityIdFromTopLevelPath(path, SKILLS_PATH_PREFIX);
 }
 
-/** The segment `/workflows/<segment>` addresses: a routine id (the
- * canonical address) or a name-derived slug the detail route resolves and
- * redirects to the id. `null` for the bare roster path, a path outside
- * Workflows, or a segment whose percent-escapes cannot be decoded. */
+/** A routine id (canonical) or a name-derived slug the detail route
+ * resolves and redirects to the id. */
 export function routineSegmentFromPath(path: string): string | null {
   return entityIdFromTopLevelPath(path, WORKFLOWS_PATH_PREFIX);
 }
diff --git a/apps/web/src/pending-approvals.test.tsx b/apps/web/src/pending-approvals.test.tsx
index d0bbe8258..9306c8a14 100644
--- a/apps/web/src/pending-approvals.test.tsx
+++ b/apps/web/src/pending-approvals.test.tsx
@@ -1,9 +1,6 @@
-// The client-side composer behind every approval surface: the platform's
-// pending list, named through the run view and the account's own
-// membership. What matters here is that a run is named once no matter how
-// many approvals it raised, that a refused list read is shown as a failure
-// rather than an empty queue, and that the chat card's status read speaks
-// the same display model.
+// Covers: a run is named once no matter how many approvals it raised, a
+// refused list read shows as a failure not an empty queue, and the chat
+// card's status read speaks the same display model.
 
 import { afterEach, describe, expect, test } from "bun:test";
 import { QueryClient } from "@tanstack/react-query";
diff --git a/apps/web/src/pending-approvals.ts b/apps/web/src/pending-approvals.ts
index 8f8e6169a..50ca9acc2 100644
--- a/apps/web/src/pending-approvals.ts
+++ b/apps/web/src/pending-approvals.ts
@@ -1,11 +1,5 @@
-// What's waiting on a person, composed on the client from Interchange's own
-// approval and run views. The platform's `GET /approvals` carries ids, the
-// tool snapshot and a status; the name of the agent that is asking lives on
-// the run view (`definitionName`), the bench's name on the account's
-// membership, and the human headline comes from `@corbits/approvals`'
-// `headlineFor`. Composing those three here is what lets this app render an
-// approval without a raw id ever reaching a rendered string, and without a
-// sibling read of its own on the hub.
+// Composes approval + run + membership views client-side so this app
+// renders an approval without a raw id ever reaching a rendered string.
 
 import { ApprovalResponse, WorkflowRunResponse } from "@intx/types";
 import { useQueries } from "@tanstack/react-query";
@@ -53,12 +47,8 @@ function runViewPath(tenantId: string, runId: string): string {
   return `/api/tenants/${tenantId}/runs/${runId}`;
 }
 
-/**
- * The display name of the agent behind a run. Answers `UNNAMED_AGENT` rather
- * than failing when the run view is unreadable — a per-deployment approver
- * can hold the grant to resolve an approval without holding the read grant
- * on its run.
- */
+// Answers `UNNAMED_AGENT` rather than failing when the run view is
+// unreadable — an approver can lack the read grant on the run itself.
 async function fetchAgentName(tenantId: string, runId: string): Promise<string> {
   const response = await fetch(runViewPath(tenantId, runId), {
     headers: { accept: "application/json" },
@@ -81,11 +71,8 @@ function composeApproval(row: ApprovalRow, agentName: string): ApprovalDisplay {
   };
 }
 
-/**
- * Every approval pending on this bench, newest-first as the platform lists
- * them. One naming read per distinct run, cached by react-query, so a run
- * with several pending asks is named once.
- */
+// One naming read per distinct run, cached by react-query, so a run with
+// several pending asks is named once.
 export function usePendingApprovals(
   tenantId: string | null,
   options?: { readonly refetchInterval?: number | false },
@@ -131,12 +118,8 @@ export function usePendingApprovals(
   };
 }
 
-/**
- * How many things need this bench's attention right now — the count the
- * shell's chip and the second column's signal render. `null` while unknown
- * (no bench selected yet, or the read hasn't resolved), so a caller never
- * mistakes "still loading" for "zero pending."
- */
+// `null` while unknown, so a caller never mistakes "still loading" for
+// "zero pending."
 export function usePendingApprovalCount(tenantId: string | null): number | null {
   const list = useAPIQuery(
     tenantId === null ? "" : pendingApprovalsPath(tenantId),
@@ -151,12 +134,8 @@ export type ApprovalDetailResult =
   | { readonly kind: "not-found" }
   | { readonly kind: "error"; readonly message: string };
 
-/**
- * The chat approve card's live status read: one approval, in any status,
- * through the same composer the list uses. The grant this read is refused
- * on (403) is the same per-deployment grant approve and reject are gated
- * on, so a refusal here is proof the viewer cannot act on it.
- */
+// A 403 here is proof the viewer cannot act on it — the same
+// per-deployment grant approve/reject are gated on.
 export async function getApprovalDetail(
   tenantId: string,
   approvalId: string,
diff --git a/apps/web/src/query-client.test.ts b/apps/web/src/query-client.test.ts
index b4bc6d32b..fa077cbd6 100644
--- a/apps/web/src/query-client.test.ts
+++ b/apps/web/src/query-client.test.ts
@@ -28,10 +28,8 @@ describe("pathToQueryKey", () => {
 });
 
 describe("tenantKeys.routineActivity", () => {
-  // the sidebar routine-activity seam keeps a shared cache key that
-  // names the seam — not the deleted `/top-level-runs` route — so both
-  // mounts subscribe to one entry and a future native fires equivalent has
-  // a key to rewire.
+  // Keyed by the seam, not the deleted `/top-level-runs` route, so both
+  // mounts share one cache entry.
   test("keys routine activity per tenant without the deleted route name", () => {
     expect(tenantKeys.routineActivity("tnt_1")).toEqual(["tenant", "tnt_1", "routine-activity"]);
     expect((tenantKeys.routineActivity("tnt_1") as readonly unknown[]).join("/")).not.toContain(
diff --git a/apps/web/src/query-client.ts b/apps/web/src/query-client.ts
index eb8077de1..f4c462d9d 100644
--- a/apps/web/src/query-client.ts
+++ b/apps/web/src/query-client.ts
@@ -8,45 +8,24 @@ import { ApiQueryError, UnauthenticatedError } from "@/lib/api-query";
 import { workbenchesQueryKey } from "@/chat/workbench-tenants";
 import type { WorkbenchKind } from "@/chat/workbench-tenants";
 
-/**
- * Retry policy shared by every query in the app: no session and a
- * definitive 404 both mean retrying cannot help — a 404 on a detail
- * lookup (an artifact or approval deleted since the link was made) is a
- * real, stable answer, not a transient failure, so retrying it three
- * times only delays an honest quiet no-op. Everything else (500s,
- * network failures) gets the normal three attempts.
- */
+// A 404 is a stable answer, not a transient failure, so retrying it three
+// times only delays an honest quiet no-op.
 export function shouldRetryQuery(failureCount: number, error: unknown): boolean {
   if (error instanceof UnauthenticatedError) return false;
   if (error instanceof ApiQueryError && error.status === 404) return false;
   return failureCount < 3;
 }
 
-/**
- * True for any error this app's hub requests throw to mean "the hub no
- * longer recognizes this session" — a 401 from `useAPIQuery` surfaces as
- * `UnauthenticatedError`, everywhere else (mutations, hand-rolled fetches
- * in `agents-api.ts`/`routines-api.ts`/etc.) as an `ApiQueryError` whose
- * `status` is 401. Both mean the same thing: the DB was reset, the
- * session's user was deleted, or the cookie simply expired mid-session.
- */
+// Both shapes mean the same thing: the DB was reset, the user was
+// deleted, or the cookie expired mid-session.
 export function isAuthInvalidError(error: unknown): boolean {
   if (error instanceof UnauthenticatedError) return true;
   return error instanceof ApiQueryError && error.status === 401;
 }
 
-/**
- * One QueryClient for the signed-in shell, wired so ANY query or mutation
- * that discovers the session is no longer valid — a restarted hub on an
- * empty DB, a cookie for a deleted user, a session that simply expired —
- * routes the whole app back to the login screen, not just the one widget
- * that happened to notice. Without this, a query that 401s renders its own
- * local "sign in required" box while the rest of the shell (nav, other
- * panels) keeps rendering as if nothing happened — the broken half-state
- * this hook exists to prevent. `onAuthInvalid` is called at most once per
- * invalid-session discovery; the caller is responsible for making it
- * idempotent (main.tsx's `handleSignOut` already is).
- */
+// Without this, a query that 401s renders its own "sign in required" box
+// while the rest of the shell keeps rendering. Caller must make
+// `onAuthInvalid` idempotent.
 export function createAppQueryClient(onAuthInvalid: () => void = () => undefined): QueryClient {
   return new QueryClient({
     queryCache: new QueryCache({
@@ -92,10 +71,8 @@ export const tenantKeys = {
   routineRunHistories: (tenantId: string) => ["tenant", tenantId, "routine-run-histories"] as const,
   definitions: (tenantId: string) => ["tenant", tenantId, "definitions"] as const,
   agentDirectory: (tenantId: string) => ["tenant", tenantId, "agents", "directory"] as const,
-  /** The sidebar's unified list of agent-DM candidates, backed by the
-   * stock `GET /workflows/definitions` listing (see `listAgentDefinitions`
-   * in `agents-api.ts`). Kept apart from `agentDirectory` above, which is
-   * a different surface's own key. */
+  // Kept apart from `agentDirectory` above, which is a different
+  // surface's own key.
   visibleAgents: (tenantId: string) => ["tenant", tenantId, "agents", "visible"] as const,
   assets: (tenantId: string) => ["tenant", tenantId, "assets"] as const,
   artifacts: (tenantId: string) => ["tenant", tenantId, "artifacts"] as const,
@@ -107,23 +84,15 @@ export const tenantKeys = {
   principals: (tenantId: string) => ["tenant", tenantId, "principals"] as const,
   roles: (tenantId: string) => ["tenant", tenantId, "roles"] as const,
   grants: (tenantId: string) => ["tenant", tenantId, "grants"] as const,
-  /** Settings section-nav gating (People/Roles/Grants/Credentials). Keyed
-   * so col2's nav band and the settings stage — mounted in separate
-   * subtrees — share one cached probe instead of each firing its own. */
+  // Keyed so col2's nav band and the settings stage share one cached
+  // probe instead of each firing its own.
   settingsAccess: (tenantId: string, principalId: string) =>
     ["tenant", tenantId, "settings-access", principalId] as const,
-  /** Delegates to `@/chat`'s own key builder — that package owns
-   * both the workbenches endpoint and `WorkbenchKind`, so this is the one array
-   * shape every workbench-listing surface (bench-activity, command palette,
-   * the Routines picker, `ChatWorkspace`'s own sidebar) keys against,
-   * rather than each side of the app/package boundary keeping its own copy
-   * of the literal that could drift apart. */
+  // Delegates to `@/chat`'s own key builder so every workbench-listing
+  // surface keys against one shape, not a copy that could drift apart.
   workbenches: (tenantId: string, kind: WorkbenchKind) => workbenchesQueryKey(tenantId, kind),
-  /** The sidebar routine-activity seam (`./shell/routine-activity.ts`).
-   * The `feed=fires` route this read is gone, so the query resolves with
-   * no items and issues no fetch — the key is kept (not the deleted
-   * `/top-level-runs` path) so both sidebar mounts still share one cache
-   * entry, and so a future native fires equivalent has a key to rewire. */
+  // The `feed=fires` route is gone; the key is kept so a future native
+  // fires equivalent has somewhere to rewire.
   routineActivity: (tenantId: string) => ["tenant", tenantId, "routine-activity"] as const,
   /** A workbench's own timeline reads: `tenantId` is the owning
    * bench chat's workbench-tenancy addresses these routes at (see
@@ -136,12 +105,8 @@ export const tenantKeys = {
     ["tenant", tenantId, "workbench-timeline-routine-runs", workbenchId] as const,
 };
 
-/**
- * Every surface that runs a routine (the routine panel's Run now button,
- * the shell context menu's Run now item) must refresh the same two reads —
- * the routines list and its run history — or one of them goes stale while
- * the other doesn't.
- */
+// Both reads must refresh together or one goes stale while the other
+// doesn't.
 export function invalidateRoutineQueries(queryClient: QueryClient, tenantId: string): void {
   void queryClient.invalidateQueries({
     queryKey: tenantKeys.routines(tenantId),
@@ -151,10 +116,8 @@ export function invalidateRoutineQueries(queryClient: QueryClient, tenantId: str
   });
 }
 
-/**
- * Map a hub GET path onto a stable query key. Unknown paths fall back to a
- * path-keyed entry so callers cannot accidentally share cache entries.
- */
+// Unknown paths fall back to a path-keyed entry so callers can't
+// accidentally share cache entries.
 export function pathToQueryKey(path: string): readonly unknown[] {
   if (path === "/api/me") return meKeys.profile;
   if (path === "/api/me/principals") return meKeys.principals;
diff --git a/apps/web/src/react-ui-toast-mock.ts b/apps/web/src/react-ui-toast-mock.ts
index 9458cd609..827803485 100644
--- a/apps/web/src/react-ui-toast-mock.ts
+++ b/apps/web/src/react-ui-toast-mock.ts
@@ -1,14 +1,5 @@
-// Observing `@corbits/react-ui`'s `toast` from a test means `mock.module`,
-// which rewrites the module registry for the whole process rather than for
-// the calling file — and bun offers no way to take that back. A stub
-// installed by one test file is therefore still installed when every later
-// file loads, and `toast-single-system.test.tsx` renders the real toaster
-// and asserts on the DOM: under a plain stub it observes nothing and fails
-// for reasons that have nothing to do with toasts.
-//
-// So the spy DELEGATES rather than replaces. Callers get the call record
-// they assert on, and any file that renders a real `<Toaster />` still sees
-// real toasts, whichever order bun happens to load the suites in.
+// Delegates rather than replaces `toast` — see docs/test-toast-mock.md for
+// why a plain stub breaks other suites via bun's global module registry.
 
 import { mock } from "bun:test";
 import { toast as sonnerToast } from "sonner";
@@ -18,10 +9,7 @@ const realToast = actualReactUi.toast;
 
 type ToastFn = typeof actualReactUi.toast;
 
-/**
- * Installs a delegating spy over `toast` and returns it. Call once at module
- * scope; `mockClear()` it between tests the way any other spy is cleared.
- */
+// Call once at module scope; `mockClear()` between tests like any spy.
 export function spyOnReactUiToast(): ReturnType<typeof mock<ToastFn>> {
   const spy = mock(((...args: Parameters<ToastFn>) => realToast(...args)) as ToastFn);
   // `toast` carries its own variants (`toast.error` and friends); the spy
@@ -34,12 +22,8 @@ export function spyOnReactUiToast(): ReturnType<typeof mock<ToastFn>> {
   return spy;
 }
 
-/**
- * Empties sonner's toast store. The store is global and outlives any one
- * `<Toaster />` mount or test file, so a suite that counts rendered toasts
- * starts here. `@corbits/react-ui`'s `toast` is a raise-only wrapper with no
- * dismiss of its own, so the clear goes to sonner directly.
- */
+// Sonner's store is global and outlives any one test file; `toast` is a
+// raise-only wrapper with no dismiss of its own, so this clears sonner directly.
 export function clearToasts(): void {
   sonnerToast.dismiss();
 }
diff --git a/apps/web/src/redirect.tsx b/apps/web/src/redirect.tsx
index c9dddd480..1f5000610 100644
--- a/apps/web/src/redirect.tsx
+++ b/apps/web/src/redirect.tsx
@@ -1,7 +1,5 @@
-// A screen that only exists to forward. The hop happens during render, not
-// from an effect, so the route it leaves never paints a frame of its own —
-// the router store publishes the new path on a microtask, so nothing is
-// updated mid-render.
+// Hops during render, not from an effect, so the route it leaves never
+// paints a frame of its own.
 
 import { useRef } from "react";
 
diff --git a/apps/web/src/root.tsx b/apps/web/src/root.tsx
index 86da1e014..4a603069e 100644
--- a/apps/web/src/root.tsx
+++ b/apps/web/src/root.tsx
@@ -37,12 +37,8 @@ export function Root() {
     [navigate],
   );
 
-  // The first-login hook: once per session that reaches signed-in, ask
-  // the hub's native setup-status route whether any bench exists yet. An
-  // empty hub reports setup-required so we route into the setup screen;
-  // a hub with tenants loads the shell normally. Read-only on purpose
-  // — this never mints anything. A failure blocks the shell
-  // entirely rather than leaving the user silently benchless.
+  // Read-only on purpose — never mints anything. A failure blocks the
+  // shell rather than leaving the user silently benchless.
   const [provisioningError, setProvisioningError] = useState<{
     message: string;
     refId?: string | undefined;
@@ -78,12 +74,8 @@ export function Root() {
     });
   }, []);
 
-  // Per-user storage when signed in so theme preference follows the account;
-  // signed-out / loading share the anonymous host key. Not synced to the
-  // preferences store: @corbits/react-ui's ThemeProvider owns mode
-  // entirely internally (localStorage read/write on setMode/cycleMode) and
-  // exposes no onChange hook or externally-supplied initial value a host
-  // could observe or override without forking the component.
+  // Per-user storage key so theme follows the account; not synced to the
+  // preferences store since ThemeProvider owns mode entirely internally.
   const themeStorageKey =
     session.kind === "signed-in" ? `corbits-theme:${session.user.id}` : "corbits-theme";
 
diff --git a/apps/web/src/router-store.ts b/apps/web/src/router-store.ts
index 12e1ed477..c9bc3c0be 100644
--- a/apps/web/src/router-store.ts
+++ b/apps/web/src/router-store.ts
@@ -1,9 +1,5 @@
-// The browser history as an external store: the path lives outside React,
-// so the shell subscribes with `useSyncExternalStore` instead of an effect
-// that registers a `popstate` listener after the first paint. Retired paths
-// are canonicalized here, before any screen mounts — a bookmark to
-// `/files/a1` becomes `/artifacts/a1` in the URL bar and in the store, and
-// no route entry exists just to bounce it.
+// The path lives outside React (`useSyncExternalStore`, not a `popstate`
+// effect). Retired paths canonicalize here before any screen mounts.
 
 import { redirectTargetFor } from "./routes";
 
@@ -45,12 +41,8 @@ export function getPath(): string {
   return currentPath;
 }
 
-/**
- * Push a new entry and publish the new path. The store keeps the pathname
- * only — every comparison against it (`matchesRoute`, `LOGIN_PATH`,
- * `ONBOARDING_PATH`) expects a bare path — while a query string like
- * `/login?next=...` still reaches the URL bar.
- */
+// The store keeps the pathname only, since every comparison against it
+// expects a bare path; a query string still reaches the URL bar.
 export function navigateTo(to: string): void {
   const url = new URL(to, window.location.origin);
   const canonical = canonicalPath(url.pathname);
diff --git a/apps/web/src/routes.tsx b/apps/web/src/routes.tsx
index f2060d719..d43484148 100644
--- a/apps/web/src/routes.tsx
+++ b/apps/web/src/routes.tsx
@@ -1,19 +1,5 @@
-// The route table: one entry per screen, consumed by the command palette
-// (label) and the route switch (render), so navigation and pages cannot
-// drift apart. The sidebar itself lists workbenches (conversations), not
-// routes — the primary footer reaches Artifacts, Skills, Tools, and
-// Workflows. Insights moved under Settings, reachable there and by deep
-// link and the palette. Conversation deep links
-// (`/w/:workbenchId`) stay routable; `/` is the Myra land hop (ensure +
-// open her conversation) for a bench with a workbench already, or the
-// guided first-workbench describe screen for a bench with none — never a
-// Home dashboard.
-// Approvals has no page — the Activity band owns them. Agents and Skills
-// are their own rail destinations again. Every path this app has retired
-// along the way (`/settings/agents`, `/routines`, `/files`, `/library`,
-// `/inbox`, `/mission-control`) lives in `RETIRED_PREFIXES` below, which
-// the router resolves before a screen mounts — never a route entry whose
-// only job is to bounce.
+// One entry per screen, consumed by both the palette and the route switch,
+// so navigation and pages cannot drift apart.
 
 import {
   ChatCircle,
@@ -82,12 +68,8 @@ const RoutineDetailRoute = lazy(async () => ({
   default: (await import("./pages/routine-detail-page")).RoutineDetailRoute,
 }));
 
-/** The signed-out screen — a real route, not a conditional swap:
- * any unauthenticated request for another path bounces here with `?next=`
- * so a successful sign-in returns to where the visitor meant to go. Not
- * one of `APP_ROUTES`: like `ONBOARDING_PATH`, it renders above the shell
- * entirely (no sidebar, no chrome to be "current" in) and is reached only
- * through the signed-out branch of `App`'s session switch. */
+// A real route, not a conditional swap, so a successful sign-in with
+// `?next=` returns to where the visitor meant to go.
 export const LOGIN_PATH = "/login";
 
 /** Landing point for a session the first-login hook just provisioned a
@@ -98,33 +80,18 @@ export const ONBOARDING_PATH = "/onboarding";
 /** Settings path — sidebar footer + settings page. */
 export const SETTINGS_PATH = "/settings";
 
-/** The template picker — every "+ New workbench" affordance
- * (sidebar, command palette) hops here first; picking a row is what
- * actually mints the workbench. Not in `NAV_ROUTES`: it has no sidebar
- * row of its own, only the "+" control and the palette reach it. */
+// Not in `NAV_ROUTES`: only the "+" control and the palette reach it.
 export const NEW_WORKBENCH_PATH = "/new";
 
-/** Detail routes are addressed by slug: one route path per
- * entity, ending in this segment. A path matches only when its last
- * segment is a real slug, so `/agents/wfd_1` still resolves to the Agents
- * roster (which owns id deep links) while `/agents/triage-bot` resolves to
- * the agent's own screen. */
+// A path matches only when its last segment is a real slug, so
+// `/agents/wfd_1` resolves to the roster, not a detail screen.
 const SLUG_SEGMENT = "/:slug";
 
 export const SKILL_DETAIL_PATH = `${SKILLS_PATH_PREFIX}${SLUG_SEGMENT}`;
 
-/**
- * Workflows are addressed by id, not by slug. DESIGN.md allows a slug in a
- * route only where it is "immutable and tenant-unique, enforced as a hard
- * database constraint — never a soft convention"; a workflow has no slug
- * column, so a name-derived one is exactly the soft convention that rule
- * forbids, and the documented fallback is the opaque id. So this route
- * claims any single segment under `/workflows`: an id renders the page,
- * and a name still resolves — `routine-detail-page.tsx` redirects it to
- * the id path — which keeps human-typed and shared-by-name links working
- * without making the fragile address canonical. A real slug column is
- * ticketed separately.
- */
+// Addressed by id, not slug: a workflow has no slug column, so a
+// name-derived one would be exactly the soft convention DESIGN.md
+// forbids. A name still resolves — the page redirects it to the id path.
 const ROUTINE_SEGMENT = "/:routine";
 export const ROUTINE_DETAIL_PATH = `${WORKFLOWS_PATH_PREFIX}${ROUTINE_SEGMENT}`;
 
@@ -147,22 +114,13 @@ export type AppRoute = {
   readonly label: string;
   readonly icon: ReactNode;
   readonly render: (path: string, navigate: (to: string) => void) => ReactElement;
-  /** False only for the one screen with no `StageTopBar` of its own — Myra
-   * land (`/`) is a bare ensure+redirect hop (see `pages/home-page.tsx`)
-   * with nothing in the stage to title itself while it resolves. `AppShell`
-   * covers that gap generically (`shell/app-shell.tsx`) rather than home-page
-   * inventing chrome for a screen that's never meant to linger. Every other
-   * route titles its own stage. */
+  // False only for `/`: a bare ensure+redirect hop with nothing to title
+  // while it resolves; `AppShell` covers that gap generically.
   readonly hasStageTopBar?: boolean;
 };
 
-/**
- * Matches nested product paths (`/routines/:id`, `/insights/...`) plus
- * conversation deep links (which also match when Myra land `/` is active)
- * and the slug-addressed detail routes (`/agents/:slug`). Other routes are
- * exact path matches. A roster prefix still matches its own nested paths,
- * so the sidebar footer row stays lit on a detail screen.
- */
+// A roster prefix still matches its own nested paths, so the sidebar
+// footer row stays lit on a detail screen.
 export function matchesRoute(routePath: string, path: string): boolean {
   if (routePath === CHATS_PATH_PREFIX) {
     return isChatPath(path);
@@ -316,13 +274,8 @@ function routesInOrder(paths: readonly string[]): readonly AppRoute[] {
   });
 }
 
-/**
- * Everything the command palette treats as a product destination (its
- * "Pages" group). The primary sidebar footer reaches Artifacts / Skills /
- * Tools / Workflows; Insights lives under Settings now. Agents, Insights
- * and Settings stay palette- and deep-link-reachable even though they are
- * off the primary rail.
- */
+// Agents, Insights and Settings stay palette- and deep-link-reachable
+// even though they're off the primary sidebar rail.
 export const NAV_ROUTES: readonly AppRoute[] = routesInOrder([
   "/artifacts",
   "/skills",
diff --git a/apps/web/src/routines-api.ts b/apps/web/src/routines-api.ts
index 820566c46..a9149e5a6 100644
--- a/apps/web/src/routines-api.ts
+++ b/apps/web/src/routines-api.ts
@@ -1,18 +1,6 @@
-// The Routines page's seam to stock workflow deployments: list, run-now,
-// pause/resume. `@corbits/workflows`'s deleted `./schedule/scheduled-route.ts`
-// (and the hub route it backed) is gone; this reads the stock deployments
-// listing (`GET /workflows/deployments`) joined against the tenant's workflow
-// assets (`GET /assets?kind=workflow`) for a display name, exactly the two
-// stock reads `vendor/intx/hub-api/src/routes/workflows.ts` exposes.
-//
-// The `schedule` trigger is reserved on Interchange but unimplemented — no
-// scheduler fires it — so a schedule here is a `@corbits/cron` row addressed
-// at the deployment's live run, joined in from `GET /cron` by that address
-// (the same `run_<id>@<domain>` join `chat/threads-api.ts` does against
-// `listTopLevelRuns`). Run-now and pause/resume have no backing stock route
-// either (`/deployments` is list/create only; no per-deployment PATCH or
-// trigger route exists), so both stay rejected promises with a message
-// naming the missing route, same pattern as before.
+// The Routines page's seam to stock workflow deployments. See
+// docs/routines-scheduling.md for the schedule join and why run-now/
+// pause/resume stay rejected promises.
 
 import { type } from "arktype";
 import { useQuery } from "@tanstack/react-query";
@@ -87,11 +75,8 @@ async function fetchJSON<T>(path: string, schema: (data: unknown) => T | type.er
   return parsed;
 }
 
-/** Myra's own deploy source and every agent `agent-deploy.ts` created are
- * `workflow`-kind assets too, but they're chat partners, not workflows —
- * excluded by the same asset naming the chat/deploy pipeline already owns
- * (`MYRA_SOURCE_CONFIG.assetName`, `agent-<slug>-source`), so this list
- * never depends on runtime agent state to stay accurate. */
+// Myra and every deployed agent are `workflow`-kind assets too, but they're
+// chat partners, not workflows — excluded by name, not runtime state.
 function isAgentAssetName(name: string): boolean {
   return name === MYRA_SOURCE_CONFIG.assetName || isAgentDeploySourceAssetName(name);
 }
@@ -165,13 +150,8 @@ export function setScheduledWorkflowStatus(
   );
 }
 
-/**
- * Tenant-scoped query via TanStack Query. Keys must be stable arrays that
- * already include the tenant id under the `["tenant", tenantId, ...]`
- * convention so a bench switch can `removeQueries` the whole prefix.
- * When `enabled` is false the previous result is not kept on screen — TQ
- * drops the active fetch and the adapter reports loading until re-enabled.
- */
+// Keys must be stable arrays under `["tenant", tenantId, ...]` so a bench
+// switch can `removeQueries` the whole prefix.
 export function useTenantQuery<T>(
   key: readonly unknown[],
   enabled: boolean,
diff --git a/apps/web/src/session.ts b/apps/web/src/session.ts
index cf1a26e7a..1d44e69e2 100644
--- a/apps/web/src/session.ts
+++ b/apps/web/src/session.ts
@@ -1,7 +1,5 @@
-// The one session boundary: a single probe of better-auth's get-session
-// endpoint decides whether the app mounts the shell or the auth screen, and
-// the email+password calls live beside it so every /api/auth path is written
-// in exactly one file.
+// The one session boundary: a probe of better-auth's get-session endpoint
+// decides shell vs. auth screen; every /api/auth path lives in this file.
 
 import { type } from "arktype";
 
@@ -21,11 +19,8 @@ export type SessionState =
   | { readonly kind: "error"; readonly message: string }
   | { readonly kind: "signed-in"; readonly user: SessionUser };
 
-/**
- * Asks the hub whether this browser has a session. better-auth answers 200
- * with a JSON `null` body when there is none, so "signed out" is a normal
- * response here — never a 401 in the log.
- */
+// better-auth answers 200 with a JSON `null` body when there's no
+// session, so "signed out" is normal here, never a 401 in the log.
 export async function fetchSession(): Promise<SessionState> {
   try {
     const response = await fetch("/api/auth/get-session", {
@@ -41,12 +36,8 @@ export async function fetchSession(): Promise<SessionState> {
     const body: unknown = await response.json();
     if (body === null) return { kind: "signed-out" };
     const parsed = SessionPayload(body);
-    // A session payload that parses but is missing its user (or is
-    // shaped unrecognizably) means the hub answered without a session
-    // this app can use — a restarted hub on an empty DB, or a cookie for
-    // a user that no longer exists. That is "no session", not a genuine
-    // connectivity failure: it routes to the login screen exactly like a
-    // 401 or a `null` body, never to the "connection lost" error state.
+    // An unrecognizable payload means "no session" (restarted hub, dead
+    // cookie), not a connectivity failure — routes to login, not "offline".
     if (parsed instanceof type.errors) return { kind: "signed-out" };
     return { kind: "signed-in", user: parsed.user };
   } catch {
@@ -63,13 +54,8 @@ export type AuthResult =
 
 const FailureBody = type({ message: "string" });
 
-/**
- * better-auth answers a rate-limited request with a bare 429 and an
- * `X-Retry-After` header (seconds). Every auth entry point in this file
- * shares this so sign-in, sign-up, and social sign-in all tell the person
- * what happened and when it's worth trying again, instead of surfacing
- * better-auth's generic "Too many requests" body.
- */
+// Shared so sign-in, sign-up, and social sign-in all tell the person when
+// it's worth retrying, instead of surfacing better-auth's generic body.
 function rateLimitedResult(response: Response): AuthResult {
   const retryAfterSeconds = Number(response.headers.get("x-retry-after"));
   return {
@@ -120,11 +106,8 @@ export function signIn(email: string, password: string): Promise<AuthResult> {
   return postAuth("/api/auth/sign-in/email", { email, password });
 }
 
-/**
- * Creates the account. better-auth requires a display name; like the CLI's
- * admin bootstrap, it starts as the address's local part until the hub grows
- * a profile editor.
- */
+// better-auth requires a display name; starts as the address's local part
+// until the hub grows a profile editor.
 export function signUp(email: string, password: string): Promise<AuthResult> {
   const name = email.split("@")[0] ?? email;
   return postAuth("/api/auth/sign-up/email", { name, email, password });
@@ -133,29 +116,16 @@ export function signUp(email: string, password: string): Promise<AuthResult> {
 const SocialProviderId = type("'google' | 'github'");
 export type SocialProviderId = typeof SocialProviderId.infer;
 
-/**
- * Client config for the sign-in screen's OAuth buttons: the providers
- * this client knows how to draw. Stock Interchange exposes no sign-in
- * discovery endpoint, so the client drives — there is intentionally no
- * fetch here. The hub still decides which of these actually work:
- * better-auth only wires the credential pairs it was given, so an
- * unconfigured click surfaces better-auth's own error on the form.
- */
+// Stock Interchange exposes no sign-in discovery endpoint, so the client
+// drives this list — an unconfigured click surfaces better-auth's own
+// error on the form.
 export const SOCIAL_SIGN_IN_PROVIDERS: readonly SocialProviderId[] = ["google", "github"];
 
 const SocialSignInResponse = type({ url: "string" });
 
-/**
- * Starts better-auth's OAuth redirect flow: better-auth's
- * sign-in/social endpoint does not itself redirect the browser — it
- * answers with the provider's authorization URL as JSON, and the
- * client is the one that navigates there. The provider then redirects
- * back to better-auth's own callback endpoint, which exchanges the
- * code, sets the session cookie, and only then redirects the browser
- * to `callbackURL` — so by the time this SPA reloads there, the normal
- * `fetchSession` probe on mount already finds a signed-in session with
- * no dedicated callback route needed on this side.
- */
+// better-auth's endpoint answers with the authorization URL as JSON
+// rather than redirecting itself; by the time the SPA reloads at
+// `callbackURL`, `fetchSession` on mount already finds a signed-in session.
 export async function signInSocial(provider: SocialProviderId): Promise<AuthResult | null> {
   try {
     const response = await fetch("/api/auth/sign-in/social", {
@@ -195,11 +165,8 @@ export async function signInSocial(provider: SocialProviderId): Promise<AuthResu
   }
 }
 
-/** Fires the server-side sign-out. The UI signs out optimistically
- * regardless of this call's outcome (see `main.tsx`'s `handleSignOut`) —
- * returns whether the server actually cleared the session, so the caller
- * can surface a failure rather than silently leaving a live session
- * behind on the server. */
+// The UI signs out optimistically regardless of outcome; the boolean
+// lets the caller surface a failure instead of leaving a live session.
 export async function signOut(): Promise<boolean> {
   return fetch("/api/auth/sign-out", {
     method: "POST",
diff --git a/apps/web/src/settings-access.ts b/apps/web/src/settings-access.ts
index e88249565..6476f1a8b 100644
--- a/apps/web/src/settings-access.ts
+++ b/apps/web/src/settings-access.ts
@@ -1,11 +1,6 @@
-// Settings section-nav gating, deduplicated: col2's nav band and the
-// settings stage both mount independently and both need the same four
-// tenancy probes (People/Roles/Grants/Credentials). Riding the app's shared
-// QueryClient — instead of each mount calling `@/settings`'s bare
-// `useTenancyAccess`, which fetches on every mount with no cache — means
-// two mounted consumers share one in-flight request and one cached result.
-// The package stays free of TanStack Query: this only injects the
-// package's probe into the app's cache, the package never imports Query.
+// Rides the app's shared QueryClient so col2's nav band and the settings
+// stage share one in-flight request instead of each fetching on mount.
+// The `@/settings` package itself stays free of TanStack Query.
 
 import { coalesceSectionAccess, probeSectionAccess } from "@/settings";
 import type { TenancyAccess } from "@/settings";
@@ -33,11 +28,8 @@ function coalesceTenancyAccess(
   };
 }
 
-/** One shared probe per (tenant, principal), not one per mounted consumer.
- * `null` ids report `loading` — the same "not shown yet, never disabled"
- * contract `@/settings`'s own hook holds. A thrown evaluate
- * (network/5xx) is `error`, not `denied`; a refetch failure keeps the
- * last allow/deny so gated nav does not vanish as if unauthorized. */
+// A thrown evaluate is `error`, not `denied`; a refetch failure keeps the
+// last allow/deny so gated nav doesn't vanish as if unauthorized.
 export function useSettingsAccess(
   tenantId: string | null,
   principalId: string | null,
diff --git a/apps/web/src/settings-groups.tsx b/apps/web/src/settings-groups.tsx
index 7371a36c3..b68cf924d 100644
--- a/apps/web/src/settings-groups.tsx
+++ b/apps/web/src/settings-groups.tsx
@@ -1,9 +1,5 @@
-// One resolver for the settings section groups this app actually shows —
-// the package's own Account/Everyone registry, plus this app's one splice:
-// Insights, pulled off the primary nav rail and reachable here instead.
-// Both `settings-page.tsx` (stage) and `pages/settings-nav.tsx` call this
-// rather than the package's bare `resolveSettingsSectionGroups` directly,
-// so the two can never drift.
+// Both the stage and the nav call this, not the package's bare resolver
+// directly, so the two can never drift.
 
 import { ChartBar } from "@/lib/icons";
 import { insertEveryoneSections, resolveSettingsSectionGroups } from "@/settings";
diff --git a/apps/web/src/settings/access.test.ts b/apps/web/src/settings/access.test.ts
index 30f7c1a29..003128452 100644
--- a/apps/web/src/settings/access.test.ts
+++ b/apps/web/src/settings/access.test.ts
@@ -1,7 +1,5 @@
-// ACL evaluate probes decide whether People/Roles/Grants/Credentials belong
-// in the settings nav. A 200 with effect !== allow is an authenticated deny;
-// a thrown probe (network, 5xx) is not — it must not collapse to "denied"
-// or those sections vanish as if the principal were unauthorized.
+// A thrown probe (network, 5xx) must not collapse to "denied", or a
+// section would vanish as if the principal were unauthorized.
 
 import { afterEach, describe, expect, test } from "bun:test";
 
diff --git a/apps/web/src/settings/access.ts b/apps/web/src/settings/access.ts
index 5f48f8e2d..22979bff4 100644
--- a/apps/web/src/settings/access.ts
+++ b/apps/web/src/settings/access.ts
@@ -1,13 +1,5 @@
-// Whether the People/Roles/Grants/Credentials sections belong in the
-// settings nav at all, decided the way the rest of this surface's og
-// pages already gate access: never a disabled tab, just an absent one.
-// There's no capability listing to read this off of, so this probes the
-// one grant-checked route that requires no grant of its own —
-// `evaluate` — for the resource each section is built on.
-// A 200 whose effect is not `allow` is an authenticated deny. A thrown
-// probe (network, 5xx) is `error`, never `denied` — collapsing those
-// together made the gated nav vanish as if the principal were
-// unauthorized.
+// A thrown probe (network, 5xx) is `error`, never `denied` — collapsing
+// those together made the gated nav vanish as if unauthorized.
 
 import { evaluate } from "./tenancy-api";
 
diff --git a/apps/web/src/settings/account-section.tsx b/apps/web/src/settings/account-section.tsx
index 218efef03..325404f7a 100644
--- a/apps/web/src/settings/account-section.tsx
+++ b/apps/web/src/settings/account-section.tsx
@@ -1,11 +1,6 @@
-// Personal Settings' opening section: a glanceable Account card (avatar,
-// name, email — copyable — and Sign out), the same name/email/verified
-// readout as before tucked below as a quieter subsection (still read-only —
-// there is no native profile-update route; see `vendor/intx/hub-api/src/
-// routes` — only tenants and principals carry a PATCH), an Appearance card
-// wired to `@corbits/react-ui`'s three-state ThemeProvider. The Agent card
-// (a display-only Timezone row) was removed — nothing there could be
-// changed until a hub preference store exists to write it to.
+// Name/email readout is read-only: no native profile-update route exists.
+// The Agent card was removed — nothing there could change until a hub
+// preference store exists to write it to.
 
 import {
   Avatar,
@@ -74,11 +69,8 @@ async function copyEmail(email: string): Promise<void> {
   }
 }
 
-/**
- * The account panel's markup on its own, taking already-resolved display
- * fields — kept separate from `AccountSection` for the same reason
- * `BenchSectionView` is: directly renderable in tests without a fetch stub.
- */
+// Kept separate from `AccountSection`, like `BenchSectionView`, so it's
+// directly renderable in tests without a fetch stub.
 export function AccountSectionView({
   id,
   name,
diff --git a/apps/web/src/settings/api-request.ts b/apps/web/src/settings/api-request.ts
index 9edf4d232..3c50d667c 100644
--- a/apps/web/src/settings/api-request.ts
+++ b/apps/web/src/settings/api-request.ts
@@ -1,13 +1,6 @@
-// Shared fetch+parse wrapper for every settings-ui API seam
-// (credentials-api.ts, access.ts, tenancy-api.ts): the same
-// envelope-first error message on every
-// non-2xx response, matching `apps/web/src/onboarding.ts`'s
-// `readErrorEnvelope` — the hub's own `{error:{userMessage, refId}}` body
-// wins when present, and the fallback names what was happening ("while
-// loading credentials") rather than the raw route, which nobody reading a
-// settings panel should ever have to see. Each seam keeps its own `Error`
-// subclass so a catch site can still tell which API failed; only the
-// request shape is shared here.
+// Fallback message names what was happening, never the raw route, which
+// nobody reading a settings panel should have to see. Each seam keeps its
+// own `Error` subclass so a catch site can tell which API failed.
 
 import { type } from "arktype";
 import type { ArkErrors } from "arktype";
@@ -16,11 +9,8 @@ const ErrorEnvelope = type({
   error: { code: "string", userMessage: "string", refId: "string" },
 });
 
-/**
- * Resolves a non-2xx response's message: the hub's own envelope
- * `userMessage` when the body carries one, otherwise a generic, path-free
- * sentence naming the status and what the caller was doing.
- */
+// The hub's own envelope `userMessage` wins when present, otherwise a
+// generic, path-free sentence.
 export function readErrorEnvelope(status: number, body: unknown, verb: string): string {
   const envelope = ErrorEnvelope(body);
   return envelope instanceof type.errors
diff --git a/apps/web/src/settings/api.ts b/apps/web/src/settings/api.ts
index 9ecc63e51..9eacc2952 100644
--- a/apps/web/src/settings/api.ts
+++ b/apps/web/src/settings/api.ts
@@ -1,10 +1,5 @@
-// The settings surface's one seam of its own to Interchange's native hub
-// routes: renaming a bench (`PATCH /api/tenants/:tenantId`, see
-// `vendor/intx/hub-api/src/routes/tenants.ts`) and reading the signed-in
-// account's profile (`GET /api/me`). Workbench settings and bench membership
-// listings are not reimplemented here — they come straight from
-// `@/chat` and `@/bench`, the packages that already own
-// those seams.
+// Workbench settings and bench membership listings aren't reimplemented
+// here — they come straight from `@/chat` and `@/bench`.
 
 import { type } from "arktype";
 import type { ArkErrors } from "arktype";
diff --git a/apps/web/src/settings/credentials-api.ts b/apps/web/src/settings/credentials-api.ts
index 7c05e05f6..b5f2c0a64 100644
--- a/apps/web/src/settings/credentials-api.ts
+++ b/apps/web/src/settings/credentials-api.ts
@@ -50,11 +50,8 @@ export function listProviders(tenantId: string): Promise<readonly Provider[]> {
   );
 }
 
-/** Mints a plain, non-inference provider row named after the credential
- * a person is about to store — the stock credentials route requires a
- * `providerId`, and a bare "add a key" form has no provider of its own
- * to point at yet. `plugin: "custom"` marks it as this form's own,
- * generic kind rather than an inference adapter. */
+// The stock credentials route requires a `providerId`, and a bare "add a
+// key" form has no provider of its own yet — this mints one.
 export function createProvider(tenantId: string, name: string): Promise<Provider> {
   return request(`/api/tenants/${tenantId}/providers`, ProviderResponse, "creating that provider", {
     method: "POST",
diff --git a/apps/web/src/settings/credentials-section.tsx b/apps/web/src/settings/credentials-section.tsx
index 96ce65a5c..8d78a616b 100644
--- a/apps/web/src/settings/credentials-section.tsx
+++ b/apps/web/src/settings/credentials-section.tsx
@@ -1,9 +1,5 @@
-// The "Credentials" settings section: a plain list-plus-create surface
-// over Interchange's own stock credential routes
-// (`vendor/intx/hub-api/src/routes/credentials.ts`) — the only way a key
-// gets stored in this repo. No connector registry, no OAuth connect
-// flow, no per-provider card: just the credentials this bench owns,
-// named and typed, with a form to add one and a button to delete it.
+// The stock credential routes are the only way a key gets stored in this
+// repo — no connector registry, no OAuth flow, no per-provider card.
 
 import {
   Button,
@@ -348,10 +344,8 @@ function readMetadataString(metadata: Credential["metadata"], key: string): stri
   return typeof value === "string" ? value : "";
 }
 
-/** Edits a credential through the stock `PATCH` route. `Base URL` and
- * `Model` are this form's own metadata convention for a local, Ollama-style
- * credential — they round-trip through the credential's opaque `metadata`
- * field, nothing platform-specific. */
+// `Base URL`/`Model` are this form's own convention, round-tripped
+// through the credential's opaque `metadata` field.
 function EditCredentialDialog({
   credential,
   onOpenChange,
diff --git a/apps/web/src/settings/grants-section.tsx b/apps/web/src/settings/grants-section.tsx
index 8804d8c1c..eca875564 100644
--- a/apps/web/src/settings/grants-section.tsx
+++ b/apps/web/src/settings/grants-section.tsx
@@ -1,8 +1,5 @@
-// The "Grants" settings section: what each role or person is allowed,
-// denied, or asked about, and on what — filterable, creatable, revocable
-// over the native `/api/tenants/:tenantId/grants` route. The resource
-// vocabulary has no listing endpoint of its own (see the tenancy
-// inventory's gap list); `resource-vocabulary.ts` carries it as a constant.
+// The resource vocabulary has no listing endpoint of its own;
+// `resource-vocabulary.ts` carries it as a constant instead.
 
 import {
   Badge,
diff --git a/apps/web/src/settings/identity.ts b/apps/web/src/settings/identity.ts
index 7c7f00268..a9ecbb419 100644
--- a/apps/web/src/settings/identity.ts
+++ b/apps/web/src/settings/identity.ts
@@ -1,16 +1,6 @@
-// Pure helpers for the People section's one identity gap: `PrincipalResponse`
-// gives agent principals no identity resolution, so `displayName` falls back
-// server-side to the raw `refId` (see `resolveIdentities` in
-// vendor/intx/hub-api/src/routes/principals.ts). The UI floor forbids ever
-// showing that raw value as the label a person reads — this derives a
-// humane stand-in from it and keeps the raw value available for a tooltip
-// only, never as visible text.
-//
-// `PRINCIPAL_KIND_LABEL` and `PRINCIPAL_KIND_ORDER` live here too, shared by
-// every picker that lists principals (Grants' target select and filter).
-// Grants assign to people, agents, *and* workflows. Roles' assignment picker
-// is scoped to user-kind principals only: agents/workflows are
-// machine identities that belong on separate surfaces.
+// An agent principal's `displayName` falls back server-side to a raw
+// `refId`; the UI floor forbids showing that raw value, so this derives a
+// humane stand-in and keeps the raw value for a tooltip only.
 
 import { SETTINGS_STRINGS } from "./strings";
 
@@ -29,12 +19,7 @@ function looksRaw(value: string): boolean {
   return RAW_LOOKING_PATTERN.test(value);
 }
 
-/**
- * Strips the plumbing off a raw agent address or id — scheme, host,
- * underscore-prefixed type tags — down to whatever's left of a human name,
- * title-cased. Falls back to a plain "Unnamed agent" when nothing
- * recognizable survives.
- */
+// Falls back to "Unnamed agent" when nothing recognizable survives.
 function derivePrincipalLabel(raw: string): string {
   const segment =
     raw
diff --git a/apps/web/src/settings/kind-cards.tsx b/apps/web/src/settings/kind-cards.tsx
index 7cf295cae..2764ebe7a 100644
--- a/apps/web/src/settings/kind-cards.tsx
+++ b/apps/web/src/settings/kind-cards.tsx
@@ -1,7 +1,5 @@
-// Selectable card grid used by guided dialogs (grant effect, credential
-// provider, workbench type, workbench kind). Mirrors the KindCardGrid shape
-// from `@corbits/react-ui` so the dialogs keep working when the pin lags
-// the component export — styling lives in styles.css.
+// Mirrors react-ui's KindCardGrid shape so dialogs keep working when the
+// pin lags the component export.
 
 import type { ReactNode } from "react";
 
diff --git a/apps/web/src/settings/models-section.tsx b/apps/web/src/settings/models-section.tsx
index c165b7872..c6ae19836 100644
--- a/apps/web/src/settings/models-section.tsx
+++ b/apps/web/src/settings/models-section.tsx
@@ -1,9 +1,4 @@
-// The "Models" settings section: a read-only view of this workbench's
-// credential providers (`GET /api/tenants/:t/providers`, the same stock
-// route `credentials-section.tsx` reads) and its resolved model catalog
-// (`GET /api/tenants/:t/models`, `createModelDiscoveryRoutes` — the same
-// read `resolveModelSources` would act on at launch). No write path here;
-// changing an offering's priority or restricting it belongs to the
+// No write path here; changing an offering's priority belongs to the
 // catalog-management routes this section deliberately doesn't touch.
 
 import {
diff --git a/apps/web/src/settings/notifications-section.tsx b/apps/web/src/settings/notifications-section.tsx
index 797bc0565..cf44f0f98 100644
--- a/apps/web/src/settings/notifications-section.tsx
+++ b/apps/web/src/settings/notifications-section.tsx
@@ -1,16 +1,6 @@
-// Personal notification prefs. Delivery still routes through the product
-// inbox / notify stack; these toggles are the operator-facing surface for
-// which classes of activity should surface. No per-user preference store
-// is mounted yet — draft state only, with an honesty note on save.
-//
-// REMOVED FROM THE SETTINGS REGISTRY (see section-registry.tsx):
-// toggles that save nothing are fake controls, not a settings section —
-// honest absence beats that. Re-add the "chat" section to
-// `SETTINGS_SECTION_GROUPS`'s "account" group only once a per-user
-// preference store exists for these fields and Save actually persists
-// them, not before. (Workbench-scoped mute/mentions prefs live on
-// `@/chat`'s workbench settings surface and already persist —
-// that is a different surface.)
+// Removed from the settings registry (see section-registry.tsx): toggles
+// that save nothing are fake controls. Re-add once a per-user preference
+// store exists and Save actually persists them.
 
 import { Button, SettingsPanel } from "@corbits/react-ui";
 import { Check } from "@/lib/icons";
diff --git a/apps/web/src/settings/people-section.tsx b/apps/web/src/settings/people-section.tsx
index 93882f286..28c77e75f 100644
--- a/apps/web/src/settings/people-section.tsx
+++ b/apps/web/src/settings/people-section.tsx
@@ -1,11 +1,5 @@
-// The "People" settings section: every human (`kind: "user"`) principal on
-// this bench, with suspend/reactivate/remove/role actions over the native
-// `/api/tenants/:tenantId/principals` and `/roles` routes. Agent and
-// workflow principals are machine identities, not people to manage here —
-// Roles/Grants sections list every kind since those assign to machines
-// too. Never renders a raw principal id or a raw agent refId — see
-// `identity.ts`. New humans join only when an operator creates them
-// through native APIs.
+// Agent/workflow principals are machine identities, not people to manage
+// here — Roles/Grants list every kind since those assign to machines too.
 
 import {
   Badge,
diff --git a/apps/web/src/settings/resource-vocabulary.ts b/apps/web/src/settings/resource-vocabulary.ts
index 8d411f7ed..5c2c5288a 100644
--- a/apps/web/src/settings/resource-vocabulary.ts
+++ b/apps/web/src/settings/resource-vocabulary.ts
@@ -1,9 +1,5 @@
-// The grant resource/action vocabulary: no hub route exposes this list (see
-// the tenancy inventory's gap list, item 8), so the Grants section carries
-// it here as a typed literal, sourced from
-// `vendor/intx/hub-api/src/routes/grants.ts`'s own resource set. If the hub
-// ever grows a capability-vocabulary endpoint, this constant is the one
-// place to delete in favor of it.
+// No hub route exposes this list, so it's carried here as a typed literal
+// until a capability-vocabulary endpoint exists to delete this in favor of.
 
 export const GRANT_RESOURCES = [
   "principal",
@@ -29,14 +25,8 @@ export const GRANT_RESOURCES = [
 ] as const;
 export type GrantResource = (typeof GRANT_RESOURCES)[number];
 
-/**
- * Plain-language labels for `GRANT_RESOURCES`, written to read in a
- * sentence ("Billing may read on {label}.") and in a table cell. Every
- * consumer of a raw resource slug — the create-grant preview sentence,
- * the grants table, the resource filter, the resource picker — reads
- * from this one map so the copy never drifts between them. The raw slug
- * still survives as a title/tooltip; it is never the visible text.
- */
+// Every consumer of a raw resource slug reads from this one map so the
+// copy never drifts between them.
 export const GRANT_RESOURCE_LABEL: Record<GrantResource, string> = {
   principal: "accounts on this workbench",
   role: "roles",
diff --git a/apps/web/src/settings/roles-section.tsx b/apps/web/src/settings/roles-section.tsx
index d9b24a453..eefc8019d 100644
--- a/apps/web/src/settings/roles-section.tsx
+++ b/apps/web/src/settings/roles-section.tsx
@@ -1,8 +1,3 @@
-// The "Roles" settings section: this bench's roles (system roles marked and
-// immutable), create/rename/delete for custom roles, and assigning or
-// unassigning a role to a principal — all over the native
-// `/api/tenants/:tenantId/roles` and `/principals/:id/roles/:id` routes.
-
 import {
   Badge,
   Button,
@@ -283,10 +278,8 @@ export function RoleAssignments({
   const [principalId, setPrincipalId] = useState("");
   const [roleId, setRoleId] = useState("");
 
-  // Scope both picker and assignments to user-kind principals only.
-  // Agents and workflows are machine identities — the "Person" picker and
-  // its assignment table should match the People section's member roster,
-  // not the full tenant-wide principal list.
+  // The "Person" picker should match People's member roster, not the
+  // full tenant-wide principal list.
   const people = principals.filter((p) => p.kind === "user");
 
   const assignments = people.flatMap((principal) =>
diff --git a/apps/web/src/settings/section-registry.tsx b/apps/web/src/settings/section-registry.tsx
index 55cbfac67..658e2bfa0 100644
--- a/apps/web/src/settings/section-registry.tsx
+++ b/apps/web/src/settings/section-registry.tsx
@@ -1,22 +1,4 @@
-// The Personal Settings / Shared Settings section registry: the
-// grouping, ordering, icons, and tenancy gates every Interchange
-// deployment gets when it mounts this package's settings surface. The
-// single-concept collapse folded Personal/Workspace into one account-scoped
-// group and one shared group — there is one workbench per account now, so
-// a "workspace-scoped" setting and an "account-scoped" one are the same
-// tenant's settings. Shared Settings is the multiplayer-sharing surface:
-// it leads with what everyone inherits (shared credentials, then
-// People), and tucks the access-control mechanics (Roles, Grants, Audit)
-// under a collapsed Advanced disclosure — nobody should have to parse
-// grants and roles just to find where a shared API key lives. Bench dies
-// outright — there is no longer a second thing to name, distinct from the
-// account, so its rename/purpose/icon form and member list have no home to
-// keep them separate in. Conversation-scoped settings (agent, capabilities,
-// history) live on the workbench's own settings surface
-// (`@/chat`'s `WorkbenchSettingsSurface`) — not here.
-// Consuming apps compose bench context and routing around
-// `resolveSettingsSectionGroups` — the domain model of "what settings
-// exist and who can see them" lives here, not in an app.
+// See docs/settings-sections.md for the grouping rationale.
 
 import { Cpu, Key, ListBullets, Shield, Star, User, Users } from "@/lib/icons";
 
@@ -47,12 +29,8 @@ const SETTINGS_SECTION_GROUPS: readonly SettingsSectionGroupDef[] = [
   {
     id: "account",
     label: SETTINGS_STRINGS.groupAccountLabel,
-    // No "Your agent" section here: it has no preference store to back it.
-    // Re-add only once a hub preference store exists and save actually persists.
-    // No Notifications ("chat") section either: toggles with no per-user
-    // preference store are fake controls — see notifications-section.tsx
-    // for the re-add condition. Account (General) is the sole
-    // Account-group section until those stores exist.
+    // No "Your agent"/Notifications sections: no preference store backs
+    // them yet — see notifications-section.tsx for the re-add condition.
     sections: [
       {
         id: "account",
@@ -69,10 +47,8 @@ const SETTINGS_SECTION_GROUPS: readonly SettingsSectionGroupDef[] = [
     label: SETTINGS_STRINGS.groupEveryoneLabel,
     sections: [
       {
-        // Leads Shared Settings: a key added here is the thing everyone
-        // creating workbenches in this tenancy inherits. A plain list
-        // and create form over the stock credentials route — nothing
-        // provider-specific lives here.
+        // Leads Shared Settings: a key added here is what everyone
+        // creating workbenches in this tenancy inherits.
         id: "credentials",
         title: SETTINGS_STRINGS.credentialsSectionTitle,
         icon: Key,
@@ -103,10 +79,8 @@ const SETTINGS_SECTION_GROUPS: readonly SettingsSectionGroupDef[] = [
         render: (ctx) => <GrantsSection tenantId={ctx.tenantId} />,
       },
       {
-        // Read-only: this workbench's providers and resolved model
-        // catalog, over the same stock routes credentials/inference
-        // already read. No gate — model:*/provider:* read is the same
-        // grant every member needs to chat at all.
+        // No gate — model:*/provider:* read is the same grant every
+        // member needs to chat at all.
         id: "models",
         title: SETTINGS_STRINGS.modelsSectionTitle,
         icon: Cpu,
@@ -123,16 +97,9 @@ const SETTINGS_SECTION_GROUPS: readonly SettingsSectionGroupDef[] = [
   },
 ];
 
-/**
- * The Personal Settings / Shared Settings groups, with a section dropped entirely — never
- * rendered disabled — until its `access[gate]` probe resolves `allowed`.
- * Loading and authenticated deny both withhold the section. A probe `error`
- * withholds too (so gated sections never flash then hide) but marks the
- * group `accessProbeFailed` so a host can show a couldn't-check state
- * instead of looking like unauthorized. Both the settings stage and a
- * host's own section nav (e.g. col2) should read from this single registry
- * so they can never drift.
- */
+// A section is dropped entirely, never rendered disabled, until its gate
+// probe resolves `allowed`. A probe `error` withholds too but marks the
+// group `accessProbeFailed` so a host can show a couldn't-check state.
 export function resolveSettingsSectionGroups(
   access: TenancyAccess,
 ): readonly SettingsSectionGroup[] {
@@ -151,15 +118,8 @@ export function resolveSettingsSectionGroups(
   });
 }
 
-/**
- * Splices host-supplied sections into the Everyone group, at its front —
- * for domain sections that live outside this package (e.g. a host app's
- * Agents/Skills directories) but still belong in the same account-wide
- * nav. A host calling this must pass the same `extra` list to every
- * consumer (settings stage and its own section nav / col2), the same
- * discipline `resolveSettingsSectionGroups` itself documents, or the two
- * surfaces drift.
- */
+// A host calling this must pass the same `extra` list to every consumer
+// (settings stage and its own section nav), or the two surfaces drift.
 export function insertEveryoneSections(
   groups: readonly SettingsSectionGroup[],
   extra: readonly SettingsSection[],
diff --git a/apps/web/src/settings/shell.tsx b/apps/web/src/settings/shell.tsx
index f68bd4b43..efb75527f 100644
--- a/apps/web/src/settings/shell.tsx
+++ b/apps/web/src/settings/shell.tsx
@@ -1,8 +1,5 @@
-// The settings surface's shell: renders the active section's panel only.
-// Section nav is a master-detail list — it lives in the host's own col2
-// (see `resolveSettingsSectionGroups`), never repeated in the stage.
-// Everything about what a section shows and how it saves lives in the
-// section's own `render`, never here.
+// Renders the active section's panel only — nav is master-detail, never
+// repeated in the stage.
 
 import { EmptyState } from "@corbits/react-ui";
 import type { Icon } from "@/lib/icons";
@@ -10,10 +7,7 @@ import type { ReactElement } from "react";
 
 import { SETTINGS_STRINGS } from "./strings";
 
-/** Whatever shared context a section needs to do its own fetching: the
- * bench currently selected in the app's chrome, and the signed-in account's
- * principal on that bench (for permission probes). A section with no use
- * for either (Account, today) simply ignores the field. */
+// A section with no use for a field (Account, today) simply ignores it.
 export type SettingsContext = {
   readonly tenantId: string | null;
   readonly principalId: string | null;
@@ -25,10 +19,8 @@ export type SettingsContext = {
    * `/settings/agents/:definitionId`), so a section with its own
    * master-detail can restore the right selection on a deep link. */
   readonly entityId?: string | null;
-  /** Ends the signed-in session — the same callback the shell's account
-   * menu calls. Absent where the host has no sign-out concept of its own
-   * (a package test rendering a section standalone); a section that
-   * offers a Sign out action simply hides it when this is undefined. */
+  // Absent where the host has no sign-out concept; a section with a
+  // Sign out action simply hides it when undefined.
   readonly onSignOut?: () => void;
 };
 
@@ -38,10 +30,7 @@ export type SettingsSection = {
   /** Leading icon for a host's own section nav (col2). */
   readonly icon: Icon;
   readonly render: (ctx: SettingsContext) => ReactElement;
-  /** Tucks this section under a collapsed "Advanced" disclosure at the
-   * bottom of its group's nav, instead of listing it as a peer section —
-   * for sections whose mechanics (roles, grants, audit) nobody should have
-   * to parse just to find the thing they actually came for. */
+  // Tucked under a collapsed "Advanced" disclosure, not a peer section.
   readonly advanced?: boolean;
 };
 
@@ -62,12 +51,8 @@ export function flattenSettingsSections(
   return groups.flatMap((group) => group.sections);
 }
 
-/**
- * The section a shell should treat as active: the requested id if it names
- * a real section, otherwise the first section — never a crash, and never a
- * blank nav. `sections` is validated non-empty by the caller; an empty
- * registry is a distinct, deliberate empty state.
- */
+// Falls back to the first section rather than crashing or showing a blank
+// nav; an empty registry is a distinct, deliberate empty state.
 export function resolveActiveSection(
   sections: readonly SettingsSection[],
   requestedId: string | null,
diff --git a/apps/web/src/settings/tenancy-api.ts b/apps/web/src/settings/tenancy-api.ts
index 50d9d63d4..84586dc3b 100644
--- a/apps/web/src/settings/tenancy-api.ts
+++ b/apps/web/src/settings/tenancy-api.ts
@@ -1,9 +1,3 @@
-// The People/Roles/Grants sections' one seam to Interchange's native
-// tenancy routes (see vendor/intx/hub-api/src/routes/{principals,roles,
-// grants}.ts). Every fetch goes through a function here, and every response
-// is parsed with an arktype schema from `@intx/types` at the boundary — the
-// same convention `@/bench`'s api.ts already holds.
-
 import { type } from "arktype";
 import type { ArkErrors } from "arktype";
 import {
@@ -93,10 +87,8 @@ export function removePrincipal(tenantId: string, principalId: string): Promise<
 
 export type InviteMemberInput = typeof InviteMember.infer;
 
-/** Invites an existing platform user to this tenant by email over the
- * stock `/members/invite` route — creates an `invited`-status principal
- * and optionally assigns a role. The invited user must already have an
- * account; there is no separate invite-by-email-only flow. */
+// The invited user must already have an account — no invite-by-email-only
+// flow exists.
 export function inviteMember(tenantId: string, input: InviteMemberInput): Promise<Principal> {
   return request(`/api/tenants/${tenantId}/members/invite`, PrincipalResponse, {
     method: "POST",
@@ -204,12 +196,8 @@ export function revokeGrant(tenantId: string, grantId: string): Promise<void> {
   });
 }
 
-/**
- * Probes whether the signed-in principal can act on a resource — the one
- * grant-checked route that itself requires no grant (see the tenancy
- * inventory), so it doubles as the permission check that decides whether
- * People/Roles/Grants show up in the settings nav at all.
- */
+// The one grant-checked route that itself requires no grant, so it
+// doubles as the check deciding whether People/Roles/Grants show up.
 export function evaluate(
   tenantId: string,
   principalId: string,
diff --git a/apps/web/src/shell/app-shell.tsx b/apps/web/src/shell/app-shell.tsx
index 0ee4d5251..5f0aabe44 100644
--- a/apps/web/src/shell/app-shell.tsx
+++ b/apps/web/src/shell/app-shell.tsx
@@ -1,15 +1,5 @@
-// The app frame: one sidebar (the workbench list and shared chrome — see
-// `sidebar.tsx`), the main pane a route renders into, and the optional
-// canvas. Every route in `../routes.tsx` mounts inside this same frame —
-// there is no per-route shell variant and no sidebar collapse. The
-// conversation lives in the main stage; the canvas is auxiliary (profiles
-// and similar) and opens on use, then closes internally.
-//
-// Canvas state is NOT owned here — it has to be visible to the command
-// palette too (a sibling of this component, not a descendant — see
-// `shell-chrome-provider.tsx`), so `ShellChromeProvider` owns it above both
-// and this component only reads it through the same hooks page code
-// already uses.
+// Canvas state is NOT owned here — see `shell-chrome-provider.tsx` for why
+// it has to be visible to the command palette too.
 
 import { lazy, Suspense, useRef, useState, type ReactNode, type RefObject } from "react";
 import type { ArtifactSaveState } from "@/library";
@@ -92,10 +82,8 @@ export function AppShell({
   const canvasFocus = useCanvasColumnFocus();
   const { selectedTenantId: tenantId } = useBench();
 
-  // A text-kind artifact's save state (single-user editing, no co-edit
-  // presence), carried with the id it belongs to: state for any other id is
-  // ignored during render, so a stale "Saved · v3" can never leak into a
-  // newly opened artifact and nothing has to be reset when one changes.
+  // Carried with the id it belongs to, so a stale "Saved · v3" can never
+  // leak into a newly opened artifact.
   const [savedFor, setSavedFor] = useState<{
     readonly id: string;
     readonly state: ArtifactSaveState;
diff --git a/apps/web/src/shell/bench-activity.ts b/apps/web/src/shell/bench-activity.ts
index 3e1fab446..8956fe02b 100644
--- a/apps/web/src/shell/bench-activity.ts
+++ b/apps/web/src/shell/bench-activity.ts
@@ -1,7 +1,3 @@
-// Everything happening in the selected bench right now, over stock
-// listings only: workbenches are the bench's child tenants, chats are the
-// person's mail threads, agents are the bench's workflow definitions, and
-// running routines come through the seam in `./routine-activity.ts`.
 // Notifications have no backing feature in the hub, so nothing is fetched
 // for them — the column renders an honest empty state instead.
 
diff --git a/apps/web/src/shell/brand-mark.tsx b/apps/web/src/shell/brand-mark.tsx
index 4b5dfe623..61024cda1 100644
--- a/apps/web/src/shell/brand-mark.tsx
+++ b/apps/web/src/shell/brand-mark.tsx
@@ -1,7 +1,5 @@
-// A static inline SVG via react-ui's `CorbitsMark`, coloured with the
-// primary orange — simple and crisp over clever: an animated dither
-// background renders as a tiny pixelated square at this size, since its
-// dither grid needs real screen real estate to read.
+// Static, not the animated dither background: its grid needs real screen
+// real estate this size doesn't have.
 
 import { CorbitsMark } from "@corbits/react-ui";
 
diff --git a/apps/web/src/shell/canvas-availability.tsx b/apps/web/src/shell/canvas-availability.tsx
index 6d6cfa8bd..17c2fc39c 100644
--- a/apps/web/src/shell/canvas-availability.tsx
+++ b/apps/web/src/shell/canvas-availability.tsx
@@ -1,8 +1,5 @@
-// Canvas host surface for stage content: whether the shell has space for the
-// fourth column, how main-stage chat opens auxiliary canvas content
-// (profiles, artifacts) without owning the canvas column itself, and — for
-// AppShell's own render, which no longer owns this state — what the canvas
-// column is actually showing right now.
+// Lets main-stage chat open auxiliary canvas content without owning the
+// canvas column itself.
 
 import { useContext, type ReactNode } from "react";
 import type { ProfileSubject } from "@/chat";
@@ -109,10 +106,8 @@ export function useOpenArtifactInCanvas(): (artifact: CanvasArtifactContent) =>
   return useContext(CanvasHostContext).openArtifact;
 }
 
-/** Opens (or replaces) the canvas's routine pane — the workbench header's
- * "New routine" action, the `/workflows` page's own create button, and an
- * existing routine's own "Edit" hop all call this. `routineId: null` starts
- * a brand-new routine; a real id opens that routine for editing. */
+// `routineId: null` starts a brand-new routine; a real id opens it for
+// editing.
 export function useOpenRoutineInCanvas(): (subject: RoutinePanelSubject) => void {
   return useContext(CanvasHostContext).openRoutine;
 }
diff --git a/apps/web/src/shell/canvas-column.tsx b/apps/web/src/shell/canvas-column.tsx
index 4e5ed4322..0e694e8c6 100644
--- a/apps/web/src/shell/canvas-column.tsx
+++ b/apps/web/src/shell/canvas-column.tsx
@@ -1,23 +1,8 @@
-// Column 4: the optional canvas. Collapsed, it takes no space at all — the
-// main pane gets the width back — and open, it hosts targeted auxiliary
-// content: profile cards, and typed artifact renderers opened
-// from a chat artifact chip or the Library page. Primary workbench
-// conversation lives in the main stage, not here.
-//
-// co-edit presence is gone. A "doc"-kind, editable artifact
-// renders `@/library`'s `ArtifactTextEditor` as a plain
-// single-user controlled textarea, debounced-saved through the artifacts
-// HTTP route; every other kind stays the read-only `ArtifactRenderer`. No
-// co-viewer cursors, no shared doc — that capability returns, if it does,
-// on top of the preserved `@corbits/presence` library, not here.
-//
-// The collapse/expand motion lives entirely in `shell.css` as a CSS
-// transition on `transform`/`opacity` (plus width, so the main pane
-// actually reflows) triggered by the `data-open` attribute — never a JS
-// animation — so rapid toggling is inherently interruptible: the browser
-// just reverses whichever transition is already in flight, there is no
-// queue to get stuck. `prefers-reduced-motion` is handled the same way, in
-// CSS, by shortening the transition to near-zero.
+// Collapse/expand is a CSS transition on `data-open`, never JS animation,
+// so rapid toggling is inherently interruptible — no queue to get stuck.
+
+// No co-edit presence: a "doc"-kind artifact is a plain single-user
+// textarea. That capability, if it returns, lives on `@corbits/presence`.
 
 import {
   Button,
@@ -64,11 +49,8 @@ export function CanvasColumn({
    * one seam to the artifacts PUT route. Absent for a non-editable artifact. */
   readonly onSaveArtifact?: (content: string) => void;
 }) {
-  // `inert` rather than `aria-hidden`: a collapsed column has to be out of
-  // both the accessibility tree and the tab order, and `aria-hidden` alone
-  // only does the first — a focusable descendant inside an `aria-hidden`
-  // subtree is an ARIA violation, and the browser moves focus out of an
-  // `inert` subtree for us when it closes.
+  // `inert`, not `aria-hidden` alone: `aria-hidden` doesn't remove a
+  // focusable descendant from the tab order.
   return (
     <div className="shell-canvas-column" data-open={open} data-focus={focus} inert={!open}>
       <div className="shell-canvas-inner">
@@ -135,14 +117,8 @@ function mentionAction(
   };
 }
 
-/** Shared header row for every canvas pane: an optional leading back
- * control, an optional title, an optional pane-specific `trailing` slot,
- * and — for the panes that use them — the mock's focus-cycle control and
- * its explicit close. `onBack` and the focus/close controls are mutually
- * exclusive in practice (a pane is either master-detail-driven, like the
- * routine pane, or focus/close-driven, like profile and artifact), but
- * both are optional so this one component covers every canvas pane's
- * header rather than each pane hand-rolling its own. */
+// `onBack` and the focus/close controls are mutually exclusive in
+// practice, but both stay optional so one component covers every pane.
 export function CanvasPaneHeader({
   title,
   onBack,
@@ -244,12 +220,8 @@ function profileActions(
   // pause endpoint exists anywhere in the hub) — omitted rather than left
   // as a no-op that pretends to do something.
   if (profile.kind === "agent") {
-    // No "Edit agent" hop here: `ProfileSubject` (chat-ui's
-    // `profile-subject.ts`) carries only address/handle/displayName, never
-    // a workbench id, so this card has no way to resolve the agent's own
-    // workbench settings. The global `/settings/agents` tab this used to
-    // target is gone — rather than hop to a dead route, the action is
-    // dropped until a subject carries enough context to land somewhere real.
+    // No "Edit agent" hop: `ProfileSubject` carries no workbench id, and
+    // the global `/settings/agents` tab this used to target is gone.
     return [
       message,
       mention,
@@ -265,11 +237,8 @@ function profileActions(
     ];
   }
 
-  // No "Grants" hop here: settings-ui's Grants section has no deep-link
-  // filter to land on this person's rules specifically, and a profile
-  // card action that lands on the unfiltered, everyone's-rules list is
-  // worse than not offering it — same reasoning the agent branch above
-  // uses to drop "Edit agent".
+  // No "Grants" hop: no deep-link filter exists, and landing on the
+  // unfiltered everyone's-rules list is worse than not offering it.
   return [
     message,
     mention,
@@ -324,11 +293,9 @@ function ProfileCanvasPane({
   );
 }
 
-/** Whether this render shows `ArtifactTextEditor` instead of the static
- * `ArtifactRenderer`: the artifact has to be a text kind. Whether the
- * resulting pane is interactive is `artifact.canEdit`, checked separately:
- * a viewer without write access still gets `ArtifactTextEditor` in its
- * own `readOnly` mode, just with keystrokes ignored. */
+/** Whether the pane is interactive is `artifact.canEdit`, checked
+ * separately — a read-only viewer still gets the editor, just in
+ * `readOnly` mode. */
 function showsTextEditor(artifact: CanvasArtifactContent): boolean {
   return artifact.rendererKind === "doc";
 }
diff --git a/apps/web/src/shell/canvas-host-context.ts b/apps/web/src/shell/canvas-host-context.ts
index 2985d1bee..0d6b51483 100644
--- a/apps/web/src/shell/canvas-host-context.ts
+++ b/apps/web/src/shell/canvas-host-context.ts
@@ -8,18 +8,8 @@ import type { ProfileSubject } from "@/chat";
 import type { ArtifactRendererKind } from "@/library";
 import type { CanvasColumnState } from "@/shell/layout";
 
-/** The canvas's typed-artifact pane: a title, the already-resolved
- * renderer selection (see `@/library`'s `resolveArtifactRendererKind`
- * / `resolveRendererKindFromMediaType`), and the content string those
- * renderers read.
- *
- * `canEdit` (phase 2) opts a text-kind ("doc") artifact into
- * `ArtifactTextEditor` instead of the read-only `ArtifactRenderer` —
- * defaults to `false`/absent so every existing caller keeps rendering
- * read-only with zero behavior change. The presence `/update` route's own
- * `asset:*`/"write" grant check is the real security boundary regardless
- * of this flag; `canEdit` only decides which component a capable viewer
- * sees, never whether a write actually lands. */
+// `canEdit` only picks the component; the `/update` route's own grant
+// check is the real security boundary regardless of this flag.
 export type CanvasArtifactContent = {
   readonly id: string;
   readonly title: string;
@@ -27,56 +17,29 @@ export type CanvasArtifactContent = {
   readonly content: string;
   readonly unavailableReason?: string;
   readonly canEdit?: boolean;
-  /** The sandboxed preview route for an `"html"`-kind artifact —
-   * see `ArtifactRenderProps.previewSrc`. Absent for every other renderer
-   * kind, and for an HTML blob with no Library artifact id to preview. */
+  // Absent for every renderer but html, and for a blob with no artifact id.
   readonly previewSrc?: string;
 };
 
-/** The canvas's routine pane subject: which routine to show, or `null` to
- * start a brand-new one. Distinct from `CanvasArtifactContent` — the panel
- * fetches and owns its own routine data (name, instruction, trigger, run
- * history) from `routineId`, the same way `ProfileCanvasPane` fetches
- * shared workbenches from a `ProfileSubject`'s address rather than being
- * handed pre-resolved content. */
+// Distinct from `CanvasArtifactContent`: the panel fetches and owns its
+// own routine data from `routineId` rather than being handed content.
 export type RoutinePanelSubject = {
-  /** Always opens the editor: a specific routine (`routineId` set) or a
-   * brand-new one (`routineId` omitted or `null`) — routines-page's own
-   * "New routine"/"Edit" actions, "Make this a routine", the composer's
-   * `/routine` command, and "New routine in this space" (:
-   * browsing/running existing routines moved to the global `/workflows`
-   * page, so this pane no longer has a list mode). */
   readonly routineId?: string | null;
-  /** Seeds the Name/Instruction fields the instant a brand-new panel opens
-   * (`routineId: null` only) — "Make this a routine" (a completed task
-   * result) and similar callers with something worth pre-filling. The
-   * panel still autosaves on the person's own edits; this only seeds the
-   * initial draft. */
+  // Seeds the Name/Instruction fields on a brand-new panel only; the panel
+  // still autosaves on the person's own edits after that.
   readonly initialName?: string;
   readonly initialInstruction?: string;
-  /** The conversation this routine belongs to — its own agent (the
-   * workbench's host participant; every workbench's host is Myra) backs the
-   * routine, and its own id is where the routine delivers. Carried through
-   * list mode too, so "New routine" picked from the list still binds to
-   * the workbench the panel was opened beside. Omitted only when there is no
-   * open conversation to bind to (e.g. a deliberate `/workflows` visit),
-   * in which case the panel falls back to this workbench's own default
-   * (Myra) workbench — never mints a new one. */
+  // Omitted only with no open conversation to bind to, in which case the
+  // panel falls back to this workbench's own default (Myra) — never mints
+  // a new one.
   readonly workbenchId?: string;
-  /** Seeds the target picker's initial selection — the
-   * conversation's own single agent participant's definition asset id,
-   * when the opener could resolve exactly one. Shown visibly in
-   * `DefinitionTargetPicker` and freely replaceable/clearable by the
-   * person; only their final explicit pick is ever sent to the backend.
-   * Omitted whenever the opener found zero or several candidates, or has
-   * no conversation to derive one from at all. */
+  // The opener's single resolved agent participant, when there was
+  // exactly one; freely replaceable, only the person's final pick is sent.
   readonly preselectedAssetId?: string;
 };
 
-/** Workbench's concrete instantiation of `@/shell/layout`'s generic
- * canvas state — a `ProfileSubject` for the profile pane, this app's own
- * `CanvasArtifactContent` for the artifact pane, `RoutinePanelSubject` for
- * the routine pane. */
+// A `ProfileSubject` for the profile pane, `CanvasArtifactContent` for the
+// artifact pane, `RoutinePanelSubject` for the routine pane.
 export type AppCanvasColumnState = CanvasColumnState<
   ProfileSubject,
   CanvasArtifactContent,
diff --git a/apps/web/src/shell/chip.tsx b/apps/web/src/shell/chip.tsx
index c6dc3b240..06e3ea4aa 100644
--- a/apps/web/src/shell/chip.tsx
+++ b/apps/web/src/shell/chip.tsx
@@ -1,14 +1,5 @@
-// Mock's `.chip[data-tone]` (workbench-flow-mock.html:262-273): a quiet
-// status pill with three tones. Ambient machine activity ("working") and a
-// resolved state ("ok") stay outlined; only a human-blocking ask
-// ("needs-you") gets a filled, high-weight treatment — the one chip a
-// person should never miss.
-//
-// No chip primitive exists yet in @corbits/react-ui (checked: `Badge` is
-// the closest sibling, but it's an uppercase rounded-sm label for
-// categorical tags, not this outlined/filled status-pill idiom with a
-// radius-0 floor) — built locally. Worth extracting upstream once a
-// second consumer needs it.
+// Only "needs-you" is filled/high-weight — the one chip a person should
+// never miss. Built locally: no chip primitive in @corbits/react-ui yet.
 import type { ReactNode } from "react";
 
 export type ChipTone = "working" | "ok" | "needs-you";
diff --git a/apps/web/src/shell/composer-insertion.tsx b/apps/web/src/shell/composer-insertion.tsx
index 202a422ee..e3ffea5a7 100644
--- a/apps/web/src/shell/composer-insertion.tsx
+++ b/apps/web/src/shell/composer-insertion.tsx
@@ -1,10 +1,5 @@
-// A shell-level seam between two independent surfaces: the canvas column's
-// ProfileCard (this app) and the active workbench's composer (mounted deep
-// inside `@/chat`'s `ChatWorkspace`, a sibling tree). The profile
-// card's Mention action needs to land `@handle` in whatever
-// composer is on screen without either side importing the other — the same
-// "shell context exposing a callback hook" shape `canvas-availability.tsx`
-// already uses for opening a profile.
+// Lets the profile card's Mention action reach the composer without
+// either side importing the other — same shape as `canvas-availability.tsx`.
 
 import { useContext, useMemo, useRef } from "react";
 import type { ReactNode } from "react";
diff --git a/apps/web/src/shell/context-menu/items.tsx b/apps/web/src/shell/context-menu/items.tsx
index 706cafea3..d45816c20 100644
--- a/apps/web/src/shell/context-menu/items.tsx
+++ b/apps/web/src/shell/context-menu/items.tsx
@@ -1,7 +1,5 @@
-// One item builder per target type. Every item here calls a real backend or
-// a real, already-shipped shell affordance — nothing toast-only. A target
-// whose mock counterpart had no working backend (mark-read, mute, archive,
-// share) simply has no builder and so contributes no items.
+// Nothing toast-only: a target with no working backend simply has no
+// builder and contributes no items.
 
 import { profileSubjectFromParticipant } from "@/chat";
 import type { ProfileSubject } from "@/chat";
@@ -173,12 +171,8 @@ function insightsRunMenu(
   };
 }
 
-/**
- * Same operation set the Files bulk action bar offers: copy
- * every acted-on file's canonical link. `target.ids` is either the single
- * right-clicked row, or the whole active selection when the row is part of
- * one — see `SHELL_CONTEXT_MENU_TARGETS`.
- */
+// `target.ids` is either the single right-clicked row, or the whole active
+// selection when the row is part of one.
 function artifactMenu(target: Extract<ShellContextMenuTarget, { type: "artifact" }>): ContextMenu {
   const count = target.ids.length;
   return {
diff --git a/apps/web/src/shell/context-menu/lib/context-menu-view.tsx b/apps/web/src/shell/context-menu/lib/context-menu-view.tsx
index 155b3f6e1..f7e35b8f2 100644
--- a/apps/web/src/shell/context-menu/lib/context-menu-view.tsx
+++ b/apps/web/src/shell/context-menu/lib/context-menu-view.tsx
@@ -10,19 +10,9 @@ import {
 import { restoreFocus } from "./focus-restore";
 import type { ContextMenu } from "./menu";
 
-/**
- * Renders a `ContextMenu` at a fixed screen point using react-ui's
- * `Menu` (Radix `DropdownMenu`) rather than a hand-rolled popover: Radix
- * already owns anchored positioning that stays on screen, focus management,
- * arrow-key navigation, and closing on Escape or an outside click, and it
- * shares its dismissable-layer stack with react-ui's `Dialog` — the same
- * stack the command palette's dialog uses — so a context menu never
- * out-races a dialog on Escape. The only custom part is anchoring the
- * (Radix-required) trigger to the click point instead of a visible button:
- * that anchor is an inert, unfocusable point, so Radix's default
- * close-focus-the-trigger behavior is overridden to focus `restoreFocusTo`
- * (the row that was right-clicked) instead.
- */
+// Uses react-ui's Radix-backed `Menu`, not a hand-rolled popover: it
+// shares a dismissable-layer stack with the command palette's dialog, so
+// a context menu never out-races it on Escape.
 export function ContextMenuView({
   x,
   y,
diff --git a/apps/web/src/shell/context-menu/lib/dialog-guard.ts b/apps/web/src/shell/context-menu/lib/dialog-guard.ts
index 047cef436..1e310b786 100644
--- a/apps/web/src/shell/context-menu/lib/dialog-guard.ts
+++ b/apps/web/src/shell/context-menu/lib/dialog-guard.ts
@@ -1,14 +1,6 @@
-// A right-click that lands on (or behind) an open modal must not also pop
-// a context menu — that's the "dialog beats context menu" half of the Esc
-// precedence chain, enforced at open time rather than by racing keydown
-// handlers. Every dialog in this codebase (react-ui's Dialog, and the
-// command palette it's built from) renders Radix's `role="dialog"` while
-// open and unmounts it on close, so presence in the DOM is exactly "is a
-// modal open" — a stable ARIA contract, not an internal implementation
-// detail. The `Escape`-closes-topmost-layer behavior itself needs no code
-// here: Dialog and the context menu's own Menu are both Radix primitives
-// sharing Radix's dismissable-layer stack, which already closes only the
-// topmost one.
+// Enforced at open time, not by racing keydown handlers: every dialog
+// renders Radix's `role="dialog"` while open, so DOM presence is exactly
+// "is a modal open."
 export function isBlockingOverlayOpen(doc?: Pick<Document, "querySelector">): boolean {
   const target = doc ?? globalThis.document;
   return target.querySelector('[role="dialog"]') !== null;
diff --git a/apps/web/src/shell/context-menu/lib/focus-restore.ts b/apps/web/src/shell/context-menu/lib/focus-restore.ts
index 7941dd92f..b9d4d561d 100644
--- a/apps/web/src/shell/context-menu/lib/focus-restore.ts
+++ b/apps/web/src/shell/context-menu/lib/focus-restore.ts
@@ -1,8 +1,5 @@
-// Radix's DropdownMenu restores focus to its trigger on close. Our trigger
-// is an inert, unfocusable 1px anchor at the click point — restoring focus
-// to it is a no-op that drops focus to `<body>`. This module finds the real
-// element worth focusing instead: the right-clicked row itself, or its
-// nearest focusable ancestor.
+// Our trigger is an inert 1px anchor, so Radix's default focus-restore
+// drops to `<body>`. This finds the real element worth focusing instead.
 
 const FOCUSABLE_SELECTOR = "a[href], button, input, select, textarea, [tabindex]";
 
diff --git a/apps/web/src/shell/context-menu/lib/index.ts b/apps/web/src/shell/context-menu/lib/index.ts
index 1299b62c2..7a8d5b153 100644
--- a/apps/web/src/shell/context-menu/lib/index.ts
+++ b/apps/web/src/shell/context-menu/lib/index.ts
@@ -1,12 +1,5 @@
-// `@/shell/context-menu/lib`: the deployment-agnostic half of the global
-// right-click context-menu system. Resolving a DOM event to a typed target
-// (`target-resolver`), deciding whether a modal overlay should suppress it
-// (`dialog-guard`), the open/position state machine
-// (`use-context-menu-state`), the single document listener that drives it
-// (`use-document-context-menu-trigger`), returning focus to the right-clicked
-// row on close (`focus-restore`), and the react-ui-backed presentation
-// (`context-menu-view`) all apply to any Interchange app with typed rows to
-// right-click on. What counts as a target and which items it offers is
+// The deployment-agnostic half of the global right-click context-menu
+// system. What counts as a target and which items it offers is
 // product-specific and stays with the consumer.
 
 export { resolveTarget } from "./target-resolver";
diff --git a/apps/web/src/shell/context-menu/lib/target-resolver.ts b/apps/web/src/shell/context-menu/lib/target-resolver.ts
index ad831a2bc..267475339 100644
--- a/apps/web/src/shell/context-menu/lib/target-resolver.ts
+++ b/apps/web/src/shell/context-menu/lib/target-resolver.ts
@@ -1,12 +1,5 @@
-// Turns the element a pointer event landed on into a typed target, the same
-// way a router turns a path into a typed route: an ordered list of
-// selector-scoped resolvers, each tried in turn against `origin.closest()`
-// so a click anywhere inside a row still resolves to that row. The first
-// *definition* to find any ancestor match wins — not the definition whose
-// match is nearest — so a target nested inside another (e.g. a profile face
-// inside a channel row) must be listed before its container, or the
-// container's definition will win even though it matches farther away.
-// Callers own what `T` is — this module only owns the walk.
+// The first definition to find any ancestor match wins, not the nearest
+// match — so a nested target must be listed before its container.
 
 export type TargetDefinition<T> = {
   /** A CSS selector `Element.closest()` can match against. */
diff --git a/apps/web/src/shell/context-menu/lib/use-context-menu-state.ts b/apps/web/src/shell/context-menu/lib/use-context-menu-state.ts
index ffaa54e29..c93ae53ef 100644
--- a/apps/web/src/shell/context-menu/lib/use-context-menu-state.ts
+++ b/apps/web/src/shell/context-menu/lib/use-context-menu-state.ts
@@ -14,10 +14,7 @@ export type ContextMenuState = {
   readonly hide: () => void;
 };
 
-/** Open/position state for a single context menu instance. Pure state — no
- * DOM listeners here, so it composes with any trigger source (the document
- * delegate in `use-document-context-menu-trigger`, or a row's own
- * `onContextMenu`). */
+// Pure state, no DOM listeners, so it composes with any trigger source.
 export function useContextMenuState(): ContextMenuState {
   const [open, setOpen] = useState(false);
   const [position, setPosition] = useState({ x: 0, y: 0 });
diff --git a/apps/web/src/shell/context-menu/lib/use-document-context-menu-trigger.ts b/apps/web/src/shell/context-menu/lib/use-document-context-menu-trigger.ts
index 4805c4f6f..519d542d1 100644
--- a/apps/web/src/shell/context-menu/lib/use-document-context-menu-trigger.ts
+++ b/apps/web/src/shell/context-menu/lib/use-document-context-menu-trigger.ts
@@ -13,18 +13,9 @@ export type ContextMenuTriggerOptions = {
   readonly onOpen: (x: number, y: number, menu: ContextMenu, origin: Element | null) => void;
 };
 
-/**
- * Wires the single document-level `contextmenu` listener the whole app
- * shares. A native right-click still wins over ours for text inputs, and an
- * open dialog (including the command palette) always wins over opening a
- * context menu underneath it — see `dialog-guard`. `resolve` returning an
- * empty menu is the same as opting out: the native menu shows instead of an
- * empty popover.
- *
- * Deliberately right-click only. This app's `Link` already gives Ctrl/Cmd
- * click its native meaning (open in a new tab), so layering a second,
- * conflicting meaning onto it here would cost more than it gives back.
- */
+// An empty `resolve` result is the same as opting out: the native menu
+// shows instead of an empty popover. Right-click only, deliberately —
+// this app's `Link` already gives Ctrl/Cmd-click its native meaning.
 export function useDocumentContextMenuTrigger(options: ContextMenuTriggerOptions): void {
   const { resolve, onOpen } = options;
   useEffect(() => {
diff --git a/apps/web/src/shell/context-menu/targets.ts b/apps/web/src/shell/context-menu/targets.ts
index eb8bbd49a..ba0b6c078 100644
--- a/apps/web/src/shell/context-menu/targets.ts
+++ b/apps/web/src/shell/context-menu/targets.ts
@@ -23,12 +23,8 @@ export type ShellContextMenuTarget =
   | {
       readonly type: "artifact";
       readonly id: string;
-      /**
-       * The ids this menu acts on: the row's own id alone, or — when the
-       * right-clicked row is part of a multi-row selection — every
-       * selected id, so a right-click inside an active selection offers
-       * the exact same operation set as the bulk action bar.
-       */
+      // The row's own id alone, or every selected id when the row is part
+      // of a multi-row selection.
       readonly ids: readonly string[];
     };
 
@@ -37,10 +33,8 @@ function attr(element: Element, name: string): string | null {
   return value === null || value === "" ? null : value;
 }
 
-// Order matters: `resolveTarget` returns the first definition whose selector
-// matches anywhere in the ancestor chain, not the nearest match overall — so
-// a target nested inside another (the profile face inside a workbench row)
-// must be listed before its container.
+// Order matters: a nested target must be listed before its container,
+// since `resolveTarget` returns the first match, not the nearest.
 export const SHELL_CONTEXT_MENU_TARGETS: readonly TargetDefinition<ShellContextMenuTarget>[] = [
   {
     selector: "[data-ctx-account]",
diff --git a/apps/web/src/shell/docks.tsx b/apps/web/src/shell/docks.tsx
index 11d4097ff..41f6a160e 100644
--- a/apps/web/src/shell/docks.tsx
+++ b/apps/web/src/shell/docks.tsx
@@ -2,13 +2,7 @@
 // switcher dock this file used to also export (`BenchDock`) is gone — see
 // `sidebar.tsx`'s header comment.
 
-/**
- * Initials for the identity dock's avatar, derived locally — the app is
- * CSP-strict, so there is never a network fetch for an avatar image.
- * Prefers the account name; an account with no usable name falls back
- * to the email's local part, and "··" stands in when neither yields a
- * letter (mirroring the reference chrome's placeholder).
- */
+// Derived locally — CSP-strict, so never a network fetch for an avatar.
 export function initialsOf(name: string, email = ""): string {
   const source = name.trim().length > 0 ? name : (email.split("@")[0] ?? "");
   const initials = source
diff --git a/apps/web/src/shell/first-run-tour-store.ts b/apps/web/src/shell/first-run-tour-store.ts
index fdeda615d..6dfdc2474 100644
--- a/apps/web/src/shell/first-run-tour-store.ts
+++ b/apps/web/src/shell/first-run-tour-store.ts
@@ -1,8 +1,5 @@
-// The first-run tour's open state, held outside the React tree like
-// `command-palette-open-store.ts`: the tour must never auto-start itself on
-// landing (it used to, and its overlay would land right over the chat the
-// person was just redirected onto), so the only way in is an explicit call
-// to `openFirstRunTour` from a command or menu action.
+// Must never auto-start on landing (it used to, overlaying the chat the
+// person was just redirected onto) — only an explicit call opens it.
 
 import { useSyncExternalStore } from "react";
 
diff --git a/apps/web/src/shell/first-run-tour.tsx b/apps/web/src/shell/first-run-tour.tsx
index ca49a8b4d..932d5725b 100644
--- a/apps/web/src/shell/first-run-tour.tsx
+++ b/apps/web/src/shell/first-run-tour.tsx
@@ -1,10 +1,6 @@
-// A guided tour of the shell, started only by explicit user action (a
-// command or menu item calling `openFirstRunTour`) — never automatically on
-// landing, which used to drop its overlay right over the chat `/` redirects
-// onto. "Seen" is a localStorage flag keyed by user id (mirrors
-// `command-palette-recents.ts`'s defensive access) so a shared browser
-// profile never re-shows it as "new" for the wrong account, and finishing or
-// skipping both mark it seen — there is no "remind me later".
+// "Seen" is a localStorage flag keyed by user id, so a shared browser
+// profile never re-shows it as "new" for the wrong account. No "remind me
+// later" — finishing or skipping both mark it seen.
 
 import Joyride, { ACTIONS, type CallBackProps, STATUS, type Step } from "react-joyride";
 import { reportError } from "@corbits/error-sink";
@@ -54,23 +50,16 @@ const STEPS: readonly Step[] = [
   },
 ];
 
-/**
- * Mounted once from `AppShell`. Renders nothing until `openFirstRunTour` is
- * called — never on its own, so a fresh landing on `/` never drops this
- * overlay over the chat the person was just redirected onto.
- */
+// Renders nothing until `openFirstRunTour` is called — never on its own,
+// so landing on `/` never drops this overlay unprompted.
 export function FirstRunTour({ userId }: { readonly userId: string }) {
   const run = useFirstRunTourOpen();
 
-  // Dismissing has to unmount Joyride, not just remember the dismissal:
-  // a running Joyride keeps two portals appended to `document.body` and
-  // an overlay over the app, and those portal containers are managed
-  // outside React's tree.
+  // Must unmount Joyride, not just remember the dismissal — its portal
+  // containers are managed outside React's tree.
   function handleCallback(data: CallBackProps) {
-    // The tooltip's close (X) button fires action "close" without ever
-    // moving status to FINISHED or SKIPPED, so it has to be treated as a
-    // dismissal in its own right — otherwise closing the tour this way
-    // never closes it.
+    // The close (X) button fires action "close" without moving status to
+    // FINISHED or SKIPPED, so it must be treated as dismissal here too.
     if (
       data.status === STATUS.FINISHED ||
       data.status === STATUS.SKIPPED ||
@@ -90,10 +79,8 @@ export function FirstRunTour({ userId }: { readonly userId: string }) {
       continuous
       showSkipButton
       disableOverlayClose
-      // The overlay otherwise swallows every click outside the spotlight —
-      // real app chrome (e.g. a roster row's Chat link) is reachable at
-      // any point in the shell, tour running or not, so clicks must pass
-      // through to it rather than land on the tour's own backdrop.
+      // Without this, the overlay swallows clicks outside the spotlight —
+      // real app chrome must stay reachable while the tour runs.
       spotlightClicks
       spotlightPadding={6}
       callback={handleCallback}
diff --git a/apps/web/src/shell/layout/breakpoints.ts b/apps/web/src/shell/layout/breakpoints.ts
index be833cdf9..8af64da93 100644
--- a/apps/web/src/shell/layout/breakpoints.ts
+++ b/apps/web/src/shell/layout/breakpoints.ts
@@ -1,7 +1,5 @@
-// The shell's layout modes and the two widths that separate them, kept free
-// of the DOM so the rules stay testable and so `use-shell-layout.ts` is the
-// only place that touches `matchMedia`. The sidebar is always present; the
-// canvas column is the one region that gives way as the viewport narrows.
+// Kept free of the DOM so the rules stay testable; `use-shell-layout.ts`
+// is the only place that touches `matchMedia`.
 
 export type ShellLayoutMode = "expanded" | "compact" | "narrow";
 
diff --git a/apps/web/src/shell/layout/canvas-column-state.ts b/apps/web/src/shell/layout/canvas-column-state.ts
index 0ce41becc..30ddf4219 100644
--- a/apps/web/src/shell/layout/canvas-column-state.ts
+++ b/apps/web/src/shell/layout/canvas-column-state.ts
@@ -1,19 +1,6 @@
-// The canvas column's state as pure transitions, separate from
-// `breakpoints.ts`'s allow/disallow rule — profile demand and the viewport's
-// veto are independent inputs; `resolveCanvasVisibility` is the one place
-// they combine.
-//
-// Canvas is auxiliary only (profiles and similar targeted surfaces). Primary
-// channel conversation lives in the main stage via route (`/`, `/c`, `/c/:id`).
-// There is no permanent toggle: canvas opens when auxiliary content is targeted
-// and closes when that content is dismissed.
-//
-// `TProfile` is whatever subject the host app's canvas renders (a
-// ProfileCard subject, or anything else worth targeting); `TArtifact` is
-// whatever typed content pane the host renders alongside it (a document, a
-// sheet, or anything else); `TRoutine` is a third, equally exclusive slot
-// for a routine editor/detail pane. This module owns only the open/focus/
-// mutual-exclusion transitions, never the shape of what's shown.
+// Pure transitions, separate from `breakpoints.ts`'s allow/disallow rule:
+// profile demand and the viewport's veto are independent inputs;
+// `resolveCanvasVisibility` is the one place they combine.
 
 export type CanvasColumnState<TProfile, TArtifact, TRoutine> = {
   readonly open: boolean;
diff --git a/apps/web/src/shell/layout/index.ts b/apps/web/src/shell/layout/index.ts
index b660214f1..be7fb5ee0 100644
--- a/apps/web/src/shell/layout/index.ts
+++ b/apps/web/src/shell/layout/index.ts
@@ -1,8 +1,5 @@
-// `@/shell/layout`: the generic shell mechanics a second Interchange
-// deployment needs — the responsive breakpoint rules and the hook that reads
-// them, the canvas column state machine, per-route scroll reset, and the
-// pending-dialog-request pattern for cross-route dialog triggers. Route
-// tables and app-specific policy stay in the consuming app.
+// Generic shell mechanics a second Interchange deployment would need.
+// Route tables and app-specific policy stay in the consuming app.
 
 export {
   canvasColumnAllowed,
diff --git a/apps/web/src/shell/layout/pending-dialog-request.ts b/apps/web/src/shell/layout/pending-dialog-request.ts
index 3e3b75e66..966bcb0c0 100644
--- a/apps/web/src/shell/layout/pending-dialog-request.ts
+++ b/apps/web/src/shell/layout/pending-dialog-request.ts
@@ -1,10 +1,5 @@
-// Generalizes the pending-flag pattern `library-upload.ts` already uses for
-// cross-route dialog triggers: a caller may fire "open this dialog" from a
-// page other than the one that owns it, before that page (and its
-// window-event listener) has mounted. Dispatching the event immediately in
-// that case is a race the listener always loses. Recording a one-shot
-// pending flag and consuming it once the target page mounts avoids both the
-// race and a setTimeout guess at when the listener will be ready.
+// Avoids dispatching before the target page's listener mounts (a race it
+// always loses) without a setTimeout guess at when it'll be ready.
 
 export type PendingDialogRequest = {
   /** On-route: dispatch immediately. Off-route: record the pending flag and
diff --git a/apps/web/src/shell/layout/use-shell-layout.ts b/apps/web/src/shell/layout/use-shell-layout.ts
index 2223b1c7a..00655524e 100644
--- a/apps/web/src/shell/layout/use-shell-layout.ts
+++ b/apps/web/src/shell/layout/use-shell-layout.ts
@@ -1,11 +1,6 @@
-// The shell's layout mode, read from the same media queries the stylesheet
-// would use rather than from a resize listener: the browser evaluates the
-// query and fires `change` only when the answer actually changes, so a drag
-// across the whole viewport produces two state updates instead of hundreds.
-//
-// Rendering to static markup (the route tests) never runs effects and has no
-// `window`, so it sees the initial "expanded" assumption — which is what a
-// server-rendered shell should assume before it has a viewport to measure.
+// Media queries, not a resize listener: `change` fires only when the
+// answer changes, so a full-viewport drag produces two updates, not
+// hundreds.
 
 import { useSyncExternalStore } from "react";
 
diff --git a/apps/web/src/shell/library-artifacts.ts b/apps/web/src/shell/library-artifacts.ts
index 9dbbd69ce..ced68f2d8 100644
--- a/apps/web/src/shell/library-artifacts.ts
+++ b/apps/web/src/shell/library-artifacts.ts
@@ -1,12 +1,3 @@
-// The Library page's one seam to the hub's real artifacts plane:
-// `GET /api/tenants/:tenantId/artifacts` (list) and
-// `GET /api/tenants/:tenantId/artifacts/:id` (detail), plus
-// `POST .../artifacts/upload` for file ingest and
-// `GET .../artifacts/counts` for the kind nav's counts.
-//
-// This module owns pure mapping + upload helper so the page stays thin and
-// the shape contract has its own tests. The old asset-shim path is gone.
-
 import type { ArtifactSummary } from "@/library";
 import { ApiQueryError, UnauthenticatedError } from "@/lib/api-query";
 
@@ -48,11 +39,7 @@ export function artifactCountsPath(tenantId: string): string {
   return `/api/tenants/${tenantId}/artifacts/counts`;
 }
 
-/**
- * POST multipart upload against the tenant artifacts surface. Returns the
- * created detail rows on 201; throws with status on non-2xx so the page can
- * surface an honest failure.
- */
+// Throws with status on non-2xx so the page can surface an honest failure.
 export async function uploadArtifactFiles(
   tenantId: string,
   files: readonly File[],
@@ -88,12 +75,7 @@ export async function uploadArtifactFiles(
   return body.artifacts;
 }
 
-/**
- * PUT `/api/tenants/:tenantId/artifacts/:id` — the artifact
- * editor's one save path now that co-edit presence is gone. Throws with
- * status on non-2xx so the host can render an honest failed-save state
- * instead of silently pretending the write landed.
- */
+// Throws with status on non-2xx, never silently pretends the write landed.
 export async function saveArtifactContent(
   tenantId: string,
   artifactId: string,
@@ -121,10 +103,8 @@ export async function saveArtifactContent(
   return (await response.json()) as ArtifactDetail;
 }
 
-/** True when the hub answered "artifacts plane not configured" (503) —
- * read off the query's own status field, never string-matched out of a
- * rendered message (that copy is display-boundary plain by design and
- * carries no status text to match against). */
+// Read off the query's status field, never string-matched out of the
+// rendered message.
 export function isArtifactsUnavailableStatus(status: number | undefined): boolean {
   return status === 503;
 }
@@ -136,17 +116,9 @@ export function artifactUploadToast(names: readonly string[]): string {
     : `Uploaded ${names.length} files`;
 }
 
-/**
- * The bulk/context-menu operation set this file adopts from the shared
- * selection system — deliberately just the one real, already-
- * shippable operation: every other candidate (delete, move, rename,
- * download) has no backend route or store method behind it yet (see
- * `packages/artifacts-hub/src/routes.ts` and `@corbits/artifacts`'
- * `ArtifactStore`), so wiring a button for any of them would be exactly the
- * dead/no-op control this adoption is required to avoid. `BulkActionBar`
- * and the shell context menu's `artifact` target both read this same
- * constant, which is what the parity test asserts against.
- */
+// Deliberately just the one shippable operation: delete/move/rename/
+// download have no backend route yet, and a button with nothing behind
+// it is exactly the dead control this adoption avoids.
 export const LIBRARY_BULK_OPERATION_IDS = ["copy-link"] as const;
 
 /** `/artifacts/a/:id` — the one canonical deep link a file has. */
@@ -172,14 +144,8 @@ export function copyArtifactLinksActionLabel(count: number): string {
   return count > 1 ? `Copy ${count} links` : "Copy link";
 }
 
-/**
- * The MIME type of a file artifact's out-of-band upload blob, read off
- * `source.upload.mimeType` — present on every artifact minted through
- * `createFileArtifact` (`@corbits/artifacts`), regardless of whether the
- * hub could inline its bytes into `content` as text. Null for an artifact
- * with no upload backing at all (e.g. a co-edited doc), which is the only
- * case where an empty `content` genuinely means "nothing here yet."
- */
+// Null for an artifact with no upload backing at all — the only case
+// where an empty `content` genuinely means "nothing here yet."
 export function uploadMimeTypeFromSource(source: Record<string, unknown>): string | null {
   const upload = source.upload;
   if (typeof upload !== "object" || upload === null) return null;
diff --git a/apps/web/src/shell/routine-activity.test.ts b/apps/web/src/shell/routine-activity.test.ts
index 3579ac9d3..b6d43d9bc 100644
--- a/apps/web/src/shell/routine-activity.test.ts
+++ b/apps/web/src/shell/routine-activity.test.ts
@@ -1,12 +1,5 @@
-// `listRoutineActivity` resolves no items without fetching. The
-// `feed=fires` route it used to read is deleted with `@corbits/run-scope`,
-// and the native `GET /workflows/runs` listing has no fires equivalent —
-// its top-level-only predicate drops every routine fire by construction,
-// and its rows carry no routine attribution to compose client-side from.
-// So the shell's "Running" band and Mission Control's active-run count
-// honestly report no routine activity until a native fires equivalent
-// exists, instead of deriving routine activity from top-level deployment
-// rows that are not routine fires.
+// See `routine-activity.ts` for why this resolves no items until a native
+// fires equivalent exists.
 
 import { afterEach, describe, expect, test } from "bun:test";
 
diff --git a/apps/web/src/shell/routine-activity.ts b/apps/web/src/shell/routine-activity.ts
index 73a04bf7c..0c812aae0 100644
--- a/apps/web/src/shell/routine-activity.ts
+++ b/apps/web/src/shell/routine-activity.ts
@@ -1,17 +1,6 @@
-// deleted `@corbits/run-scope`'s `/top-level-runs?feed=fires`
-// route — the only listing that kept a routine's fire despite it not
-// being a top-level run — and the native `GET /workflows/runs` listing
-// has no equivalent: its top-level-only predicate drops every routine
-// fire by construction, and its rows carry no routine attribution to
-// compose client-side from (matching fires to routines by definition
-// name here would be exactly the slug guess the Insights feed refuses
-// to do). So `listRoutineActivity` resolves no items without fetching:
-// the shell's "Running" band and Mission Control's active-run count
-// honestly report no routine activity until a native fires
-// equivalent exists, instead of deriving routine activity from
-// top-level deployment rows that are not routine fires. The
-// `RoutineActivityItem` shape is kept so both consumers keep compiling
-// against the seam in `./bench-activity.ts`.
+// The native runs listing has no routine-fires equivalent, so this
+// resolves no items rather than deriving activity from rows that aren't
+// routine fires — an honest "none" until that equivalent exists.
 import type { ListingTurn } from "@corbits/workflows/client";
 
 export type RoutineActivityItem = {
diff --git a/apps/web/src/shell/shell-chrome-provider.tsx b/apps/web/src/shell/shell-chrome-provider.tsx
index e53660245..8ba592c4c 100644
--- a/apps/web/src/shell/shell-chrome-provider.tsx
+++ b/apps/web/src/shell/shell-chrome-provider.tsx
@@ -1,12 +1,6 @@
-// Owns the shell chrome state that has to be visible above both the command
-// palette and the shell frame: canvas state (open/profile/focus).
-// CommandPaletteProvider and AppShell are siblings in app.tsx's Shell — a
-// palette action that "closes the canvas" has to mutate the same state
-// AppShell renders from, not a second copy scoped to AppShell's own
-// subtree. This is the one place that state lives; AppShell consumes it
-// through the same hooks page code already uses (`useCloseCanvas`, ...)
-// plus the shell-only read (`useCanvasColumnOpen`) it needs for its own
-// render.
+// Sits above CommandPaletteProvider and AppShell (siblings) so a palette
+// action that closes the canvas mutates the same state AppShell renders
+// from, not a second copy scoped to its own subtree.
 
 import { useCallback, useState, type ReactNode } from "react";
 
@@ -59,10 +53,8 @@ export function ShellChromeProvider({
     initialCanvasColumnState<ProfileSubject, CanvasArtifactContent, RoutinePanelSubject>,
   );
 
-  // The last scope and rail surface we applied, adjusted during render
-  // rather than from an effect — the canvas must never paint a frame
-  // holding another workbench's content. The initial null→ready tenant
-  // resolve is not a switch.
+  // Adjusted during render, not an effect: the canvas must never paint a
+  // frame holding another workbench's content.
   const [appliedTenantId, setAppliedTenantId] = useState<string | null>(selectedTenantId);
   const routePrefix = inAppRoutePrefix(path);
   const [appliedRoutePrefix, setAppliedRoutePrefix] = useState(routePrefix);
diff --git a/apps/web/src/shell/sidebar.tsx b/apps/web/src/shell/sidebar.tsx
index 1b5329516..4d5fcacfc 100644
--- a/apps/web/src/shell/sidebar.tsx
+++ b/apps/web/src/shell/sidebar.tsx
@@ -1,23 +1,5 @@
-// The one sidebar. Header: the brand mark, then a create dropdown + search.
-// Body: Agents and Channels — nothing page-scoped ever renders here.
-// Footer: the primary rail is Artifacts, Skills, Tools, Workflows, Agents.
-// Below the rail: a single Settings row (icon + label) — Insights, the
-// account menu (avatar, name, sign out), and everything else now live
-// inside Settings itself, not as separate sidebar affordances.
-// Always present; there is no collapse affordance and no second nav column.
-// Approvals belong in the conversation, not as a standing band here.
-//
-// Inbox is gone (owner decision: tasks + approvals don't flow
-// into workbenches). Mission Control is gone too — its pending-approvals
-// and activity panels now live inside each workbench's own workbench.
-//
-// No bench switcher: a workbench IS an agent conversation now,
-// one per account, so there is nothing to switch between in the common
-// case. A multi-bench install still resolves and routes correctly (see
-// `bench-context.tsx`) — it just has no dedicated chrome slot. The one
-// escape hatch is the command palette's hidden "Switch workbench" action
-// (`command-palette-actions.ts`), which only appears once memberships
-// resolve to more than one workbench.
+// No bench switcher: a multi-bench install still resolves via the command
+// palette's hidden "Switch workbench" action.
 
 import {
   Button,
diff --git a/apps/web/src/shell/stage-search.tsx b/apps/web/src/shell/stage-search.tsx
index b733d5684..dc749c2ea 100644
--- a/apps/web/src/shell/stage-search.tsx
+++ b/apps/web/src/shell/stage-search.tsx
@@ -1,19 +1,8 @@
-// The stage top bar's per-page filter (DECISIONS.md → Search): a magnifier
-// that morphs in place into a plain text input scoped to whatever the page
-// is showing — Files filters files, Skills filters skills. It never reaches
-// the global command palette; `Cmd+K` is a separate surface entirely
-// (`command-palette-provider.tsx`), mounted on its own rather than out of
-// this control.
-//
-// A page hands in the filter it already owns (`value`/`onChange`); this
-// component only supplies the chrome — the button, the morph, and the input
-// that drives that state directly. `StageTopBar` renders it only when a page
-// passes a filter, so a page with nothing to filter shows no magnifier.
-//
-// Motion is the width transition authored on `.stage-search` in app.css
-// (react-ui's `--duration-standard` and `--ease-in-out`). Reduced motion
-// needs nothing here: react-ui's stylesheet already collapses every
-// transition duration under `prefers-reduced-motion`.
+// Never reaches the global command palette — `Cmd+K` is a separate
+// surface, mounted on its own.
+
+// Chrome only: a page hands in the filter it already owns. `StageTopBar`
+// renders this only when a page passes a filter.
 
 import { MagnifyingGlass } from "@/lib/icons";
 import { useRef, useState } from "react";
diff --git a/apps/web/src/shell/stage-top-bar.tsx b/apps/web/src/shell/stage-top-bar.tsx
index dd9255fe7..7dd0af031 100644
--- a/apps/web/src/shell/stage-top-bar.tsx
+++ b/apps/web/src/shell/stage-top-bar.tsx
@@ -1,23 +1,9 @@
-// Every stage surface renders the same top bar, and every one of them
-// titles itself with a breadcrumb trail: `crumbs` is the single way a page
-// declares where it sits, and `actions` is the single home for its primary
-// controls (a page never keeps a "New …" button in its body). A one-level
-// page passes one crumb; a detail view passes its parent plus itself.
-//
-// Crumbs are routes, not callbacks: every level above the current page
-// carries an `href`, so the trail is deep-linkable and a plain click
-// navigates through the app's own `Link` instead of reloading the shell.
-//
-// `filter` is a page's own per-page filter (DECISIONS.md → Search), rendered
-// through `StageSearch` ahead of `actions` when a page passes one. It is not
-// shell chrome the way it used to be: a page with nothing to filter passes
-// none and gets no magnifier at all. The global command palette (`Cmd+K`)
-// is a separate surface entirely — see `command-palette-provider.tsx` —
-// mounted on its own rather than out of this bar.
-//
-// `@corbits/react-ui`'s `TopBarBreadcrumbs` renders bare `<a href>`, which
-// would drop the SPA out from under the click, so the trail lives here
-// until react-ui takes a link-render slot.
+// Crumbs are routes, not callbacks, so the trail is deep-linkable. The
+// trail lives here (not `TopBarBreadcrumbs`) since react-ui's version
+// renders bare `<a href>`, which would drop the SPA under the click.
+
+// `filter` is per-page (DECISIONS.md -> Search), not shell chrome — a page
+// with nothing to filter gets no magnifier at all.
 
 import { Fragment, type ReactNode } from "react";
 
diff --git a/apps/web/src/shell/workbench-list.tsx b/apps/web/src/shell/workbench-list.tsx
index 70e3c8468..79009de24 100644
--- a/apps/web/src/shell/workbench-list.tsx
+++ b/apps/web/src/shell/workbench-list.tsx
@@ -1,7 +1,5 @@
-// The sidebar's two labeled sections, in this order and never mixed:
-// Workbenches (the bench's child tenants, a "#" glyph each) above Chats
-// (one agent each, an initials circle each, newest first). Agent
-// membership is a workbench concept; a chat has exactly one agent.
+// Two sections, in this order and never mixed: Workbenches above Chats.
+// Agent membership is a workbench concept; a chat has exactly one agent.
 
 import { EmptyState, Input, Skeleton } from "@corbits/react-ui";
 import { Check, Hash, MagnifyingGlass } from "@/lib/icons";
diff --git a/apps/web/src/skill-display-name.ts b/apps/web/src/skill-display-name.ts
index 23c041f90..c0876656e 100644
--- a/apps/web/src/skill-display-name.ts
+++ b/apps/web/src/skill-display-name.ts
@@ -1,8 +1,5 @@
-// Person-facing title for a skill roster/detail surface. The registry id
-// stays the kebab slug; what a person reads is either an explicit
-// `displayTitle` (or the native skill asset's `displayName`, which the
-// stock asset routes carry as of) or a Title Case reading of that
-// slug.
+// The registry id stays the kebab slug; a person reads an explicit
+// `displayTitle`/`displayName`, or a Title Case reading of the slug.
 import { humanizeSlug } from "@/chat/wire/display-name";
 
 export function skillDisplayName(skill: {
diff --git a/apps/web/src/skill-source.ts b/apps/web/src/skill-source.ts
index 093b84765..2d9a095fb 100644
--- a/apps/web/src/skill-source.ts
+++ b/apps/web/src/skill-source.ts
@@ -1,7 +1,5 @@
-// A skill asset's SKILL.md content, read and written over its stock
-// smart-HTTP git remote — the same path `agent-source-read.ts` and
-// `agent-deploy.ts` use for workflow assets, mirrored here for `kind:
-// "skill"` assets since the stock asset routes carry only metadata.
+// Mirrors `agent-source-read.ts`/`agent-deploy.ts`'s git path for `kind:
+// "skill"` assets, since the stock asset routes carry only metadata.
 import { fetchSourceFileOrEmpty } from "./git-fetch";
 import { pushSourceTree } from "./git-push";
 import { withGitToken } from "./git-token";
@@ -18,10 +16,8 @@ function skillAssetUrl(tenantId: string, assetName: string): string {
   ).toString();
 }
 
-/** Mints a read-only token and fetches `SKILL.md` off the asset's `main`.
- * Returns `""` for a fresh asset (no commits yet) or one whose `main`
- * doesn't carry `SKILL.md` — neither is an error, both render an empty
- * editor. */
+/** Returns `""` for a fresh asset or one whose `main` lacks `SKILL.md` —
+ * neither is an error, both render an empty editor. */
 export async function readSkillSource(
   tenantId: string,
   assetId: string,
diff --git a/apps/web/src/skill-version-author.ts b/apps/web/src/skill-version-author.ts
index c3eb64a38..3de303645 100644
--- a/apps/web/src/skill-version-author.ts
+++ b/apps/web/src/skill-version-author.ts
@@ -1,16 +1,5 @@
-// Who saved a version of a skill, in words a person can read.
-//
-// A skill's version history IS its git history, so "who" arrives as a raw
-// commit author name. Every save made through the product commits under the
-// hub's own git identity (`interchange-hub`, fixed in
-// `vendor/intx/hub-sessions/src/repo-store/store.ts`) — a machine account,
-// not a teammate, and showing it verbatim invites a reader to mistake an
-// internal name for a person. Per-principal attribution is not plumbed
-// through the commit yet; until it is, the honest answer is the product's
-// own name, never the internal one.
-//
-// A commit written by a real person — an imported skill, a repo edited
-// outside the product — keeps their name exactly as git recorded it.
+// Product-made saves commit under the hub's fixed machine identity, shown
+// as the product's own name until per-principal attribution lands.
 
 const HUB_GIT_AUTHOR = "interchange-hub";
 
diff --git a/apps/web/src/skills-api.ts b/apps/web/src/skills-api.ts
index 1dfb91224..d3adb214a 100644
--- a/apps/web/src/skills-api.ts
+++ b/apps/web/src/skills-api.ts
@@ -1,16 +1,6 @@
-// The Skills settings section's one seam to the hub's skill assets.
-//
-// the workbench-specific skill registry this used to call
-// (`@corbits/skills`, mounted at `/api/tenants/:tenantId/skills`) was
-// deleted — skills are native `kind:"skill"` hub assets now, listed and
-// created through the stock asset routes (`@intx/hub-api`'s
-// `routes/assets.ts`). Those routes carry only asset metadata (id, name,
-// displayName, creator, timestamps): there is no stock route yet to
-// read or write a skill's SKILL.md content (description/body), its
-// version history, its scope, or who has it pinned. `description` below
-// always reads back empty and `updateSkill`/`setSkillScope`/version
-// history are gone outright rather than vendored over a route that
-// doesn't exist — see the PR body for this gap.
+// Skills are native `kind:"skill"` hub assets, listed via the stock asset
+// routes. Those carry only metadata, so `description` always reads back
+// empty and there is no update/scope/version-history route yet.
 import { type } from "arktype";
 import type { ArkErrors } from "arktype";
 
@@ -133,13 +123,8 @@ export async function loadSkill(
   return { skill };
 }
 
-/**
- * Creates a skill asset's metadata only — a bare `kind:"skill"` asset
- * row and its (empty) backing repo. There is no stock route yet to
- * populate its SKILL.md body/description in the same call;
- * the caller must fill those in through whatever surface eventually
- * covers skill content.
- */
+// Creates metadata only — no stock route yet populates SKILL.md content
+// in the same call.
 export function createSkill(
   tenantId: string,
   input: { readonly name: string; readonly displayName?: string },
diff --git a/apps/web/src/test-query-provider.tsx b/apps/web/src/test-query-provider.tsx
index f16369aef..f55c2dddd 100644
--- a/apps/web/src/test-query-provider.tsx
+++ b/apps/web/src/test-query-provider.tsx
@@ -1,7 +1,5 @@
-// Shared providers for component tests that touch useAPIQuery / BenchProvider
-// / ThemeToggle. retry:false + gcTime:0 keep failures loud and cache-free;
-// ThemeProvider is the production root (main.tsx) so shell chrome that calls
-// useTheme can render under the same contract.
+// retry:false + gcTime:0 keep test failures loud and cache-free; matches
+// main.tsx's ThemeProvider so shell chrome renders under the same contract.
 
 import { ThemeProvider } from "@corbits/react-ui";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
diff --git a/apps/web/src/threads.ts b/apps/web/src/threads.ts
index ad6bd21ea..066c96db3 100644
--- a/apps/web/src/threads.ts
+++ b/apps/web/src/threads.ts
@@ -1,10 +1,5 @@
-// Thread-native derivation: DMs are participant-filtered threads over
-// supplied stock mail snapshots — never tenants, never custom
-// idempotency keys. Creation idempotency rides the native Message-ID the
-// hub stamps and returns; the client only ever dedupes replays by that id.
-// The message shape mirrors the stock `@intx/mime` parse output
-// (messageId, inReplyTo, references, listId, cc), so these pure helpers
-// apply unchanged once stock mailbox search/thread reads land.
+// DMs are participant-filtered threads, never tenants, never custom
+// idempotency keys — the client only dedupes by the hub's native Message-ID.
 
 export type ThreadMessage = {
   readonly messageId: string;
@@ -62,13 +57,9 @@ function parentIdOf(message: ThreadMessage, knownIds: Set<string>): string | und
   return undefined;
 }
 
-/** Groups supplied messages into threads: shared List-ID wins (M:N via
- * the List-ID header where the hub carries it), then In-Reply-To/References
- * chains, then normalized-subject fallback scoped to a single participant
- * set — two reply-less groups sharing a subject but talking to different
- * correspondents never merge (each 1:1 pair keeps its own thread), while
- * same-participant groups with matching subjects still join. Input order
- * decides roots. */
+/** Shared List-ID wins, then In-Reply-To/References chains, then
+ * normalized-subject scoped to a single participant set — two reply-less
+ * groups sharing a subject never merge across different correspondents. */
 export function deriveThreads(messages: readonly ThreadMessage[]): Thread[] {
   const knownIds = new Set(messages.map((message) => message.messageId));
   const parent = new Map<string, string>();
@@ -174,10 +165,9 @@ export type ForkReference = {
   readonly references: string[];
 };
 
-/** Builds the native fork ancestry for a sub-thread first message: the
- * parent becomes In-Reply-To and closes the References chain. Pure and
- * ready for the stock submission route once it accepts headers; until
- * then the linkage rides the client-held thread store beside created ids. */
+/** Parent becomes In-Reply-To and closes the References chain. Pure; the
+ * linkage still rides the client-held thread store until a stock route
+ * accepts these headers directly. */
 export function buildForkReference(parent: {
   readonly messageId: string;
   readonly references?: readonly string[];
@@ -187,11 +177,8 @@ export function buildForkReference(parent: {
   return { inReplyTo: parent.messageId, references: ancestry };
 }
 
-/** Native Message-ID replay check: a returned id already recorded for its
- * intent means the send already happened — never resend, never mint a
- * custom key. Kept as the single shared definition of that rule (rather
- * than inlining `includes` at each send site) so every send wrapper
- * compares returned ids against recorded ones through one tested helper. */
+// The single shared definition of the replay rule, so every send wrapper
+// compares ids through one tested helper rather than inlining `includes`.
 export function isDuplicateMessageId(
   seenMessageIds: readonly string[],
   messageId: string,
diff --git a/apps/web/src/tools/deployed-tool-packages.ts b/apps/web/src/tools/deployed-tool-packages.ts
index e4439e683..bcb6e6829 100644
--- a/apps/web/src/tools/deployed-tool-packages.ts
+++ b/apps/web/src/tools/deployed-tool-packages.ts
@@ -1,10 +1,5 @@
-// The tenant's tool roster, read off what its agents actually carry rather
-// than a registry that outlives the packages it once held. An agent's tool
-// packages live in two places: pinned in its deployed `definition.json`
-// (`readAgentToolPackagePins`), or — for Myra — bundled straight into her
-// `workflow.js` closure, which never shows up in that file. Her package.json
-// dependencies are the source of truth for that bundle instead of a literal
-// copy that could drift from it.
+// Read off what agents actually carry, not a registry that outlives them.
+// Myra's tools are bundled, so her package.json is the source of truth.
 
 import { useQuery } from "@tanstack/react-query";
 import { reportError } from "@corbits/error-sink";
@@ -46,10 +41,8 @@ async function toolPackagesOf(
   }
 }
 
-/** Every tool package carried by one of the tenant's live agent deployments,
- * grouped by package name and joined against which agents carry it. An
- * agent whose definition can't be read contributes nothing rather than
- * failing the whole roster. */
+/** An agent whose definition can't be read contributes nothing, rather
+ * than failing the whole roster. */
 async function listDeployedToolPackages(tenantId: string): Promise<readonly DeployedToolPackage[]> {
   const agents = liveAgentsOf(await listChatAgents(tenantId));
   const perAgent = await Promise.all(
diff --git a/apps/web/src/workbench-create.ts b/apps/web/src/workbench-create.ts
index 1334f4356..e5ef35c0f 100644
--- a/apps/web/src/workbench-create.ts
+++ b/apps/web/src/workbench-create.ts
@@ -1,8 +1,5 @@
-// Creating a workbench is creating a child tenant and deploying an agent
-// into it: the stock member invite only takes a real user's email, and a
-// child tenant's deploy route rejects the parent's inherited asset, so an
-// agent joins a workbench by being deployed there — with the child's own
-// resolved offering, which does inherit.
+// An agent joins a workbench by being deployed into the child tenant
+// itself — its deploy route rejects the parent's inherited asset.
 
 import { isMyraAgent, listWorkbenchParticipants, sendToWorkbench } from "@/chat/threads-api";
 import { agentSlugFromSourceAssetName, deployAgentSource } from "./agent-deploy";
diff --git a/apps/web/src/workbench-not-found-event.ts b/apps/web/src/workbench-not-found-event.ts
index 6d7d05fc0..86e4b416b 100644
--- a/apps/web/src/workbench-not-found-event.ts
+++ b/apps/web/src/workbench-not-found-event.ts
@@ -1,8 +1,5 @@
-/** App-local event so a workbench-level 404 (`chat-page.tsx`, driven by
- * `ChatWorkspace`'s `onWorkbenchNotFound`) can tell the command palette to
- * drop a stale Recents entry, without coupling the chat route to
- * `CommandPaletteProvider` state — the chat route and that provider are
- * siblings in the Shell. */
+/** Lets a workbench-level 404 tell the palette to drop a stale Recents
+ * entry, without coupling the chat route to `CommandPaletteProvider`. */
 
 export const WORKBENCH_NOT_FOUND_EVENT = "workbench:workbench-not-found";
 
diff --git a/apps/web/src/workbench-path.ts b/apps/web/src/workbench-path.ts
index bfa815c88..1e22b1cfa 100644
--- a/apps/web/src/workbench-path.ts
+++ b/apps/web/src/workbench-path.ts
@@ -1,12 +1,6 @@
-// Workbench deep links live at `/w/:workbenchId`. The retired `/chat` prefix
-// still resolves here so old bookmarks and in-flight links land on the
-// same surface instead of a dead route. A workbench's settings are a full
-// stage surface (never a dialog — workbenches are tenants), routed at the
-// `/settings` sub-path of its deep link, optionally followed by the
-// section id (`/settings/:section`) and a section's own sub-selection
-// (`/settings/:section/:entityId`) — same pattern as `path-ids.ts`'s
-// `/settings/:section` and `settingsEntityIdFromPath` for the app-level
-// Settings page.
+// The retired `/chat` prefix still resolves to `/w/:workbenchId` so old
+// bookmarks land on the same surface instead of a dead route. Settings is
+// a full stage surface, never a dialog, since a workbench is a tenant.
 
 import { decodedOrNull } from "@corbits/url-path";
 
@@ -73,10 +67,8 @@ export function workbenchPath(workbenchId: string | null): string {
   return `${WORKBENCH_PATH_PREFIX}/${encodeURIComponent(workbenchId)}`;
 }
 
-/** Canonical path for a workbench's settings stage surface, optionally
- * scoped to a section (`/w/:id/settings/:section`) and that section's own
- * sub-selection (`/w/:id/settings/:section/:entityId`) for a deep link
- * straight to an agent (or similar) detail. */
+/** Canonical settings path, optionally scoped to a section and its own
+ * sub-selection, for a deep link straight to a detail like an agent. */
 export function workbenchSettingsPath(
   workbenchId: string,
   section?: WorkbenchSettingsSectionId,
@@ -89,15 +81,9 @@ export function workbenchSettingsPath(
   return `${withSection}/${encodeURIComponent(entityId)}`;
 }
 
-/** Extract the section id from `/w/:id/settings/:section` (or
- * `/settings/:section/:entityId`, or its legacy `/chat` equivalent) —
- * `undefined` for bare `/settings`, a non-settings path, a malformed
- * escape, or a segment that isn't one of `WorkbenchSettingsSectionId`'s own
- * values. Only the first segment after `/settings/` is the section, so a
- * trailing entity id does not change the section. An unrecognized id reads
- * the same as no section at all: the settings surface already falls back
- * to its first section then, the same contract `settingsSectionIdFromPath`
- * in `path-ids.ts` relies on its caller for. */
+/** `undefined` for bare `/settings`, a malformed escape, or an unrecognized
+ * section id — the caller falls back to the first section, same contract
+ * as `settingsSectionIdFromPath` in `path-ids.ts`. */
 export function workbenchSettingsSectionFromPath(
   path: string,
 ): WorkbenchSettingsSectionId | undefined {
@@ -115,12 +101,8 @@ export function workbenchSettingsSectionFromPath(
   return decoded;
 }
 
-/** Extract a section's own sub-selection from
- * `/w/:id/settings/:sectionId/:entityId` (or the legacy `/chat`
- * equivalent) — `null` when the path isn't under that section, or carries
- * no sub-id. Mirrors `settingsEntityIdFromPath` in `path-ids.ts`, but
- * locates the settings suffix the same way `workbenchSettingsSectionFromPath`
- * does (`indexOf`), because workbench paths are not rooted at `/settings`. */
+/** Mirrors `settingsEntityIdFromPath` in `path-ids.ts`, but locates the
+ * settings suffix by `indexOf` since workbench paths aren't rooted at it. */
 export function workbenchSettingsEntityIdFromPath(path: string, sectionId: string): string | null {
   const sectionPrefix = `${SETTINGS_SUFFIX}/${sectionId}/`;
   const index = path.indexOf(sectionPrefix);
diff --git a/docs/auth-dither-background.md b/docs/auth-dither-background.md
new file mode 100644
index 000000000..c847502ac
--- /dev/null
+++ b/docs/auth-dither-background.md
@@ -0,0 +1,14 @@
+# Auth dither background: 2D canvas, not WebGL
+
+`apps/web/src/auth/dither-background.tsx` renders an animated ordered-dither
+over a source image on a plain 2D canvas: a downscaled buffer is dithered
+each frame with a slow ambient sine warp plus a cursor-driven displacement,
+then upscaled with `image-rendering: pixelated`.
+
+This replaces an original WebGL port: a WebGL canvas promoted the auth panel
+to a GPU-composited layer that failed to paint (blank/white). A 2D canvas is
+CPU-rasterized, composites reliably, and retains its last frame when
+`requestAnimationFrame` is paused on a hidden tab.
+
+The loop pauses whenever the canvas is offscreen or the tab is hidden, caps
+to ~30fps, and honors `prefers-reduced-motion` reactively.
diff --git a/docs/chat-mail-threading.md b/docs/chat-mail-threading.md
new file mode 100644
index 000000000..4293ecd86
--- /dev/null
+++ b/docs/chat-mail-threading.md
@@ -0,0 +1,41 @@
+# Chat and workbench mail threading
+
+`apps/web/src/chat/threads-api.ts` is the only seam between the chat UI and
+mail: a chat has exactly one agent, and both sides are durable mail — the
+person sends from their own mailbox (keeping a Sent copy), and an agent's
+reply lands in the same mailbox's INBOX. No chat-specific hub route exists.
+
+A chat is keyed by its agent's definition asset id, not a run id: every hub
+restart releases the old run and redeploys under a new one, so keying on a
+run id would 409 the moment it turns terminal. An agent's address set spans
+every run it has ever had, which keeps history intact across a redeploy;
+sends resolve the current live run's address at send time.
+
+A workbench is a child tenant, and its conversation is that tenant's own
+mailbox — reads are the same stock mailbox routes as a chat, scoped to the
+child tenant id.
+
+## Workbench send roster
+
+`sendToWorkbench` appends a trailing roster of every participant's name and
+address to the message body (the same rows the Participants panel reads).
+The hub only delivers to a run address, which only the client otherwise
+knows, so this is what lets an agent hand a task to another agent in the
+workbench. The mail tools have no `cc` field, so the roster also tells
+agents to copy the person on a handoff by naming them as another `to`
+recipient.
+
+## Primary-thread root resolution
+
+`readHubSnapshot`'s caller resolves a workbench's primary-thread root from
+the recorded `primaryThreadMessageId`, falling back to `mail[0]` only for
+mail sent before that id existed. The mailbox list is assumed oldest-first;
+if the hub ever returns newest-first or unordered rows the fallback
+mistargets, so the recorded id stays authoritative.
+
+## Sub-thread fork replay
+
+`forkSubThread` treats a fork as already sent when parent + subject +
+recipients + body match a recorded row, returning its native Message-ID
+instead of resending. Rows recorded before recipients/body were stored
+match on parent + subject only, to preserve their exactly-once replay.
diff --git a/docs/chat-wire-contract.md b/docs/chat-wire-contract.md
new file mode 100644
index 000000000..092c41c5c
--- /dev/null
+++ b/docs/chat-wire-contract.md
@@ -0,0 +1,59 @@
+# Chat wire contract
+
+`apps/web/src/chat/wire/*` is the browser-facing half of the wire contract
+also implemented server-side in `packages/chat/src`. `apps/web` cannot import
+`@corbits/chat` — a server-only package — so this half is hand-mirrored
+rather than shared by import. Once the hub moves onto native mail threads,
+`packages/chat`'s copy goes away and this becomes the one source of truth.
+
+Keep both sides in sync by hand until then; a schema or type added to one
+side belongs on the other.
+
+## Internal-id leak guard
+
+`chat/wire/id-leak-guard.ts` centralizes the check that a person never sees
+an internal identifier (a raw `run_…`/`wfd_…`/etc., or `humanizeSlug`'s
+Title-Cased reading of one, e.g. "Run 737a058d…"). This recurred repeatedly
+as one-off display-time patches (insights, a Myra reply, a chat title)
+before being consolidated here, so a new id-generating prefix is a missed
+test run rather than a missed grep. Prefix words mirror `@intx/hub-common`'s
+`generateId` (`PREFIXES` in `packages/hub-common/src/ids.ts`).
+
+## Approve block (`chat/blocks/approve-block.tsx`)
+
+The card renders the platform's own live account of what's being asked as
+the authoritative description next to Approve/Deny; an agent's own framing
+is demoted to contextual color and never shown alone. Resolved state is
+always re-rendered from the host's status read, never from the block's own
+data or a decision response the card just made — nothing here is itself a
+decision.
+
+`@/chat` owns no session or query cache and never fetches/mutates approvals
+itself — the host supplies an `ApprovalActions` port (`chat/blocks/approval-
+actions.ts`), calling the same native approve/reject routes and
+invalidating the same query keys as Inbox, so the card, Inbox, and the
+Activity band stay one source of truth. `forbidden` is distinct from
+`canAct: false`: it means the host's own status read was refused, so the
+card shows Approve/Deny anyway and lets the real decision call's own
+authorization decide, rather than guessing a verdict or rendering
+unverified agent text as the platform's account of the request.
+
+## Stream events (`chat/wire/stream-events.ts`)
+
+Organizing rule: a subscriber must be able to render, or update its own
+state, from the event alone — never a follow-up GET. `chat.message` carries
+the full rendered row (mail headers included, when the row was actually
+mailed); `chat.presence` deltas fold into the roster `chat.presence.snapshot`
+already gave the connecting stream.
+
+## Classified inference failures (`chat/inference-failure.ts`)
+
+By the time a reply reaches the chat timeline it is a plain text part with
+no metadata — the failure's category is structured further upstream
+(`packages/chat`'s orchestrator reads it directly), but nothing carries it
+down to this render layer. So this file matches reply prose against the
+exact preambles `@intx/inference`'s `formatInferenceError` writes for
+`credential_failure` and `quota_exhausted`, anchored at the start of the
+string (never a substring, so a reply that quotes one mid-sentence can't
+false-positive). A test asserts the preambles stay byte-for-byte identical
+to the vendored source they're copied from.
diff --git a/docs/insights-native-runs.md b/docs/insights-native-runs.md
new file mode 100644
index 000000000..90307d490
--- /dev/null
+++ b/docs/insights-native-runs.md
@@ -0,0 +1,26 @@
+# Insights: native runs feed cutover
+
+`apps/web/src/insights-api.ts` reads the native tenant-scoped `GET
+/workflows/runs` listing. The old `@corbits/run-scope` and `packages/insights`
+are deleted; the hub mounts nothing Workbench-specific anymore. The four
+stock observability routes are unimplemented 501 stubs, so usage/cost,
+tool-call, latency, run-trace and cross-workbench scope lost their only data
+source and were dropped rather than faked.
+
+Differences from the deleted `feed=fires` feed, all accepted loss:
+
+- A routine's fire (not a top-level run) is no longer included.
+- No routine attribution, so history groups by definition instead.
+- The resident, never-triggered deployment placeholder is now included and
+  counted as deployed by `computeInsightsStats`.
+- The feed is single-tenant: the deleted route rolled up a workspace
+  parent's whole descendant subtree; the native listing filters one tenant.
+
+This replaces the dead `/me/workflows/runs`, whose `anchorRunId IS NULL`
+filter never matched anything (every addressed run self-anchors at
+creation), so that feed always came back empty.
+
+`InsightsRunSchema` adds `routineId`/`routineName` (absent on the native
+feed; callers fall back to `definitionId`/`definitionName`) and
+`turns`/`hasInFlightTurn`, this build's own in-flight-turn tracking, not an
+Interchange field — omitting them is not "no in-flight turn".
diff --git a/docs/myra-definition-json.md b/docs/myra-definition-json.md
new file mode 100644
index 000000000..e025b0df4
--- /dev/null
+++ b/docs/myra-definition-json.md
@@ -0,0 +1,21 @@
+# Myra's hand-built definition.json
+
+`buildMyraDefinitionJson` in `apps/web/src/myra-deploy.ts` is the
+function-free projection of what `@corbits/myra`'s `buildMyraWorkflow`
+produces, written to the asset's `definition.json` for readers — the entry
+itself is a bundle no reader can slice apart.
+
+It is hand-built here rather than by calling that function, because
+`buildMyraWorkflow` goes through `@intx/workflow`'s `defineWorkflow`/`step`,
+which pull in `@intx/agent`'s Node-bound runtime (file locking) that a
+browser bundle cannot resolve.
+
+It mirrors `defineWorkflow`'s own normalization
+(`vendor/intx/workflow/src/definition/workflow.ts`'s `normalize`/
+`applyDefaultInputStep`, and `primitives.ts`'s `step`): a single step with no
+`after` gets `input: { from: "trigger.payload" }`; `triggers: "unbounded"`
+(not the numeric default) gets `drainBehavior: "wait"`; a bare `trigger`
+becomes a one-element `triggers` array.
+
+`toolFactories` and `toolPackagePins` are empty on purpose: the real
+factories ride the bundle, and JSON cannot carry a function.
diff --git a/docs/routines-scheduling.md b/docs/routines-scheduling.md
new file mode 100644
index 000000000..8da08350d
--- /dev/null
+++ b/docs/routines-scheduling.md
@@ -0,0 +1,21 @@
+# Routines page data sources
+
+`apps/web/src/routines-api.ts` reads stock deployments (`GET
+/workflows/deployments`) joined against the tenant's workflow assets (`GET
+/assets?kind=workflow`) for a display name — the two stock reads
+`vendor/intx/hub-api/src/routes/workflows.ts` exposes. The old
+`@corbits/workflows` scheduled-route and its hub backing are gone.
+
+## Schedule column
+
+The `schedule` trigger is reserved on Interchange but unimplemented — no
+scheduler fires it. A schedule shown here is a `@corbits/cron` row addressed
+at the deployment's live run, joined in from `GET /cron` by that address
+(the same `run_<id>@<domain>` join `chat/threads-api.ts` does against
+`listTopLevelRuns`).
+
+## Run-now and pause/resume
+
+Neither has a backing stock route (`/deployments` is list/create only; no
+per-deployment PATCH or trigger route exists), so both stay rejected
+promises naming the missing route.
diff --git a/docs/settings-sections.md b/docs/settings-sections.md
new file mode 100644
index 000000000..3661d9bfe
--- /dev/null
+++ b/docs/settings-sections.md
@@ -0,0 +1,17 @@
+# Settings section registry
+
+`apps/web/src/settings/section-registry.tsx` collapsed Personal/Workspace
+into one account-scoped group and one shared group: there is one workbench
+per account now, so "workspace-scoped" and "account-scoped" name the same
+tenant's settings.
+
+Shared Settings leads with what everyone inherits (credentials, then
+People) and tucks access-control mechanics (Roles, Grants, Audit) under a
+collapsed Advanced disclosure — nobody should have to parse grants and
+roles just to find where a shared API key lives.
+
+Bench dies outright: there's no longer a second thing to name, distinct
+from the account, so its rename/purpose/icon form and member list have no
+home to keep them separate in. Conversation-scoped settings (agent,
+capabilities, history) live on the workbench's own settings surface
+instead.
diff --git a/docs/test-toast-mock.md b/docs/test-toast-mock.md
new file mode 100644
index 000000000..a3bf37886
--- /dev/null
+++ b/docs/test-toast-mock.md
@@ -0,0 +1,14 @@
+# Toast spy: delegate, never replace
+
+`apps/web/src/react-ui-toast-mock.ts` spies on `@corbits/react-ui`'s `toast`
+by delegating to the real implementation, not stubbing it out.
+
+`mock.module` rewrites bun's module registry for the whole test process, not
+just the calling file, and bun offers no way to undo it. A stub installed by
+one test file stays installed for every later file bun loads — and
+`toast-single-system.test.tsx` renders the real toaster and asserts on the
+DOM, so a plain stub would make it fail for reasons unrelated to toasts.
+
+By delegating, callers still get a call record to assert on, while any file
+that renders a real `<Toaster />` keeps seeing real toasts regardless of
+suite load order.