ui-components

Purpose

The same way snappy-os compounds knowledge through skills, the snappy-chat surface compounds UI through registered tool-component pairs. The chat is not just a transcript - it is the agent's affordance layer. Every new shape we register (a progress list, a working-folder pill row, an inline feedback form) is one more thing an agent can emit into the conversation without code changes to the framework.

Robert's framing (load-bearing): "the same way that the Snappy system is expanding its knowledge, it can also expand its own UI/UX. It could also be part of its own same system to solve that problem for us."

Today the surface knows ONE shape: DispatchCard (registered in web/src/dispatch-card.tsx, emitted by state/bin/head-screen/server.ts when intent matches the compose regex). Anything else falls through to a debug <pre>. This skill IS the recipe for adding the next shape - the authoring contract, the five canonical shapes worth shipping next, and the anti-patterns that will burn you.

The pattern (server/client contract)

snappy-chat consumes AG-UI events via agUIAdapter() from @openuidev/react-headless. Component registration happens through a custom assistantMessage renderer that inspects message.toolCalls and dispatches on tc.function?.name.

1. Server emits a TOOL_CALL triple inside the SSE stream

From state/bin/head-screen/server.ts:6081-6083 (the live emitter):

writeAgUI({ type: "TOOL_CALL_START", toolCallId, toolCallName: "DispatchCard" });
writeAgUI({ type: "TOOL_CALL_ARGS",  toolCallId, delta: argsBlob });
writeAgUI({ type: "TOOL_CALL_END",   toolCallId });

• toolCallId is tc-${randomUUID()} - must be unique per call.
• toolCallName MUST exactly match the React component the client registered.
• delta is a JSON string. One emit is fine; multiple deltas concat. The

client parses tc.function?.arguments once after TOOL_CALL_END.

• The triple sits between RUN_STARTED and RUN_FINISHED inside the

text/event-stream response.

2. Client renders the component when it sees a known tool name

From web/src/dispatch-card.tsx:268-283 (the dispatch site):

{toolCalls.map((tc) => {
  const name = tc.function?.name;
  const rawArgs = tc.function?.arguments ?? "";
  if (name === "DispatchCard") {
    const parsed = parseArgs(rawArgs);
    if (parsed) return <DispatchCard key={tc.id} toolCallId={tc.id} args={parsed} />;
  }
  // Unknown tool name → debug fallback so authors notice the mismatch.
  return <div key={tc.id} className="dispatch-card dispatch-card-debug">…</div>;
})}

The assistantMessage prop on <FullScreen> (web/src/App.tsx:174) is where the renderer gets wired:

<FullScreen
  streamProtocol={agUIAdapter()}
  assistantMessage={GenAssistantMessage}
  …
/>

3. User interaction flows back via the bridge, not React state

The component sends events through window.bridge.send(...) and subscribes to results via window.bridge.on(...). Component state is local UI state only (in-flight, edit mode, optimistic resolution); the source of truth lives behind the bridge. See dispatch-card.tsx:96-111 for the round-trip pattern (dispatch.action out, dispatch.result in, 5s watchdog).

4. Force-remount on context switch

<FullScreen key={\chat-${bundle.path ?? "none"}\}> - bumping the key when the bundle changes guarantees stale tool-call state can't leak across contexts. Same trap exists in Crayon; same fix.

Component recipes

Eight canonical shapes. Prefer reusing one of these over inventing a new one.

1. DispatchCard (already shipped)

Verb / channel / draft / actions card. The pattern reference. Use whenever the agent has produced something that needs human approve / edit / reject before it leaves the machine.

interface DispatchCardArgs {
  intent: string;
  verb: string;        // "post" | "draft" | "send" | "compose" | "publish" | …
  channel: string;     // "linkedin" | "x" | "email" | "slack" | …
  draft: string;       // The prose to be approved.
  actions: string[];   // Subset of ["approve", "edit", "reject"].
}

Registration (web/src/dispatch-card.tsx, dispatched in GenAssistantMessage):

