@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/wizard.md

@@ -0,0 +1,58 @@
+## What it is
+
+A multi-step flow: an ordered set of stages, a rail showing where you are, a panel for the active step, and a Back / Skip / Next footer.
+
+## The contract
+
+```
+@steps (required) — the ordered stages
+@activeIndex?, @defaultActiveIndex?, @onStepChange? — the position; the callback
+             fires on every move, BACKWARDS INCLUDED
+@onComplete? — fires when the terminal step's primary is activated and allowed
+@onRefused?  — fires when a forward move was REFUSED, with the index refused at
+@canAdvance? — coarse override of the per-step valid flag. Resolution order:
+               @canAdvance ?? step.valid ?? true
+@navigation? — 'linear' (Back and Next only) | 'visited' (default — back to anywhere
+               already reached, forward through the gate) | freer still
+@label?      — accessible name for the rail. Default 'Steps'
+@railVariant?, @summary?, @hideTitle?
+@busy?       — the primary is busy; an async commit is in flight
+@backLabel?, @nextLabel?, @skipLabel?, @completeLabel?, @emptyTitle?
+
+<:step>   the active step's content; receives (step, index, api)
+<:rail>   replaces the StepList rail entirely — this is where a clickable rail goes
+<:footer> replaces the Back / Skip / Next footer
+```
+
+**`@onRefused` is the arg most wizards do not have.** A forward move blocked by validation is an event worth knowing about — it is where a caller shows *why* — and a wizard that simply does nothing when Next is pressed is the most frustrating version of this component.
+
+**Validation resolution is stated in the contract**: `@canAdvance ?? step.valid ?? true`. The coarse override wins, then the step's own flag, then permission.
+
+**`@navigation='visited'` is the default**, which is the humane middle: you can go back to anything you have reached, and forward only through the gate.
+
+**`@onStepChange` fires on backwards moves too**, so a caller tracking progress is never out of step.
+
+## Prior art
+
+The wizard/stepper in every kit, and SLDS's in particular.
+
+Where Pretui is better: the refusal event, the stated resolution order, and the rail being a real **StepList** rather than a bespoke set of dots — so step state and its accessibility come from one place.
+
+Where it is thinner: no branching — steps are a linear array — no per-step async validation contract beyond `@busy`, and no persistence of a partially-completed flow.
+
+## Accessibility
+
+- **The rail is a StepList**, so complete, current and upcoming are conveyed as text rather than by colour.
+- **A refused move needs saying.** The component reports it; the caller renders the reason, and a wizard that refuses silently is inaccessible to everyone equally.
+- **`@busy` locks the primary rather than removing it**, so focus stays where the reader put it.
+- **`<:rail>` is where a clickable rail goes**, and a caller who builds one inherits responsibility for its keyboard model — the default rail is not interactive.
+- **The step panel is titled unless `@hideTitle`**, which is what lets a screen-reader user confirm the move happened.
+- **Skip is a named control**, so an optional step is visibly optional rather than being a Next that behaves differently.
+
+## Theming
+
+The rail is **StepList**'s, the footer is built from the kit's **Button**, and the panel takes the shared surface tokens.
+
+Nothing is wizard-specific, which is what keeps a flow looking like the application it interrupts rather than like a separate installer.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/wizard.usage.gts

