@femtomc/mu-agent 26.2.108 → 26.2.110

package/README.md

@@ -27,6 +27,7 @@ They are organized as category meta-skills plus subskills:
 
 - `core`
   - `mu`
+  - `programmable-ui`
   - `memory`
   - `tmux`
   - `code-mode`
@@ -48,6 +49,7 @@ They are organized as category meta-skills plus subskills:
 
 Starter skills are version-synced by CLI bootstrap. Initial bootstrap seeds missing
 skills; bundled-version changes refresh installed starter skill files.
+Operator-facing workflow detail lives in the skill docs (for example, `core/programmable-ui`).
 
 ## Install
 
@@ -75,7 +77,7 @@ Current stack:
 
 - `brandingExtension` — mu compact header/footer branding + default theme
 - `eventLogExtension` — event tail + watch widget
-- `uiExtension` — programmable `UiDoc` surface (`/mu ui ...`, `mu_ui`) with terminal auto-prompt/awaiting behavior and deterministic action fallbacks
+- `uiExtension` — programmable `UiDoc` surface (`/mu ui ...`, `mu_ui`)
 
 Default operator UI theme is `mu-gruvbox-dark`.
 
@@ -86,24 +88,7 @@ Default operator UI theme is `mu-gruvbox-dark`.
 - `/mu brand on|off|toggle` — enable/disable UI branding
 - `/mu ui ...` — inspect interactive `UiDoc`s (`status`/`snapshot`)
 - `/mu help` — dispatcher catalog of registered `/mu` subcommands
-- `ctrl+shift+u` — reopen local programmable-UI interaction flow (in-TUI doc/action picker, auto-fill payload-backed template values, prompt unresolved values, submit composed prompt)
-
-## Programmable UI documents
-
-Skills can publish interactive UI state via the `mu_ui` tool. Rendered `UiDoc`s survive session reconnects
-(30 minute retention per session ID), respect revision/version bumps, and route action clicks/taps back to
-plain command text via `metadata.command_text` (the `/answer` flow is the reference pattern).
-
-Actions without `metadata.command_text` are treated as non-interactive and rendered as deterministic fallback rows.
-
-Current runtime behavior is channel-specific:
-
-- Slack renders rich blocks + interactive action buttons.
-- Discord/Telegram/Neovim render text-first docs; interactive actions are tokenized, while status-profile actions deterministically degrade to command-text fallback.
-- Terminal operator UI (`mu serve`) renders docs in-widget, auto-prompts when agent publishes new runnable actions, shows `awaiting` UI status/widget state until resolved, and supports manual reopen via `ctrl+shift+u` (in-TUI picker overlay + prompt composition).
-- When interactive controls cannot be rendered, adapters append deterministic text fallback.
-
-See the [Programmable UI substrate guide](../../docs/mu-ui.md) for the full support matrix and workflow.
+- `ctrl+shift+u` — reopen local programmable-UI interaction flow
 
 ## Tooling model (CLI-first)
 

package/dist/extensions/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/extensions/ui.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AA8+BpF,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,QA2N3C;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/extensions/ui.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,+BAA+B,CAAC;AAs/BpF,wBAAgB,WAAW,CAAC,EAAE,EAAE,YAAY,QA6N3C;AAED,eAAe,WAAW,CAAC"}

package/dist/extensions/ui.js

@@ -2,22 +2,29 @@ import { normalizeUiDocs, parseUiDoc, resolveUiStatusProfileName, uiStatusProfil
 import { matchesKey } from "@mariozechner/pi-tui";
 import { registerMuSubcommand } from "./mu-command-dispatcher.js";
 const UI_DISPLAY_DOCS_MAX = 16;
-const UI_WIDGET_COMPONENTS_MAX = 6;
-const UI_WIDGET_ACTIONS_MAX = 4;
 const UI_PICKER_COMPONENTS_MAX = 8;
 const UI_PICKER_LIST_ITEMS_MAX = 4;
 const UI_PICKER_KEYVALUE_ROWS_MAX = 4;
 const UI_SESSION_KEY_FALLBACK = "__mu_ui_active_session__";
 const UI_PROMPT_PREVIEW_MAX = 160;
 const UI_INTERACT_SHORTCUT = "ctrl+shift+u";
+const UI_INTERACT_OVERLAY_OPTIONS = {
+    anchor: "top-left",
+    row: 0,
+    col: 0,
+    width: "100%",
+    maxHeight: "100%",
+    margin: 0,
+};
 const STATE_BY_SESSION = new Map();
 const UI_STATE_TTL_MS = 30 * 60 * 1000; // keep session state for 30 minutes after last access
 function createState() {
     return {
         docsById: new Map(),
-        pendingPrompt: null,
+        pendingPrompts: [],
         promptedRevisionKeys: new Set(),
         awaitingUiIds: new Set(),
+        interactionDepth: 0,
     };
 }
 function pruneStaleStates(nowMs) {
@@ -78,6 +85,38 @@ function retainAwaitingUiIdsForActiveDocs(state) {
         }
     }
 }
