@zq-silk/yui 0.7.0 → 0.8.1

package/dist/cli/interactionPolicy.js

@@ -1,3 +1,4 @@
+import { findCommandNode } from "./commandCatalog.js";
 const taskTarget = (command, argumentIndex = 2, statuses) => ({
     commandPath: ["task", command],
     selectors: [{
@@ -47,7 +48,7 @@ export const INTERACTION_POLICIES = Object.freeze([
             "--development": "value"
         }
     },
-    ...["add", "update", "retire", "list", "show"].map((command) => ({
+    ...["add", "retire", "list", "show"].map((command) => ({
         commandPath: ["project", "knowledge", command],
         selectors: [{
                 argumentIndex: 3,
@@ -57,26 +58,24 @@ export const INTERACTION_POLICIES = Object.freeze([
             }],
         ...(command === "add"
             ? { trailingOptions: { "--body": "value" } }
-            : command === "update"
-                ? { trailingOptions: { "--title": "value", "--body": "value" } }
-                : command === "list"
-                    ? { trailingOptions: { "--all": "flag" } }
-                    : {})
+            : command === "list"
+                ? { trailingOptions: { "--all": "flag" } }
+                : {})
     })),
     ...["show", "capabilities", "update", "remove"].map((command) => ({
-        commandPath: ["agent", command],
+        commandPath: ["config", "agent", command],
         selectors: [{
-                argumentIndex: 2,
+                argumentIndex: 3,
                 entity: "agent",
                 provider: "configured-agents",
                 actionTarget: true
             }],
         ...(command === "remove"
-            ? { confirmation: { action: "Remove Agent", targetArgumentIndex: 2 } }
+            ? { confirmation: { action: "Remove Agent", targetArgumentIndex: 3 } }
             : {})
     })),
     {
-        commandPath: ["role", "add"],
+        commandPath: ["config", "role", "add"],
         selectors: [{
                 option: "--agent",
                 requiredOption: true,
@@ -93,29 +92,31 @@ export const INTERACTION_POLICIES = Object.freeze([
             "--search": "value"
         }
     },
-    ...["show", "update", "remove", "enter"].map((command) => ({
-        commandPath: ["role", command],
+    ...["show", "update", "remove", "enter", "context"].map((command) => ({
+        commandPath: command === "enter" || command === "context"
+            ? ["session", command]
+            : ["config", "role", command],
         selectors: [{
-                argumentIndex: 2,
+                argumentIndex: command === "enter" || command === "context" ? 2 : 3,
                 entity: "global-role",
                 provider: "global-roles",
                 actionTarget: true
             }],
         ...(command === "remove"
-            ? { confirmation: { action: "Remove Role", targetArgumentIndex: 2 } }
+            ? { confirmation: { action: "Remove Role", targetArgumentIndex: 3 } }
             : {})
     })),
     ...["bind", "unbind"].map((command) => ({
-        commandPath: ["role", command],
+        commandPath: ["config", "role", command],
         selectors: [
-            { argumentIndex: 2, entity: "global-role", provider: "global-roles", actionTarget: true },
-            { argumentIndex: 3, entity: "agent", provider: "configured-agents", actionTarget: false }
+            { argumentIndex: 3, entity: "global-role", provider: "global-roles", actionTarget: true },
+            { argumentIndex: 4, entity: "agent", provider: "configured-agents", actionTarget: false }
         ]
     })),
     ...["record", "replace"].map((command) => ({
-        commandPath: ["role", "session", command],
+        commandPath: ["session", command],
         selectors: [{
-                argumentIndex: 3,
+                argumentIndex: 2,
                 entity: "global-role",
                 provider: "global-roles",
                 actionTarget: true
@@ -125,7 +126,7 @@ export const INTERACTION_POLICIES = Object.freeze([
             : { "--native-id": "value" }
     })),
     {
-        commandPath: ["profile", "add"],
+        commandPath: ["config", "profile", "add"],
         selectors: [],
         trailingOptions: {
             "--description": "value", "--instructions": "value",
@@ -133,9 +134,9 @@ export const INTERACTION_POLICIES = Object.freeze([
         }
     },
     ...["show", "update", "remove"].map((command) => ({
-        commandPath: ["profile", command],
+        commandPath: ["config", "profile", command],
         selectors: [{
-                argumentIndex: 2,
+                argumentIndex: 3,
                 entity: "agent-profile",
                 provider: "agent-profiles",
                 actionTarget: true
@@ -151,7 +152,7 @@ export const INTERACTION_POLICIES = Object.freeze([
             }
             : {}),
         ...(command === "remove"
-            ? { confirmation: { action: "Remove Agent Profile", targetArgumentIndex: 2 } }
+            ? { confirmation: { action: "Remove Agent Profile", targetArgumentIndex: 3 } }
             : {})
     })),
     taskTarget("show"),
@@ -630,10 +631,30 @@ export function validateInteractionPolicies(policies = INTERACTION_POLICIES) {
         if (paths.has(path))
             throw new Error(`Duplicate interaction policy: ${path}`);
         paths.add(path);
+        const node = findCommandNode(policy.commandPath);
+        if (node === undefined || node.hidden) {
+            throw new Error(`Interaction policy references an unknown command: ${path}`);
+        }
         for (const selector of policy.selectors) {
             if ((selector.argumentIndex === undefined) === (selector.option === undefined)) {
                 throw new Error(`Interaction selector must declare exactly one slot: ${path}`);
             }
+            if (selector.argumentIndex !== undefined && (!Number.isInteger(selector.argumentIndex)
+                || selector.argumentIndex < node.path.length - 1)) {
+                throw new Error(`Interaction selector has an invalid argument index: ${path}`);
+            }
+            if (selector.option !== undefined && !node.options.includes(selector.option)) {
+                throw new Error(`Interaction selector references an unknown option: ${path} ${selector.option}`);
+            }
+        }
+        for (const option of Object.keys(policy.trailingOptions ?? {})) {
+            if (!node.options.includes(option)) {
+                throw new Error(`Interaction policy references an unknown trailing option: ${path} ${option}`);
+            }
+        }
+        if (policy.confirmation !== undefined && !policy.selectors.some((selector) => selector.argumentIndex === policy.confirmation?.targetArgumentIndex
+            && selector.actionTarget)) {
+            throw new Error(`Interaction confirmation has no action target selector: ${path}`);
         }
     }
 }

package/dist/cli/interactiveSelection.js

@@ -53,7 +53,7 @@ export async function resolveInteractiveArguments(args, node, ports, io) {
 }
 export function allowsInteractiveSelection(args, globalJson) {
     return !globalJson && !args.includes("--json")
-        && !(args[0] === "completion" && args[1] === "candidates");
+        && !(args[0] === "config" && args[1] === "completion" && args[2] === "candidates");
 }
 function missingSlot(args, selector, node) {
     if (selector.argumentIndex !== undefined) {

package/dist/cli/invocationRouter.js

@@ -31,7 +31,7 @@ function resolveExecutionPath(args) {
             break;
         const child = findChild(node, args[index] ?? "");
         const internalExecutable = child !== undefined && ((node === ROOT_COMMAND && child.name === "internal")
-            || (node.path.join(" ") === "yui completion" && child.name === "candidates")
+            || (node.path.join(" ") === "yui config completion" && child.name === "candidates")
             || (node.path.join(" ") === "yui task run" && child.name === "checkpoint")
             || (node.path.join(" ") === "yui controller"
                 && (child.name === "identity" || child.name === "live-identity")));

package/dist/cli/roleWizard.js

@@ -20,7 +20,7 @@ export async function resolveRoleWizardArguments(commandArgs, ports, io) {
     return { kind: "unchanged", args };
 }
 export async function resolveGlobalRoleAgentConfigurationArguments(roleName, agentId, ports, io) {
-    const args = ["role", "update", roleName];
+    const args = ["config", "role", "update", roleName];
     if (!io.interactive || io.json)
         return { kind: "unchanged", args };
     const role = asRole(await ports.call("role.show", { name: roleName }));
@@ -31,7 +31,7 @@ export async function resolveGlobalRoleAgentConfigurationArguments(roleName, age
     return updateAgentBindingSettings(args, role, binding, ports, io);
 }
 function isGlobalRoleAdd(args) {
-    return args[0] === "role" && args[1] === "add";
+    return args[0] === "config" && args[1] === "role" && args[2] === "add";
 }
 function isTaskRoleAdd(args) {
     return args[0] === "task" && args[1] === "role" && args[2] === "add";
@@ -39,18 +39,18 @@ function isTaskRoleAdd(args) {
 // Explicit update options always win. This keeps scripts and deliberate
 // non-interactive invocations out of the wizard even when run from a TTY.
 function isGlobalRoleUpdate(args) {
-    return args.length === 3 && args[0] === "role" && args[1] === "update"
-        && isValue(args[2]);
+    return args.length === 4 && args[0] === "config" && args[1] === "role"
+        && args[2] === "update" && isValue(args[3]);
 }
 function isTaskRoleUpdate(args) {
     return args.length === 5 && args[0] === "task" && args[1] === "role"
         && args[2] === "update" && isValue(args[3]) && isValue(args[4]);
 }
 async function addGlobalRole(args, ports, io) {
-    const named = await ensureRoleName(args, 2, io);
+    const named = await ensureRoleName(args, 3, io);
     if (named === undefined)
         return { kind: "cancelled", args };
-    const explicitSettings = hasExplicitAddSettings(named, 3);
+    const explicitSettings = hasExplicitAddSettings(named, 4);
     const agents = await loadAgentSelection(ports);
     const explicitAgent = optionValue(named, "--agent");
     const selected = explicitAgent ?? await selectConfiguredAgent(ports, io, "Create Global Role from Agent", agents);
@@ -236,7 +236,7 @@ async function configureNewAgentField(args, agent, ports, io) {
         : { kind: "resolved", args: [...args, selected.set, value] };
 }
 async function updateGlobalRole(args, ports, io) {
-    const role = asRole(await ports.call("role.show", { name: args[2] }));
+    const role = asRole(await ports.call("role.show", { name: args[3] }));
     if (role === undefined)
         return { kind: "unchanged", args };
     return updateRole(args, role, ports, io, false);
@@ -286,7 +286,7 @@ async function updateRoleSettings(args, role, ports, io, taskRole) {
             return { kind: "cancelled", args };
         return taskRole
             ? { kind: "resolved", args: ["task", "role", "bind", args[3] ?? "", args[4] ?? "", target] }
-            : { kind: "resolved", args: ["role", "bind", args[2] ?? "", target] };
+            : { kind: "resolved", args: ["config", "role", "bind", args[3] ?? "", target] };
     }
     if (field === "workspace") {
         const value = (await io.question(`Workspace [${roleDisplay(role.workspace)}]: `))?.trim();

package/dist/cli.js

@@ -5,6 +5,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import { renderCommandHelp } from "./cli/helpRenderer.js";
+import { describeCommandTree, findCommandNode } from "./cli/commandCatalog.js";
 import { routeInvocation } from "./cli/invocationRouter.js";
 import { renderCompletion } from "./cli/completion.js";
 import { resolveCompletionCandidates } from "./cli/dynamicCompletion.js";
@@ -16,12 +17,14 @@ import { resolveOperatorWizardArguments } from "./cli/operatorWizard.js";
 import { runUpdateCommand } from "./cli/updateCommand.js";
 import { runUpgradeCommand } from "./cli/upgradeCommand.js";
 import { formatTimestamp } from "./output/timePresentation.js";
-import { resolveTmuxBin } from "./config/yuiConfig.js";
+import { resolveTmuxBin, resolveTmuxHistoryLimit } from "./config/yuiConfig.js";
 import { renderAgentConfigurationCatalog } from "./output/agentConfigurationPresentation.js";
 import { nativeAgentEnvironmentNames } from "./agent/launchEnvironment.js";
 import { runAgentCommand } from "./commands/agentCommands.js";
 import { runGlobalRoleCommand } from "./commands/globalRoleCommands.js";
 import { runConfigCommand } from "./commands/configCommands.js";
+import { CONFIG_DOMAINS } from "./config/configCatalog.js";
+import { runConfigOverview } from "./commands/configOverview.js";
 import { parseControllerCleanupOptions, parseControllerStatusOptions, parseControllerRuntimeSnapshot, renderControllerResourceStatus, renderRuntimeIdentitySection, summarizeDurablePhysicalMismatch, runInteractiveControllerCleanup } from "./commands/controllerCommands.js";
 import { parseExecutionAuditOptions, runExecutionAuditCommand } from "./commands/executionAuditCommands.js";
 import { parseSessionReconcileOptions, runSessionReconcileCommand } from "./commands/sessionCommands.js";
@@ -168,10 +171,25 @@ export async function main() {
         }
         throw usageError("Release usage: yui release install <source-dir> | list | activate [release-id].");
     }
-    if (args[0] === "completion") {
+    if (args[0] === "config" && args[1] === "completion") {
         await completionCommand(home, invocation.node);
         return;
     }
+    if (args[0] === "config" && args[1] === "describe") {
+        const describeNode = findCommandNode(["config", "describe"]);
+        if (describeNode === undefined)
+            throw new Error("Config describe command is missing from the catalog.");
+        const domain = args[2];
+        const domains = describeNode.argumentValues[0] ?? [];
+        if (args.length > 3 || (domain !== undefined && !domains.includes(domain))) {
+            throw usageError(`Config describe usage: ${describeNode.usage.join(" | ")}.`);
+        }
+        const target = findCommandNode(domain === undefined ? ["config"] : ["config", domain]);
+        if (target === undefined)
+            throw new Error(`Config domain is missing from the catalog: ${domain}.`);
+        emit(renderCommandHelp(target, VERSION), false, describeCommandTree(target));
+        return;
+    }
     if (args[0] === "setup") {
         if (jsonOutput)
             throw usageError("Setup does not support --json.");
@@ -261,13 +279,13 @@ export async function main() {
         }
         throw usageError("Internal lifecycle callback usage is invalid.");
     }
-    if (args[0] === "session") {
-        if (args[1] !== "reconcile") {
-            throw usageError("Session usage: yui session reconcile [--report] [--cleanup].");
-        }
+    if (args[0] === "session" && args[1] === "reconcile") {
         const options = parseSessionReconcileOptions(args.slice(2));
         const store = openCompatibleFileTaskStore(home);
-        const tmux = new TmuxManager(resolveTmuxBin(store.getConfig().tmuxBin), new NodeCommandExecutor(), { yuiHome: home });
+        const tmux = new TmuxManager(resolveTmuxBin(store.getConfig().tmuxBin), new NodeCommandExecutor(), {
+            yuiHome: home,
+            historyLimit: resolveTmuxHistoryLimit(store.getConfig().tmuxHistoryLimit)
+        });
         const reconciliation = new SessionOwnerReconciliation({
             home,
             store,
@@ -474,6 +492,7 @@ export async function main() {
     const executor = new NodeCommandExecutor();
     const tmux = new TmuxManager(resolveTmuxBin(store.getConfig().tmuxBin), executor, {
         yuiHome: home,
+        historyLimit: resolveTmuxHistoryLimit(store.getConfig().tmuxHistoryLimit),
         terminalInput: process.stdin,
         onWarning: (message) => process.stderr.write(`Warning: ${message}\n`)
     });
@@ -531,77 +550,102 @@ export async function main() {
         process.stdout.write(`Yui web control room: http://${displayHost}:${options.port}\n`);
         return;
     }
-    if (resolved[0] === "agent") {
-        const agentArgs = resolved.slice(1);
-        if (agentArgs[0] === "capabilities") {
-            if (agentArgs.length !== 2) {
-                throw usageError("Agent capabilities usage: yui agent capabilities <agent-id>");
+    if (resolved[0] === "config") {
+        const domain = resolved[1];
+        const roleOptions = {
+            yuiHome: home,
+            env: process.env
+        };
+        if (domain === "show") {
+            const result = runConfigOverview(resolved.slice(2), store, process.env, resolveCliIdentity(process.env), roleOptions);
+            emit(result.output, false, result.data);
+            return;
+        }
+        if (CONFIG_DOMAINS.includes(domain ?? "")) {
+            const configDomain = domain;
+            const domainArgs = resolved.slice(2);
+            const result = runConfigCommand(configDomain, domainArgs, store);
+            if (domainArgs[0] === "set"
+                && domainArgs[1] === "reconciliation-interval-seconds") {
+                const refresh = await refreshRunningFileTaskControllerConfiguration(home, { environment: process.env });
+                emit(withControllerRefreshWarning(result.output, refresh, "Controller configuration"));
+                return;
             }
-            const agent = store.getConfiguredAgent(agentArgs[1] ?? "");
-            if (agent === null)
-                throw agentNotFound(agentArgs[1] ?? "");
-            const result = await catalogs.resolve({
-                agent,
-                cwd: store.getConfig().defaultWorkspace ?? process.cwd()
-            });
-            emit(renderAgentConfigurationCatalog(result), false, result);
+            emit(result.output, false, result.data);
             return;
         }
-        const affectedAgentId = agentArgs[1];
-        const previousAgent = typeof affectedAgentId === "string"
-            ? store.getConfiguredAgent(affectedAgentId)
-            : null;
-        const output = runAgentCommand(agentArgs, store);
-        if (agentArgs[0] === "add"
-            || agentArgs[0] === "update"
-            || agentArgs[0] === "remove") {
-            const currentAgent = typeof affectedAgentId === "string"
+        if (domain === "agent") {
+            const agentArgs = resolved.slice(2);
+            if (agentArgs[0] === "capabilities") {
+                if (agentArgs.length !== 2) {
+                    throw usageError("Agent capabilities usage: yui config agent capabilities <agent-id>");
+                }
+                const agent = store.getConfiguredAgent(agentArgs[1] ?? "");
+                if (agent === null)
+                    throw agentNotFound(agentArgs[1] ?? "");
+                const result = await catalogs.resolve({
+                    agent,
+                    cwd: store.getConfig().defaultWorkspace ?? process.cwd()
+                });
+                emit(renderAgentConfigurationCatalog(result), false, result);
+                return;
+            }
+            const affectedAgentId = agentArgs[1];
+            const previousAgent = typeof affectedAgentId === "string"
                 ? store.getConfiguredAgent(affectedAgentId)
                 : null;
-            const capabilityNotice = currentAgent !== null
-                && (agentArgs[0] === "add" || agentArgs[0] === "update")
-                ? renderAgentConfigurationResolutionNotice(await catalogs.resolve({
-                    agent: currentAgent,
-                    cwd: store.getConfig().defaultWorkspace ?? process.cwd()
-                }))
-                : "";
-            const scope = agentEnvironmentRefreshScope(previousAgent, currentAgent, store.listConfiguredAgents());
-            const refresh = await refreshRunningFileTaskControllerEnvironment(home, store, process.env, scope);
-            emit(withControllerRefreshWarning(`${output.trimEnd()}${capabilityNotice.length === 0 ? "\n" : `\n${capabilityNotice}`}`, refresh, "Agent environment"));
+            const output = runAgentCommand(agentArgs, store);
+            if (agentArgs[0] === "add"
+                || agentArgs[0] === "update"
+                || agentArgs[0] === "remove") {
+                const currentAgent = typeof affectedAgentId === "string"
+                    ? store.getConfiguredAgent(affectedAgentId)
+                    : null;
+                const capabilityNotice = currentAgent !== null
+                    && (agentArgs[0] === "add" || agentArgs[0] === "update")
+                    ? renderAgentConfigurationResolutionNotice(await catalogs.resolve({
+                        agent: currentAgent,
+                        cwd: store.getConfig().defaultWorkspace ?? process.cwd()
+                    }))
+                    : "";
+                const scope = agentEnvironmentRefreshScope(previousAgent, currentAgent, store.listConfiguredAgents());
+                const refresh = await refreshRunningFileTaskControllerEnvironment(home, store, process.env, scope);
+                emit(withControllerRefreshWarning(`${output.trimEnd()}${capabilityNotice.length === 0 ? "\n" : `\n${capabilityNotice}`}`, refresh, "Agent environment"));
+                return;
+            }
+            emit(output);
             return;
         }
-        emit(output);
-        return;
-    }
-    if (resolved[0] === "config") {
-        const configArgs = resolved.slice(1);
-        const result = runConfigCommand(configArgs, store);
-        if (configArgs[0] === "set"
-            && configArgs[1] === "reconciliation-interval-seconds") {
-            const refresh = await refreshRunningFileTaskControllerConfiguration(home, { environment: process.env });
-            emit(withControllerRefreshWarning(result.output, refresh, "Controller configuration"));
+        if (domain === "profile") {
+            const result = runProfileCommand(resolved.slice(2), store);
+            emit(result.output, false, result.data);
             return;
         }
-        emit(result.output, false, result.data);
-        return;
+        if (domain === "role") {
+            const result = runGlobalRoleCommand(resolved.slice(2), store, roleOptions);
+            if (typeof result !== "string") {
+                throw new Error("Config Role commands cannot enter a runtime Session.");
+            }
+            emit(result);
+            return;
+        }
+        throw usageError(`Unknown configuration domain: ${domain ?? ""}.`);
     }
     if (resolved[0] === "project") {
         const result = await runProjectCommand(resolved.slice(1), store, { environment: process.env });
         emit(result.output, false, result.data);
         return;
     }
-    if (resolved[0] === "profile") {
-        const result = runProfileCommand(resolved.slice(1), store);
-        emit(result.output, false, result.data);
-        return;
-    }
-    if (resolved[0] === "role") {
+    if (resolved[0] === "session") {
         const roleOptions = {
             yuiHome: home,
             env: process.env,
             jsonOutput
         };
-        const result = runGlobalRoleCommand(resolved.slice(1), store, roleOptions);
+        const sessionArgs = resolved[1] === "enter" || resolved[1] === "context"
+            ? [resolved[1], ...resolved.slice(2)]
+            : ["session", resolved[1] ?? "", ...resolved.slice(2)];
+        const result = runGlobalRoleCommand(sessionArgs, store, roleOptions);
         if (typeof result === "string") {
             emit(result);
             return;
@@ -1659,7 +1703,7 @@ async function deltaRecheckPreflightForTaskCommand(args, store, actualTaskReview
     const config = store.getReviewConfig();
     if (!deltaRecheckEnabled(config)) {
         throw usageError("Delta-recheck is not enabled for this Project's review policy. "
-            + "Set `yui config set review --role <role> --trigger final --delta-recheck enabled` "
+            + "Set `yui config workflow set review --role <role> --trigger final --delta-recheck enabled` "
             + "or request a full Review.");
     }
     const reviewConfig = config;
@@ -1809,7 +1853,7 @@ async function executeOperatorSessionControl(control, home, store, runtime, tmux
                     process.stdout.write("Cancelled.\n");
                     return;
                 }
-                const updated = runGlobalRoleCommand(resolution.args.slice(1), store, { yuiHome: home, env: process.env });
+                const updated = runGlobalRoleCommand(resolution.args.slice(2), store, { yuiHome: home, env: process.env });
                 if (typeof updated !== "string") {
                     throw new Error("Operator Agent configuration returned an invalid control result.");
                 }
@@ -1865,11 +1909,11 @@ function renderControllerResult(method, value) {
         : "Controller was already stopped.";
 }
 async function completionCommand(home, node) {
-    if (args[1] === "candidates") {
-        const separator = args.indexOf("--");
-        const prefix = args[2];
-        if (prefix === undefined || separator !== 3) {
-            throw usageError("Completion candidates usage: yui completion candidates <prefix> -- <words...>");
+    if (args[2] === "candidates") {
+        const separator = args.indexOf("--", 4);
+        const prefix = args[3];
+        if (prefix === undefined || separator !== 4) {
+            throw usageError("Completion candidates usage: yui config completion candidates <prefix> -- <words...>");
         }
         const candidates = await resolveCompletionCandidates({
             current: prefix,
@@ -1884,9 +1928,9 @@ async function completionCommand(home, node) {
     if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
         throw usageError("Completion configuration requires an interactive terminal.");
     }
-    const shell = completionShell(args[1]);
-    if (args.length > (shell === undefined ? 1 : 2)) {
-        throw usageError("Completion usage: yui completion [bash|zsh|fish]");
+    const shell = completionShell(args[2]);
+    if (args.length > (shell === undefined ? 2 : 3)) {
+        throw usageError("Completion usage: yui config completion [bash|zsh|fish]");
     }
     const store = openCompatibleFileTaskStore(home);
     const ioHandle = terminalIo();
@@ -1921,7 +1965,7 @@ async function resolveTerminalArguments(commandArgs, node, store, catalogs) {
         // Global Role add owns its Agent choice so the configured default can be
         // shown explicitly. Other commands first resolve missing positional
         // targets through the generic selector, then enter the focused Role UI.
-        if ((operatorArgs[0] === "role" && operatorArgs[1] === "add")
+        if ((operatorArgs[0] === "config" && operatorArgs[1] === "role" && operatorArgs[2] === "add")
             || (operatorArgs[0] === "task" && operatorArgs[1] === "role" && operatorArgs[2] === "add")) {
             const wizard = await resolveRoleWizardArguments(operatorArgs, ports, handle.io);
             if (wizard.kind === "cancelled")
@@ -1983,7 +2027,7 @@ async function preflightAgentConfigurationMutation(commandArgs, store, catalogs)
     });
 }
 function hasModelOrEffortMutation(args) {
-    const operation = args[0] === "role"
+    const operation = (args[0] === "config" && args[1] === "role")
         || (args[0] === "task" && args[1] === "role");
     return operation && [
         "--model", "--effort", "--clear-model", "--clear-effort"
@@ -1993,8 +2037,8 @@ function configurationMutationAgentId(args, store) {
     const explicit = optionValue(args, "--agent");
     if (explicit !== undefined)
         return explicit;
-    if (args[0] === "role" && args[1] === "update") {
-        return store.getGlobalRole(args[2] ?? "")?.activeAgentId;
+    if (args[0] === "config" && args[1] === "role" && args[2] === "update") {
+        return store.getGlobalRole(args[3] ?? "")?.activeAgentId;
     }
     if (args[0] === "task" && args[1] === "role") {
         if (args[2] === "add")

package/dist/commands/agentCommands.js

@@ -15,7 +15,7 @@ export function runAgentCommand(args, store) {
         default:
             throw usageError(command === undefined
                 ? "Agent command is required."
-                : `Unknown command: agent ${command}`);
+                : `Unknown command: config agent ${command}`);
     }
 }
 function addAgent(args, store) {
@@ -38,12 +38,12 @@ function addAgent(args, store) {
     }
     const created = store.createConfiguredAgentIfAbsent(agent);
     if (created === null) {
-        throw usageError(`Agent already exists: ${id}. Use yui agent update to change it.`);
+        throw usageError(`Agent already exists: ${id}. Use yui config agent update to change it.`);
     }
     return renderAgent(`Added agent ${id}`, created);
 }
 function listAgents(args, store) {
-    assertNoArguments(args, "Agent list usage: yui agent list");
+    assertNoArguments(args, "Agent list usage: yui config agent list");
     const agents = store.listConfiguredAgents();
     if (agents.length === 0)
         return "No agents configured.\n";
@@ -62,7 +62,7 @@ function listAgents(args, store) {
 function showAgent(args, store) {
     const [rawId, ...rest] = args;
     const id = agentId(rawId);
-    assertNoArguments(rest, "Agent show usage: yui agent show <agent-id>");
+    assertNoArguments(rest, "Agent show usage: yui config agent show <agent-id>");
     const agent = store.getConfiguredAgent(id);
     if (agent === null)
         throw agentNotFound(id);
@@ -137,7 +137,7 @@ function updateAgent(args, store) {
 function removeAgent(args, store) {
     const [rawId, ...rest] = args;
     const id = agentId(rawId);
-    assertNoArguments(rest, "Agent remove usage: yui agent remove <agent-id>");
+    assertNoArguments(rest, "Agent remove usage: yui config agent remove <agent-id>");
     const removed = store.transaction((tx) => {
         if (tx.getConfiguredAgent(id) === null)
             return false;