if (name === "DispatchCard") {
  const parsed = parseArgs(rawArgs);
  if (parsed) return <DispatchCard key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: pulse-up from the bottom of the chat lane; channel-tinted hairline; per-channel character counter. Resolved state collapses to a single status line.

2. ProgressList

Numbered live-step list with check / spinner / error icons. Use when an agent reports multi-step progress and the user wants to see the chain landing. Do NOT use for one-shot work (use prose) or for >12 steps (chunk into multiple lists).

interface ProgressListArgs {
  steps: Array<{
    id: string;
    label: string;
    status: "done" | "running" | "pending" | "error";
    detail?: string;        // optional one-line note
  }>;
  currentStepId?: string;   // for the spinner highlight
  title?: string;           // optional list header
}

Registration:

if (name === "ProgressList") {
  const parsed = parseProgressListArgs(rawArgs);
  if (parsed) return <ProgressList key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: each step fades-in as it lands; the running step has a slow spinner; errors flash once on transition.

3. WorkingFolder

A horizontal stack of file pills the agent is currently operating on. Use when the agent's reply will reference multiple files and the user benefits from seeing them as concrete pills (clickable opens in Finder via the bridge).

interface WorkingFolderArgs {
  files: Array<{
    path: string;
    kind: "doc" | "data" | "code" | "image";
    clickable?: boolean;    // default true
    label?: string;         // override the basename
  }>;
  caption?: string;         // e.g. "Operating on the loop journal"
}

Registration:

if (name === "WorkingFolder") {
  const parsed = parseWorkingFolderArgs(rawArgs);
  if (parsed) return <WorkingFolder key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Click → window.bridge.send("file.reveal", { path }).

4. ContextPanel

Collapsible section listing connectors (web search, browser, mounted bundles, MCP tools). Use when the agent wants to surface the capabilities in scope for the current turn - usually at the top of a long reply.

interface ContextPanelArgs {
  connectors: Array<{
    id: string;
    label: string;
    status: "on" | "off" | "loading";
    icon?: string;          // SF Symbol name or emoji fallback
    detail?: string;        // optional hover text
  }>;
  collapsedByDefault?: boolean;
}

Registration:

if (name === "ContextPanel") {
  const parsed = parseContextPanelArgs(rawArgs);
  if (parsed) return <ContextPanel key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Toggle → window.bridge.send("context.toggle", { id, next }) so Swift can wire the connector on/off without a full round-trip.

5. FeedbackForm

Inline form for the user to give the agent feedback in the moment. Use when the agent wants graded input (rating + free-text) before the next turn - e.g. after a draft is approved, or after a multi-step task completes.

interface FeedbackFormArgs {
  prompt: string;
  fields: Array<{
    id: string;
    label: string;
    type: "text" | "textarea" | "rating";
    required?: boolean;
    placeholder?: string;
    max?: number;            // for rating, default 5
  }>;
  submitLabel?: string;      // default "Send"
}

Registration:

if (name === "FeedbackForm") {
  const parsed = parseFeedbackFormArgs(rawArgs);
  if (parsed) return <FeedbackForm key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Submit → window.bridge.send("feedback.submit", { tool_call_id, fields }); the resolved state collapses to a single confirmation line so the chat transcript stays readable.

6. ImagePreview

Inline image card with click-to-zoom. Use whenever the agent has produced or wants to surface a single still image - generated artwork, screenshot, diagram, photo. The frame caps at 360px tall by default; clicking the frame expands it inline up to 80vh (no separate window).

interface ImagePreviewArgs {
  src: string;        // URL or data: URI
  alt?: string;
  caption?: string;   // optional sub-chip in the header
}

Registration:

if (name === "ImagePreview") {
  const parsed = parseImagePreviewArgs(rawArgs);
  if (parsed) return <ImagePreview key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: same blur-to-clear card-enter as DispatchCard. Click anywhere on the frame to toggle zoom - it does NOT open a new window or navigate away. No bridge round-trip; the image is local UI only.

7. VideoPreview

Inline HTML5 <video> with native controls. Use for short clips (≤60s) the agent generated or selected. Prefer ImagePreview when the asset is still - video has higher CPU cost on render.

interface VideoPreviewArgs {
  src: string;          // URL
  poster?: string;
  caption?: string;
  autoplay?: boolean;   // default false; when true the player is muted
}

Registration:

if (name === "VideoPreview") {
  const parsed = parseVideoPreviewArgs(rawArgs);
  if (parsed) return <VideoPreview key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Entrance: card-enter. Always renders with controls, preload="metadata", and playsInline. autoplay=true forces muted (browser autoplay policy requires muted to start). No bridge - the player is self-contained.

8. ConfirmDialog

Yes/no decision card. Use whenever the agent needs a single binary confirmation before proceeding - destructive ops, irreversible sends, state mutations the user might want to abort. Differs from DispatchCard in that there is no draft to edit; it's pure decision.

interface ConfirmDialogArgs {
  question: string;
  detail?: string;        // sub-line context
  confirmLabel?: string;  // default "Confirm"
  cancelLabel?: string;   // default "Cancel"
}

Registration:

if (name === "ConfirmDialog") {
  const parsed = parseConfirmDialogArgs(rawArgs);
  if (parsed) return <ConfirmDialog key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Click → window.bridge.send("confirm.answer", { tool_call_id, answer }) where answer is "confirm" | "cancel". Resolved state collapses to a single status line so the chat transcript stays clean (mirrors DispatchCard's resolved style).

9. AgentDetail

Inline read-only card surfacing a single snappy-os agent's canonical state (prompt, schedule, last tick, last output preview). Use whenever the user wants to see WHAT an agent is and what it last did without leaving the chat. The snappy-chat sidebar's Scheduled rows fire the matching intent ("show me agent <id>") when clicked, so the chat mirrors the cockpit's surface.

interface AgentDetailArgs {
  id: string;             // canonical agent id (state/agents/<id>.json)
  status: string;         // "running" | "paused" | "done" | "stopped"
  prompt?: string;        // the agent's full prompt body
  schedule_cron?: string | null;
  last_tick_at?: string | null;   // ISO timestamp
  last_output?: string | null;    // truncated server-side
}

Registration:

if (name === "AgentDetail") {
  const parsed = parseAgentDetailArgs(rawArgs);
  if (parsed) return <AgentDetail key={tc.id} toolCallId={tc.id} args={parsed} />;
}

Server emits when intent matches /show\s+me\s+agent\s+(\S+)|agent\s+(\S+)\s+(?:detail|status)/i. Pulls the record via state/lib/agents.ts → readAgent(id). No last_output truncation in the parser - server should pre-truncate or the client caps display at 480 characters. No bridge round-trip; pure read-only render.

How to add a new shape

1. Pick a stable name. PascalCase, no spaces. The name is the contract

between server and client and CANNOT change without a migration. Examples: ProgressList, WorkingFolder. Counter-examples: progress_list, Smaller Card.

1. Define the props interface in web/src/components/<name>.tsx. One

exported interface <Name>Args, one default-exported component function <Name>({ toolCallId, args }: { toolCallId: string; args: <Name>Args }) {…}. Mirror the DispatchCard shape so muscle memory works.

1. Register the dispatch. Add the if (name === "<Name>") { … } branch

to GenAssistantMessage in web/src/dispatch-card.tsx (or extract the dispatch into its own module once you have ≥3 shapes - refactor when the pain shows up, not before).

1. Add the server-side emitter. In state/bin/head-screen/server.ts (or

the dispatching skill that owns this surface), emit the TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END triple between RUN_STARTED and RUN_FINISHED. Use tc-${randomUUID()} for the id.

1. Verify with curl + visual check.

   curl -N -H 'content-type: application/json' \
     -d '{"intent":"<test prompt>", "threadId":"manual-test"}' \
     http://127.0.0.1:3147/dispatch/chat

You should see the triple in the SSE output. Then load the chat in the cockpit and confirm the component renders. If you see the dispatch-card-debug <pre> instead of your component, the name didn't match - go back to step 3.

1. Update this SKILL.md. Add the new shape to the "Component recipes"

section so the next subagent inherits it. This is the compounding step - skip it and the system forgets. (Per CONSTITUTION invariant #2, prose IS the code; documenting the new shape here is the registration.)

When to make a NEW shape vs reuse

Reuse first.

• "I need to show progress on a 4-step deploy" → ProgressList.
• "I need a smaller version of DispatchCard" → still DispatchCard, with a

compact: true prop. Adding it to the existing schema is cheap; minting a near-duplicate component costs you the next migration.

• "I need to show the agent's current files-in-scope" → WorkingFolder.
• "I need to show 12 video thumbnails the agent is choosing between" → NEW

shape. The data shape genuinely differs; props don't fit any existing recipe; entrance behavior is different (grid, not list).

Test: if the new prop set fits inside an existing recipe with ≤2 optional fields added, it's not a new shape.

Anti-patterns

These will burn you. Pulled from the equivalent traps in state/skills/crayon-sdk/gotchas.md and the live debug fallback in dispatch-card.tsx.

1. Component name in TOOL_CALL must EXACTLY match the registered name.

No fuzzy match, no case-insensitive lookup. dispatchcard != DispatchCard. The dispatch site is a literal string compare.

1. Always emit TOOL_CALL_END. If you forget, the parser keeps the call

open and the chat looks hung. Wrap the emit in a try/finally or use a single helper.

1. templateProps JSON parses lazily - never rely on partial deltas.

The client concatenates all delta strings and parses once. If you stream a half-JSON delta and never close, parse fails silently and the debug <pre> appears.

1. Don't put domain state in the component. Local UI state (in-flight,

edit mode, optimistic-resolved) is fine. Source of truth lives behind window.bridge. A component that owns state that should round-trip will desync the moment a second turn lands.

1. Bump <FullScreen key={…}> when context changes. Bundle path,

thread id, mode switch - anything that should reset the conversation. Otherwise stale toolCalls from the previous context render under the new context.

1. Don't ship a shape without adding it to this SKILL.md. A registered

component that only one author knows about isn't compounding - it's tribal knowledge. The doc IS the contract.

Eval

auto-shape - this is a prose-only skill. The eval grades:

1. Frontmatter shape (name, description, eval present and valid).
2. AGENTS.md loader present at state/skills/ui-components/AGENTS.md.
3. Reference-file integrity: pointers to web/src/dispatch-card.tsx,

web/src/App.tsx, and state/bin/head-screen/server.ts resolve.

A row lands in state/log/evals.ndjson whenever an agent invokes the loader and writes back via loader-feedback.log.

ui-components - loader

Per-turn rules for the ui-components skill. Full reference: state/skills/ui-components/SKILL.md. Do not skip these.

Critical Rules

• Name match is the contract. toolCallName in the server's TOOL_CALL_START MUST exactly equal the string the client checks for in GenAssistantMessage (case-sensitive, PascalCase). Mismatch = unknown name. As of round 7 (2026-04-28T21:04:26Z) the dispatcher renders null on unknown names - the chat shows nothing instead of a debug card. Silent fallback means a typo is invisible. Verify with the curl loopback below before claiming the shape is wired.
• Always emit TOOL_CALL_END. The triple is TOOL_CALL_START → one-or-more TOOL_CALL_ARGS → TOOL_CALL_END, all between RUN_STARTED and RUN_FINISHED. Skip the END and the parser keeps the call open and the chat looks hung. Wrap in a try/finally.
• Args parse is strict, single-shot. Round 7 made the dispatcher concatenate all delta strings then JSON.parse once after TOOL_CALL_END. Invalid JSON, missing required props, or wrong-type props → null render (no debug <pre>). Stream one delta whenever possible; if multiple, ensure their concatenation is a single complete JSON object. Don't ship half-objects expecting the next delta to complete them - the parser doesn't backtrack.
• LLM-driven emission is the primary path; regex matchers in state/bin/head-screen/server.ts are fallback only. Round 6 (2026-04-28T20:56:32Z) flipped the architecture: the model emits [[TOOL:Name]]{json}[[/TOOL]] markers in its text stream and the server lifts them into TOOL_CALL_* events. Server-side regex like intent.match(/show me agent .../) exists only for cases the model can't reach (pre-LLM dispatch, scripted tests). Author new shapes by teaching the model the marker grammar in the system prompt, NOT by adding regex branches.
• State lives behind the bridge, not in the component. Local UI state (in-flight, edit mode, optimistic resolution) is fine. Domain state round-trips via window.bridge.send(...) / window.bridge.on(...). Same pattern as DispatchCard's dispatch.action / dispatch.result.
• Reuse before invent - nine canonical shapes already cover the common cases. DispatchCard (verb/channel/draft/actions), ProgressList (numbered live steps), WorkingFolder (file pills), ContextPanel (connector list), FeedbackForm (graded input), ImagePreview (still + click-to-zoom), VideoPreview (HTML5 <video> controls), ConfirmDialog (binary yes/no), AgentDetail (read-only agent state). New shape only when prop schema genuinely differs (≥3 required fields don't fit any existing recipe with ≤2 optional additions). "Smaller version of X" = add a compact: true prop to X, not a new component.
• Update SKILL.md when you ship a new shape. Per CONSTITUTION invariant #2, prose IS the code; the new component recipe is registered in SKILL.md or it's tribal knowledge.
• Bump <FullScreen key={...}> on context switch. Bundle path, thread id, mode change - anything that should reset the conversation. Otherwise stale toolCalls from the previous context render under the new context. Same trap exists in Crayon; same fix.
• Sidebar Scheduled rows fire chat intents. Round 5 (2026-04-28T20:21:18Z) wired the snappy-chat sidebar's Scheduled rows to dispatch show me agent <id> on click, which the server matches and emits as an AgentDetail tool call. If you change the AgentDetail shape, also verify the sidebar click-handler's intent-template still parses cleanly server-side.
• TCC / screen-capture failures are out-of-scope for this skill. The 2026-04-29T01:23:56Z gap (peekaboo / screencapture failing from a tmux+claude --dangerously-skip-permissions chain because the responsible client at runtime resolves to claude.exe without Screen Recording grant, and no Peekaboo.app/Claude.app bridge socket exists) belongs to snappy-face / system TCC, not ui-components. Don't add component recipes to "fix" capture issues.

Commands

| ui dashboard | state/skills/ui-components/resources/ui.openui | |emit triple (server, inside SSE handler):

writeAgUI({ type: "TOOL_CALL_START", toolCallId: `tc-${randomUUID()}`, toolCallName: "<Name>" });
writeAgUI({ type: "TOOL_CALL_ARGS",  toolCallId, delta: JSON.stringify(args) });
writeAgUI({ type: "TOOL_CALL_END",   toolCallId });

|LLM-driven marker (preferred, taught via system prompt):

[[TOOL:Name]]{"prop":"value"}[[/TOOL]]

|register dispatch (client, in GenAssistantMessage, web/src/dispatch-card.tsx):

if (name === "<Name>") {
  const parsed = parse<Name>Args(rawArgs);   // strict JSON.parse + shape check
  if (parsed) return <<Name> key={tc.id} toolCallId={tc.id} args={parsed} />;
  return null;                                // unknown / invalid → null render
}

|verify (curl loopback, watch for the triple in SSE):

curl -N -H 'content-type: application/json' \
  -d '{"intent":"<test prompt>", "threadId":"manual-test"}' \
  http://127.0.0.1:3147/dispatch/chat

|reference files:

• web/src/dispatch-card.tsx - pattern reference (component + dispatcher + parsers)
• web/src/App.tsx:166-184 - <FullScreen> wiring + key remount trap
• state/bin/head-screen/server.ts:6061-6084 - server-side emit example
• web/src/sidebar.tsx - Scheduled rows that fire AgentDetail intents (round 5)

|nine canonical shapes (full schemas in SKILL.md § Component recipes):

• DispatchCard - { intent, verb, channel, draft, actions[] }
• ProgressList - { steps[{id,label,status,detail?}], currentStepId?, title? }
• WorkingFolder - { files[{path,kind,clickable?,label?}], caption? }
• ContextPanel - { connectors[{id,label,status,icon?,detail?}], collapsedByDefault? }
• FeedbackForm - { prompt, fields[{id,label,type,required?,placeholder?,max?}], submitLabel? }
• ImagePreview - { src, alt?, caption? }
• VideoPreview - { src, poster?, caption?, autoplay? } (autoplay forces muted)
• ConfirmDialog - { question, detail?, confirmLabel?, cancelLabel? }
• AgentDetail - { id, status, prompt?, schedule_cron?, last_tick_at?, last_output? }

|bridge events round-trip:

• dispatch.action / dispatch.result (DispatchCard)
• file.reveal (WorkingFolder click)
• context.toggle (ContextPanel)
• feedback.submit (FeedbackForm)
• confirm.answer (ConfirmDialog)
• ImagePreview / VideoPreview / AgentDetail / ProgressList: no bridge - pure render

|sub-references inside SKILL.md:

• "The pattern" - four-step server/client contract
• "Component recipes" - nine canonical shapes with full props schemas
• "How to add a new shape" - six-step authoring procedure
• "When to make a NEW shape vs reuse" - the ≤2-optional-fields test
• "Anti-patterns" - six traps with examples

|eval log: state/log/evals.ndjson (skill: "ui-components", eval_mode: shape)

Trigger keywords

The inject hook attaches this loader when the prompt mentions any of: ui-components, add a UI component, register a component, dynamic UI, tool call card, progress list, working folder, context panel, feedback form, image preview, video preview, confirm dialog, agent detail, crayon component, openui component, generative UI, assistantMessage, TOOL_CALL_START, [[TOOL:.

Self-Test

An agent reading this should correctly:

1. [ ] Emit the TOOL_CALL_START / TOOL_CALL_ARGS / TOOL_CALL_END triple between RUN_STARTED and RUN_FINISHED in the SSE stream
2. [ ] Use a PascalCase toolCallName that EXACTLY matches the client dispatch string in GenAssistantMessage (mismatch = silent null render, not debug card)
3. [ ] Stream args as ONE complete JSON object - concatenated deltas must parse via a single JSON.parse; partial objects fail-soft to null
4. [ ] Prefer teaching the model the [[TOOL:Name]]{json}[[/TOOL]] marker over adding a server-side regex branch (LLM-driven is primary, regex is fallback)
5. [ ] Reuse one of the nine canonical shapes (DispatchCard, ProgressList, WorkingFolder, ContextPanel, FeedbackForm, ImagePreview, VideoPreview, ConfirmDialog, AgentDetail) before minting a new one
6. [ ] Round-trip user interaction via window.bridge.send / window.bridge.on rather than holding domain state in the component
7. [ ] Bump <FullScreen key={...}> when bundle/thread/mode changes so prior-context tool-calls don't leak across
8. [ ] Update state/skills/ui-components/SKILL.md when shipping a new shape so the next subagent inherits it

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] ui-components: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] ui-components: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

• <slug> MUST be the literal folder name of this loader

(state/skills/<slug>/AGENTS.md). The class token between [ts] and : is the producer slug, the writeback class, AND the grade class - they must be equal so state/lib/controller-tune.ts can pair the brief.

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

• action_kind is the SECOND pairing predicate (added 2026-04-27, task #327).

Pick the value that describes what you actually did - same slug, different action_kind means the writeback satisfies a different brief layer:

• shape-ok - only frontmatter-shape verification passed (rare from

a human; usually emitted by the lint, not a loader echo)

• skill-ran - the skill ran end-to-end and an eval row landed

in state/log/evals.ndjson

• loader-rewritten - you EDITED this AGENTS.md inline (the FIXED case),

OR the regen drain rewrote it

• pattern-elevated - you promoted a recurring failure to a Critical Rule

(rule fix or new-skill scaffold) If you LOGGED (couldn't fix inline), omit action_kind - the inferrer will pick it up from your body keywords.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/ui-components/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.