@zq-silk/yui 0.7.1 → 0.8.2

package/dist/cli/commandCatalog.js

@@ -1,5 +1,5 @@
 import { supportedAgentAdapterIds } from "../agent/adapterCatalog.js";
-import { CONFIG_KEYS } from "../commands/configCommands.js";
+import { CONFIG_DEFINITIONS, CONFIG_DOMAINS, configDefinitionsForDomain } from "../config/configCatalog.js";
 function buildNode(input, parentPath = []) {
     const path = [...parentPath, input.name];
     const children = (input.children ?? []).map((child) => buildNode(child, path));
@@ -7,12 +7,16 @@ function buildNode(input, parentPath = []) {
     const usage = input.usage === undefined
         ? [`${path.join(" ")}${children.length > 0 && !executable ? " <command>" : ""}`]
         : typeof input.usage === "string" ? [input.usage] : [...input.usage];
+    const examples = input.examples === undefined
+        ? usage
+        : typeof input.examples === "string" ? [input.examples] : [...input.examples];
     return Object.freeze({
         name: input.name,
         path: Object.freeze(path),
         summary: input.summary,
         kind: children.length === 0 ? "leaf" : executable ? "hybrid" : "group",
         usage: Object.freeze(usage),
+        examples: Object.freeze(examples),
         sections: Object.freeze((input.sections ?? []).map((section) => Object.freeze({
             ...section,
             entries: Object.freeze([...section.entries])
@@ -37,49 +41,91 @@ function buildNode(input, parentPath = []) {
 function freezeRecord(record) {
     return Object.freeze(Object.fromEntries(Object.entries(record ?? {}).map(([key, values]) => [key, Object.freeze([...values])])));
 }
-const CONFIG_KEY_VALUES = [
-    { name: "time-zone", summary: "IANA timezone for human-facing timestamps (default: Asia/Shanghai)." },
-    { name: "reconciliation-interval-seconds", summary: "Recovery reconciliation interval, 5-300 seconds (default: 120)." },
-    { name: "leader-next-action", summary: "Leader next-action mode: display, warn, or enforce (default: display)." },
-    { name: "context-budget", summary: "Per-Session context token budget; set with --soft-tokens <n> --hard-tokens <n> (default: soft 100000 / hard 120000)." },
-    { name: "resources-gc-mode", summary: "Resource GC mode: report or quarantine (default: report)." },
-    { name: "resources-gc-auto-quarantine", summary: "Auto-quarantine terminal Task resources: true or false (default: false)." },
-    { name: "provider-retry-mode", summary: "Provider retry mode: off, shadow, or enforce (default: enforce)." },
-    { name: "provider-retry-adapters", summary: "Adapters with in-place retry: all, comma-separated adapter ids, or off (default: all)." },
-    { name: "provider-retry-max-window-ms", summary: "Total retry budget per Run lineage in milliseconds (default: 600000)." },
-    { name: "yield-receipt-replay", summary: "Replay committed yield receipts on resend: true or false (default: true)." },
-    { name: "tmux-bin", summary: "Path to the tmux binary (default: tmux)." },
-    { name: "git-bin", summary: "Path to the git binary (default: git)." },
-    { name: "telemetry-mode", summary: "Telemetry mode: legacy, dual, or bounded (default: legacy)." },
-    { name: "telemetry-terminal-keep", summary: "Telemetry terminal retention count (default: 200)." },
-    { name: "telemetry-run-cap", summary: "Telemetry per-run row cap (default: 50000)." },
-    { name: "review", summary: "Global WorkItem review rule; set with --role <global-role> --trigger <always|leader|final> [--finding-ledger <shadow|enforce>] [--delta-recheck <enabled|disabled>] (default: disabled)." }
-];
+const CONFIG_KEY_VALUES = CONFIG_DEFINITIONS.map((definition) => ({
+    name: definition.key,
+    summary: definition.summary,
+    takesEffect: definition.takesEffect
+}));
+const CONFIG_DOMAIN_SUMMARIES = {
+    system: "Configure Home-wide defaults and human-facing presentation.",
+    runtime: "Configure Controller recovery, concurrency, health, launch, delivery, and Provider retry policy.",
+    workflow: "Configure Leader convergence, context, and optional review policy.",
+    resources: "Configure resource garbage collection and quarantine policy.",
+    tools: "Configure tmux and optional diagnostic telemetry."
+};
+function durableConfigDomainNode(domain) {
+    const definitions = configDefinitionsForDomain(domain);
+    const keys = definitions.map(({ key }) => key);
+    const values = CONFIG_KEY_VALUES.filter(({ name }) => keys.includes(name));
+    const options = domain === "workflow"
+        ? [
+            "--soft-tokens", "--hard-tokens", "--role", "--trigger", "--finding-ledger",
+            "--delta-recheck", "--delta-recheck-max-lines", "--delta-recheck-max-files"
+        ]
+        : domain === "runtime"
+            ? ["--quiet-after-seconds", "--diagnostic-after-seconds", "--stall-after-seconds"]
+            : [];
+    return {
+        name: domain,
+        summary: CONFIG_DOMAIN_SUMMARIES[domain],
+        examples: [
+            `yui config ${domain} show`,
+            `yui config ${domain} set ${keys[0]} <value>`,
+            `yui config ${domain} clear ${keys[0]}`
+        ],
+        sections: [{ id: "manage", title: "Commands", entries: ["show", "set", "clear"] }],
+        children: [
+            { name: "show", summary: `Show effective ${domain} configuration.` },
+            {
+                name: "set",
+                summary: `Set one ${domain} configuration key.`,
+                usage: `yui config ${domain} set <key> <value...>`,
+                sections: [{ id: "keys", title: "Configuration keys", entries: keys }],
+                values,
+                options,
+                optionValues: domain === "workflow"
+                    ? {
+                        "--trigger": ["always", "leader", "final"],
+                        "--finding-ledger": ["shadow", "enforce"],
+                        "--delta-recheck": ["enabled", "disabled"]
+                    }
+                    : {}
+            },
+            {
+                name: "clear",
+                summary: `Reset one ${domain} configuration key to its default.`,
+                usage: `yui config ${domain} clear <key>`,
+                sections: [{ id: "keys", title: "Configuration keys", entries: keys }],
+                values
+            }
+        ]
+    };
+}
 const agentChildren = [
     {
         name: "add",
         summary: "Add a configured native Agent CLI.",
-        usage: "yui agent add <id> [--adapter <adapter>] --command <command> [--arg <arg> ...] [--env TARGET=PROCESS_NAME ...]",
+        usage: "yui config agent add <id> [--adapter <adapter>] --command <command> [--arg <arg> ...] [--env TARGET=PROCESS_NAME ...]",
         options: ["--adapter", "--command", "--arg", "--env"],
         optionValues: { "--adapter": supportedAgentAdapterIds() },
         executableOptions: ["--command"]
     },
     { name: "list", summary: "List configured Agents." },
-    { name: "show", summary: "Show one configured Agent.", usage: "yui agent show <id>" },
+    { name: "show", summary: "Show one configured Agent.", usage: "yui config agent show <id>" },
     {
         name: "capabilities",
         summary: "Probe one Agent CLI for runtime configuration options.",
-        usage: "yui agent capabilities <id>"
+        usage: "yui config agent capabilities <id>"
     },
     {
         name: "update",
         summary: "Update a configured Agent.",
-        usage: "yui agent update <id> [--adapter <adapter>] [--command <command>] [--arg <arg> ... | --clear-args] [--env TARGET=PROCESS_NAME ... | --clear-env]",
+        usage: "yui config agent update <id> [--adapter <adapter>] [--command <command>] [--arg <arg> ... | --clear-args] [--env TARGET=PROCESS_NAME ... | --clear-env]",
         options: ["--adapter", "--command", "--arg", "--clear-args", "--env", "--clear-env"],
         optionValues: { "--adapter": supportedAgentAdapterIds() },
         executableOptions: ["--command"]
     },
-    { name: "remove", summary: "Remove a configured Agent.", usage: "yui agent remove <id>" }
+    { name: "remove", summary: "Remove a configured Agent.", usage: "yui config agent remove <id>" }
 ];
 const roleProfileOptions = [
     "--description", "--responsibility", "--constraint",
@@ -114,67 +160,83 @@ const roleChildren = [
     {
         name: "add",
         summary: "Add a reusable global Role.",
-        usage: "yui role add <name> --agent <id> [Role and Agent settings]",
+        usage: "yui config role add <name> --agent <id> [Role and Agent settings]",
         options: ["--agent", "--workspace", ...roleProfileOptions, ...roleAgentOptions],
         optionValues: roleAgentOptionValues,
         fileOptions: ["--workspace"]
     },
     { name: "list", summary: "List global Roles." },
-    { name: "show", summary: "Show one global Role.", usage: "yui role show <name>" },
-    { name: "context", summary: "Load the exact authorized global Role context.", usage: "yui role context <name>" },
+    { name: "show", summary: "Show one global Role.", usage: "yui config role show <name>" },
     {
         name: "update",
         summary: "Update a global Role.",
-        usage: "yui role update <name> [profile options] [clear options]",
+        usage: "yui config role update <name> [profile options] [clear options]",
         options: ["--agent", "--workspace", ...roleProfileOptions, ...roleAgentOptions,
             ...roleProfileClearOptions, ...roleAgentClearOptions],
         optionValues: roleAgentOptionValues,
         fileOptions: ["--workspace"]
     },
-    { name: "remove", summary: "Remove a global Role.", usage: "yui role remove <name>" },
-    { name: "bind", summary: "Bind and activate an Agent for a global Role.", usage: "yui role bind <role> <agent-id>" },
-    { name: "unbind", summary: "Unbind a dormant Agent from a global Role.", usage: "yui role unbind <role> <agent-id>" },
-    { name: "enter", summary: "Enter a global Role's native session.", usage: "yui role enter <role>" },
+    { name: "remove", summary: "Remove a global Role.", usage: "yui config role remove <name>" },
+    { name: "bind", summary: "Bind and activate an Agent for a global Role.", usage: "yui config role bind <role> <agent-id>" },
+    { name: "unbind", summary: "Unbind a dormant Agent from a global Role.", usage: "yui config role unbind <role> <agent-id>" }
+];
+const globalSessionChildren = [
+    { name: "enter", summary: "Enter a global Role's native session.", usage: "yui session enter <role>" },
     {
-        name: "session",
-        summary: "Manage native session IDs for a global Role.",
-        sections: [{ id: "manage", title: "Commands", entries: ["record", "replace"] }],
-        children: [
-            {
-                name: "record",
-                summary: "Record the active Agent's native session ID.",
-                usage: "yui role session record <role> --native-id <id>",
-                options: ["--native-id"]
-            },
-            {
-                name: "replace",
-                summary: "Explicitly replace the active Agent's native session ID.",
-                usage: "yui role session replace <role> --native-id <id> --reason <text>",
-                options: ["--native-id", "--reason"]
-            }
-        ]
+        name: "context",
+        summary: "Load the exact authorized global Role context.",
+        usage: "yui session context <role>"
+    },
+    {
+        name: "record",
+        summary: "Record the active Agent's native session ID.",
+        usage: "yui session record <role> --native-id <id>",
+        options: ["--native-id"]
+    },
+    {
+        name: "replace",
+        summary: "Explicitly replace the active Agent's native session ID.",
+        usage: "yui session replace <role> --native-id <id> --reason <text>",
+        options: ["--native-id", "--reason"]
+    },
+    {
+        name: "reconcile",
+        summary: "Reconcile durable Session owners with native sessions.",
+        usage: "yui session reconcile [--report] [--cleanup]",
+        options: ["--report", "--cleanup"]
     }
 ];
 const profileChildren = [
     {
         name: "add",
         summary: "Add a reusable Agent Profile.",
-        usage: "yui profile add <id> [--access <read|write>] [Profile settings]",
+        usage: "yui config profile add <id> [--access <read|write>] [Profile settings]",
         options: ["--access", ...agentProfileOptions],
         optionValues: { "--access": ["read", "write"] }
     },
     { name: "list", summary: "List Agent Profiles." },
-    { name: "show", summary: "Show one Agent Profile.", usage: "yui profile show <id>" },
+    { name: "show", summary: "Show one Agent Profile.", usage: "yui config profile show <id>" },
     {
         name: "update",
         summary: "Update an Agent Profile.",
-        usage: "yui profile update <id> [--access <read|write>] [Profile settings]",
+        usage: "yui config profile update <id> [--access <read|write>] [Profile settings]",
         options: ["--access", ...agentProfileOptions, ...agentProfileClearOptions],
         optionValues: { "--access": ["read", "write"] }
     },
-    { name: "remove", summary: "Remove a custom Agent Profile.", usage: "yui profile remove <id>" },
+    { name: "remove", summary: "Remove a custom Agent Profile.", usage: "yui config profile remove <id>" },
     { name: "reset", summary: "Reset all built-in Agent Profiles." }
 ];
+const completionChildren = [
+    { name: "bash", summary: "Interactively configure Bash completion." },
+    { name: "zsh", summary: "Interactively configure Zsh completion." },
+    { name: "fish", summary: "Interactively configure Fish completion." },
+    {
+        name: "candidates",
+        summary: "Resolve internal dynamic completion candidates.",
+        usage: "yui config completion candidates <prefix> -- <words...>",
+        hidden: true
+    }
+];
 const taskChildren = [
     {
         name: "create",
@@ -451,7 +513,8 @@ const taskChildren = [
         name: "role",
         summary: "Manage Roles within a Task.",
         sections: [{ id: "manage", title: "Commands", entries: [
-                    "add", "list", "status", "show", "update", "remove", "bind", "unbind", "reset", "enter"
+                    "add", "list", "status", "show", "update", "remove", "bind", "unbind", "reset",
+                    "view", "takeover", "release"
                 ] }],
         children: [
             {
@@ -486,10 +549,19 @@ const taskChildren = [
                 options: ["--reason"]
             },
             {
-                name: "enter",
-                summary: "Attach to an existing Task Role session without starting it.",
-                usage: "yui task role enter <task> <role> [--read-only | --read-write]",
-                options: ["--read-only", "--read-write"]
+                name: "view",
+                summary: "Attach read-only to a managed Provider presentation surface.",
+                usage: "yui task role view <task> <role>"
+            },
+            {
+                name: "takeover",
+                summary: "Acquire Provider writer authority and enter the PTY input gateway.",
+                usage: "yui task role takeover <task> <role>"
+            },
+            {
+                name: "release",
+                summary: "Return stranded human Provider authority to the Controller.",
+                usage: "yui task role release <task> <role>"
             }
         ]
     },
@@ -613,7 +685,7 @@ const taskChildren = [
     {
         name: "run",
         summary: "Inspect and control Task Role Agent Runs.",
-        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "checkpoint"] }],
+        sections: [{ id: "manage", title: "Commands", entries: ["list", "show", "retry", "settle", "recover", "yield", "context", "checkpoint"] }],
         children: [
             { name: "list", summary: "List Runs for a work item.", usage: "yui task run list <task>/<work>" },
             {
@@ -644,6 +716,28 @@ const taskChildren = [
                 options: ["--summary", "--summary-file"],
                 fileOptions: ["--summary-file"]
             },
+            {
+                name: "context",
+                summary: "Load the exact authorized Run context.",
+                usage: "yui task run context <task>/<run> [--json]",
+                executable: true,
+                hidden: true,
+                sections: [{ id: "load", title: "Commands", entries: ["expand", "delta"] }],
+                children: [
+                    {
+                        name: "expand",
+                        summary: "Expand one authorized Run context reference.",
+                        usage: "yui task run context expand <task>/<run> <ref-id> [--mode full]",
+                        options: ["--mode"]
+                    },
+                    {
+                        name: "delta",
+                        summary: "Load authorized Run context changes after a cursor.",
+                        usage: "yui task run context delta <task>/<run> --after <cursor>",
+                        options: ["--after"]
+                    }
+                ]
+            },
             {
                 name: "checkpoint",
                 summary: "Record durable progress for a long-running Agent Run.",
@@ -878,24 +972,19 @@ const taskChildren = [
             { name: "show", summary: "Show one ChangeSet.", usage: "yui task change-set show <task>/<change-set>" }
         ]
     },
-    {
-        name: "enter",
-        summary: "Attach to an existing Task Role, defaulting to Leader and read-only.",
-        usage: "yui task enter <task> [role] [--read-only | --read-write]",
-        options: ["--read-only", "--read-write"]
-    }
 ];
 export const ROOT_COMMAND = buildNode({
     name: "yui",
     summary: "Coordinate durable, isolated Agent work.",
     usage: "yui [--json] <command>",
+    examples: ["yui setup", "yui operator enter", "yui config show", "yui task list"],
     sections: [
         { id: "general", title: "General", entries: [
-                "help", "version", "update", "upgrade", "setup", "doctor", "completion"
+                "help", "version", "update", "upgrade", "setup", "doctor"
             ] },
         { id: "workflow", title: "Workflow", entries: ["operator", "project", "task"] },
-        { id: "configuration", title: "Configuration", entries: ["config", "agent", "profile", "role"] },
-        { id: "operations", title: "Operations", entries: ["web", "controller", "execution", "job", "jobs", "telemetry", "release"] },
+        { id: "configuration", title: "Configuration", entries: ["config"] },
+        { id: "operations", title: "Operations", entries: ["web", "controller", "session", "execution", "job", "jobs", "telemetry", "release"] },
         { id: "resources", title: "Resources", entries: ["resources"] },
         { id: "internal", title: "Internal", entries: ["internal"] }
     ],
@@ -909,7 +998,11 @@ export const ROOT_COMMAND = buildNode({
             usage: "yui upgrade [--dry-run]",
             options: ["--dry-run"]
         },
-        { name: "setup", summary: "Initialize or update Yui configuration." },
+        {
+            name: "setup",
+            summary: "Initialize the minimum Operator and Leader configuration required to execute Tasks.",
+            examples: "yui setup"
+        },
         { name: "doctor", summary: "Check Yui dependencies and file state." },
         {
             name: "web",
@@ -917,28 +1010,6 @@ export const ROOT_COMMAND = buildNode({
             usage: "yui web [--host <loopback>] [--port <port>]",
             options: ["--host", "--port"]
         },
-        {
-            name: "completion",
-            summary: "Interactively configure shell completion.",
-            executable: true,
-            acceptsArguments: false,
-            usage: ["yui completion", "yui completion <bash|zsh|fish>"],
-            sections: [
-                { id: "shells", title: "Shells", entries: ["bash", "zsh", "fish"] },
-                { id: "internal", title: "Internal", entries: ["candidates"] }
-            ],
-            children: [
-                { name: "bash", summary: "Interactively configure Bash completion." },
-                { name: "zsh", summary: "Interactively configure Zsh completion." },
-                { name: "fish", summary: "Interactively configure Fish completion." },
-                {
-                    name: "candidates",
-                    summary: "Resolve internal dynamic completion candidates.",
-                    usage: "yui completion candidates <prefix> -- <words...>",
-                    hidden: true
-                }
-            ]
-        },
         {
             name: "controller",
             summary: "Inspect and recover local Controller runtime resources.",
@@ -1028,29 +1099,78 @@ export const ROOT_COMMAND = buildNode({
         },
         {
             name: "config",
-            summary: "Inspect or update Yui configuration.",
-            sections: [{ id: "manage", title: "Commands", entries: ["show", "set", "clear"] }],
+            summary: "Inspect, understand, and update all persistent Yui configuration.",
+            examples: [
+                "yui config show",
+                "yui config describe runtime",
+                "yui config workflow show",
+                "yui config agent list",
+                "yui config role show operator",
+                "yui config profile list",
+                "yui config completion"
+            ],
+            sections: [
+                { id: "inspect", title: "Inspect", entries: ["show", "describe"] },
+                { id: "domains", title: "Configuration domains", entries: [
+                        ...CONFIG_DOMAINS, "agent", "role", "profile", "completion"
+                    ] }
+            ],
             children: [
-                { name: "show", summary: "Show effective Yui configuration." },
                 {
-                    name: "set",
-                    summary: "Set one Yui configuration key.",
-                    usage: "yui config set <key> <value...>",
-                    sections: [{ id: "keys", title: "Configuration keys", entries: [...CONFIG_KEYS] }],
-                    values: CONFIG_KEY_VALUES,
-                    options: ["--role", "--trigger", "--finding-ledger", "--delta-recheck", "--delta-recheck-max-lines", "--delta-recheck-max-files"],
-                    optionValues: {
-                        "--trigger": ["always", "leader", "final"],
-                        "--finding-ledger": ["shadow", "enforce"],
-                        "--delta-recheck": ["enabled", "disabled"]
-                    }
+                    name: "show",
+                    summary: "Show the complete effective Yui configuration.",
+                    examples: ["yui config show", "yui --json config show"]
+                },
+                {
+                    name: "describe",
+                    summary: "Explain configuration effects, defaults, choices, and activation behavior.",
+                    usage: `yui config describe [${[...CONFIG_DOMAINS, "agent", "role", "profile", "completion"].join("|")}]`,
+                    examples: ["yui config describe", "yui --json config describe role"],
+                    argumentValues: { 0: [...CONFIG_DOMAINS, "agent", "role", "profile", "completion"] }
+                },
+                ...CONFIG_DOMAINS.map(durableConfigDomainNode),
+                {
+                    name: "agent",
+                    summary: "Manage configured native Agent CLIs; launch-setting changes require affected Sessions to be stopped.",
+                    examples: ["yui config agent list", "yui config agent capabilities codex"],
+                    sections: [
+                        { id: "inspect", title: "Inspect", entries: ["list", "show", "capabilities"] },
+                        { id: "manage", title: "Manage", entries: ["add", "update", "remove"] }
+                    ],
+                    children: agentChildren
+                },
+                {
+                    name: "profile",
+                    summary: "Manage reusable Agent Profiles; updates affect future copies and do not rewrite existing Task Roles.",
+                    examples: ["yui config profile list", "yui config profile show implementer"],
+                    sections: [
+                        { id: "inspect", title: "Inspect", entries: ["list", "show"] },
+                        { id: "manage", title: "Manage", entries: ["add", "update", "remove", "reset"] }
+                    ],
+                    children: profileChildren
                 },
                 {
-                    name: "clear",
-                    summary: "Reset one Yui configuration key to its default.",
-                    usage: "yui config clear <key>",
-                    sections: [{ id: "keys", title: "Configuration keys", entries: [...CONFIG_KEYS] }],
-                    values: CONFIG_KEY_VALUES
+                    name: "role",
+                    summary: "Manage reusable global Roles and desired Agent launch configuration for the next compatible Session.",
+                    examples: ["yui config role list", "yui config role show operator"],
+                    sections: [
+                        { id: "inspect", title: "Inspect", entries: ["list", "show"] },
+                        { id: "manage", title: "Manage", entries: ["add", "update", "remove", "bind", "unbind"] }
+                    ],
+                    children: roleChildren
+                },
+                {
+                    name: "completion",
+                    summary: "Interactively configure shell completion after confirming generated files and startup-file changes.",
+                    executable: true,
+                    acceptsArguments: false,
+                    usage: ["yui config completion", "yui config completion <bash|zsh|fish>"],
+                    examples: ["yui config completion", "yui config completion zsh"],
+                    sections: [
+                        { id: "shells", title: "Shells", entries: ["bash", "zsh", "fish"] },
+                        { id: "internal", title: "Internal", entries: ["candidates"] }
+                    ],
+                    children: completionChildren
                 }
             ]
         },
@@ -1207,39 +1327,25 @@ export const ROOT_COMMAND = buildNode({
             ]
         },
         {
-            name: "agent",
-            summary: "Manage configured native Agent CLIs.",
-            sections: [
-                { id: "inspect", title: "Inspect", entries: ["list", "show", "capabilities"] },
-                { id: "manage", title: "Manage", entries: ["add", "update", "remove"] }
+            name: "session",
+            summary: "Load and enter global Role sessions, and reconcile their durable identities.",
+            examples: [
+                "yui session context operator --json",
+                "yui session enter operator",
+                "yui session reconcile --report"
             ],
-            children: agentChildren
-        },
-        {
-            name: "profile",
-            summary: "Manage reusable Agent Profiles.",
-            sections: [
-                { id: "inspect", title: "Inspect", entries: ["list", "show"] },
-                { id: "manage", title: "Manage", entries: ["add", "update", "remove", "reset"] }
-            ],
-            children: profileChildren
-        },
-        {
-            name: "role",
-            summary: "Manage reusable global Roles and their native sessions.",
             sections: [
-                { id: "inspect", title: "Inspect", entries: ["list", "show", "context"] },
-                { id: "manage", title: "Manage", entries: ["add", "update", "remove", "bind", "unbind"] },
-                { id: "sessions", title: "Sessions", entries: ["enter", "session"] }
+                { id: "global", title: "Global Role sessions", entries: ["context", "enter", "record", "replace"] },
+                { id: "recovery", title: "Recovery", entries: ["reconcile"] }
             ],
-            children: roleChildren
+            children: globalSessionChildren
         },
         {
             name: "task",
             summary: "Manage Tasks, WorkItems, Agent Runs, and integration.",
             sections: [
                 { id: "lifecycle", title: "Lifecycle", entries: ["create", "project", "base", "update", "activate", "complete", "reopen", "retire", "list", "show", "context", "next-action", "archive", "rebuild", "history", "replace", "reconcile"] },
-                { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "enter", "overlap", "change-set"] },
+                { id: "collaboration", title: "Collaboration", entries: ["message", "input", "grant", "workflow", "publication", "work", "run", "review", "integration", "role", "overlap", "change-set"] },
                 { id: "knowledge", title: "Task Knowledge", entries: ["brief", "decision", "milestone", "event", "continuation", "wake"] }
             ],
             children: taskChildren
@@ -1279,8 +1385,17 @@ export const ROOT_COMMAND = buildNode({
             name: "internal",
             summary: "Internal Yui callbacks.",
             hidden: true,
-            sections: [{ id: "callbacks", title: "Callbacks", entries: ["session-notify", "runtime-hook"] }],
+            sections: [{
+                    id: "callbacks",
+                    title: "Callbacks",
+                    entries: ["session-notify", "runtime-hook", "agent-host"]
+                }],
             children: [
+                {
+                    name: "agent-host",
+                    summary: "Run the persistent structured Provider host.",
+                    usage: "yui internal agent-host <launch-id> <ticket>"
+                },
                 {
                     name: "session-notify",
                     summary: "Record a structured native session notification.",
@@ -1333,6 +1448,20 @@ export function findCommandNode(path) {
     return node;
 }
 export const findCommand = findCommandNode;
+/** Structured help projection consumed by `config describe --json` and Operator. */
+export function describeCommandTree(node) {
+    return {
+        path: node.path.slice(1).join(" "),
+        summary: node.summary,
+        usage: node.usage,
+        examples: node.examples,
+        options: node.options,
+        optionValues: node.optionValues,
+        argumentValues: node.argumentValues,
+        values: node.values,
+        children: visibleChildren(node).map(describeCommandTree)
+    };
+}
 export function validateCommandCatalog(root) {
     const reservedAliases = new Set(["-h", "--help", "-help", "-v", "--version"]);
     const commandPathProviders = [];
@@ -1341,6 +1470,16 @@ export function validateCommandCatalog(root) {
             throw new Error(`Command summary is required: ${node.path.join(" ")}`);
         if (node.usage.length === 0)
             throw new Error(`Command usage is required: ${node.path.join(" ")}`);
+        if (node.examples.length === 0 || node.examples.some((example) => example.trim().length === 0)) {
+            throw new Error(`Command examples are required: ${node.path.join(" ")}`);
+        }
+        const canonicalPath = node.path.join(" ");
+        for (const example of node.examples) {
+            const normalized = example.replace(/^yui --json(?=\s|$)/, "yui");
+            if (normalized !== canonicalPath && !normalized.startsWith(`${canonicalPath} `)) {
+                throw new Error(`Command example does not match its path: ${canonicalPath}: ${example}`);
+            }
+        }
         if (node.commandPathArguments) {
             commandPathProviders.push(node);
             const ownsOtherCompletionMetadata = node.kind !== "leaf"
@@ -1432,10 +1571,18 @@ export function validateCommandCatalog(root) {
             if (!options.has(option))
                 throw new Error(`Executable completion references unknown option: ${[...node.path, option].join(" ")}`);
         }
+        if (new Set(node.workspaceMapOptions).size !== node.workspaceMapOptions.length) {
+            throw new Error(`Duplicate workspace-map completion option: ${node.path.join(" ")}`);
+        }
+        for (const option of node.workspaceMapOptions) {
+            if (!options.has(option))
+                throw new Error(`Workspace-map completion references unknown option: ${[...node.path, option].join(" ")}`);
+        }
         for (const option of options) {
             const owners = Number(Object.hasOwn(node.optionValues, option))
                 + Number(node.fileOptions.includes(option))
-                + Number(node.executableOptions.includes(option));
+                + Number(node.executableOptions.includes(option))
+                + Number(node.workspaceMapOptions.includes(option));
             if (owners > 1)
                 throw new Error(`Multiple completion owners for option: ${[...node.path, option].join(" ")}`);
         }