@jxsuite/studio 5.3.0 → 5.4.0

package/src/services/tool-outcomes.ts

@@ -0,0 +1,143 @@
+/**
+ * Tool-outcomes.ts — where a persisted tool call's outcome lives, and how a restore finds it.
+ *
+ * A tool call's outcome is recorded twice while a turn runs: as the `result` on its
+ * `ToolCallRecord`, which the chip renders, and as the `tool` message that answers it, which the
+ * provider reads. The second is the one that must survive, because it is the one the wire carries,
+ * and it is the one that always did: until the turn became accountable (specs/ai.md §3.2) the first was never populated for a
+ * finished call (the loop looked for the record after closing the stream), so every persisted
+ * `result` was `null`: every restored chip rendered as still pending, and an answered question as
+ * one still open (specs/ai.md §3.4).
+ *
+ * So the tool message is the single source. A save strips `result` from every record, which keeps
+ * the payload free of a second, disagreeing copy; a restore backfills each record from the reply
+ * that answers it. A question nothing answered keeps no result, which is what makes it render
+ * inert rather than as one still waiting; an ordinary call nothing answered never completed, and
+ * says so.
+ *
+ * **A seal is not an answer.** When a question was left open, the send path seals its request with
+ * a synthesized failure so the wire stays well-formed (`pruneOrphanToolMessages`). For an ordinary
+ * call that failure IS the outcome to show: it never completed. For a question it is the absence of
+ * an answer, so a restore leaves it without a result, and the chip draws the inert "still open when
+ * the session was reloaded" card rather than a failure.
+ *
+ * @docs studio/ai/chat
+ * @license MIT
+ */
+
+import type { ToolResult } from "@jxsuite/ai/tools";
+import type { PersistedMessage } from "./ai-session-store";
+import { UNANSWERED_TOOL_RESULT } from "./context-manager";
+
+/** The tool that suspends a turn on the author (services/ai-ask.ts). */
+const ASK_TOOL = "ask_user";
+
+/** The outcome of an ordinary call that never ran to completion — the seal's own words. */
+const NEVER_COMPLETED = JSON.parse(UNANSWERED_TOOL_RESULT) as ToolResult;
+
+/** A tool-call record as persisted: `id` and `name` are what pairing and the chip read. */
+interface PersistedToolCall {
+  id?: unknown;
+  name?: unknown;
+  result?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * The messages as they should be persisted: every tool-call record without its `result`.
+ *
+ * Copies, never mutates — the live chat's records are the ones the panel is rendering.
+ *
+ * @param {readonly PersistedMessage[]} messages
+ * @returns {PersistedMessage[]}
+ */
+export function stripToolResults(messages: readonly PersistedMessage[]): PersistedMessage[] {
+  return messages.map((message) => {
+    if (!Array.isArray(message.toolCalls)) {
+      return message;
+    }
+    return {
+      ...message,
+      toolCalls: message.toolCalls.map((call) => {
+        if (!call || typeof call !== "object") {
+          return call;
+        }
+        const { result: _result, ...rest } = call as PersistedToolCall;
+        return rest;
+      }),
+    };
+  });
+}
+
+/** A tool message's content as a `ToolResult`, or null when it is not one. */
+function parseToolResult(content: unknown): ToolResult | null {
+  if (typeof content !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(content) as unknown;
+    return parsed &&
+      typeof parsed === "object" &&
+      typeof (parsed as ToolResult).success === "boolean"
+      ? (parsed as ToolResult)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The messages as they should be restored: every tool-call record carrying the result of the tool
+ * message that answered it.
+ *
+ * **Pairing is per request, not by id across the transcript.** A provider may number its calls
+ * afresh each round (`call_0` in round one and again in round two), so the reply to a call is
+ * looked for only among the `tool` messages directly after the assistant message that made it — the
+ * one position the wire allows a reply in. A record that already carries a result (a payload
+ * written before results were stripped) keeps it only when no reply is found.
+ *
+ * @param {readonly PersistedMessage[]} messages
+ * @returns {PersistedMessage[]}
+ */
+export function backfillToolResults(messages: readonly PersistedMessage[]): PersistedMessage[] {
+  return messages.map((message, index) => {
+    if (message.role !== "assistant" || !Array.isArray(message.toolCalls)) {
+      return message;
+    }
+    const replies = new Map<string, ToolResult>();
+    const sealed = new Set<string>();
+    for (let next = index + 1; next < messages.length; next++) {
+      const reply = messages[next]!;
+      if (reply.role !== "tool") {
+        break;
+      }
+      const result = parseToolResult(reply.content);
+      if (typeof reply.toolCallId === "string" && result && !replies.has(reply.toolCallId)) {
+        replies.set(reply.toolCallId, result);
+        if (reply.content === UNANSWERED_TOOL_RESULT) {
+          sealed.add(reply.toolCallId);
+        }
+      }
+    }
+    return {
+      ...message,
+      toolCalls: message.toolCalls.map((call) => {
+        if (!call || typeof call !== "object") {
+          return call;
+        }
+        const record = call as PersistedToolCall;
+        const id = typeof record.id === "string" ? record.id : undefined;
+        const answered = id === undefined ? undefined : replies.get(id);
+        if (record.name === ASK_TOOL) {
+          /* A question's only outcomes are an answer or none: a seal is not an answer, and a
+             question nothing answered stays open, which the chip draws as inert. */
+          const reply = answered && id !== undefined && !sealed.has(id) ? answered : undefined;
+          return { ...record, result: reply ?? record.result ?? null };
+        }
+        /* Nothing is in flight after a restore, so an ordinary call nothing answered (a round Stop
+           ended before its tools ran) never completed: the outcome the next send's seal will say. */
+        return { ...record, result: answered ?? record.result ?? NEVER_COMPLETED };
+      }),
+    };
+  });
+}

package/src/settings/contexts-section.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * Contexts — the ONE place a project's rendering contexts are defined (plan §4.2, §2 principle 5).
+ * Contexts — the ONE place a project's rendering contexts are defined (§6.2, §17.1).
  *
  * A rendering context is anything the document can be resolved _under_: a size breakpoint, a colour
  * scheme, a feature query. All three are the same thing on disk — one entry in `project.json`'s
@@ -15,9 +15,9 @@
  *    '(prefers-color-scheme: dark)'` to `$media` **without ever using the word breakpoint**, so the
  *    one control that created a colour scheme was filed under variables.
  *
- * All four are gone. §2 principle 5 is why: **definition and selection are different levels.** The
- * pane context bar's Rendering-context control _selects_ among these; its popover's footer is
- * "Manage contexts…", which opens this section. Nothing here selects, and nothing there defines.
+ * All four are gone. §6.2 is why: **definition and selection are different levels.** The pane
+ * context bar's Rendering-context control _selects_ among these; its popover's footer is "Manage
+ * contexts…", which opens this section. Nothing here selects, and nothing there defines.
  *
  * **This section writes the project, not the document.** Per-document `$media` overlays still merge
  * at render time (`site-context.ts`'s `getEffectiveMedia`) and the on-disk format is unchanged —
@@ -27,8 +27,8 @@
  * Failures are surfaced, not swallowed: every write runs through {@link persistMedia}, which
  * schema-validates the candidate `project.json` with `jx-validate` first (the human editing this
  * file used to get **no validation at all** — that was wired to the AI's `write_project_config`
- * alone), parks any rejection under the control that caused it, and re-projects. §7.1's third tier:
- * a bad value belongs at its control, not in a toast that expires.
+ * alone), parks any rejection under the control that caused it, and re-projects. §16.1's third
+ * tier: a bad value belongs at its control, not in a toast that expires.
  *
  * **The markup is `surfaces/settings-contexts.json`.** This module is the section's decisions —
  * what a context is, what refuses one, and what reaches disk — and the surface adapter beside that
@@ -120,8 +120,8 @@ export function splitContexts(media?: Record<string, string> | undefined): {
  * The `$media` key a typed name becomes: `Wide screen` → `--wide-screen`.
  *
  * Typing the leading dashes is allowed but never required — the dashes are a storage detail of the
- * CSS custom-property namespace `$media` shares, and §8.4 says a definition surface may not make
- * the user spell one.
+ * CSS custom-property namespace `$media` shares, and a definition surface may not make the user
+ * spell one (the plain-word rule, `studio-ui-guidelines.md` §11.3).
  *
  * @param {string} name
  * @returns {string}

package/src/settings/contributed-section.ts

@@ -129,9 +129,9 @@ export function resetContributedSectionState(): void {
  * Select an entry of a map-layout section by key — the addressable form of clicking an entry row.
  *
  * Five screenshot steps used to reach these rows by typing an empty string into a hand-stamped
- * region id, carrying `unstable: { reason: "\"settings.selectEntry\" has no command record", until:
- * "P6.2" }`. This is P6.2 and the record is `settings.open {section, entry}`: an entry is a KEY in
- * the section's own map, so naming it is naming state rather than reproducing a gesture.
+ * region id, carrying an `unstable` hatch whose reason was `"settings.selectEntry" has no command
+ * record`. The record is `settings.open {section, entry}`: an entry is a KEY in the section's own
+ * map, so naming it is naming state rather than reproducing a gesture.
  *
  * @param {string} sectionKey
  * @param {string} entryKey
@@ -153,7 +153,7 @@ export function selectContributedEntry(sectionKey: string, entryKey: string): st
   return null;
 }
 
-// ─── Validation (§7.1 inline tier, §7.2 Problems) ─────────────────────────────
+// ─── Validation (§16.1 inline tier, §16.3 Problems) ───────────────────────────
 
 /**
  * The last validator run's messages, keyed by the JSON-pointer base they were rendered under.
@@ -215,8 +215,8 @@ export function routeDiagnostics(
  * The write itself now belongs to `tabs/project-config.ts` — one serialisation, one error path, and
  * a transaction the author can undo. This module used to own a second writer, at
  * `JSON.stringify(config, null, "\t")`, which re-indented the whole file on any edit; and before
- * that it was `void saveProjectConfig()` at five call sites with no validation at all. §7.2 files a
- * failed config write as a Problem, because it must be fixed and it is about a named file; the
+ * that it was `void saveProjectConfig()` at five call sites with no validation at all. §17.1 files
+ * a failed config write as a Problem, because it must be fixed and it is about a named file; the
  * chokepoint files it, so a failure here only has to stop.
  *
  * **The write comes first, and the order is the honest one.** This form mutates

package/src/settings/css-vars-editor.ts

@@ -1,6 +1,6 @@
 /// <reference lib="dom" />
 /**
- * The design-token editor — the token half of **Project Styles** (plan §9.4).
+ * The design-token editor — the token half of **Project Styles** (§7.1).
  *
  * Every token in the project's root `style` block, grouped by what it names, each editable in place
  * and each able to carry a different value in any **rendering context** the project declares. The
@@ -17,8 +17,8 @@
  * Three things it does NOT do, each on purpose:
  *
  * - **It does not define a context.** Breakpoints and colour schemes are declared once, in Project
- *   Settings › Contexts, and this level only overrides against them (§2 principle 5). Where nothing
- *   is declared it says so and routes there.
+ *   Settings › Contexts, and this level only overrides against them (§6.2). Where nothing is
+ *   declared it says so and routes there.
  * - **It does not change the file format.** Overrides are the same `"@--ctx": { "--token": … }`
  *   blocks the compiler already reads, and an emptied block is removed rather than left behind.
  * - **It does not re-render the canvas.** An edit is pushed to every live canvas in place through
@@ -272,8 +272,9 @@ function view(container: HTMLElement): CssVarsView {
   const hasScheme = declared.some((context) => context.kind === "scheme");
   const groups: GroupView[] = [];
   for (const { group, tokens } of groupTokens(rootStyle)) {
-    /* A bucket named "Other" over an empty list teaches nothing (§2 principle 6). Every other
-       group keeps its heading and its add row, because an empty one is where a palette starts. */
+    /* A bucket named "Other" over an empty list teaches nothing (`studio-ui-guidelines.md` §11.1).
+       Every other group keeps its heading and its add row, because an empty one is where a palette
+       starts. */
     if (group.id === "other" && tokens.length === 0) {
       continue;
     }

package/src/settings/extension-commands.ts

@@ -20,11 +20,11 @@
  * **`enablement` is `ctx.project.open` and nothing else, on all three.** A precondition that
  * depends on an ARGUMENT cannot live there — `enablement` cannot see one — so "is this a real
  * extension?", "can this backend run it?" and "is it still enabled?" are refused with a
- * `RangeError` naming the value, the shape §12.4 prescribes and `pane.derive` already uses. The
- * first two are answered by the derived enum that `registry.run` coerces `package` against — a
- * value outside it reads `is not declared — declared: …` — and the sentences inside `run` remain
- * for the callers that reach it directly (the Extensions section's switch) and for a row that
- * changed between the schema being read and the verb running.
+ * `RangeError` naming the value, the shape `studio-ui-guidelines.md` §12.4 prescribes and
+ * `pane.derive` already uses. The first two are answered by the derived enum that `registry.run`
+ * coerces `package` against — a value outside it reads `is not declared — declared: …` — and the
+ * sentences inside `run` remain for the callers that reach it directly (the Extensions section's
+ * switch) and for a row that changed between the schema being read and the verb running.
  *
  * **The in-flight latch lives here, not in the section**, because the assistant can run these too:
  * a latch the renderer owned would let a tool call and a click install concurrently.
@@ -137,11 +137,11 @@ export async function enableExtension(specifier: string): Promise<void> {
   try {
     if (!row.installed && !row.bundled) {
       /*
-       * `beginActivity`, not `showProgressModal`. §13.3 reserves blocking for an operation that
-       * cannot proceed while the author edits, and this one can — the only real hazard is a second
-       * concurrent write, which the latch closes for a fraction of the cost of freezing the app.
-       * `ui/progress-modal.ts` also enumerates its four call sites as a closed set, and a fifth
-       * would make a written invariant false.
+       * `beginActivity`, not `showProgressModal`. `studio-ui-guidelines.md` §13.3 reserves blocking
+       * for an operation that cannot proceed while the author edits, and this one can — the only
+       * real hazard is a second concurrent write, which the latch closes for a fraction of the cost
+       * of freezing the app. `ui/progress-modal.ts` also enumerates its four call sites as a closed
+       * set, and a fifth would make a written invariant false.
        */
       const activity = beginActivity({
         source: "Extensions",
@@ -161,8 +161,8 @@ export async function enableExtension(specifier: string): Promise<void> {
        * The activity ends HERE, before the config write, and that boundary is load-bearing:
        * `ActivityHandle.fail` raises its own Problem and `commitProjectConfig` raises another keyed
        * `save:project.json`, so an activity spanning both would post two Problems for one failure
-       * with different keys — undeduplicable, and exactly what §13.3 rule 3 forbids. It is also
-       * honest: the install did succeed.
+       * with different keys — undeduplicable, and exactly what `studio-ui-guidelines.md` §13.3
+       * rule 3 forbids. It is also honest: the install did succeed.
        */
       activity.done();
     }
@@ -210,8 +210,8 @@ export async function disableExtension(specifier: string): Promise<void> {
  *
  * Refuses while `project.json` still names it, because removing the package under a live
  * `extensions` entry produces precisely the enabled-but-missing state that fails the next build.
- * §12.4's rule: the strict member's refusal is evidence the write is unsafe, so the loose member
- * must not do it anyway.
+ * `studio-ui-guidelines.md` §12.4's rule: the strict member's refusal is evidence the write is
+ * unsafe, so the loose member must not do it anyway.
  *
  * @param {string} name
  * @returns {Promise<void>}
@@ -357,10 +357,11 @@ export function extensionCommands(): AnyCommand[] {
       enablement: (ctx) => ctx.project.open,
       undo: "none",
       /*
-       * Deliberately no `aiTool`. §12.4 binds an agent tool that WRITES what a command writes to
-       * the command's rule; it does not require every command to have one. The model has no read
-       * that tells it whether a dependency is load-bearing elsewhere in the project, so it cannot
-       * form the judgement this verb needs, and the act is destructive and not undoable.
+       * Deliberately no `aiTool`. `studio-ui-guidelines.md` §12.4 binds an agent tool that WRITES
+       * what a command writes to the command's rule; it does not require every command to have one.
+       * The model has no read that tells it whether a dependency is load-bearing elsewhere in the
+       * project, so it cannot form the judgement this verb needs, and the act is destructive and
+       * not undoable.
        */
       run: async (_ctx, args) =>
         removeExtensionPackage(stringArg("packages.remove", args, "package")),

package/src/settings/extension-sections.ts

@@ -89,13 +89,13 @@ const registeredKeys = new Set<string>();
 /**
  * The sync currently running, so concurrent callers join it instead of racing it.
  *
- * This is half of the deep-link fix (plan §12 P6.2). `refreshExtensionUi` (`format/format-host.ts`)
- * fires this function **fire-and-forget** on project activation and after every `project.json`
- * write, and the settings surface used to start a SECOND, interleaved run and await only its own.
- * The two runs share {@link registeredKeys} and both reach {@link unregisterSettingsSection}, so a
- * key one run had just registered could be seen as stale by the other and unregistered — after the
- * awaited promise had already resolved. Coalescing makes "the sections are ready" one fact about
- * the registry rather than one fact per caller.
+ * This is half of the deep-link fix (`settings.open { section, entry }`, §17.1).
+ * `refreshExtensionUi` (`format/format-host.ts`) fires this function **fire-and-forget** on project
+ * activation and after every `project.json` write, and the settings surface used to start a SECOND,
+ * interleaved run and await only its own. The two runs share {@link registeredKeys} and both reach
+ * {@link unregisterSettingsSection}, so a key one run had just registered could be seen as stale by
+ * the other and unregistered — after the awaited promise had already resolved. Coalescing makes
+ * "the sections are ready" one fact about the registry rather than one fact per caller.
  */
 let _inFlight: Promise<void> | null = null;
 

package/src/settings/extensions-section.ts

@@ -126,9 +126,9 @@ function blockedReason(row: ExtensionRow): string {
  * The per-row Remove, as the document reads it.
  *
  * Refused while the extension is still enabled, and DISABLED with the reason rather than hidden
- * (guidelines §10): removing the package while `project.json` still names it manufactures exactly
- * the broken state this section exists to eliminate. It is absent only when there is nothing to
- * remove — a package the project never installed, or one the backend bundles.
+ * (`studio-ui-guidelines.md` §10): removing the package while `project.json` still names it
+ * manufactures exactly the broken state this section exists to eliminate. It is absent only when
+ * there is nothing to remove — a package the project never installed, or one the backend bundles.
  */
 function removeFor(
   row: ExtensionRow,

package/src/settings/general-settings.ts

@@ -3,10 +3,11 @@
  * Overview — the project's identity: name, description, production URL, favicon, global styles.
  *
  * It has lost a field twice for the same reason. Breakpoints were one of **four** places `$media`
- * could be defined (plan §4.2) and this was the only one that named them; they live in Contexts
- * now, beside the colour schemes and feature queries they share a map with. The platform adapter
- * has moved to Deploy in P6.2, because §2 principle 5 says a definition site is a LEVEL, not a
- * field on some other level's form — and "what this site is" and "where it ships" are two levels.
+ * could be defined and this was the only one that named them; they live in Contexts now, beside the
+ * colour schemes and feature queries they share a map with. The platform adapter has moved to
+ * Deploy, because a definition site is a LEVEL, not a field on some other level's form (the rule
+ * §6.2 applies to rendering contexts) — and "what this site is" and "where it ships" are two
+ * levels.
  *
  * **The markup left too.** The section is the `settings-overview` surface
  * (`surfaces/settings-overview.json`), mounted by `surfaces/settings-overview.ts`; what is here is
@@ -102,16 +103,17 @@ const CLEAR_URL = { url: undefined } as unknown as Partial<ProjectConfig>;
  * What the surface should be showing, from the configuration and the registry as they stand now.
  *
  * The Project Styles button is rendered FROM the `styles.open` record, so it is disabled rather
- * than absent when it cannot act (§12.3) and it cannot drift from the palette row or the gear menu.
- * The record's TITLE, and nothing else off the registry: `disabledReason` would be the §12.3 shape
- * for a control that can be inapplicable, but this one cannot be — `styles.open` is gated on
- * `ctx.project.open` and Overview is a section of the project's own configuration document, so by
- * the time this renders the answer is always yes. Asking anyway would also be a FOCUS read inside a
- * function that was handed a container, which is what `scripts/check-pane-singletons.ts` rule 4
- * forbids: a pane-scoped surface must not report the focused pane's state. A project-level verb
- * happens to read the same in every pane, but the way to be right about that is not to ask. The one
- * thing that can genuinely be missing is the registry itself (bootstrap order, a test), and that is
- * an existence check, not a state read.
+ * than absent when it cannot act (`studio-ui-guidelines.md` §12.3) and it cannot drift from the
+ * palette row or the gear menu. The record's TITLE, and nothing else off the registry:
+ * `disabledReason` would be the `studio-ui-guidelines.md` §12.3 shape for a control that can be
+ * inapplicable, but this one cannot be — `styles.open` is gated on `ctx.project.open` and Overview
+ * is a section of the project's own configuration document, so by the time this renders the answer
+ * is always yes. Asking anyway would also be a FOCUS read inside a function that was handed a
+ * container, which is what `scripts/check-pane-singletons.ts` rule 4 forbids: a pane-scoped surface
+ * must not report the focused pane's state. A project-level verb happens to read the same in every
+ * pane, but the way to be right about that is not to ask. The one thing that can genuinely be
+ * missing is the registry itself (bootstrap order, a test), and that is an existence check, not a
+ * state read.
  */
 function values(container: HTMLElement): OverviewValues {
   const cfg = config();
@@ -188,10 +190,11 @@ function actions(container: HTMLElement): OverviewActions {
     /*
      * Project Styles is the SAME document in a different editor, and `styles.open` is the one place
      * that says so. This used to write `session.ui.canvasMode` here directly — a second
-     * implementation of a capability, §12.5's defect in miniature: the button and the command could
-     * disagree about what "open Project Styles" means, and only one of them was reachable by name.
-     * The mode is still a fact about the TAB, and there is exactly one `project.json` tab, so
-     * `revealTab`'s `focusPane` puts the keyboard on whichever pane holds it.
+     * implementation of a capability, `studio-ui-guidelines.md` §12.5's defect in miniature: the
+     * button and the command could disagree about what "open Project Styles" means, and only one of
+     * them was reachable by name. The mode is still a fact about the TAB, and there is exactly one
+     * `project.json` tab, so `revealTab`'s `focusPane` puts the keyboard on whichever pane holds
+     * it.
      */
     openStyles: () => {
       void activeRegistry()?.run("styles.open");

package/src/settings/preferences-accounts.ts

@@ -10,9 +10,9 @@
  *   blank key into a dialog that did not say that is what a blank key means;
  * - The Cloudflare publish token and account id (`services/cf-settings.ts`) — not clearable at all.
  *
- * Plan §9.3 puts them under Preferences › Accounts, "listed, revocable". This module is that list.
- * It is deliberately UI-free — a record per account with a `revoke` — so the disconnect path is
- * testable without a dialog, and so the same records can back a future Problems entry or an
+ * §15 puts them under Preferences › Accounts, "listed with a Disconnect each". This module is that
+ * list. It is deliberately UI-free — a record per account with a `revoke` — so the disconnect path
+ * is testable without a dialog, and so the same records can back a future Problems entry or an
  * `accounts.revoke` command without being re-derived from a template.
  *
  * **No secret is ever returned.** A record says whether something is stored and what it is for;

package/src/settings/preferences-dialog.ts

@@ -2,13 +2,13 @@
 /**
  * Preferences-dialog.ts — ⌘, the application-preferences surface Studio did not have.
  *
- * Plan §9.3 draws the line this file finally makes real. **Project Settings** configures a project
- * and belongs to the project (breakpoints, definitions, deploy); **Preferences** configures the
+ * §15 draws the line this file finally makes real. **Project Settings** configures a project and
+ * belongs to the project (breakpoints, definitions, deploy); **Preferences** configures the
  * application and follows you between them. Studio shipped only the first, behind a gear in the
  * rail — the slot every other editor spends on the second — and so had nowhere at all to put the
  * chrome theme, the assistant's provider key, the keyboard, or the three credentials it holds.
  *
- * Four sections, and each one closes a hole that was named in the plan:
+ * Four sections, and each one closes a hole the shell redesign named:
  *
  * - **Appearance** — the chrome theme. `shell.theme` and `view.setTheme` already existed; nothing
  *   rendered them, so the only way to change the theme was to run a command by hand.
@@ -19,11 +19,12 @@
  *   this, `clearGithubToken()` had zero callers: signing out of GitHub was not expressible.
  * - **Keyboard** — GENERATED from `commands/reference.ts`'s `shortcutReference()`, the same
  *   projection `docs/studio/interface/shortcuts.md` is built from. The registry is the one place a
- *   chord is declared, so the sheet cannot drift from the app or from the docs. Per §13.5 there is
- *   deliberately no screenshot of it — photographing generated content is a bug. It is searchable
- *   two ways, because there are two questions ("what is the shortcut for X" and "what did I just
- *   press"), and rebindable — as a LAYER over the registry (`settings/preferences-keymap.ts`), so
- *   the sheet stays a projection and the app's own record of a default is never edited.
+ *   chord is declared, so the sheet cannot drift from the app or from the docs. Per CLAUDE.md's
+ *   Screenshot Policy there is deliberately no screenshot of it — photographing generated content
+ *   is a bug. It is searchable two ways, because there are two questions ("what is the shortcut for
+ *   X" and "what did I just press"), and rebindable — as a LAYER over the registry
+ *   (`settings/preferences-keymap.ts`), so the sheet stays a projection and the app's own record of
+ *   a default is never edited.
  *
  * **This module is the FLOW; `surfaces/preferences.json` is what it draws.** Every function below
  * either answers a question about state or changes some, and the answers leave here as strings and

package/src/settings/preferences-sections.ts

@@ -25,7 +25,7 @@ export interface PreferencesSection {
 /**
  * The sections, in sheet order.
  *
- * §9.3 lists six for the finished surface (Editor behaviour and Updates/About are the other two).
+ * §15 lists six for the finished surface (Editor behaviour and Updates/About are the other two).
  * Four are built; a section is added here when it has something to configure, never before — an
  * empty pane is the "declared but unbuilt" state the rail already refuses to render.
  */

package/src/settings/project-sections.ts

@@ -12,7 +12,7 @@
  * error plumbing both still share.
  *
  * **Raw JSON does not open a second editor.** It shows what is on disk and hands the author to the
- * Code editor over the SAME tab — one document, three editors (§9.3), so switching to the text and
+ * Code editor over the SAME tab — one document, three editors (§17.1), so switching to the text and
  * back keeps one undo stack instead of forking two.
  *
  * **The markup left.** Each section is a Jx document over the kit — `surfaces/settings-deploy.json`
@@ -130,7 +130,7 @@ function deployActions(container: HTMLElement): DeployActions {
  * Where the project is built for, and what it is built with.
  *
  * The adapter moved off Overview: Overview says what the site IS, and the adapter is a fact about
- * where it SHIPS — the same split §2 principle 5 applies to Contexts.
+ * where it SHIPS — the same split §6.2 applies to Contexts.
  *
  * The pane calls this again whenever something it cannot see may have changed, and a remount would
  * take the keyboard out of the picker the reader is in — so a standing surface is updated and only

package/src/settings/section-registry.ts

@@ -3,8 +3,8 @@
  *
  * `registerSettingsSection` is a **preserved public contract** (specs/extensions.md §9.1): an
  * extension's `project` class declares a `$studio.settings` block and `settings/extension-sections`
- * turns it into one of these records. P6 moved Project Settings out of a modal and into a document
- * in the pane; the registry did not move with it, because a section is a contribution to
+ * turns it into one of these records. Project Settings moved out of a modal and into a document in
+ * the pane (§17.1); the registry did not move with it, because a section is a contribution to
  * CONFIGURATION, not to a dialog. Splitting it out is what lets the host be replaced without the
  * contribution point being touched.
  *
@@ -15,10 +15,11 @@
  *
  * **What is requested and what is displayed are two variables, and unregistering touches neither.**
  * The modal had one, and its `unregisterSettingsSection` reset it to `"general"` — which is half of
- * the deep-link race P6 exists to close. The contribution sync unregisters stale keys before it
- * registers fresh ones, so a section merely being REFRESHED took the caller's requested section
- * down with it, silently, after the awaited readiness promise had already resolved. Here a request
- * outlives its section going away and is satisfied the moment the key comes back.
+ * the deep-link race `settings.open { section, entry }` (§17.1) exists to close. The contribution
+ * sync unregisters stale keys before it registers fresh ones, so a section merely being REFRESHED
+ * took the caller's requested section down with it, silently, after the awaited readiness promise
+ * had already resolved. Here a request outlives its section going away and is satisfied the moment
+ * the key comes back.
  */
 
 /** A Project Settings section: an inner-nav entry plus a renderer for the content area. */