@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/config/__tests__/default-profile-catalog.test.ts

@@ -228,12 +228,10 @@ describe("resolver integration", () => {
     expect(resolved.model).not.toBe("claude-sonnet-4-6");
   });
 
-  test("a pre-existing user profile cannot shadow an internal profile's call sites", () => {
-    // `latency-optimized` was a legal custom profile name before it was
-    // reserved, so a workspace can already hold one. The user-shadow rule
-    // that lets a user replace a default they can select must not apply to a
-    // name they were never able to select: the voice front model would
-    // silently run on an arbitrary user model.
+  test("a user profile cannot shadow latency-optimized", () => {
+    // `latency-optimized` is code-owned: it fronts every live-voice turn, so
+    // a same-named workspace entry never governs what it resolves to. The
+    // entry stays on disk and stays a valid `activeProfile` reference.
     const llm = LLMSchema.parse({
       profiles: {
         "latency-optimized": {
@@ -246,17 +244,16 @@ describe("resolver integration", () => {
         },
       },
     });
-    const body = CODE_DEFAULT_PROFILE_ENTRIES["latency-optimized"];
+    const body = CODE_DEFAULT_PROFILE_ENTRIES["latency-optimized"]!;
     for (const callSite of ["voiceFrontDoor", "voiceFrontDecision"] as const) {
       const resolved = resolveCallSiteConfig(callSite, llm);
       expect(resolved.model).toBe(body.model as string);
       expect(resolved.model).not.toBe("claude-opus-4-6");
       expect(String(resolved.provider)).toBe("vellum");
     }
-    // The entry itself is untouched — still on disk, still listed, and still
-    // a valid `activeProfile` reference for the user who created it.
+    // Listing follows resolution: the catalog body is what surfaces.
     expect(getEffectiveProfiles(llm.profiles)["latency-optimized"]?.model).toBe(
-      "claude-opus-4-6",
+      body.model,
     );
     expect(() =>
       LLMSchema.parse({

package/src/config/__tests__/deployment-context-defaults.test.ts

@@ -52,6 +52,7 @@ afterAll(() => {
 });
 
 import { setStorePathForTesting } from "../../__tests__/encrypted-store-test-helpers.js";
+import { enableMemoryV3LiveForNewWorkspacesMigration } from "../../workspace/migrations/105-enable-memory-v3-live-for-new-workspaces.js";
 import { invalidateConfigCache, loadConfig } from "../loader.js";
 
 // ---------------------------------------------------------------------------
@@ -221,7 +222,7 @@ describe("deployment-context embedding-provider default (via loadConfig)", () =>
     expect(config.memory.qdrant.vectorSize).toBe(384);
   });
 
-  test("first launch seeds memory.v3 with only `live` — tuning knobs resolve from the schema, not disk", () => {
+  test("first launch persists nothing under memory.v3, not even `live`", () => {
     if (existsSync(CONFIG_PATH)) {
       rmSync(CONFIG_PATH, { force: true });
     }
@@ -233,16 +234,37 @@ describe("deployment-context embedding-provider default (via loadConfig)", () =>
     expect(config.memory.v3.gate.denseThreshold).toBe(0.66);
     expect(config.memory.v3.needleK).toBe(100);
 
-    // Persisted config.json carries ONLY `live` under memory.v3 — no tuning knob
-    // is frozen to disk, so a shipped schema-default change reaches this
-    // assistant on its next load (mirrors the embedding-provider strip above).
+    // Nothing under memory.v3 is frozen to disk. Tuning knobs stay absent so a
+    // shipped schema-default change reaches this assistant on its next load
+    // (mirrors the embedding-provider strip above), and `live` stays absent so
+    // migration 105 can record the initial choice: 105 bails on any value
+    // already present, and this seed runs before workspace migrations.
     const raw = readConfig();
     const v3Raw = ((raw.memory as Record<string, unknown>).v3 ?? {}) as Record<
       string,
       unknown
     >;
-    expect(Object.keys(v3Raw)).toEqual(["live"]);
+    expect(Object.keys(v3Raw)).toEqual([]);
     expect(v3Raw.gate).toBeUndefined();
     expect(v3Raw.needleK).toBeUndefined();
   });
+
+  test("migration 105 turns v3 on for a workspace this seed just created", () => {
+    if (existsSync(CONFIG_PATH)) {
+      rmSync(CONFIG_PATH, { force: true });
+    }
+    delete process.env.IS_PLATFORM;
+
+    loadConfig();
+    enableMemoryV3LiveForNewWorkspacesMigration.run(WORKSPACE_DIR, {
+      isNewWorkspace: true,
+    });
+
+    const raw = readConfig();
+    const v3Raw = ((raw.memory as Record<string, unknown>).v3 ?? {}) as Record<
+      string,
+      unknown
+    >;
+    expect(v3Raw.live).toBe(true);
+  });
 });

package/src/config/assistant-feature-flags.ts

@@ -313,10 +313,15 @@ export async function refreshOverridesFromGateway(): Promise<boolean> {
  *      registry)
  *   2. Registry `defaultEnabled` (for declared assistant-scope keys)
  *   3. `false` (for undeclared keys with no override)
+ *
+ * Resolution reads only the override and registry caches, so `_config` is
+ * accepted for the convenience of call sites that already hold one and never
+ * consulted. Callers without a config in hand should omit it rather than load
+ * one for this.
  */
 export function getAssistantFeatureFlagValue(
   key: string,
-  _config: AssistantConfig,
+  _config?: AssistantConfig,
 ): boolean | string {
   const defaults = loadDefaultsRegistry();
   const declared = defaults[key];
@@ -343,7 +348,7 @@ export function getAssistantFeatureFlagValue(
  */
 export function isAssistantFeatureFlagEnabled(
   key: string,
-  config: AssistantConfig,
+  config?: AssistantConfig,
 ): boolean {
   return !!getAssistantFeatureFlagValue(key, config);
 }

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: app-builder
-description: Build and edit small, personal visual tools and artifacts — dashboards, trackers, calculators, data visualizations, charts, simple landing pages, and slide decks the user wants for THEMSELVES. This is the right skill whenever the user asks to "visualize this," "make a chart," or "build an artifact" for their own use, or to edit an app they already built here. Do NOT reach for a ui_show dynamic_page to fake an artifact — build a real persistent app here. NOT for complex, multi-user, or shippable products — those go to a real project folder with a coding agent (see Scope below).
+description: Build and edit small, personal visual tools and artifacts — dashboards, trackers, calculators, data visualizations, charts, simple landing pages, and slide decks the user wants for THEMSELVES. This is the right skill whenever the user asks to "visualize this," "make a chart," or "build an artifact" for their own use, or to edit an app they already built here. Do NOT reach for a ui_show dynamic_page to fake an artifact — build a real persistent app here. A one-off diagram, chart, or explainer that just accompanies an answer belongs to the visualize skill (ui_show visual), not an app. NOT for complex, multi-user, or shippable products — those go to a real project folder with a coding agent (see Scope below).
 metadata:
   emoji: "🛠️"
   vellum:
@@ -9,10 +9,11 @@ metadata:
     includes: ["frontend-design"]
     activation-hints:
       - "User asks to build a dashboard, tracker, calculator, data visualization, chart, simple landing page, or slide deck for their own use"
-      - "User asks to visualize something, make a chart, or build an artifact — build a real persistent app here, never a ui_show dynamic_page"
+      - "User asks to build an artifact, tool, or app they will keep using — build a real persistent app here, never a ui_show dynamic_page"
       - "User asks to change, fix, restyle, or extend an app they already built in the sandbox — open it and iterate"
       - "User asks to open, show, or pull up an app they already built — this skill provides app_list + app_open even when nothing needs editing"
     avoid-when:
+      - "An inline diagram, chart, or explainer that accompanies an answer and will not be reopened — use the visualize skill"
       - "User wants a complex app, a multi-user app, or something to publish, deploy, or hand off to others — route to a local project folder + coding agent instead (see Scope)"
 ---
 

package/src/config/bundled-skills/subagent/SKILL.md

@@ -56,7 +56,9 @@ Orient yourself first (read the relevant files, understand the task), then consu
 - **When you get stuck or are weighing a change in direction.**
 - **Once before you declare the task done.**
 
-The consult is synchronous and read-only: spawning an `advisor` subagent BLOCKS until it returns guidance. It runs on a stronger model and inherits your full context, so it sees the task, your tool calls, and their results without you re-explaining. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim — and say so when you do.
+The consult is synchronous and read-only: spawning an `advisor` subagent BLOCKS until it returns guidance. It runs on a stronger model and inherits your full context, so it sees the task, your tool calls, and their results without you re-explaining. It also receives a snapshot of your environment (the tools available to you this turn, the full skill catalog, and your workspace) so its guidance can point you at existing platform capabilities by name. Give its guidance serious weight; only override it when primary-source evidence contradicts a specific claim, and say so when you do.
+
+Beyond that snapshot, the advisor sees only what is in this conversation. It cannot read files, other conversations, or external systems on its own. If you want it to weigh specific evidence (a file's contents, a command's output, results gathered elsewhere), surface that evidence in the conversation or the spawn objective before consulting.
 
 Spawn the advisor **alone** — do NOT batch the consult in the same turn as other tool calls (especially file edits, shell commands, or anything destructive or expensive). Tool calls you issue in the same turn run concurrently with the consult, so they would execute before you see its guidance. Consult the advisor by itself, read its guidance, then act.
 

package/src/config/bundled-skills/subagent/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "subagent_spawn",
-      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Can use scoped roles (researcher, coder, planner).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. Defaults to general role (the 'advisor' role is the exception — it is honored as a fork). Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it inherits your full context, has no tools, and BLOCKS until it returns focused strategic guidance in a single response.",
+      "description": "Spawn an independent subagent to work on a task in parallel. The subagent runs autonomously and its results are reported back when complete.\n\nTwo modes:\n- **Regular sub-agent** (fork: false or omitted): Gets only the objective + context fields. Use for self-contained tasks with clear objectives. Can use scoped roles (researcher, coder, planner).\n- **Fork** (fork: true): Inherits full parent context (messages, system prompt, memory). Shares KV cache for near-free context inheritance. Use when the task benefits from knowing what you've been discussing. Defaults to general role (the 'advisor' role is the exception: it is honored as a fork). Results are internal by default (send_result_to_user: false). Read with last_n: 1 to get only the final synthesis.\n\nDecision heuristic: Does the task need to know what we've been talking about? Fork. Is it self-contained? Regular sub-agent.\n\nThe 'advisor' role is a synchronous, read-only \"consult a stronger advisor\" mode: it inherits your full context plus a snapshot of your environment (available tools, skill catalog, workspace), has no tools of its own, and BLOCKS until it returns focused strategic guidance in a single response.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -19,7 +19,7 @@
           },
           "context": {
             "type": "string",
-            "description": "Optional additional context to pass to the subagent. Ignored when fork is true — forks inherit the parent's full context."
+            "description": "Optional additional context to pass to the subagent. Ignored when fork is true; forks inherit the parent's full context."
           },
           "fork": {
             "type": "boolean",
@@ -39,7 +39,7 @@
               "investigator",
               "advisor"
             ],
-            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'investigator': root-cause analysis — debugging, log forensics, tracing behavior across many files; uses read-only search/read tools (code_search, file_read, file_list) with no shell access and returns a compact root-cause report. 'advisor': synchronous, read-only \"consult a stronger advisor\" — inherits full context, has no tools, and blocks until it returns focused strategic guidance. 'general': full access (default). The read-only roles (researcher, planner, investigator, advisor) cannot persist output — use 'coder' or 'general' for any objective that must write files or run commands, or a read-only subagent will finish without producing anything. Non-advisor roles are ignored when fork: true (forks default to general); the advisor role is honored even as a fork."
+            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'investigator': root-cause analysis: debugging, log forensics, tracing behavior across many files; uses read-only search/read tools (code_search, file_read, file_list) with no shell access and returns a compact root-cause report. 'advisor': synchronous, read-only \"consult a stronger advisor\": inherits full context plus a snapshot of your environment (available tools, skill catalog, workspace), has no tools of its own, and blocks until it returns focused strategic guidance. 'general': full access (default). The read-only roles (researcher, planner, investigator, advisor) cannot persist output; use 'coder' or 'general' for any objective that must write files or run commands, or a read-only subagent will finish without producing anything. Non-advisor roles are ignored when fork: true (forks default to general); the advisor role is honored even as a fork."
           },
           "inference_profile": {
             "type": "string",

package/src/config/bundled-skills/visualize/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: visualize
+description: Render a polished visual inline in the chat as part of your answer — a diagram, a chart, an interactive explainer, or a UI mockup. Load it proactively whenever an explanation would land better as a picture than as prose. Do not wait to be asked.
+metadata:
+  emoji: "📊"
+  vellum:
+    display-name: "Visualize"
+    category: "content"
+    always-candidate: true
+    activation-hints:
+      - "Explaining how something works, or how the parts of a system relate to each other"
+      - "Comparing options, tradeoffs, or before and after states side by side"
+      - "Walking through numbers, rates, growth, or a distribution the user should see"
+      - "Teaching a concept step by step, where the user should be able to move through it"
+      - "Answering how would you explain this, or helping the user teach or onboard someone else"
+    avoid-when:
+      - "Simple factual answers where a sentence or a markdown list already says it"
+      - "Durable apps or tools the user will reopen and keep using — use the app-builder skill"
+---
+
+You are authoring a self-contained HTML fragment that renders inline in the chat transcript, directly beneath the paragraph you are writing. It renders in a sandboxed frame sized to your content, with the host's design tokens injected, so it looks native in light and dark mode.
+
+## Invocation
+
+```
+ui_show { surface_type: "visual", data: { html: "<fragment>", height: 320 } }
+```
+
+- `height` is a rough pixel estimate (80 to 1400); the host measures and corrects after first paint.
+- One visual per call. To change one already shown, `ui_dismiss` its `surface_id` and show a new one.
+- Prose goes in your reply, the visual goes in the tool: no titles, intros, or captions inside the fragment, and never describe in prose what the visual already shows.
+- If ui_show returns an error, read it, fix the arguments, and call again. Every rejection is fixable in the next call; never debug via shell or files, and never narrate retries.
+
+A visual is part of one answer. Durable things the user reopens (a dashboard, a tracker, a calculator they keep) are apps: use the `app-builder` skill.
+
+## Design instincts
+
+- Seamless and flat: no gradients, shadows, glow, or texture. Flat fills, hairline borders.
+- Compact and honest: show the essential, explain the rest in prose; every number on screen is one you actually have.
+- Pick the lightest form that carries the idea, and invent freely: a bespoke drawing that fits this answer beats a stock layout. Interaction has to earn its place; steppers are for stages that genuinely follow one another, tabs are not a default. Vary layout between visuals in one conversation.
+- Route diagrams on the verb: "walk me through" wants a flowchart; "how is it organised" wants containment boxes; "how does it actually work" wants the mechanism drawn as an intuition, not a safer flowchart.
+
+## Sandbox constraints (hard)
+
+- No network: no script src, stylesheets, @import, remote images, web fonts, fetch, or CDN libraries. Charts and diagrams are hand-drawn inline SVG; images are inline SVG only.
+- Fragment only: no DOCTYPE, html, head, or body. No HTML comments, no emoji.
+- Hard cap 24000 characters; aim well under 8000. Too big to fit is too big to render. Split rich subjects into two visuals with prose between.
+- No position fixed or sticky, no nested scrollbars: the frame auto-sizes from in-flow content.
+- No localStorage, sessionStorage, or cookies. Hold state in JS variables.
+
+## Fragment structure
+
+Order: a visually hidden `<h2 class="sr-only">` one-sentence summary, a short style block, the markup, one script element last. Always quote every attribute value (`class="row-box hit"`, never `class=row-box hit`). Include verbatim when using sr-only:
+
+```css
+.sr-only{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
+```
+
+Usable width is about 660px; the host insets content 6px vertically and 10px from the sides. Rows holding controls carry their own padding of at least 8px on the crowded sides. Keep the outer background transparent.
+
+## Design tokens
+
+The COMPLETE list of injected CSS variables. Any other var() name is rejected unless your own style block declares it. Never hardcode a colour: hex, rgb(), hsl(), and oklch() literals are rejected everywhere, including SVG fill and stroke; only `transparent` and `currentColor` are allowed.
+
+Semantic tokens flip automatically between light and dark. Use them for every surface, body text, border, and status colour:
+
+- Surfaces: --surface-base (page), --surface-lift (card), --surface-overlay, --surface-sunken (recessed tile), --surface-hover, --surface-active.
+- Text, strongest to faintest: --content-emphasised, --content-strong, --content-default (body), --content-secondary (labels and any text under 14px), --content-tertiary (14px and up only), --content-quiet, --content-faint, --content-disabled, --content-inset (on inverted fills). Text at 11 to 13px always takes --content-secondary or stronger.
+- Borders: --border-base (hairline), --border-subtle, --border-element (visible control edge), --border-hover, --border-active, --border-disabled.
+- Status pairs: --system-positive-strong/-weak, --system-negative-strong/-weak (and --system-negative-hover), --system-mid-strong/-weak, --system-info-strong/-weak.
+- Type: --font-sans (default), --font-mono (identifiers, code, tabular numbers only), --font-serif (editorial pull-quotes only).
+- Radius: --radius-xs 2, --radius-sm 4, --radius-md 8, --radius-lg 12, --radius-xl 16, --radius-xxl 20, --radius-pill 999.
+
+Palette ramps are for categorical encoding only, never page surfaces or body text: --color-moss-50..950 and --color-stone-50..950 (neutrals), --color-forest-100..950, --color-emerald-100..950, --color-danger-100..950, --color-amber-100..950. Stops run light (100) to dark (950). Author every ramp use against the light theme as a matched triple from ONE ramp, and the host mirrors it in dark mode as a unit:
+
+```css
+background: var(--color-forest-100);
+border-color: var(--color-forest-600);
+color: var(--color-forest-900);
+```
+
+The two rules the mirror imposes: text on a tinted fill takes the same ramp's 900 (secondary 800), never a --content-* token; and text sitting on the page (SVG labels, axis ticks, anything outside a tinted fill) takes --content-*, never a bare ramp stop. A dark ramp stop used as text is only valid where its light counterpart is painted right there on the same element or enclosing group.
+
+Colour discipline: colour encodes category, not sequence. At most two accent ramps per visual plus a neutral, one accent moment per visual, system tokens only for genuine success/failure/warning/info, and a one-line legend whenever colour carries meaning. Never distinguish categories by colour alone; pair with a label or shape.
+
+## Typography and spacing
+
+- Sizes: 18px section label, 15px item title, 14px body (default), 12px secondary, 11px floor. Weights 400 and 500 only. Sentence case everywhere.
+- Line-height 1.6 for prose; vertical rhythm in rem (0.5, 1, 1.5, 2); internal gaps in px (8, 12, 16).
+- Card: --surface-lift, 1px --border-base, --radius-lg, padding 1rem 1.25rem. Tile: --surface-sunken with a 1px --border-subtle (it dissolves into the light page without the hairline), --radius-md.
+- Buttons and pills take --radius-pill or --radius-sm, one choice per visual. No box-shadow except a focus ring. Size height to content honestly; no empty bands.
+- Round every displayed number (Math.round, toFixed, toLocaleString); give range inputs an explicit step so the control emits round values.
+
+## Complexity budget (hard)
+
+At most 4 items across one row, 5 diagram nodes, 2 ramps, 5-word subtitles. Past any of these, split into two visuals with prose between. Over roughly 8000 characters means you are building too much.
+
+## SVG mechanics
+
+Anything with nodes and arrows is ONE inline SVG with `width="100%"` and `viewBox="0 0 680 H"`, never a row of HTML divs (divs clip silently at the frame edge; SVG scales). Skeleton:
+
+```html
+<svg width="100%" viewBox="0 0 680 320" role="img">
+  <title>One sentence.</title>
+  <desc>What the boxes and arrows are.</desc>
+  <style>
+    text{font-family:var(--font-sans)}
+    .th{font-size:14px;font-weight:500;fill:var(--content-strong)}
+    .ts{font-size:12px;fill:var(--content-secondary)}
+    .box rect{fill:var(--surface-lift);stroke:var(--border-element)}
+    .arr{stroke:var(--border-element);fill:none;marker-end:url(#a)}
+  </style>
+  <defs><marker id="a" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round"/></marker></defs>
+</svg>
+```
+
+- Keep viewBox width 680 (one unit = one CSS pixel). Lay nodes out on the grid below instead of computing positions: it is already sized so nothing overlaps and nothing clips, so there is no spacing arithmetic to do, and the validator checks bounds for you on submit.
+  - Node width 140, height 44 (single line, text at y + 22) or 56 (title at y + 20, subtitle at y + 38).
+  - 4 nodes across: x = 30, 200, 370, 540. 3 across: x = 60, 270, 480. 2 across: x = 120, 420.
+  - Rows at y = 20, 110, 200, 290. viewBox height = last row's y + 80.
+  - Horizontal arrows run between node edges at the node's mid height. Arrow labels fit only at 2 or 3 nodes across (12 above the arrow, centred on the gap); at 4 across the gaps are 30px, nothing fits, so leave those arrows unlabeled and carry the verbs in your prose.
+  - Containers wrap a row group with 16 of margin; free-form shapes for illustrative drawings stay inside one grid cell or one row band.
+- Every coordinate is an absolute viewBox coordinate. Never use the transform attribute: translated groups mix local and absolute positions and labels land outside their boxes (the validator rejects transforms). A node is a rect plus its text at the rect's own position:
+
+```html
+<g class="n-forest">
+  <rect x="200" y="110" width="140" height="56" rx="8" />
+  <text class="th" x="270" y="130" text-anchor="middle" dominant-baseline="central">Resolver</text>
+  <text class="ts" x="270" y="148" text-anchor="middle" dominant-baseline="central">checks cache</text>
+</g>
+```
+
+- Node titles fit at about 13 characters; subtitles at 5 words. Longer means shorten the words, never the spacing. SVG text never wraps; no rotated text.
+- Background fills scope to the shape, never the group: `.note rect{fill:var(--surface-sunken)}`, not `.note{fill:...}`. fill inherits to text, so a group-level surface fill silently repaints the labels inside it in the background colour.
+- Every text element needs `dominant-baseline="central"` with y at the centre of its slot. Two sizes only: 14px titles, 12px everything else.
+- Any path or polyline used as a line carries `fill="none"` or it renders as a black blob. Strokes: 1px structure, 2px chart line. One arrowhead marker is the whole of defs; no filters, no gradients.
+- A coloured node applies its matched ramp triple as one class on the group containing rect and text together.
+- Charts: 2px lines, no dot per datum unless points are the story; bars with rx 2 and a 4px gap minimum; gridlines 1px --border-subtle; label axes directly rather than with a legend when there are two series or fewer.
+
+## Interaction mechanics
+
+One state object, one render() function, handlers mutate state and call render(); call render() once at the end of the script so the first paint is populated. Controls are unstyled by the sandbox; style them yourself:
+
+```css
+.btn{padding:6px 12px;border-radius:var(--radius-md);border:1px solid var(--border-element);background:transparent;font:400 13px var(--font-sans);color:var(--content-default);cursor:pointer}
+.btn:hover{background:var(--surface-hover)}
+```
+
+- Selected state lives on aria-pressed or aria-selected and the CSS keys off that attribute. Every control is a real button or input, never a clickable div; glyph-only controls get aria-label.
+- Range inputs: min, max, value, explicit step; recompute on `input`; put the live readout beside the control with a min-width so digits do not jitter.
+- A static table is better as markdown in your reply; a table earns a fragment only when rows react to interaction. Use table-layout:fixed and --font-mono at 12px.
+
+A global `sendPrompt(text)` sends text to the chat as though the user typed it, for follow-ups that need you to think ("Compare last quarter"). Give such controls a trailing arrow glyph (&#8599;). Filtering, sorting, and recomputing happen in local JS instead, instantly. sendPrompt fires only from a real user click, never on load or a timer.
+
+## Accessibility
+
+HTML fragments open with the sr-only h2; a lone-SVG fragment instead carries role="img" with title and desc as its first children. Toggle state never lives on colour alone.
+
+## Now compose
+
+Everything you need is above, and none of it needs verifying in advance: the grid already spaces things, and the validator checks tokens, contrast, and bounds when you submit, telling you exactly what to change if anything is off. Pre-checking coordinates, estimating label widths, or reviewing markup in your head duplicates work the validator does in milliseconds.
+
+Your next action is the ui_show call itself. Your entire reasoning budget for this visual is a few sentences: name the form, name the grid slots you will use, done. Markup written in reasoning does not render, does not count as showing the user anything, and has to be written all over again inside the call, so a draft there spends the entire budget and produces nothing on screen. Compose the fragment for the first time inside `data.html` as you write the call. If you notice yourself reasoning about the fragment's contents, stop and start the call.

package/src/config/call-site-defaults.ts

@@ -123,10 +123,11 @@ export const CALL_SITE_DEFAULTS: Record<LLMCallSite, CallSiteDefaultConfig> = {
   },
   // Endpoint decisions gate live-voice turn-end latency, and `cost-optimized`'s
   // upstream cannot fit any usable decision budget (~1s+ per forced tool call).
-  // `latency-optimized` is the internal latency-class profile (see
+  // `latency-optimized` is the latency-class profile (see
   // default-profile-catalog.ts): managed installs get the pinned latency model,
   // BYOK installs resolve their own provider's latency model through the intent
-  // table rather than a model id they may hold no credential for.
+  // table rather than a model id they may hold no credential for. The profile
+  // is user-facing ("Speed"), so a user edit to it moves this call site too.
   voiceFrontDecision: {
     profile: "latency-optimized",
     effort: "low",