+function retainPendingPromptsForActiveDocs(state) {
+    state.pendingPrompts = state.pendingPrompts.filter((pending) => {
+        const doc = state.docsById.get(pending.uiId);
+        if (!doc) {
+            return false;
+        }
+        if (pending.kind === "review") {
+            return isStatusProfileStatusVariant(doc);
+        }
+        const actions = runnableActions(doc);
+        if (actions.length === 0) {
+            return false;
+        }
+        if (!pending.actionId) {
+            return true;
+        }
+        return actions.some((action) => action.id === pending.actionId);
+    });
+}
+function removePendingPromptsForUiId(state, uiId) {
+    state.pendingPrompts = state.pendingPrompts.filter((pending) => pending.uiId !== uiId);
+}
+function enqueuePendingPrompt(state, pending) {
+    const duplicate = state.pendingPrompts.some((existing) => {
+        return (existing.kind === pending.kind &&
+            existing.uiId === pending.uiId &&
+            existing.actionId === pending.actionId);
+    });
+    if (!duplicate) {
+        state.pendingPrompts.push(pending);
+    }
+}
 function armAutoPromptForUiDocs(state, changedUiIds) {
     if (changedUiIds.length === 0) {
         return;
@@ -89,26 +128,30 @@ function armAutoPromptForUiDocs(state, changedUiIds) {
             changedDocs.push(doc);
         }
     }
-    const candidates = changedDocs.filter((doc) => {
-        if (runnableActions(doc).length === 0) {
-            return false;
-        }
-        return !state.promptedRevisionKeys.has(docRevisionKey(doc));
-    });
-    if (candidates.length === 0) {
+    const unpromptedDocs = changedDocs.filter((doc) => !state.promptedRevisionKeys.has(docRevisionKey(doc)));
+    if (unpromptedDocs.length === 0) {
         return;
     }
-    candidates.sort((left, right) => {
+    const byMostRecentRevision = (left, right) => {
         if (left.updated_at_ms !== right.updated_at_ms) {
             return right.updated_at_ms - left.updated_at_ms;
         }
         return left.ui_id.localeCompare(right.ui_id);
-    });
-    const doc = candidates[0];
-    const actions = runnableActions(doc);
-    const actionId = actions.length === 1 ? actions[0].id : undefined;
-    state.pendingPrompt = { uiId: doc.ui_id, actionId };
-    state.promptedRevisionKeys.add(docRevisionKey(doc));
+    };
+    const runnableCandidates = unpromptedDocs.filter((doc) => runnableActions(doc).length > 0).sort(byMostRecentRevision);
+    if (runnableCandidates.length > 0) {
+        const doc = runnableCandidates[0];
+        const actions = runnableActions(doc);
+        const actionId = actions.length === 1 ? actions[0].id : undefined;
+        enqueuePendingPrompt(state, { kind: "action", uiId: doc.ui_id, actionId });
+        state.promptedRevisionKeys.add(docRevisionKey(doc));
+    }
+    const statusCandidates = unpromptedDocs.filter((doc) => isStatusProfileStatusVariant(doc)).sort(byMostRecentRevision);
+    if (statusCandidates.length > 0) {
+        const doc = statusCandidates[0];
+        enqueuePendingPrompt(state, { kind: "review", uiId: doc.ui_id });
+        state.promptedRevisionKeys.add(docRevisionKey(doc));
+    }
 }
 function preferredDocForState(state, candidate) {
     const existing = state.docsById.get(candidate.ui_id);
@@ -122,6 +165,23 @@ function preferredDocForState(state, candidate) {
 function awaitingDocs(state, docs) {
     return docs.filter((doc) => state.awaitingUiIds.has(doc.ui_id) && runnableActions(doc).length > 0);
 }
+function beginUiInteraction(ctx, state) {
+    state.interactionDepth += 1;
+    refreshUi(ctx);
+}
+function endUiInteraction(ctx, state) {
+    state.interactionDepth = Math.max(0, state.interactionDepth - 1);
+    refreshUi(ctx);
+}
+async function withUiInteraction(ctx, state, run) {
+    beginUiInteraction(ctx, state);
+    try {
+        return await run();
+    }
+    finally {
+        endUiInteraction(ctx, state);
+    }
+}
 function short(text, max = 64) {
     const normalized = text.replace(/\s+/g, " ").trim();
     if (normalized.length <= max) {
@@ -430,9 +490,11 @@ function boundedIndex(index, length) {
 function pickerComponentLines(component) {
     switch (component.kind) {
         case "text":
-            return [`text · ${component.text}`];
+            return [component.text];
         case "list": {
-            const lines = [`list${component.title ? ` · ${component.title}` : ""}`];
+            const title = component.title?.trim();
+            const prefix = title && title.length > 0 ? `${title} · ` : "";
+            const lines = [`${prefix}${component.items.length} item(s)`];
             const visible = component.items.slice(0, UI_PICKER_LIST_ITEMS_MAX);
             for (const item of visible) {
                 const detail = item.detail ? ` — ${item.detail}` : "";
@@ -444,7 +506,9 @@ function pickerComponentLines(component) {
             return lines;
         }
         case "key_value": {
-            const lines = [`key_value${component.title ? ` · ${component.title}` : ""}`];
+            const title = component.title?.trim();
+            const prefix = title && title.length > 0 ? `${title} · ` : "";
+            const lines = [`${prefix}${component.rows.length} row(s)`];
             const visible = component.rows.slice(0, UI_PICKER_KEYVALUE_ROWS_MAX);
             for (const row of visible) {
                 lines.push(`${row.key}: ${row.value}`);
@@ -455,7 +519,7 @@ function pickerComponentLines(component) {
             return lines;
         }
         case "divider":
-            return ["divider"];
+            return ["—"];
         default:
             return ["component"];
     }
@@ -636,18 +700,14 @@ async function pickUiActionInteractively(opts) {
         initialActionId: opts.actionId,
     }), {
         overlay: true,
-        overlayOptions: {
-            anchor: "center",
-            width: "78%",
-            maxHeight: "70%",
-            margin: 1,
-        },
+        overlayOptions: UI_INTERACT_OVERLAY_OPTIONS,
     });
     return selected ?? null;
 }
 function applyUiAction(params, state) {
     retainPromptedRevisionKeysForActiveDocs(state);
     retainAwaitingUiIdsForActiveDocs(state);
+    retainPendingPromptsForActiveDocs(state);
     const docs = activeDocs(state);
     const awaitingCount = awaitingDocs(state, docs).length;
     switch (params.action) {
@@ -690,6 +750,7 @@ function applyUiAction(params, state) {
             }
             retainPromptedRevisionKeysForActiveDocs(state);
             retainAwaitingUiIdsForActiveDocs(state);
+            retainPendingPromptsForActiveDocs(state);
             return {
                 ok: true,
                 action: params.action,
@@ -713,6 +774,7 @@ function applyUiAction(params, state) {
             }
             retainPromptedRevisionKeysForActiveDocs(state);
             retainAwaitingUiIdsForActiveDocs(state);
+            retainPendingPromptsForActiveDocs(state);
             return {
                 ok: true,
                 action: "replace",
@@ -732,17 +794,16 @@ function applyUiAction(params, state) {
             if (!state.docsById.delete(uiId)) {
                 return { ok: false, action: "remove", message: `UI doc not found: ${uiId}` };
             }
-            if (state.pendingPrompt?.uiId === uiId) {
-                state.pendingPrompt = null;
-            }
+            removePendingPromptsForUiId(state, uiId);
             state.awaitingUiIds.delete(uiId);
             retainPromptedRevisionKeysForActiveDocs(state);
             retainAwaitingUiIdsForActiveDocs(state);
+            retainPendingPromptsForActiveDocs(state);
             return { ok: true, action: "remove", message: `UI doc removed: ${uiId}` };
         }
         case "clear":
             state.docsById.clear();
-            state.pendingPrompt = null;
+            state.pendingPrompts = [];
             state.promptedRevisionKeys.clear();
             state.awaitingUiIds.clear();
             return { ok: true, action: "clear", message: "UI docs cleared." };
@@ -763,61 +824,6 @@ function buildToolResult(opts) {
     };
     return result;
 }
-function renderDocPreview(theme, doc, opts) {
-    const lines = [];
-    const headerParts = [theme.fg("accent", doc.title), theme.fg("muted", `[${doc.ui_id}]`)];
-    if (opts.awaitingResponse) {
-        headerParts.push(theme.fg("accent", "awaiting-response"));
-    }
-    lines.push(headerParts.join(" "));
-    if (doc.summary) {
-        lines.push(theme.fg("muted", short(doc.summary, 80)));
-    }
-    if (opts.awaitingCount > 0) {
-        lines.push(theme.fg("accent", `Awaiting user response for ${opts.awaitingCount} UI doc(s).`));
-    }
-    const components = doc.components.slice(0, UI_WIDGET_COMPONENTS_MAX);
-    if (components.length > 0) {
-        lines.push(theme.fg("dim", "Components:"));
-        for (const component of components) {
-            lines.push(`  ${componentPreview(component)}`);
-        }
-    }
-    const interactiveActions = runnableActions(doc);
-    if (interactiveActions.length > 0) {
-        lines.push(theme.fg("muted", "Actions:"));
-        const visibleActions = interactiveActions.slice(0, UI_WIDGET_ACTIONS_MAX);
-        for (let idx = 0; idx < visibleActions.length; idx += 1) {
-            const action = visibleActions[idx];
-            lines.push(`  ${idx + 1}. ${action.label}`);
-        }
-        if (interactiveActions.length > visibleActions.length) {
-            lines.push(`  ... (+${interactiveActions.length - visibleActions.length} more actions)`);
-        }
-        if (opts.awaitingResponse) {
-            lines.push(theme.fg("accent", "Awaiting your response. Select an action to continue."));
-        }
-        lines.push(theme.fg("dim", `Press ${UI_INTERACT_SHORTCUT} to compose and submit a prompt from actions.`));
-    }
-    else {
-        lines.push(theme.fg("dim", "No interactive actions."));
-    }
-    return lines;
-}
-function componentPreview(component) {
-    const { kind } = component;
-    switch (kind) {
-        case "text":
-            return `text · ${short(component.text, 80)}`;
-        case "list":
-            return `list · ${component.title ?? kind} · ${component.items.length} item(s)`;
-        case "key_value":
-            return `key_value · ${component.title ?? kind} · ${component.rows.length} row(s)`;
-        case "divider":
-            return "divider";
-    }
-    return kind;
-}
 function refreshUi(ctx) {
     const key = sessionKey(ctx);
     const state = ensureState(key);
@@ -833,39 +839,33 @@ function refreshUi(ctx) {
     }
     const awaiting = awaitingDocs(state, docs);
     const labels = docs.map((doc) => doc.ui_id).join(", ");
+    const readiness = state.interactionDepth > 0
+        ? ctx.ui.theme.fg("accent", "prompting")
+        : awaiting.length > 0
+            ? ctx.ui.theme.fg("accent", `awaiting ${awaiting.length}`)
+            : ctx.ui.theme.fg("dim", "ready");
     ctx.ui.setStatus("mu-ui", [
         ctx.ui.theme.fg("dim", "ui"),
         ctx.ui.theme.fg("muted", "·"),
         ctx.ui.theme.fg("accent", `${docs.length}`),
         ctx.ui.theme.fg("muted", "·"),
-        awaiting.length > 0
-            ? ctx.ui.theme.fg("accent", `awaiting ${awaiting.length}`)
-            : ctx.ui.theme.fg("dim", "ready"),
+        readiness,
         ctx.ui.theme.fg("muted", "·"),
         ctx.ui.theme.fg("text", labels),
     ].join(" "));
-    const primaryDoc = awaiting[0] ?? docs[0];
-    ctx.ui.setWidget("mu-ui", renderDocPreview(ctx.ui.theme, primaryDoc, {
-        awaitingResponse: state.awaitingUiIds.has(primaryDoc.ui_id),
-        awaitingCount: awaiting.length,
-    }), { placement: "belowEditor" });
+    ctx.ui.setWidget("mu-ui", undefined);
 }
 export function uiExtension(pi) {
     const commandUsage = "/mu ui status|snapshot [compact|multiline]|interact [ui_id [action_id]]";
     const usage = `Usage: ${commandUsage}`;
-    const runUiActionFromDoc = async (ctx, state, uiId, actionId) => {
+    const runUiActionFromDoc = async (ctx, state, uiId, actionId) => withUiInteraction(ctx, state, async () => {
         const docs = activeDocs(state, UI_DISPLAY_DOCS_MAX);
         if (docs.length === 0) {
             ctx.ui.notify("No UI docs are currently available.", "info");
             return;
         }
-        const entries = docs
-            .map((doc) => ({ doc, actions: runnableActions(doc) }))
-            .filter((entry) => entry.actions.length > 0);
-        if (entries.length === 0) {
-            ctx.ui.notify("No runnable UI actions are currently available.", "error");
-            return;
-        }
+        const entries = docs.map((doc) => ({ doc, actions: runnableActions(doc) }));
+        const runnableEntries = entries.filter((entry) => entry.actions.length > 0);
         let selectedDoc = null;
         let selectedAction = null;
         const normalizedUiId = uiId?.trim() ?? "";
@@ -892,14 +892,19 @@ export function uiExtension(pi) {
                 actionId: normalizedActionId.length > 0 ? normalizedActionId : undefined,
             });
             if (!picked) {
-                ctx.ui.notify("UI interaction cancelled.", "info");
+                if (runnableEntries.length > 0) {
+                    ctx.ui.notify("UI interaction cancelled.", "info");
+                }
                 return;
             }
             selectedDoc = picked.doc;
             selectedAction = picked.action;
         }
         if (!selectedDoc || !selectedAction) {
-            ctx.ui.notify("No UI action was selected.", "error");
+            if (runnableEntries.length === 0) {
+                return;
+            }
+            ctx.ui.notify("No UI action was selected.", "info");
             return;
         }
         const commandText = actionCommandText(selectedAction);
@@ -938,12 +943,11 @@ export function uiExtension(pi) {
         }
         pi.sendUserMessage(finalPrompt);
         state.awaitingUiIds.delete(selectedDoc.ui_id);
-        if (state.pendingPrompt?.uiId === selectedDoc.ui_id) {
-            state.pendingPrompt = null;
-        }
+        removePendingPromptsForUiId(state, selectedDoc.ui_id);
         retainAwaitingUiIdsForActiveDocs(state);
+        retainPendingPromptsForActiveDocs(state);
         ctx.ui.notify(`Submitted prompt from ${selectedDoc.ui_id}/${selectedAction.id}.`, "info");
-    };
+    });
     registerMuSubcommand(pi, {
         subcommand: "ui",
         summary: "Inspect and manage interactive UI docs",
@@ -982,7 +986,7 @@ export function uiExtension(pi) {
         },
     });
     pi.registerShortcut(UI_INTERACT_SHORTCUT, {
-        description: "Interact with programmable UI docs and submit prompt",
+        description: "Open programmable UI modal and optionally submit prompt",
         handler: async (ctx) => {
             const key = sessionKey(ctx);
             const state = ensureState(key);
@@ -1033,12 +1037,14 @@ export function uiExtension(pi) {
         }
         const key = sessionKey(ctx);
         const state = ensureState(key);
-        const pending = state.pendingPrompt;
+        retainPendingPromptsForActiveDocs(state);
+        const pending = state.pendingPrompts.shift();
         if (!pending) {
             return;
         }
-        state.pendingPrompt = null;
-        ctx.ui.notify(`Agent requested input via ${pending.uiId}. Submit now or press ${UI_INTERACT_SHORTCUT} later.`, "info");
+        if (pending.kind === "action") {
+            ctx.ui.notify(`Agent requested input via ${pending.uiId}. Submit now or press ${UI_INTERACT_SHORTCUT} later.`, "info");
+        }
         await runUiActionFromDoc(ctx, state, pending.uiId, pending.actionId);
         refreshUi(ctx);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@femtomc/mu-agent",
-	"version": "26.2.108",
+	"version": "26.2.110",
 	"description": "Shared operator runtime for mu assistant sessions and serve extensions.",
 	"keywords": [
 		"mu",
@@ -25,7 +25,7 @@
 		"themes/**"
 	],
 	"dependencies": {
-		"@femtomc/mu-core": "26.2.108",
+		"@femtomc/mu-core": "26.2.110",
 		"@mariozechner/pi-agent-core": "^0.54.2",
 		"@mariozechner/pi-ai": "^0.54.2",
 		"@mariozechner/pi-coding-agent": "^0.54.2",

package/prompts/skills/core/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: core
-description: "Meta-skill for core mu operating primitives. Routes to mu, memory, tmux, and code-mode based on task shape."
+description: "Meta-skill for core mu operating primitives. Routes to mu, programmable-ui, memory, tmux, and code-mode based on task shape."
 ---
 
 # core
@@ -10,6 +10,7 @@ Use this meta-skill when the user asks for general `mu` operation guidance and y
 ## Subskills
 
 - `mu` — default CLI-first operating workflow (inspect, mutate, verify, handoff).
+- `programmable-ui` — canonical `mu_ui`/`UiDoc` workflow for publishing, inspecting, and debugging interactive UI docs.
 - `memory` — prior-context retrieval, timeline reconstruction, and memory-index maintenance.
 - `tmux` — persistent terminal/session substrate for bounded command execution and fan-out.
 - `code-mode` — tmux-backed REPL loops for iterative execution and context compression.
@@ -17,12 +18,14 @@ Use this meta-skill when the user asks for general `mu` operation guidance and y
 ## Selection guide
 
 1. Start with `mu` for most day-to-day operator work.
-2. Add `memory` when prior context or timeline anchors are required.
-3. Add `tmux` when durable shell state or parallel worker shells are needed.
-4. Add `code-mode` when solving by live execution is cheaper than chat-only reasoning.
+2. Route to `programmable-ui` when the user asks about `mu_ui`, `/mu ui ...`, `UiDoc` payloads, action wiring, or interactive prompt behavior.
+3. Add `memory` when prior context or timeline anchors are required.
+4. Add `tmux` when durable shell state or parallel worker shells are needed.
+5. Add `code-mode` when solving by live execution is cheaper than chat-only reasoning.
 
 ## Common patterns
 
 - **Bounded investigation**: Use `mu` commands (`get`, `read`, `health`) to inspect current state, then use `memory` to find "when did this last work?" before attempting a fix.
+- **Programmable UI scaffolding**: Route to `programmable-ui` to emit schema-valid `UiDoc` templates quickly, verify state with `/mu ui status|snapshot`, and close docs with `mu_ui remove|clear`.
 - **Context compression**: If a user asks for complex debugging that involves running code and printing huge errors, route to `code-mode`. The agent can spin up a REPL, iterate on a fix offline, and return only the root cause to the chat.
 - **Parallel fan-out**: If a command takes a long time, or needs to run across multiple directories, route to `tmux` to spawn parallel worker shells, keep them running in the background, and periodically read their output.

package/prompts/skills/core/mu/SKILL.md

@@ -224,6 +224,7 @@ Keep operator↔human communication mu_ui-first across these skills:
 - one non-interactive status doc per active profile (`metadata.profile.variant: "status"`)
 - separate interactive prompt docs for decisions (`metadata.command_text` actions)
 - explicit `mu_ui remove` teardown for resolved prompts and completed passes
+For focused `UiDoc` schema templates/action wiring/status diagnostics, use `programmable-ui`.
 For REPL-driven exploration and context compression, use `code-mode`.
 For persistent terminal sessions and worker fan-out mechanics, use `tmux`.
 For recurring bounded automation loops, use `heartbeats`.
@@ -247,6 +248,7 @@ For wall-clock schedules (one-shot, interval, cron-expression), use `crons`.
 
 - Prior-context retrieval and index maintenance: **`memory`**
 - Planning/decomposition and DAG review: **`planning`**
+- Programmable UI schema/templates/action-routing diagnostics: **`programmable-ui`**
 - mu_ui-first status/prompt communication patterns for DAG work: **`planning`**, **`execution`**, **`control-flow`**, **`model-routing`**
 - Shared DAG semantics for planning + execution: **`protocol`**
 - Loop/termination policy overlays (review gates, retries, escalation): **`control-flow`**

package/prompts/skills/core/programmable-ui/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: programmable-ui
+description: "Builds and debugs mu_ui UiDocs with schema-valid payloads, interaction wiring, and status/snapshot verification."
+---
+
+# programmable-ui
+
+Use this skill when the task involves `mu_ui`, `UiDoc` payloads, interactive actions, or `/mu ui ...` inspection commands.
+
+## Contents
+
+- [Core contract](#core-contract)
+- [60-second quickstart](#60-second-quickstart)
+- [UiDoc schema cheat sheet](#uidoc-schema-cheat-sheet)
+- [mu_ui action semantics](#mu_ui-action-semantics)
+- [Canonical templates](#canonical-templates)
+- [Status-profile rules](#status-profile-rules)
+- [Debugging playbook](#debugging-playbook)
+- [Verify and teardown checklist](#verify-and-teardown-checklist)
+- [Evaluation scenarios](#evaluation-scenarios)
+
+## Core contract
+
+1. **Publish schema-valid docs only**
+   - `mu_ui` accepts `doc: object`, but runtime validation is strict (`UiDoc` schema).
+   - Invalid payloads fail with `Invalid UiDoc.`.
+
+2. **Keep interaction command-driven**
+   - Interactive actions must set `action.metadata.command_text` (for example `/answer yes`).
+   - User clicks/taps are translated back into normal command turns.
+
+3. **Separate status and decisions**
+   - Keep one non-interactive status doc per active profile (`metadata.profile.variant: "status"`).
+   - Use separate interactive docs for user decisions.
+
+4. **Use monotonic revisions**
+   - Increment `revision.version` on each update for the same `ui_id`.
+   - Replays/reconnects keep the highest revision deterministically.
+
+5. **Read -> act -> verify**
+   - After each `set|update|replace|remove|clear`, check `/mu ui status` and `/mu ui snapshot`.
+
+6. **Close docs explicitly**
+   - Resolve prompts with `mu_ui remove` (preferred) or `mu_ui clear`.
+
+## 60-second quickstart
+
+1. Publish one interactive doc:
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:demo",
+    "title": "Demo",
+    "summary": "Minimal interactive panel",
+    "components": [
+      { "kind": "text", "id": "intro", "text": "Choose an option", "metadata": {} }
+    ],
+    "actions": [
+      {
+        "id": "ack",
+        "label": "Acknowledge",
+        "kind": "primary",
+        "payload": { "choice": "ack" },
+        "metadata": { "command_text": "/answer ack" }
+      }
+    ],
+    "revision": { "id": "rev:demo:1", "version": 1 },
+    "updated_at_ms": 1,
+    "metadata": {}
+  }
+}
+```
+
+2. Verify live state:
+
+```text
+/mu ui status
+/mu ui snapshot compact
+/mu ui snapshot multiline
+```
+
+3. Handle command (`/answer ack`) in normal skill logic.
+
+4. Remove prompt doc:
+
+```json
+{ "action": "remove", "ui_id": "ui:demo" }
+```
+
+## UiDoc schema cheat sheet
+
+Required top-level fields for each doc:
+
+- `v`: `1`
+- `ui_id`: non-empty string (max 64)
+- `title`: non-empty string
+- `components`: non-empty array (`text|list|key_value|divider`)
+- `revision`: `{ id: string, version: nonnegative int }`
+- `updated_at_ms`: nonnegative integer
+
+Common optional fields (recommended):
+
+- `summary`: deterministic fallback summary
+- `actions`: interactive options (empty for pure status)
+- `metadata`: profile/snapshot metadata and custom annotations
+
+Component minimums:
+
+- `text`: `id`, `text`
+- `list`: `id`, `items[]` (`id`, `label`, optional `detail`, optional `tone`)
+- `key_value`: `id`, `rows[]` (`key`, `value`, optional `tone`)
+- `divider`: `id`
+
+Action minimums:
+
+- `id`, `label`
+- `metadata.command_text` required for interactive routing
+- optional: `kind`, `description`, `payload`, `component_id`, `callback_token`
+
+## mu_ui action semantics
+
+- `status`
+  - Returns count, `ui_id` list, status-profile counts/warnings, and awaiting counts.
+- `snapshot`
+  - `snapshot_format`: `compact|multiline` (defaults to `compact`).
+- `set`
+  - Upsert one doc by `ui_id`.
+- `update`
+  - Same behavior as `set` (single-doc upsert).
+- `replace`
+  - Replace entire active doc set with `docs[]`.
+- `remove`
+  - Remove one doc by `ui_id`.
+- `clear`
+  - Remove all docs for the session.
+
+## Canonical templates
+
+### 1) Interactive `/answer` prompt
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:answer",
+    "title": "Answer",
+    "summary": "Please choose yes or no",
+    "components": [
+      { "kind": "text", "id": "prompt", "text": "Choose an answer", "metadata": {} }
+    ],
+    "actions": [
+      {
+        "id": "answer_yes",
+        "label": "Yes",
+        "kind": "primary",
+        "payload": { "choice": "yes" },
+        "metadata": { "command_text": "/answer yes" }
+      },
+      {
+        "id": "answer_no",
+        "label": "No",
+        "kind": "secondary",
+        "payload": { "choice": "no" },
+        "metadata": { "command_text": "/answer no" }
+      }
+    ],
+    "revision": { "id": "rev:answer:1", "version": 1 },
+    "updated_at_ms": 1,
+    "metadata": {}
+  }
+}
+```
+
+Handler contract:
+
+1. Parse `/answer <choice>`.
+2. Validate choice.
+3. `mu_ui remove` (or `clear`) for `ui:answer`.
+4. Emit normal response.
+
+### 2) Status-profile doc (non-interactive)
+
+```json
+{
+  "action": "set",
+  "doc": {
+    "v": 1,
+    "ui_id": "ui:planning",
+    "title": "Planning status",
+    "summary": "Drafting issue DAG",
+    "components": [
+      {
+        "kind": "key_value",
+        "id": "kv",
+        "rows": [
+          { "key": "phase", "value": "decomposition" },
+          { "key": "next", "value": "approval prompt" }
+        ],
+        "metadata": {}
+      },
+      {
+        "kind": "list",
+        "id": "milestones",
+        "items": [
+          { "id": "m1", "label": "Root issue captured" },
+          { "id": "m2", "label": "Leaf tasks drafted" }
+        ],
+        "metadata": {}
+      }
+    ],
+    "actions": [],
+    "revision": { "id": "rev:planning:12", "version": 12 },
+    "updated_at_ms": 1730000000000,
+    "metadata": {
+      "profile": {
+        "id": "planning",
+        "variant": "status",
+        "snapshot": {
+          "compact": "planning: DAG draft ready",
+          "multiline": "phase: decomposition\nnext: approval prompt"
+        }
+      }
+    }
+  }
+}
+```
+
+### 3) Parameterized command text with payload defaults
+
+```json
+{
+  "id": "approve",
+  "label": "Approve",
+  "payload": { "choice": "approve", "note": "looks good" },
+  "metadata": { "command_text": "/answer choice={{choice}} note={{note}}" }
+}
+```
+
+In terminal UI interaction flow, placeholders are auto-filled from `payload` when possible, and unresolved fields are prompted.
+
+## Status-profile rules
+
+When `metadata.profile.id` is one of `planning|subagents|control-flow|model-routing` and variant is `status`:
+
+- expected `ui_id` values:
+  - `planning` -> `ui:planning`
+  - `subagents` -> `ui:subagents`
+  - `control-flow` -> `ui:control-flow`
+  - `model-routing` -> `ui:model-routing`
+- keep `actions: []` (status docs are non-interactive)
+- include `summary` plus `metadata.profile.snapshot.compact`
+- preferred components by profile:
+  - `planning`: `key_value` + `list`
+  - `subagents`: `key_value` + `list`
+  - `control-flow`: `key_value`
+  - `model-routing`: `key_value` + `list`
+
+Use `/mu ui status` to catch profile warnings early.
+
+## Debugging playbook
+
+- **`doc is required`**
+  - Missing `doc` parameter for `set|update`.
+- **`Invalid UiDoc.`**
+  - Schema mismatch. Re-check required fields and component/action shapes.
+- **`docs must be an array` / `docs[i]: invalid UiDoc`**
+  - `replace` payload malformed.
+- **Action appears but cannot run**
+  - Missing/empty `metadata.command_text`, or status-profile doc (actions intentionally non-runnable).
+- **`awaiting` stays non-zero**
+  - Prompt doc still active. Remove with `mu_ui remove` once handled.
+
+## Verify and teardown checklist
+
+After each change:
+
+1. `/mu ui status` shows expected doc count and ids.
+2. `/mu ui snapshot compact` shows deterministic summary.
+3. `/mu ui snapshot multiline` shows readable panel/action projection.
+4. Prompt resolved? Remove/clear doc explicitly.
+5. Keep issue/forum truth in sync; `mu_ui` is communication state, not source-of-truth task state.
+
+## Evaluation scenarios
+
+1. **First-time interactive prompt**
+   - Publish `ui:answer`, click action, confirm `/answer ...` reaches normal handler, remove prompt doc.
+
+2. **Status + decision split**
+   - Keep `ui:planning` status-profile doc active; open separate interactive approval doc; verify status remains non-interactive.
+
+3. **Replay/reconnect safety**
+   - Publish revisions 1 then 2; replay stale rev 1; verify highest revision remains active.
+
+4. **Channel degrade resilience**
+   - Ensure every actionable row has deterministic `command_text` fallback so manual command entry always works.