@@ -0,0 +1,188 @@
+// Pretui — Wizard usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Wizard } from './wizard';
+import type { WizardStep } from './wizard';
+
+// ── Wizard ───────────────────────────────────────────────────────────────
+const NAVIGATIONS = ['linear', 'visited', 'free'];
+
+const RAIL_VARIANTS = ['steps', 'track'];
+
+// Dropped upstream surface: aef6db-stepper's modal mode (compose
+// <Dialog><Wizard /></Dialog> — Dialog already owns the focus trap,
+// Escape and aria-modal that the upstream never implemented) and its
+// @allowStepJump boolean, superseded by the three-valued @navigation.
+class WizardUsage extends Component {
+  navigations = NAVIGATIONS;
+  railVariants = RAIL_VARIANTS;
+
+  @tracked activeIndex = 0;
+  @tracked navigation = 'visited';
+  @tracked railVariant = 'steps';
+  @tracked summary = true;
+  @tracked busy = false;
+  @tracked emailFilled = false;
+  @tracked lastEvent = 'nothing yet';
+
+  get steps(): WizardStep[] {
+    return [
+      {
+        id: 'account',
+        label: 'Account',
+        detail: 'Who is signing up',
+        valid: this.emailFilled,
+        blockedReason: 'Enter an email address before continuing.',
+      },
+      { id: 'plan', label: 'Plan', detail: 'Pick a tier' },
+      { id: 'team', label: 'Team', detail: 'Invite colleagues', optional: true },
+      { id: 'review', label: 'Review', detail: 'Confirm and start' },
+    ];
+  }
+
+  setNavigation = (v: string) => (this.navigation = v);
+  setRailVariant = (v: string) => (this.railVariant = v);
+  setSummary = (v: boolean) => (this.summary = v);
+  setBusy = (v: boolean) => (this.busy = v);
+  setEmailFilled = (v: boolean) => (this.emailFilled = v);
+
+  onStepChange = (index: number) => {
+    this.activeIndex = index;
+    this.lastEvent = 'moved to step ' + (index + 1);
+  };
+  onComplete = () => (this.lastEvent = 'completed');
+  onRefused = (index: number) =>
+    (this.lastEvent = 'refused at step ' + (index + 1));
+
+  get navigationValue() {
+    return this.navigation as 'linear' | 'visited' | 'free';
+  }
+  get railVariantValue() {
+    return this.railVariant as 'steps' | 'track';
+  }
+  get usage() {
+    return "<Wizard @steps={{this.steps}} @activeIndex={{this.i}} @navigation='" +
+      this.navigation +
+      "' @onStepChange={{this.go}} @onComplete={{this.done}} as |step index api| />";
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Wizard'
+      @description='A gated multi-step flow: a step model that declares its own validity, a footer that refuses forward movement and says why, and a progress rail that is StepList rather than a second copy of it. Turn the email switch off and press Next to see a refusal explain itself instead of greying out.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Wizard
+          @steps={{this.steps}}
+          @activeIndex={{this.activeIndex}}
+          @navigation={{this.navigationValue}}
+          @railVariant={{this.railVariantValue}}
+          @summary={{this.summary}}
+          @busy={{this.busy}}
+          @label='Set-up steps'
+          @onStepChange={{this.onStepChange}}
+          @onComplete={{this.onComplete}}
+          @onRefused={{this.onRefused}}
+        >
+          <:step as |step|>
+            <p class='pretui-demo-steptext'>
+              Panel for
+              {{step.label}}.
+              {{step.detail}}.
+            </p>
+          </:step>
+        </Wizard>
+        <p class='pretui-demo-readout' data-test-wizard-readout>
+          step
+          {{this.activeIndex}}
+          ·
+          {{this.lastEvent}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='activeIndex'
+          @defaultValue={{0}}
+          @value={{this.activeIndex}}
+          @description='Controlled index, range-checked against the step list. Omit and seed defaultActiveIndex for uncontrolled use.'
+        />
+        <Args.String
+          @name='navigation'
+          @defaultValue='visited'
+          @value={{this.navigation}}
+          @options={{this.navigations}}
+          @description='How freely a reader may move. linear is Back and Next only; visited allows returning to anywhere already reached; free allows anything. Forward movement always passes the active step gate, which is the fix for the upstream jump-past-invalid bug.'
+          @onInput={{this.setNavigation}}
+        />
+        <Args.Bool
+          @name='step.valid'
+          @defaultValue={{false}}
+          @value={{this.emailFilled}}
+          @description='Stands in here for the first step declaring itself valid. When false, Next is aria-disabled but still focusable and clickable, and activating it reveals the blockedReason in a live alert.'
+          @onInput={{this.setEmailFilled}}
+        />
+        <Args.String
+          @name='railVariant'
+          @defaultValue='steps'
+          @value={{this.railVariant}}
+          @options={{this.railVariants}}
+          @description='Forwarded straight to StepList — the rail is that component, not a reimplementation of it.'
+          @onInput={{this.setRailVariant}}
+        />
+        <Args.Bool
+          @name='summary'
+          @defaultValue={{false}}
+          @value={{this.summary}}
+          @description="Show StepList's derived completion summary above the rail."
+          @onInput={{this.setSummary}}
+        />
+        <Args.Bool
+          @name='busy'
+          @defaultValue={{false}}
+          @value={{this.busy}}
+          @description='An async commit is in flight — the primary shows its spinner and stops accepting pointer events.'
+          @onInput={{this.setBusy}}
+        />
+        <Args.Action
+          @name='onStepChange'
+          @description='Fires on every move, backwards included. The survey and stepper sources both bypassed this on the way back, so a consumer persisting progress lost every backwards move.'
+        />
+        <Args.Action
+          @name='onComplete'
+          @description='The terminal step primary commits rather than advancing, and only if the gate allows.'
+        />
+        <Args.Yield
+          @name='step'
+          @description='The active step content, receiving (step, index, api).'
+        />
+        <Args.Yield
+          @name='rail'
+          @description='Replaces the StepList rail entirely — this is where a clickable rail goes, and the api arrives with goTo and canGoTo already wired.'
+        />
+        <Args.Yield
+          @name='footer'
+          @description='Replaces the Back / Skip / Next footer.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-steptext {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      .pretui-demo-readout {
+        margin: var(--space-4, 12px) 0 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        font-variant-numeric: tabular-nums;
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_WIZARD: Record<string, unknown> = {
+  Wizard: WizardUsage,
+};

package/bundled-realms/pretui/components/work-item.gts

@@ -0,0 +1,207 @@
+// Pretui — WorkItem: one unit of agent work at three densities (step, action, run), with status text for every state.
+import Component from '@glimmer/component';
+import { ProgressBar } from './progress-bar';
+import { Spinner } from './spinner';
+
+type Tone = 'idle' | 'running' | 'attention' | 'done' | 'failed';
+const TONES: Record<string, Tone> = {
+  pending: 'idle', preparing: 'running', running: 'running', applying: 'running',
+  handoff: 'running', reconnecting: 'running', 'host-attached': 'running',
+  fallback: 'running', ready: 'attention', 'awaiting-approval': 'attention',
+  ask: 'attention', input: 'attention', completed: 'done', kept: 'done',
+  delivered: 'done', failed: 'failed', invalid: 'failed', reverted: 'idle',
+  canceled: 'idle',
+};
+const GLYPHS: Record<Tone, string> = { idle: '·', running: '', attention: '●', done: '✓', failed: '✕' };
+const DEFAULT_STATUS: Record<string, string> = {
+  pending: 'queued', preparing: 'preparing…', running: 'running…',
+  applying: 'applying…', handoff: 'handing off…', reconnecting: 'reconnecting…',
+  'host-attached': 'attached', fallback: 'fallback…', ready: '● needs you',
+  'awaiting-approval': '● needs you', ask: '● needs you', input: '● needs you',
+  completed: 'done', kept: 'kept', delivered: 'delivered', failed: 'failed',
+  invalid: 'invalid', reverted: 'reverted', canceled: 'canceled',
+};
+
+export interface WorkItemSignature {
+  Args: {
+    tier?: 'step' | 'action' | 'run';
+    state?: string;
+    verb?: string;
+    title: string;
+    status?: string;
+    progressValue?: number;
+    progressMax?: number;
+    count?: string;
+    activity?: string;
+  };
+  Blocks: { default: []; footer: [] };
+  Element: HTMLDivElement;
+}
+
+export class WorkItem extends Component<WorkItemSignature> {
+  get state() {
+    return this.args.state ?? 'pending';
+  }
+  get tone(): Tone {
+    return TONES[this.state] ?? 'idle';
+  }
+  get glyph() {
+    return GLYPHS[this.tone];
+  }
+  get isRunning() {
+    return this.tone === 'running';
+  }
+  get isAttention() {
+    return this.tone === 'attention';
+  }
+  get statusText() {
+    return this.args.status ?? DEFAULT_STATUS[this.state] ?? this.state;
+  }
+  get hasProgress() {
+    return this.args.progressValue !== undefined;
+  }
+  get progressValue() {
+    return this.args.progressValue ?? 0;
+  }
+  get countText() {
+    if (this.args.count) {
+      return this.args.count;
+    }
+    return `${this.progressValue} / ${this.args.progressMax ?? 100}`;
+  }
+  get hasBody() {
+    return this.hasProgress || this.args.activity;
+  }
+  <template>
+    <div
+      class='pretui-workitem'
+      data-tier={{if @tier @tier 'step'}}
+      data-state={{this.state}}
+      data-attention={{if this.isAttention 'true'}}
+      data-test-pretui-work-item
+      ...attributes
+    >
+      <div class='pretui-workitem-row'>
+        <span class='pretui-disc' data-tone={{this.tone}}>
+          {{#if this.isRunning}}<Spinner @size={{9}} />{{else}}{{this.glyph}}{{/if}}
+        </span>
+        {{#if @verb}}<span class='pretui-verb'>{{@verb}}</span>{{/if}}
+        <span class='pretui-workitem-title'>{{@title}}</span>
+        <span class='pretui-workitem-status' data-tone={{this.tone}}>{{this.statusText}}</span>
+      </div>
+      {{#if this.hasBody}}
+        <div class='pretui-workitem-body'>
+          {{#if this.hasProgress}}
+            <ProgressBar @value={{this.progressValue}} @max={{@progressMax}} @count={{this.countText}} />
+          {{/if}}
+          {{#if @activity}}<div class='pretui-activity'>{{@activity}}</div>{{/if}}
+          {{yield}}
+        </div>
+      {{else}}
+        {{yield}}
+      {{/if}}
+      {{yield to='footer'}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-workitem {
+          display: flex;
+          flex-direction: column;
+          background: var(--card);
+          border-radius: 10px;
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+          font-size: var(--text-ui-md, 12.5px);
+        }
+        .pretui-workitem[data-attention] {
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 60%, var(--border)),
+            0 2px 10px color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 14%, transparent);
+          background: linear-gradient(
+            180deg,
+            color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 7%, var(--card)),
+            var(--card) 55%
+          );
+        }
+        .pretui-workitem[data-state='failed'],
+        .pretui-workitem[data-state='invalid'] {
+          box-shadow: 0 0 0 1px color-mix(in oklch, var(--destructive) 45%, var(--border));
+        }
+        .pretui-workitem-row {
+          display: flex;
+          align-items: center;
+          gap: 9px;
+          padding: 7px 11px;
+          min-height: 32px;
+        }
+        .pretui-workitem-body {
+          padding: 0 11px 9px 36px;
+          display: flex;
+          flex-direction: column;
+          gap: 8px;
+        }
+        .pretui-disc {
+          width: 16px;
+          height: 16px;
+          border-radius: 50%;
+          display: grid;
+          place-items: center;
+          flex: none;
+          font-size: 9px;
+          font-weight: 700;
+          background: var(--inset, var(--boxel-100));
+          color: var(--muted-foreground);
+          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+        }
+        .pretui-disc[data-tone='failed'] {
+          background: color-mix(in oklch, var(--destructive) 15%, var(--card));
+          color: var(--pretui-destructive-ink, var(--boxel-danger));
+        }
+        .pretui-disc[data-tone='attention'] {
+          background: color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 22%, var(--card));
+          color: var(--pretui-attention-ink, var(--pretui-attention, var(--boxel-fuschia)));
+        }
+        .pretui-verb {
+          font-family: var(--font-mono);
+          font-size: 10px;
+          font-weight: 600;
+          letter-spacing: 0.06em;
+          color: var(--muted-foreground);
+          flex: none;
+        }
+        .pretui-workitem-title {
+          font-weight: 500;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+          min-width: 0;
+          flex: 1;
+        }
+        .pretui-workitem-status {
+          margin-left: auto;
+          flex: none;
+          font-size: var(--text-ui-sm, 11.5px);
+          color: var(--muted-foreground);
+          display: flex;
+          align-items: center;
+          gap: 6px;
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-workitem-status[data-tone='attention'] {
+          color: var(--pretui-attention-ink, var(--pretui-attention, var(--boxel-fuschia)));
+          font-weight: 600;
+        }
+        .pretui-workitem-status[data-tone='failed'] {
+          color: var(--pretui-destructive-ink, var(--boxel-danger));
+          font-weight: 500;
+        }
+        .pretui-activity {
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          color: var(--ink-3, var(--boxel-400));
+          white-space: nowrap;
+          overflow: hidden;
+          text-overflow: ellipsis;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/work-item.md

@@ -0,0 +1,58 @@
+## What it is
+
+The atom of the agentic territory: one unit of agent work, at one of three densities, showing its state in words. Use it for every step, action and run an agent reports. It is the row an agent transcript is made of; **Fold** nests them, **ApprovalFooter** gates them, **DiffBlock** shows what they changed, **ResultCard** shows what they produced.
+
+## The contract
+
+```
+@tier? 'step' | 'action' | 'run'
+@state?, @verb?, @title (required), @status?
+@progressValue?, @progressMax?, @count?, @activity?
+<:default>  <:footer>
+```
+
+**`@state` is an open string mapped through two tables, not an enum.** Nineteen states — `pending`, `preparing`, `running`, `applying`, `handoff`, `reconnecting`, `host-attached`, `fallback`, `ready`, `awaiting-approval`, `ask`, `input`, `completed`, `kept`, `delivered`, `failed`, `invalid`, `reverted`, `canceled` — collapse through `TONES` into five tones (`idle`, `running`, `attention`, `done`, `failed`), and through `DEFAULT_STATUS` into a default status phrase. So an agent reports its real state vocabulary and the UI does the collapsing, rather than every caller translating into a UI enum.
+
+**`@status` overrides the default phrase**, so a caller can say "applying 3 of 7" where the table would say "applying…".
+
+**`@tier` is density, not importance**: `step` is the quietest, `run` the loudest. That distinction is the territory's whole point — importance is carried by tone, containment by **Fold**'s indentation, and density by tier.
+
+## Prior art
+
+There is essentially no prior art. Radix, Web Awesome, React Spectrum and shadcn ship nothing for agent work, because the pattern is two years old. The recognisable references are product surfaces — Claude Code's tool-call rows, Cursor's composer steps, Devin's task list, GitHub Actions' step list — none of which is a component library.
+
+So the interesting comparison is against the design laws this territory states, and they are worth quoting as the actual specification:
+
+- **"Color never carries state alone: every state renders status text."** Every tone ships a phrase. There is no green-check-only row.
+- **"The attention hue is reserved for 'a human must act now'."** One colour in the whole territory means "you". `ready`, `awaiting-approval`, `ask` and `input` all render `● needs you` — the same four words, so the phrase is learnable.
+- **The glyph table has an empty string for `running`** — a running item shows a **Spinner**, not a character, because motion is the honest signal for in-progress and a static glyph is not.
+
+Where it is thin: no error detail slot (a `failed` item shows "failed" and whatever you put in `<:default>`), no retry affordance, no timing/duration display, and no cancel. Composer, TaskRow, Recommendation and the thinking-trace rail exist in the design mirror and are not translated yet.
+
+## Accessibility
+
+No APG pattern. The relevant criteria are WCAG **1.4.1 Use of Colour**, **4.1.3 Status Messages** and **2.2.2**.
+
+What is right, and it is unusually good for this kind of component:
+
+- **State is always text.** `1.4.1` is satisfied by construction, not by a lint rule — the tone is a color _and_ a phrase, and the phrase is not optional. Most agent UIs fail exactly here.
+- **The `● needs you` phrasing puts the meaning in words** rather than in the attention hue.
+- **Progress uses ProgressBar** rather than a bespoke bar, inheriting its role and value properties.
+
+Gaps, and the first is the big one:
+
+- **State changes are not announced.** A WorkItem going from `running` to `awaiting-approval` — the single most important transition in the territory, because it means the user must act — changes text silently. There is no live region anywhere in this component. For a transcript that updates while the user reads it, a `role="status"` region (existing in the DOM _before_ the change) reporting attention-state transitions is the highest-value addition to the whole territory. `assertive` for `attention` and `failed`, polite for the rest, mirroring **Alert**'s tone-driven role.
+- **The glyph characters are content.** `·`, `●`, `✓`, `✕` sit in the DOM and are announced — "middle dot", "black circle", "check mark" — before or after the status phrase, which is noise since the phrase already carries the meaning. They should be `aria-hidden`.
+- **The row has no grouping semantics.** Title, status, count and activity are sibling elements; a screen-reader user hears them as one run with no structure. `role="group"` with `aria-label` from the title, or a `<dl>`, would give it shape.
+- **No accessible name distinguishes the tiers.** A `step` and a `run` announce identically.
+- **`@activity` is a live-ish field** (what the agent is doing right now) with no live-region treatment.
+- **Progress with no `aria-valuemin`, no accessible name and no `aria-valuetext`** — see **ProgressBar**'s own note; the gaps travel.
+- The **Spinner** used for `running` carries `role="status"` and the label "Loading", so a running row may announce "Loading" alongside its own status phrase.
+
+## Theming
+
+Tone hues: the four semantic tokens plus the reserved attention hue (`--pretui-attention`), each driving ink and glyph. Surface and structure: `--card`, `--border`, `--muted-foreground`, `--foreground`, `--font-mono` (the verb voice), `--text-ui-*`. Progress: **ProgressBar**'s `--primary`/`--inset`.
+
+**The attention hue is the one token a theme must not reuse.** Its meaning in this territory is "a human must act now", and a theme that also uses it for a decorative accent destroys the signal. Everything else in the territory is deliberately quiet so that one color can be loud.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/work-item.usage.gts

@@ -0,0 +1,103 @@
+// Pretui — WorkItem usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { WorkItem } from './work-item';
+
+const WORK_TIERS = ['step', 'action', 'run'];
+
+const WORK_STATES = [
+  'pending',
+  'preparing',
+  'running',
+  'applying',
+  'handoff',
+  'reconnecting',
+  'host-attached',
+  'fallback',
+  'ready',
+  'awaiting-approval',
+  'ask',
+  'input',
+  'completed',
+  'kept',
+  'delivered',
+  'failed',
+  'invalid',
+  'reverted',
+  'canceled',
+];
+
+class WorkItemUsage extends GlimmerComponent {
+  @tracked tier = 'action';
+  @tracked state = 'awaiting-approval';
+  @tracked verb = 'EDIT';
+  @tracked title = 'menu.json — add two teas';
+  setTier = (v: string) => (this.tier = v);
+  setState = (v: string) => (this.state = v);
+  setVerb = (v: string) => (this.verb = v);
+  setTitle = (v: string) => (this.title = v);
+  get tierVal() {
+    return this.tier as 'step' | 'action' | 'run';
+  }
+  <template>
+    <FreestyleUsage
+      @name='WorkItem'
+      @description='The agentic work row at three densities (step / action / run) across the full state machine. Color never carries state alone — every state renders status text; the magenta attention treatment is reserved for "a human must act now".'
+    >
+      <:example>
+        <WorkItem
+          @tier={{this.tierVal}}
+          @state={{this.state}}
+          @verb={{this.verb}}
+          @title={{this.title}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='tier'
+          @value={{this.tier}}
+          @options={{WORK_TIERS}}
+          @defaultValue='step'
+          @description='Density: step (one line in a run), action (approvable work), run (a whole delegated session).'
+          @onInput={{this.setTier}}
+        />
+        <Args.String
+          @name='state'
+          @value={{this.state}}
+          @options={{WORK_STATES}}
+          @defaultValue='pending'
+          @description='The full state machine; each state maps to a tone (idle/running/attention/done/failed) and default status text.'
+          @onInput={{this.setState}}
+        />
+        <Args.String
+          @name='verb'
+          @value={{this.verb}}
+          @description='The mono VERB tier of the transmutation grammar (EDIT, RUN, SEARCH…).'
+          @onInput={{this.setVerb}}
+        />
+        <Args.String
+          @name='title'
+          @value={{this.title}}
+          @required={{true}}
+          @description='What the work is, in label terms.'
+          @onInput={{this.setTitle}}
+        />
+        <Args.Base
+          @name='progressValue / progressMax / count / activity'
+          @typeLabel='Number/String'
+          @description='Run-tier extras: progress bar, count text, and the mono activity line.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='default / footer'
+          @description='Body content (result cards, diffs) and the approval footer.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_WORK_ITEM: Record<string, unknown> = {
+  WorkItem: WorkItemUsage,
+};