From efdce199839f6b8971ad5d8065d5d2ec46aad65b Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 18 Jun 2026 22:12:05 -0700
Subject: [PATCH 1/5] docs: plan for demo welcome-suggestion clarity + palette
 validation

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../plans/2026-06-19-demo-welcome-clarity.md  | 117 ++++++++++++++++++
 1 file changed, 117 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-19-demo-welcome-clarity.md

diff --git a/docs/superpowers/plans/2026-06-19-demo-welcome-clarity.md b/docs/superpowers/plans/2026-06-19-demo-welcome-clarity.md
new file mode 100644
index 00000000..736e682c
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-19-demo-welcome-clarity.md
@@ -0,0 +1,117 @@
+# Demo Welcome-Suggestion Clarity + Palette Validation — Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`).
+
+**Goal:** Make the demos' welcome suggestions self-explanatory to a developer (clearer, inferrable titles + a short description per suggestion, surfaced as a multiline dropdown subtitle and a hover tooltip on chips), repo-wide; and stop stale `localStorage` palette values from breaking the demos on a fresh checkout (validate-on-read).
+
+**Design (settled via audit + decisions):**
+- **Lib:** `ChatSelectOption` gains an optional `description?: string`; `chat-select` renders it as a subtitle line (multiline option). `chat-welcome-suggestion` (the chip) gains an optional `description?` input rendered as a `title` + `aria-description` **hover/focus tooltip** (no visible subtitle — keeps chips compact). One `description` field serves both surfaces.
+- **Copy:** Every welcome suggestion across the 13 apps gets a developer-inferrable title + a 1-line description. Guidelines below.
+- **Persistence (Item B):** the two demo palette services validate each read against the current allowed value-set; an unknown/stale value falls back to the default (no versioning).
+
+**Tech Stack:** Angular 21 (signals, `input`), vitest, Nx. No backcompat constraint.
+
+**Audit inventory (the source of truth for which apps/suggestions exist):** see the AP1 repo-wide audit — 13 apps. `examples/chat` (17 suggestions) + `examples/ag-ui` (7) use a featured-chip + `chat-select` "More prompts" dropdown; 11 cockpit apps use plain `chat-welcome-suggestion` chips (1–2 each).
+
+---
+
+## Copy guidelines (apply to every suggestion)
+
+- **Title:** a short, developer-inferrable noun/verb phrase that names the *capability or pattern* being shown (not jargon). Sentence case. Examples: "Consent-gated clear" → **"Clear a day (asks first)"**; "Human approval" → **"Approve before a refund"**; "Demo: render a contact form" → **"Generative UI: contact form"**.
+- **Description:** one concise sentence (≤ ~90 chars) saying what the prompt exercises / what the user will see. Example: "Streams a form component the model fills in, then you submit it back."
+- **Value (the prompt):** keep existing prompts unless a title change makes a small wording tweak natural; do **not** alter prompts that e2e specs assert on (see Verify).
+- Keep capitalization/style consistent across apps.
+
+---
+
+## Task 1: Lib — `ChatSelectOption.description` + multiline option + chip tooltip
+
+**Files:**
+- `libs/chat/src/lib/primitives/chat-select/chat-select.component.ts`
+- `libs/chat/src/lib/styles/chat-select.styles.ts`
+- `libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.ts`
+- specs for both components
+
+- [ ] **Step 1 (chat-select):** add `description?: string` to `ChatSelectOption`. Update the option `<button>` template to render a label line + (when present) a description subtitle line:
+```html
+<button ... class="chat-select__option" ...>
+  <span class="chat-select__option-label">{{ opt.label }}</span>
+  @if (opt.description) {
+    <span class="chat-select__option-desc">{{ opt.description }}</span>
+  }
+</button>
+```
+Update `chat-select.styles.ts`: make `.chat-select__option` a vertical flex (`display:flex; flex-direction:column; align-items:flex-start`), add `.chat-select__option-desc` (smaller, `--ngaf-chat-text-muted`/the muted token used elsewhere, `white-space:normal`, `line-height:1.3`, small margin-top). Keep label-only options rendering unchanged (no desc → no subtitle).
+
+- [ ] **Step 2 (chat-welcome-suggestion):** add `readonly description = input<string>()`. In the template, bind it as a tooltip on the button: `[attr.title]="description() || null"` and `[attr.aria-description]="description() || null"`. Do NOT add a visible subtitle (keep the chip compact). Keep `label`/`value`/icon slot unchanged.
+
+- [ ] **Step 3:** Update the existing component specs (`chat-select.component.spec.ts`, `chat-welcome-suggestion.component.spec.ts`): assert an option with a `description` renders the `.chat-select__option-desc` text; assert a chip with `description` sets `title`/`aria-description`; assert absence renders neither (no regression).
+
+- [ ] **Step 4:** `npx nx run-many -t test lint build --projects=chat --skip-nx-cache` — green. Commit:
+```bash
+git add libs/chat/src/lib/primitives/chat-select libs/chat/src/lib/primitives/chat-welcome libs/chat/src/lib/styles/chat-select.styles.ts
+git commit -m "feat(chat): optional description on ChatSelectOption (multiline) + chat-welcome-suggestion (tooltip)"
+```
+
+---
+
+## Task 2: examples/* — improved titles + descriptions + wire description through
+
+**Files:**
+- `examples/chat/angular/src/app/modes/welcome-suggestions.ts` + `welcome-suggestions.component.ts`
+- `examples/ag-ui/angular/src/app/modes/welcome-suggestions.ts` + `welcome-suggestions.component.ts`
+
+- [ ] **Step 1:** Extend the `WelcomeSuggestion` interface in each app to `{ label: string; value: string; description: string }`. Rewrite every suggestion's `label` (per the copy guidelines) and add a `description`. Do NOT change `value` prompts that e2e relies on (the examples/chat `url-routing`/`send-receive` specs and examples/ag-ui specs may assert on sent prompts — check `e2e/*.spec.ts` first; keep those prompt strings intact).
+- [ ] **Step 2:** Wire `description` through: in `welcome-suggestions.component.ts`, pass `[description]` to the featured `chat-welcome-suggestion`, and include `description` in the `moreOptions` mapping to `ChatSelectOption[]` (so the dropdown is multiline).
+- [ ] **Step 3:** Build both apps: `npx nx run-many -t build --projects=examples-chat-angular,examples-ag-ui-angular --skip-nx-cache` — green.
+- [ ] **Step 4:** Commit:
+```bash
+git add examples/chat/angular/src/app/modes examples/ag-ui/angular/src/app/modes
+git commit -m "feat(examples): clearer welcome-suggestion titles + descriptions (multiline dropdown)"
+```
+
+---
+
+## Task 3: cockpit/* — improved titles + descriptions (chip tooltips)
+
+**Files (11 apps, inline suggestion arrays in each `*.component.ts`):** tool-calls, subagents, a2ui, interrupts, generative-ui (chat); streaming, interrupts, persistence (langgraph); json-render, a2ui, interrupts (ag-ui). (See the AP1 inventory for each file + current suggestions.)
+
+- [ ] **Step 1:** In each cockpit app's component, the inline suggestions array gains a `description` per item and improved `label`s (copy guidelines). Pass `[description]` to each `chat-welcome-suggestion` chip in the template. Where two apps mirror each other (e.g. chat/interrupts ≈ ag-ui/interrupts), use identical copy.
+- [ ] **Step 2:** Build the affected cockpit apps (a representative `nx run-many -t build` across the 11, or `--all` if faster) — green.
+- [ ] **Step 3:** Commit:
+```bash
+git add cockpit
+git commit -m "feat(cockpit): clearer welcome-suggestion titles + descriptions (chip tooltips)"
+```
+
+---
+
+## Task 4: Item B — validate-on-read in the palette services
+
+**Files:**
+- `examples/chat/angular/src/app/shell/palette-persistence.service.ts`
+- `examples/ag-ui/angular/src/app/shell/palette-persistence.service.ts`
+
+- [ ] **Step 1:** Each palette service exposes typed reads (model/effort/genUiMode/theme/colorScheme/sidenavMode/etc.). Add a validation layer: for each enum-like field, define the **current allowed value-set** (mirror the dropdown option values the shell already declares — import/reuse them rather than duplicating where possible) and, on read, return the stored value only if it's in the allowed set; otherwise return `undefined` (so the caller's `?? default` kicks in). Non-enum fields (e.g. `selectedProjectId`, free strings, booleans) pass through unchanged. This makes a stale/renamed value (e.g. an old `effort`) fall back to the default instead of loading an invalid selection.
+- [ ] **Step 2:** Add/extend the palette service spec: a stored value outside the allowed set reads back as `undefined` (→ default); a valid value reads back unchanged.
+- [ ] **Step 3:** Build both apps + run the chat/ag-ui shell specs. Commit:
+```bash
+git add examples/chat/angular/src/app/shell/palette-persistence.service.ts examples/ag-ui/angular/src/app/shell/palette-persistence.service.ts examples/*/angular/src/app/shell/*.spec.ts
+git commit -m "fix(examples): validate palette localStorage reads (stale value → default)"
+```
+
+---
+
+## Task 5: Verify + PR
+
+- [ ] **Step 1:** `npx nx run-many -t test lint build --projects=chat --skip-nx-cache`; build all affected example + cockpit apps; run the `examples/chat` + `examples/ag-ui` e2e (free ports first) to confirm no welcome-suggestion/prompt assertion broke. If an e2e asserts a label/prompt that changed, reconcile (prefer keeping the prompt; update the spec only if the label is what's asserted and the new label is correct).
+- [ ] **Step 2:** Final review (correctness of the lib option/tooltip change; copy quality + consistency; the palette validation doesn't drop valid values; no e2e regressions).
+- [ ] **Step 3:** Regenerate api-docs (chat gained a `description` on `ChatSelectOption` + chip input); commit if changed. Open PR, arm auto-merge, self-healing watcher.
+
+---
+
+## Self-Review
+- Coverage: lib option+tooltip (T1); examples copy+wiring (T2); cockpit copy (T3); palette validation (T4); verify+PR (T5). ✓
+- Consistency: one `description` field powers both the dropdown subtitle and the chip tooltip; copy guidelines applied uniformly.
+- Risk: changing welcome-suggestion `value` prompts could break e2e — explicitly guarded (keep prompts; check specs first). Palette validation must not drop valid values — covered by the spec.
+- Conflict-safety vs #685: touches `libs/chat` primitives + example/cockpit apps; does NOT touch `agent.ts`/`public-api` agent exports, so no overlap with the #685 DX branch.

From 99b01e3061c30c28ac915d46382e3688778553dd Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 18 Jun 2026 22:23:31 -0700
Subject: [PATCH 2/5] feat(chat): optional description on ChatSelectOption
 (multiline) + chat-welcome-suggestion (tooltip)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../chat-select/chat-select.component.spec.ts      | 13 +++++++++++++
 .../chat-select/chat-select.component.ts           |  6 +++++-
 .../chat-welcome-suggestion.component.spec.ts      | 14 ++++++++++++++
 .../chat-welcome-suggestion.component.ts           | 10 +++++++++-
 libs/chat/src/lib/styles/chat-select.styles.ts     | 11 ++++++++++-
 5 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/libs/chat/src/lib/primitives/chat-select/chat-select.component.spec.ts b/libs/chat/src/lib/primitives/chat-select/chat-select.component.spec.ts
index 2f017e29..f9e43e49 100644
--- a/libs/chat/src/lib/primitives/chat-select/chat-select.component.spec.ts
+++ b/libs/chat/src/lib/primitives/chat-select/chat-select.component.spec.ts
@@ -63,6 +63,19 @@ describe('ChatSelectComponent', () => {
     expect(opts.length).toBe(3);
   });
 
+  it('renders an option description as a subtitle, and omits it when absent', () => {
+    setSignalInput(fixture, 'options', [
+      { value: 'a', label: 'Alpha', description: 'The first letter' },
+      { value: 'b', label: 'Bravo' },
+    ] as readonly ChatSelectOption[]);
+    fixture.detectChanges();
+    host.querySelector<HTMLButtonElement>('.chat-select__trigger')!.click();
+    fixture.detectChanges();
+    const opts = host.querySelectorAll('.chat-select__option');
+    expect(opts[0].querySelector('.chat-select__option-desc')?.textContent).toContain('The first letter');
+    expect(opts[1].querySelector('.chat-select__option-desc')).toBeNull();
+  });
+
   it('emits valueChange and closes the menu on option click', () => {
     let emitted: string | undefined;
     fixture.componentInstance.value.subscribe((v) => { emitted = v; });
diff --git a/libs/chat/src/lib/primitives/chat-select/chat-select.component.ts b/libs/chat/src/lib/primitives/chat-select/chat-select.component.ts
index e012f006..d41e0394 100644
--- a/libs/chat/src/lib/primitives/chat-select/chat-select.component.ts
+++ b/libs/chat/src/lib/primitives/chat-select/chat-select.component.ts
@@ -19,6 +19,7 @@ import { CHAT_SELECT_STYLES } from '../../styles/chat-select.styles';
 export interface ChatSelectOption {
   value: string;
   label: string;
+  description?: string;
   disabled?: boolean;
 }
 
@@ -72,7 +73,10 @@ export interface ChatSelectOption {
             [attr.aria-selected]="opt.value === value()"
             (click)="selectOption(opt)"
           >
-            {{ opt.label }}
+            <span class="chat-select__option-label">{{ opt.label }}</span>
+            @if (opt.description) {
+              <span class="chat-select__option-desc">{{ opt.description }}</span>
+            }
           </button>
         }
       </div>
diff --git a/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.spec.ts b/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.spec.ts
index 72df7b28..ddb76ac0 100644
--- a/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.spec.ts
+++ b/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.spec.ts
@@ -51,4 +51,18 @@ describe('ChatWelcomeSuggestionComponent', () => {
     button!.click();
     expect(emitted).toBe('tell-me');
   });
+
+  it('exposes description as a title + aria-description tooltip when set', () => {
+    setSignalInput(fixture.componentInstance.description, 'What this prompt demonstrates');
+    fixture.detectChanges();
+    const button = (fixture.nativeElement as HTMLElement).querySelector('button')!;
+    expect(button.getAttribute('title')).toBe('What this prompt demonstrates');
+    expect(button.getAttribute('aria-description')).toBe('What this prompt demonstrates');
+  });
+
+  it('omits the tooltip attributes when no description is provided', () => {
+    const button = (fixture.nativeElement as HTMLElement).querySelector('button')!;
+    expect(button.getAttribute('title')).toBeNull();
+    expect(button.getAttribute('aria-description')).toBeNull();
+  });
 });
diff --git a/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.ts b/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.ts
index 90dbff88..69c94d53 100644
--- a/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.ts
+++ b/libs/chat/src/lib/primitives/chat-welcome/chat-welcome-suggestion.component.ts
@@ -9,7 +9,13 @@ import { CHAT_WELCOME_SUGGESTION_STYLES } from '../../styles/chat-welcome.styles
   changeDetection: ChangeDetectionStrategy.OnPush,
   styles: [CHAT_HOST_TOKENS, CHAT_WELCOME_SUGGESTION_STYLES],
   template: `
-    <button type="button" class="chat-welcome-suggestion" (click)="selected.emit(value())">
+    <button
+      type="button"
+      class="chat-welcome-suggestion"
+      [attr.title]="description() || null"
+      [attr.aria-description]="description() || null"
+      (click)="selected.emit(value())"
+    >
       <ng-content select="[chatWelcomeSuggestionIcon]" />
       <span class="chat-welcome-suggestion__label">{{ label() }}</span>
       <span class="chat-welcome-suggestion__chevron" aria-hidden="true">›</span>
@@ -19,5 +25,7 @@ import { CHAT_WELCOME_SUGGESTION_STYLES } from '../../styles/chat-welcome.styles
 export class ChatWelcomeSuggestionComponent {
   readonly label = input.required<string>();
   readonly value = input.required<string>();
+  /** Optional short description, surfaced as a hover/focus tooltip on the chip. */
+  readonly description = input<string>();
   readonly selected = output<string>();
 }
diff --git a/libs/chat/src/lib/styles/chat-select.styles.ts b/libs/chat/src/lib/styles/chat-select.styles.ts
index 280e1793..0a01b099 100644
--- a/libs/chat/src/lib/styles/chat-select.styles.ts
+++ b/libs/chat/src/lib/styles/chat-select.styles.ts
@@ -52,7 +52,10 @@ export const CHAT_SELECT_STYLES = `
     z-index: 10;
   }
   .chat-select__option {
-    display: block;
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 2px;
     width: 100%;
     text-align: left;
     border: 0;
@@ -64,6 +67,12 @@ export const CHAT_SELECT_STYLES = `
     font-size: var(--ngaf-chat-font-size-sm);
     cursor: pointer;
   }
+  .chat-select__option-desc {
+    font-size: var(--ngaf-chat-font-size-xs);
+    color: var(--ngaf-chat-text-muted);
+    line-height: 1.3;
+    white-space: normal;
+  }
   .chat-select__option:hover:not(:disabled),
   .chat-select__option:focus-visible {
     background: var(--ngaf-chat-surface-alt);

From 843dd7b4dae34e7a89bbb149e0e3b47f044e13ab Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 18 Jun 2026 22:32:06 -0700
Subject: [PATCH 3/5] feat(examples): clearer welcome-suggestion titles +
 descriptions (multiline dropdown)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../modes/welcome-suggestions.component.ts    |  3 +-
 .../src/app/modes/welcome-suggestions.ts      | 43 ++++++++++++---
 .../chat/angular/e2e/initial-render.spec.ts   |  2 +-
 examples/chat/angular/e2e/lifecycle.spec.ts   |  2 +-
 .../modes/welcome-suggestions.component.ts    |  3 +-
 .../src/app/modes/welcome-suggestions.ts      | 55 ++++++++++++++-----
 6 files changed, 83 insertions(+), 25 deletions(-)

diff --git a/examples/ag-ui/angular/src/app/modes/welcome-suggestions.component.ts b/examples/ag-ui/angular/src/app/modes/welcome-suggestions.component.ts
index 9e3da8df..522d1ade 100644
--- a/examples/ag-ui/angular/src/app/modes/welcome-suggestions.component.ts
+++ b/examples/ag-ui/angular/src/app/modes/welcome-suggestions.component.ts
@@ -28,6 +28,7 @@ import { FEATURED_SUGGESTIONS, MORE_SUGGESTIONS } from './welcome-suggestions';
         class="welcome-suggestions__featured"
         [label]="featuredOne.label"
         [value]="featuredOne.value"
+        [description]="featuredOne.description"
         (selected)="selected.emit($event)"
       />
       <chat-select
@@ -113,5 +114,5 @@ export class WelcomeSuggestionsComponent {
   protected readonly moreOptions: readonly ChatSelectOption[] = [
     ...FEATURED_SUGGESTIONS.slice(1),
     ...MORE_SUGGESTIONS,
-  ].map((s) => ({ value: s.value, label: s.label }));
+  ].map((s) => ({ value: s.value, label: s.label, description: s.description }));
 }
diff --git a/examples/ag-ui/angular/src/app/modes/welcome-suggestions.ts b/examples/ag-ui/angular/src/app/modes/welcome-suggestions.ts
index 2d4930fb..460b8799 100644
--- a/examples/ag-ui/angular/src/app/modes/welcome-suggestions.ts
+++ b/examples/ag-ui/angular/src/app/modes/welcome-suggestions.ts
@@ -13,19 +13,48 @@
 export interface WelcomeSuggestion {
   readonly label: string;
   readonly value: string;
+  readonly description: string;
 }
 
 export const FEATURED_SUGGESTIONS: readonly WelcomeSuggestion[] = [
-  { label: 'Docs & citations', value: 'What do the docs say about streaming?' },
-  { label: 'Generative UI', value: 'Build me a revenue dashboard' },
-  { label: 'Human approval', value: 'Issue me a $50 refund' },
+  {
+    label: 'Search docs and cite sources',
+    value: 'What do the docs say about streaming?',
+    description: 'Calls a search tool and weaves inline citations into the reply.',
+  },
+  {
+    label: 'Generative UI: revenue dashboard',
+    value: 'Build me a revenue dashboard',
+    description: 'Streams a composed UI surface the model builds on the fly.',
+  },
+  {
+    label: 'Approve before a refund',
+    value: 'Issue me a $50 refund',
+    description: 'Pauses mid-run and asks for your explicit approval before proceeding.',
+  },
 ];
 
 export const MORE_SUGGESTIONS: readonly WelcomeSuggestion[] = [
-  { label: 'Read my itinerary', value: "What's on my itinerary?" },
-  { label: 'Agent edits the page', value: 'Add the Louvre to day 2 of my trip' },
-  { label: 'Consent-gated clear', value: 'Clear my day 2 plans' },
-  { label: 'Research subagent', value: 'Research AG-UI and give me the highlights' },
+  {
+    label: 'Read my itinerary',
+    value: "What's on my itinerary?",
+    description: 'Agent calls a browser-side tool to read your trip data.',
+  },
+  {
+    label: 'Agent adds a stop to day 2',
+    value: 'Add the Louvre to day 2 of my trip',
+    description: 'Agent mutates the itinerary panel directly via a client tool.',
+  },
+  {
+    label: 'Clear a day (asks first)',
+    value: 'Clear my day 2 plans',
+    description: 'Client tool requires your confirmation before clearing the day.',
+  },
+  {
+    label: 'Delegate to a research subagent',
+    value: 'Research AG-UI and give me the highlights',
+    description: 'Parent spawns a subagent and streams its summary back to you.',
+  },
 ];
 
 /**
diff --git a/examples/chat/angular/e2e/initial-render.spec.ts b/examples/chat/angular/e2e/initial-render.spec.ts
index 9e434620..77311461 100644
--- a/examples/chat/angular/e2e/initial-render.spec.ts
+++ b/examples/chat/angular/e2e/initial-render.spec.ts
@@ -19,7 +19,7 @@ test('initial render: root route redirects to welcome-state embed mode', async (
     page.getByRole('heading', { name: 'How can I help?' })
   ).toBeVisible();
   await expect(
-    page.getByRole('button', { name: /Demo: render a contact form/i })
+    page.getByRole('button', { name: /Generative UI: contact form/i })
   ).toBeVisible();
   await expect(
     page.getByRole('button', { name: 'More prompts' })
diff --git a/examples/chat/angular/e2e/lifecycle.spec.ts b/examples/chat/angular/e2e/lifecycle.spec.ts
index 3d753088..e050e846 100644
--- a/examples/chat/angular/e2e/lifecycle.spec.ts
+++ b/examples/chat/angular/e2e/lifecycle.spec.ts
@@ -61,7 +61,7 @@ test('lifecycle: selecting a welcome suggestion submits and clears welcome state
 }) => {
   await openDemo(page, '/embed');
   await page
-    .getByRole('button', { name: /Demo: render a contact form/i })
+    .getByRole('button', { name: /Generative UI: contact form/i })
     .click();
 
   await expect(
diff --git a/examples/chat/angular/src/app/modes/welcome-suggestions.component.ts b/examples/chat/angular/src/app/modes/welcome-suggestions.component.ts
index 9e3da8df..522d1ade 100644
--- a/examples/chat/angular/src/app/modes/welcome-suggestions.component.ts
+++ b/examples/chat/angular/src/app/modes/welcome-suggestions.component.ts
@@ -28,6 +28,7 @@ import { FEATURED_SUGGESTIONS, MORE_SUGGESTIONS } from './welcome-suggestions';
         class="welcome-suggestions__featured"
         [label]="featuredOne.label"
         [value]="featuredOne.value"
+        [description]="featuredOne.description"
         (selected)="selected.emit($event)"
       />
       <chat-select
@@ -113,5 +114,5 @@ export class WelcomeSuggestionsComponent {
   protected readonly moreOptions: readonly ChatSelectOption[] = [
     ...FEATURED_SUGGESTIONS.slice(1),
     ...MORE_SUGGESTIONS,
-  ].map((s) => ({ value: s.value, label: s.label }));
+  ].map((s) => ({ value: s.value, label: s.label, description: s.description }));
 }
diff --git a/examples/chat/angular/src/app/modes/welcome-suggestions.ts b/examples/chat/angular/src/app/modes/welcome-suggestions.ts
index 94ec9285..0900df12 100644
--- a/examples/chat/angular/src/app/modes/welcome-suggestions.ts
+++ b/examples/chat/angular/src/app/modes/welcome-suggestions.ts
@@ -20,88 +20,115 @@
 export interface WelcomeSuggestion {
   readonly label: string;
   readonly value: string;
+  readonly description: string;
 }
 
 export const FEATURED_SUGGESTIONS: readonly WelcomeSuggestion[] = [
   // 1. GenUI surface render — the canonical demo's most differentiating capability
   {
-    label: 'Demo: render a contact form',
+    label: 'Generative UI: contact form',
     value:
       'Show me a contact form with fields for name, email address, subject, and a multi-line message, plus a Send button.',
+    description: 'Streams a form the model builds; you can fill it in and submit.',
   },
 
   // 2. Markdown / streaming showcase
-  { label: 'Tell me about coral reefs', value: 'Tell me about coral reefs' },
+  {
+    label: 'Tell me about coral reefs',
+    value: 'Tell me about coral reefs',
+    description: 'Streams a rich markdown response — headings, bullets, and emphasis.',
+  },
 
   // 3. Tool use + citations
   {
-    label: 'What are Angular signals? (search + cite sources)',
+    label: 'Angular signals — search and cite',
     value:
       'Use the search tool to find authoritative information about Angular signals, then explain what they are and when to use them. Cite each source inline as [^doc-id] using the document `id` field returned by the tool.',
+    description: 'Calls a search tool and weaves inline citations into the reply.',
   },
 ];
 
 export const MORE_SUGGESTIONS: readonly WelcomeSuggestion[] = [
-  { label: 'Write a haiku about Angular', value: 'Write a haiku about Angular' },
-  { label: 'List 5 productivity tips', value: 'List 5 productivity tips, in markdown bullets.' },
   {
-    label: 'Compare Angular signals, RxJS, and zone.js',
+    label: 'Write a haiku about Angular',
+    value: 'Write a haiku about Angular',
+    description: 'Quick streaming output — good for checking latency.',
+  },
+  {
+    label: 'List 5 productivity tips',
+    value: 'List 5 productivity tips, in markdown bullets.',
+    description: 'Renders a markdown bullet list in the streaming bubble.',
+  },
+  {
+    label: 'Compare signals, RxJS, and zone.js',
     value:
       'Show me a table comparing Angular signals, RxJS, and zone.js — three columns: name, mental model, when to use.',
+    description: 'Renders a markdown comparison table across three columns.',
   },
   {
     label: 'Explain promises with code',
     value: 'Explain JavaScript promises with a fenced code block in TypeScript.',
+    description: 'Shows the syntax-highlighted code block renderer.',
   },
   {
-    label: 'Solve a multi-step puzzle (try Effort = high)',
+    label: 'Solve a multi-step puzzle',
     value:
       'Three friends start with 14 apples. They share them so each gets a different prime number of apples and one gets exactly twice as many as another. How many does each get? Walk through your reasoning step by step.',
+    description: 'Try Effort = high — shows step-by-step chain-of-thought output.',
   },
   {
-    label: 'Demo: ask for approval before a sensitive action',
+    label: 'Approve before a destructive action',
     value:
       'I want to clean up old database backups older than 90 days. Walk me through what you would delete, and call request_approval before doing anything destructive so I can review your plan.',
+    description: 'Pauses mid-run for your approval before proceeding.',
   },
   {
-    label: 'Demo: dispatch a research subagent',
+    label: 'Dispatch a research subagent',
     value:
       'Use the research subagent to investigate the history and motivation behind Angular standalone components, then report back with a concise summary.',
+    description: 'Parent delegates work to a subagent and streams back the result.',
   },
   {
-    label: 'Demo: render a feedback form',
+    label: 'Generative UI: feedback form',
     value:
       'Build me an interactive feedback form with a name field, a 1–5 rating picker, and a Submit button.',
+    description: 'Renders an interactive form with a rating input and Submit button.',
   },
   {
-    label: 'Demo: render a settings card',
+    label: 'Generative UI: settings card',
     value:
       'Render a settings card with a toggle for dark mode, a language dropdown (English / Spanish / French), and a Save button.',
+    description: 'Composes toggle, dropdown, and button components into a card.',
   },
   {
-    label: 'Demo: render a poll',
+    label: 'Generative UI: poll',
     value:
       'Create a quick poll asking "Which front-end framework do you prefer?" with options Angular, React, Vue, and Svelte, plus a Vote button.',
+    description: 'Renders a live-vote poll component you can interact with.',
   },
   {
-    label: 'Demo: render a media-rich product card',
+    label: 'Generative UI: media product card',
     value:
       'Render a product card with: a header image at the top, a tab strip with two tabs ("Overview" and "Specs"). Under Overview show a Row containing an icon and a short description Text. Under Specs show a List of feature bullets each prefixed with a small icon. Below the tabs add a primary "Add to cart" Button.',
+    description: 'Combines image, tabs, icons, and list into a rich product card.',
   },
   {
-    label: 'Demo: render a booking surface with modal',
+    label: 'Generative UI: booking surface with modal',
     value:
       'Render a booking surface: a heading "Book your trip", a DateTimeInput for travel date, a horizontal divider, then a Row containing two Cards (one for departure city, one for return city) each with a TextField. Below the Row add a primary "Continue" Button whose action opens a Modal containing a confirmation Column with a summary Text and Confirm / Cancel Buttons.',
+    description: 'Multi-component layout ending in a confirmation modal.',
   },
   {
     label: 'Smoke: media + layout kitchen sink',
     value:
       'Render a Card containing a Tabs component with two tabs labeled "Media" and "Layout". Under the Media tab show a Column containing: a header Image (use https://placehold.co/600x300/4f8df5/ffffff.png as the URL), an Icon (any icon name from the canonical set, e.g. star), a short Text caption, an AudioPlayer (use https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3 as the URL), and a Video (use https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4 as the URL). Under the Layout tab show: a Row containing two Text components separated by a vertical Divider, then a horizontal Divider, then a List of three Text bullet items, then a Column containing two Text components.',
+    description: 'Exercises image, audio, video, divider, row, and list primitives.',
   },
   {
     label: 'Smoke: interactive form kitchen sink',
     value:
       'Render a Card titled "Profile setup" containing a Column with: a TextField for display name, a Slider for "experience years" (range 0-30), a CheckBox for "subscribe to newsletter", a DateTimeInput for birthday (date only), a MultipleChoice for "favorite frameworks" with options Angular, React, Vue, Svelte and maxAllowedSelections of 3 (multi-select), a horizontal Divider, a Row containing a primary "Save" Button and a secondary "Open details" Button whose action opens a Modal with a Column containing a Text summary and a Close Button.',
+    description: 'Exercises every interactive input type plus a modal flow.',
   },
 ];
 

From d6d45e0cbca1ea0ca6167d71dd8053aaf52b8c31 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 18 Jun 2026 22:34:29 -0700
Subject: [PATCH 4/5] feat(cockpit): clearer welcome-suggestion titles +
 descriptions (chip tooltips)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .../a2ui/angular/src/app/a2ui.component.ts    |  14 ++-
 .../angular/src/app/interrupts.component.ts   |  14 ++-
 .../angular/src/app/json-render.component.ts  |  14 ++-
 .../a2ui/angular/src/app/a2ui.component.ts    |  13 +-
 .../src/app/generative-ui.component.ts        |  13 +-
 .../angular/src/app/interrupts.component.ts   |  13 +-
 .../angular/src/app/subagents.component.ts    |   7 +-
 .../angular/src/app/tool-calls.component.ts   |   7 +-
 .../angular/src/app/interrupts.component.ts   |  14 ++-
 .../angular/src/app/persistence.component.ts  |   7 +-
 .../angular/src/app/streaming.component.ts    |  13 +-
 .../shell/palette-persistence.service.spec.ts | 111 ++++++++++++++++++
 .../app/shell/palette-persistence.service.ts  |  28 ++++-
 .../shell/palette-persistence.service.spec.ts |  88 ++++++++++++++
 .../app/shell/palette-persistence.service.ts  |  33 +++++-
 15 files changed, 366 insertions(+), 23 deletions(-)
 create mode 100644 examples/ag-ui/angular/src/app/shell/palette-persistence.service.spec.ts

diff --git a/cockpit/ag-ui/a2ui/angular/src/app/a2ui.component.ts b/cockpit/ag-ui/a2ui/angular/src/app/a2ui.component.ts
index 46b351ed..fa88a168 100644
--- a/cockpit/ag-ui/a2ui/angular/src/app/a2ui.component.ts
+++ b/cockpit/ag-ui/a2ui/angular/src/app/a2ui.component.ts
@@ -5,8 +5,16 @@ import { ExampleChatLayoutComponent } from '@threadplane/example-layouts';
 import { injectAgent } from '@threadplane/ag-ui';
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'LAX → JFK', value: 'I want to fly LAX to JFK' },
-  { label: 'SFO → SEA', value: 'I want to fly SFO to SEA' },
+  {
+    label: 'Book LAX → JFK',
+    value: 'I want to fly LAX to JFK',
+    description: 'Agent emits an A2UI form spec; watch the booking form render in-chat.',
+  },
+  {
+    label: 'Book SFO → SEA',
+    value: 'I want to fly SFO to SEA',
+    description: 'Same A2UI pattern on a different route — try both to compare.',
+  },
 ] as const;
 
 @Component({
@@ -18,7 +26,7 @@ const WELCOME_SUGGESTIONS = [
       <chat main [agent]="agent" [views]="catalog" class="flex-1 min-w-0">
         <div chatWelcomeSuggestions>
           @for (s of suggestions; track s.value) {
-            <chat-welcome-suggestion [label]="s.label" [value]="s.value" (selected)="send($event)" />
+            <chat-welcome-suggestion [label]="s.label" [value]="s.value" [description]="s.description" (selected)="send($event)" />
           }
         </div>
       </chat>
diff --git a/cockpit/ag-ui/interrupts/angular/src/app/interrupts.component.ts b/cockpit/ag-ui/interrupts/angular/src/app/interrupts.component.ts
index 301242ec..6263b6d7 100644
--- a/cockpit/ag-ui/interrupts/angular/src/app/interrupts.component.ts
+++ b/cockpit/ag-ui/interrupts/angular/src/app/interrupts.component.ts
@@ -6,8 +6,17 @@ import { ExampleChatLayoutComponent } from '@threadplane/example-layouts';
 import { CurrencyPipe } from '@angular/common';
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'Refund a duplicate charge', value: 'Refund $47.50 to customer cus_a8x2k — they were charged twice for the same order.' },
-  { label: 'Refund a chargeback', value: 'Refund $129.00 to customer cus_z19fp who opened a chargeback for unrecognized activity.' },
+  // label asserted by e2e (interrupts.spec.ts page.getByText) — do not change.
+  {
+    label: 'Refund a duplicate charge',
+    value: 'Refund $47.50 to customer cus_a8x2k — they were charged twice for the same order.',
+    description: 'Graph pauses at request_approval; approve or edit the amount in the modal.',
+  },
+  {
+    label: 'Refund a chargeback',
+    value: 'Refund $129.00 to customer cus_z19fp who opened a chargeback for unrecognized activity.',
+    description: 'Chargeback path — same interrupt pattern with a different reason string.',
+  },
 ] as const;
 
 /**
@@ -45,6 +54,7 @@ const WELCOME_SUGGESTIONS = [
               <chat-welcome-suggestion
                 [label]="s.label"
                 [value]="s.value"
+                [description]="s.description"
                 (selected)="send($event)"
               />
             }
diff --git a/cockpit/ag-ui/json-render/angular/src/app/json-render.component.ts b/cockpit/ag-ui/json-render/angular/src/app/json-render.component.ts
index cf5a669a..6b74df71 100644
--- a/cockpit/ag-ui/json-render/angular/src/app/json-render.component.ts
+++ b/cockpit/ag-ui/json-render/angular/src/app/json-render.component.ts
@@ -21,8 +21,16 @@ const dashboardViews = views({
 });
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'Airline operations dashboard', value: 'Show me a dashboard of airline operations.' },
-  { label: 'Filter to cancelled flights',  value: 'Filter to only the cancelled flights.' },
+  {
+    label: 'Airline operations dashboard',
+    value: 'Show me a dashboard of airline operations.',
+    description: 'Agent emits a render spec; charts and KPI cards appear inline in the chat.',
+  },
+  {
+    label: 'Filter to cancelled flights',
+    value: 'Filter to only the cancelled flights.',
+    description: 'Follow-up that updates the dashboard state — shows GenUI mutation in action.',
+  },
 ] as const;
 
 @Component({
@@ -34,7 +42,7 @@ const WELCOME_SUGGESTIONS = [
       <chat main [agent]="agent" [views]="dashboardViews" [store]="dashStore" class="flex-1 min-w-0">
         <div chatWelcomeSuggestions>
           @for (s of suggestions; track s.value) {
-            <chat-welcome-suggestion [label]="s.label" [value]="s.value" (selected)="send($event)" />
+            <chat-welcome-suggestion [label]="s.label" [value]="s.value" [description]="s.description" (selected)="send($event)" />
           }
         </div>
       </chat>
diff --git a/cockpit/chat/a2ui/angular/src/app/a2ui.component.ts b/cockpit/chat/a2ui/angular/src/app/a2ui.component.ts
index 0ed33dbc..bec48829 100644
--- a/cockpit/chat/a2ui/angular/src/app/a2ui.component.ts
+++ b/cockpit/chat/a2ui/angular/src/app/a2ui.component.ts
@@ -5,8 +5,16 @@ import { ExampleChatLayoutComponent } from '@threadplane/example-layouts';
 import { injectAgent } from '@threadplane/langgraph';
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'LAX → JFK',          value: 'I want to fly LAX to JFK' },
-  { label: 'SFO → SEA',          value: 'I want to fly SFO to SEA' },
+  {
+    label: 'Book LAX → JFK',
+    value: 'I want to fly LAX to JFK',
+    description: 'Agent emits an A2UI form spec; watch the booking form render in-chat.',
+  },
+  {
+    label: 'Book SFO → SEA',
+    value: 'I want to fly SFO to SEA',
+    description: 'Same A2UI pattern on a different route — try both to compare.',
+  },
 ] as const;
 
 @Component({
@@ -21,6 +29,7 @@ const WELCOME_SUGGESTIONS = [
             <chat-welcome-suggestion
               [label]="s.label"
               [value]="s.value"
+              [description]="s.description"
               (selected)="send($event)"
             />
           }
diff --git a/cockpit/chat/generative-ui/angular/src/app/generative-ui.component.ts b/cockpit/chat/generative-ui/angular/src/app/generative-ui.component.ts
index 248592bb..ea007f6a 100644
--- a/cockpit/chat/generative-ui/angular/src/app/generative-ui.component.ts
+++ b/cockpit/chat/generative-ui/angular/src/app/generative-ui.component.ts
@@ -22,8 +22,16 @@ const dashboardViews = views({
 });
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'Airline operations dashboard', value: 'Show me a dashboard of airline operations.' },
-  { label: 'Filter to cancelled flights',  value: 'Filter to only the cancelled flights.' },
+  {
+    label: 'Airline operations dashboard',
+    value: 'Show me a dashboard of airline operations.',
+    description: 'Agent emits a render spec; charts and KPI cards appear inline in the chat.',
+  },
+  {
+    label: 'Filter to cancelled flights',
+    value: 'Filter to only the cancelled flights.',
+    description: 'Follow-up that updates the dashboard state — shows GenUI mutation in action.',
+  },
 ] as const;
 
 @Component({
@@ -38,6 +46,7 @@ const WELCOME_SUGGESTIONS = [
             <chat-welcome-suggestion
               [label]="s.label"
               [value]="s.value"
+              [description]="s.description"
               (selected)="send($event)"
             />
           }
diff --git a/cockpit/chat/interrupts/angular/src/app/interrupts.component.ts b/cockpit/chat/interrupts/angular/src/app/interrupts.component.ts
index f0a13a8f..427dbfa6 100644
--- a/cockpit/chat/interrupts/angular/src/app/interrupts.component.ts
+++ b/cockpit/chat/interrupts/angular/src/app/interrupts.component.ts
@@ -13,9 +13,17 @@ import { injectAgent } from '@threadplane/langgraph';
 const SUGGESTIONS = [
   // values match cockpit/chat/interrupts/angular/e2e/c-interrupts.spec.ts.
   // Confirm flow: book + Accept → "Booked …"
-  { label: 'Book UA123 (confirm)', value: 'Book me on UA123.' },
+  {
+    label: 'Book a flight (you confirm)',
+    value: 'Book me on UA123.',
+    description: 'Agent pauses for approval; click Accept in the sidebar to complete the booking.',
+  },
   // Cancel flow: book + Ignore → "Booking cancelled."
-  { label: 'Book AA404 (cancel)', value: 'Book me on AA404.' },
+  {
+    label: 'Book a flight (you cancel)',
+    value: 'Book me on AA404.',
+    description: 'Same interrupt flow; click Ignore to see the cancellation path.',
+  },
 ] as const;
 
 /**
@@ -49,6 +57,7 @@ const SUGGESTIONS = [
             <chat-welcome-suggestion
               [label]="s.label"
               [value]="s.value"
+              [description]="s.description"
               (selected)="send($event)"
             />
           }
diff --git a/cockpit/chat/subagents/angular/src/app/subagents.component.ts b/cockpit/chat/subagents/angular/src/app/subagents.component.ts
index e579d6cd..0c14812f 100644
--- a/cockpit/chat/subagents/angular/src/app/subagents.component.ts
+++ b/cockpit/chat/subagents/angular/src/app/subagents.component.ts
@@ -11,7 +11,11 @@ import { injectAgent } from '@threadplane/langgraph';
 
 const SUGGESTIONS = [
   // value matches cockpit/chat/subagents/angular/e2e/c-subagents.spec.ts PROMPT.
-  { label: 'Plan a trip', value: 'Plan a trip from LAX to JFK' },
+  {
+    label: 'Plan a trip from LAX to JFK',
+    value: 'Plan a trip from LAX to JFK',
+    description: 'Orchestrator fans out to research, analysis, and summary subagents in parallel.',
+  },
 ] as const;
 
 /**
@@ -39,6 +43,7 @@ const SUGGESTIONS = [
             <chat-welcome-suggestion
               [label]="s.label"
               [value]="s.value"
+              [description]="s.description"
               (selected)="send($event)"
             />
           }
diff --git a/cockpit/chat/tool-calls/angular/src/app/tool-calls.component.ts b/cockpit/chat/tool-calls/angular/src/app/tool-calls.component.ts
index d9f589dc..84be398f 100644
--- a/cockpit/chat/tool-calls/angular/src/app/tool-calls.component.ts
+++ b/cockpit/chat/tool-calls/angular/src/app/tool-calls.component.ts
@@ -11,7 +11,11 @@ import { injectAgent } from '@threadplane/langgraph';
 
 const SUGGESTIONS = [
   // value matches cockpit/chat/tool-calls/angular/e2e/c-tool-calls.spec.ts PROMPT.
-  { label: 'Look up flight UA123', value: "What's the status of UA123?" },
+  {
+    label: 'Check a flight status',
+    value: "What's the status of UA123?",
+    description: 'Calls a lookup_flight tool; watch the tool-call card stream in the sidebar.',
+  },
 ] as const;
 
 /**
@@ -38,6 +42,7 @@ const SUGGESTIONS = [
             <chat-welcome-suggestion
               [label]="s.label"
               [value]="s.value"
+              [description]="s.description"
               (selected)="send($event)"
             />
           }
diff --git a/cockpit/langgraph/interrupts/angular/src/app/interrupts.component.ts b/cockpit/langgraph/interrupts/angular/src/app/interrupts.component.ts
index 7c9f9e7a..cc051d26 100644
--- a/cockpit/langgraph/interrupts/angular/src/app/interrupts.component.ts
+++ b/cockpit/langgraph/interrupts/angular/src/app/interrupts.component.ts
@@ -6,8 +6,17 @@ import { ExampleChatLayoutComponent } from '@threadplane/example-layouts';
 import { CurrencyPipe } from '@angular/common';
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'Refund a duplicate charge', value: 'Refund $47.50 to customer cus_a8x2k — they were charged twice for the same order.' },
-  { label: 'Refund a chargeback', value: 'Refund $129.00 to customer cus_z19fp who opened a chargeback for unrecognized activity.' },
+  // label asserted by e2e (interrupts.spec.ts page.getByText) — do not change.
+  {
+    label: 'Refund a duplicate charge',
+    value: 'Refund $47.50 to customer cus_a8x2k — they were charged twice for the same order.',
+    description: 'Graph pauses at request_approval; approve or edit the amount in the modal.',
+  },
+  {
+    label: 'Refund a chargeback',
+    value: 'Refund $129.00 to customer cus_z19fp who opened a chargeback for unrecognized activity.',
+    description: 'Chargeback path — same interrupt pattern with a different reason string.',
+  },
 ] as const;
 
 /**
@@ -45,6 +54,7 @@ const WELCOME_SUGGESTIONS = [
               <chat-welcome-suggestion
                 [label]="s.label"
                 [value]="s.value"
+                [description]="s.description"
                 (selected)="send($event)"
               />
             }
diff --git a/cockpit/langgraph/persistence/angular/src/app/persistence.component.ts b/cockpit/langgraph/persistence/angular/src/app/persistence.component.ts
index 8dacf2eb..296b6990 100644
--- a/cockpit/langgraph/persistence/angular/src/app/persistence.component.ts
+++ b/cockpit/langgraph/persistence/angular/src/app/persistence.component.ts
@@ -6,7 +6,11 @@ import { ExampleChatLayoutComponent } from '@threadplane/example-layouts';
 import { environment } from '../environments/environment';
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'Save this thread for later', value: 'Help me draft a project brief I can revisit.' },
+  {
+    label: 'Start a saved thread',
+    value: 'Help me draft a project brief I can revisit.',
+    description: 'Each reply gets a thread ID; click the sidebar to switch between conversations.',
+  },
 ] as const;
 
 interface Thread {
@@ -67,6 +71,7 @@ let threadCounter = 0;
             <chat-welcome-suggestion
               [label]="s.label"
               [value]="s.value"
+              [description]="s.description"
               (selected)="send($event)"
             />
           }
diff --git a/cockpit/langgraph/streaming/angular/src/app/streaming.component.ts b/cockpit/langgraph/streaming/angular/src/app/streaming.component.ts
index b2504cb7..3bbcd436 100644
--- a/cockpit/langgraph/streaming/angular/src/app/streaming.component.ts
+++ b/cockpit/langgraph/streaming/angular/src/app/streaming.component.ts
@@ -5,8 +5,16 @@ import { injectAgent } from '@threadplane/langgraph';
 import { ExampleChatLayoutComponent } from '@threadplane/example-layouts';
 
 const WELCOME_SUGGESTIONS = [
-  { label: 'Stream a long answer',             value: 'Explain LangGraph checkpointing in 200 words.' },
-  { label: 'Walk me through agent tool calls', value: 'Show me how an agent decides which tool to use.' },
+  {
+    label: 'Stream a long answer',
+    value: 'Explain LangGraph checkpointing in 200 words.',
+    description: 'Watch tokens arrive incrementally — the simplest @threadplane/chat integration.',
+  },
+  {
+    label: 'How agents pick tools',
+    value: 'Show me how an agent decides which tool to use.',
+    description: 'Explains tool-selection reasoning; good entry point for the tool-calls demo.',
+  },
 ] as const;
 
 /**
@@ -28,6 +36,7 @@ const WELCOME_SUGGESTIONS = [
             <chat-welcome-suggestion
               [label]="s.label"
               [value]="s.value"
+              [description]="s.description"
               (selected)="send($event)"
             />
           }
diff --git a/examples/ag-ui/angular/src/app/shell/palette-persistence.service.spec.ts b/examples/ag-ui/angular/src/app/shell/palette-persistence.service.spec.ts
new file mode 100644
index 00000000..7ffb05ba
--- /dev/null
+++ b/examples/ag-ui/angular/src/app/shell/palette-persistence.service.spec.ts
@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MIT
+import { describe, it, expect, beforeEach } from 'vitest';
+import { TestBed } from '@angular/core/testing';
+import { PalettePersistence } from './palette-persistence.service';
+
+const KEY = 'threadplane-ag-ui-demo:palette';
+
+describe('PalettePersistence (ag-ui)', () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  // ── Baseline behavior ─────────────────────────────────────────────────────
+
+  it('returns null when nothing is stored', () => {
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('model')).toBeNull();
+    expect(svc.read('effort')).toBeNull();
+    expect(svc.read('genUiMode')).toBeNull();
+    expect(svc.read('theme')).toBeNull();
+    expect(svc.read('colorScheme')).toBeNull();
+  });
+
+  it('round-trips a valid model value', () => {
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    svc.write('model', 'gpt-5-mini');
+    expect(svc.read('model')).toBe('gpt-5-mini');
+  });
+
+  it('round-trips a valid effort value', () => {
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    svc.write('effort', 'high');
+    expect(svc.read('effort')).toBe('high');
+  });
+
+  it('survives malformed storage (returns null and does not throw)', () => {
+    localStorage.setItem(KEY, 'not-valid-json');
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('model')).toBeNull();
+  });
+
+  it('clearing a key with null removes it from storage', () => {
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    svc.write('model', 'gpt-5-mini');
+    expect(svc.read('model')).toBe('gpt-5-mini');
+    svc.write('model', null);
+    expect(svc.read('model')).toBeNull();
+  });
+
+  // ── Validate-on-read: enum fields ─────────────────────────────────────────
+
+  it('returns null for a stale model value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ model: 'gpt-4-turbo' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('model')).toBeNull();
+  });
+
+  it('returns a valid model value (gpt-5-nano) unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ model: 'gpt-5-nano' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('model')).toBe('gpt-5-nano');
+  });
+
+  it('returns null for a stale effort value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ effort: 'turbo' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('effort')).toBeNull();
+  });
+
+  it('returns a valid effort value (low) unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ effort: 'low' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('effort')).toBe('low');
+  });
+
+  it('returns null for a stale genUiMode value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ genUiMode: 'legacy-render' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('genUiMode')).toBeNull();
+  });
+
+  it('returns a valid genUiMode value (a2ui) unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ genUiMode: 'a2ui' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('genUiMode')).toBe('a2ui');
+  });
+
+  it('returns null for a stale theme value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ theme: 'ocean-blue' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('theme')).toBeNull();
+  });
+
+  it('returns a valid theme value (material-light) unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ theme: 'material-light' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('theme')).toBe('material-light');
+  });
+
+  it('returns null for a stale colorScheme value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ colorScheme: 'system' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('colorScheme')).toBeNull();
+  });
+
+  it('returns a valid colorScheme value (dark) unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ colorScheme: 'dark' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('colorScheme')).toBe('dark');
+  });
+});
diff --git a/examples/ag-ui/angular/src/app/shell/palette-persistence.service.ts b/examples/ag-ui/angular/src/app/shell/palette-persistence.service.ts
index d84f1007..13b346fb 100644
--- a/examples/ag-ui/angular/src/app/shell/palette-persistence.service.ts
+++ b/examples/ag-ui/angular/src/app/shell/palette-persistence.service.ts
@@ -13,17 +13,43 @@ interface PaletteState {
 
 type PaletteKey = keyof PaletteState;
 
+/**
+ * Allowed value sets for enum-like palette fields. Kept here (local allowlist
+ * approach) because the shell component declares these as private signals —
+ * extracting/exporting them from the component would add coupling for little
+ * gain. Update these whenever the dropdown options in ag-ui-shell.component.ts
+ * change.
+ */
+const ALLOWED: Record<PaletteKey, ReadonlySet<string>> = {
+  model:       new Set(['gpt-5-mini', 'gpt-5-nano']),
+  effort:      new Set(['minimal', 'low', 'medium', 'high']),
+  genUiMode:   new Set(['a2ui', 'json-render']),
+  theme:       new Set(['default-dark', 'default-light', 'material-dark', 'material-light']),
+  colorScheme: new Set(['light', 'dark']),
+};
+
 /**
  * Tiny localStorage-backed persistence for control-palette state. Single
  * JSON object under `threadplane-ag-ui-demo:palette` so reads/writes are
  * atomic-per-key. Survives malformed JSON by returning `null` and
  * silently overwriting on next write.
+ *
+ * All fields are enum-like and are validated against their current allowed
+ * value sets on read: a stale value (e.g. a renamed enum member from a
+ * previous release) returns `null` so the caller's `?? default` falls back
+ * cleanly.
  */
 @Injectable({ providedIn: 'root' })
 export class PalettePersistence {
   read<K extends PaletteKey>(key: K): PaletteState[K] | null {
     const raw = this.load();
-    return (raw[key] as PaletteState[K] | undefined) ?? null;
+    const value = (raw[key] as PaletteState[K] | undefined) ?? null;
+
+    if (value !== null && value !== undefined) {
+      if (!ALLOWED[key].has(value as string)) return null;
+    }
+
+    return value;
   }
 
   write<K extends PaletteKey>(key: K, value: PaletteState[K] | null): void {
diff --git a/examples/chat/angular/src/app/shell/palette-persistence.service.spec.ts b/examples/chat/angular/src/app/shell/palette-persistence.service.spec.ts
index 0b9f7b43..42251986 100644
--- a/examples/chat/angular/src/app/shell/palette-persistence.service.spec.ts
+++ b/examples/chat/angular/src/app/shell/palette-persistence.service.spec.ts
@@ -49,4 +49,92 @@ describe('PalettePersistence', () => {
     const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
     expect(svc.read('model')).toBeNull();
   });
+
+  // ── Validate-on-read: enum fields ─────────────────────────────────────────
+
+  it('returns null for a stale model value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ model: 'gpt-4-turbo' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('model')).toBeNull();
+  });
+
+  it('returns a valid model value unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ model: 'gpt-5' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('model')).toBe('gpt-5');
+  });
+
+  it('returns null for a stale effort value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ effort: 'ultra' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('effort')).toBeNull();
+  });
+
+  it('returns a valid effort value unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ effort: 'medium' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('effort')).toBe('medium');
+  });
+
+  it('returns null for a stale genUiMode value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ genUiMode: 'legacy-render' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('genUiMode')).toBeNull();
+  });
+
+  it('returns a valid genUiMode value unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ genUiMode: 'json-render' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('genUiMode')).toBe('json-render');
+  });
+
+  it('returns null for a stale theme value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ theme: 'ocean-blue' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('theme')).toBeNull();
+  });
+
+  it('returns a valid theme value unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ theme: 'material-dark' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('theme')).toBe('material-dark');
+  });
+
+  it('returns null for a stale colorScheme value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ colorScheme: 'system' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('colorScheme')).toBeNull();
+  });
+
+  it('returns a valid colorScheme value unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ colorScheme: 'light' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('colorScheme')).toBe('light');
+  });
+
+  it('returns null for a stale sidenavMode value not in the allowed set', () => {
+    localStorage.setItem(KEY, JSON.stringify({ sidenavMode: 'mini' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('sidenavMode')).toBeNull();
+  });
+
+  it('returns a valid sidenavMode value unchanged', () => {
+    localStorage.setItem(KEY, JSON.stringify({ sidenavMode: 'expanded' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('sidenavMode')).toBe('expanded');
+  });
+
+  // ── Non-enum fields pass through without validation ───────────────────────
+
+  it('passes selectedProjectId through without validation', () => {
+    localStorage.setItem(KEY, JSON.stringify({ selectedProjectId: 'any-arbitrary-id-123' }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('selectedProjectId')).toBe('any-arbitrary-id-123');
+  });
+
+  it('passes drawerOpen boolean through without validation', () => {
+    localStorage.setItem(KEY, JSON.stringify({ drawerOpen: true }));
+    const svc = TestBed.runInInjectionContext(() => new PalettePersistence());
+    expect(svc.read('drawerOpen')).toBe(true);
+  });
 });
diff --git a/examples/chat/angular/src/app/shell/palette-persistence.service.ts b/examples/chat/angular/src/app/shell/palette-persistence.service.ts
index f5438e67..3abc1553 100644
--- a/examples/chat/angular/src/app/shell/palette-persistence.service.ts
+++ b/examples/chat/angular/src/app/shell/palette-persistence.service.ts
@@ -16,17 +16,48 @@ interface PaletteState {
 
 type PaletteKey = keyof PaletteState;
 
+/**
+ * Allowed value sets for enum-like palette fields. Kept here (local allowlist
+ * approach) because the shell component declares these as private signals —
+ * extracting/exporting them from the component would add coupling for little
+ * gain. Update these whenever the dropdown options in demo-shell.component.ts
+ * change.
+ */
+const ALLOWED = {
+  model:       new Set(['gpt-5', 'gpt-5-mini', 'gpt-5-nano']),
+  effort:      new Set(['minimal', 'low', 'medium', 'high']),
+  genUiMode:   new Set(['a2ui', 'json-render']),
+  theme:       new Set(['default-dark', 'default-light', 'material-dark', 'material-light']),
+  colorScheme: new Set<string>(['light', 'dark']),
+  sidenavMode: new Set<string>(['expanded', 'collapsed']),
+} as const satisfies Partial<Record<PaletteKey, ReadonlySet<string>>>;
+
+type EnumKey = keyof typeof ALLOWED;
+
 /**
  * Tiny localStorage-backed persistence for control-palette state. Single
  * JSON object under `threadplane-chat-demo:palette` so reads/writes are
  * atomic-per-key. Survives malformed JSON by returning `null` and
  * silently overwriting on next write.
+ *
+ * Enum-like fields (model, effort, genUiMode, theme, colorScheme,
+ * sidenavMode) are validated against their current allowed value sets on
+ * read: a stale value (e.g. a renamed enum member from a previous release)
+ * returns `null` so the caller's `?? default` falls back cleanly.
+ * Non-enum fields (selectedProjectId, drawerOpen) pass through unchanged.
  */
 @Injectable({ providedIn: 'root' })
 export class PalettePersistence {
   read<K extends PaletteKey>(key: K): PaletteState[K] | null {
     const raw = this.load();
-    return (raw[key] as PaletteState[K] | undefined) ?? null;
+    const value = (raw[key] as PaletteState[K] | undefined) ?? null;
+
+    if (key in ALLOWED && value !== null && value !== undefined) {
+      const allowed = ALLOWED[key as EnumKey] as ReadonlySet<string>;
+      if (!allowed.has(value as string)) return null;
+    }
+
+    return value;
   }
 
   write<K extends PaletteKey>(key: K, value: PaletteState[K] | null): void {

From 3bf81d07d19e1c732ea50ce4a2087b536dc83420 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Thu, 18 Jun 2026 22:57:20 -0700
Subject: [PATCH 5/5] docs(chat): regenerate api-docs for
 ChatSelectOption.description + chip tooltip

---
 apps/website/content/docs/chat/api/api-docs.json | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/apps/website/content/docs/chat/api/api-docs.json b/apps/website/content/docs/chat/api/api-docs.json
index e6736866..16145fe8 100644
--- a/apps/website/content/docs/chat/api/api-docs.json
+++ b/apps/website/content/docs/chat/api/api-docs.json
@@ -4721,6 +4721,12 @@
     "params": [],
     "examples": [],
     "properties": [
+      {
+        "name": "description",
+        "type": "InputSignal<string | undefined>",
+        "description": "Optional short description, surfaced as a hover/focus tooltip on the chip.",
+        "optional": false
+      },
       {
         "name": "label",
         "type": "InputSignal<string>",
@@ -5939,6 +5945,12 @@
     "kind": "interface",
     "description": "",
     "properties": [
+      {
+        "name": "description",
+        "type": "string",
+        "description": "",
+        "optional": true
+      },
       {
         "name": "disabled",
         "type": "boolean",