@kisev/skills-opencode 2.4.1 → 3.0.0

package/dist/cli.js

@@ -1,15 +1,21 @@
 #!/usr/bin/env node
 import { AgentProfileError, applyAgentProfileChange, availableModels, availableModelVariants, FIXED_AGENT_ROLES, listAgentProfiles, previewAgentProfileChange, validateAgentName, validateModel, validateVariant, } from "./agent-profiles.js";
-import { renderDoctor, renderInventory, renderPlan, renderReconcile, shellCommand, terminalSafe, } from "./cli-output.js";
+import { renderDoctor, renderInventory, renderPlan, renderReconcile, scopeArguments, shellCommand, terminalSafe, } from "./cli-output.js";
 import { collectDoctorFacts, doctorExitCode } from "./doctor.js";
 import { CATALOG } from "./catalog.js";
-import { apply, defaultSelection, InstallerError, normalizeSelection, PACKAGE_COMMANDS, preview, SELECTABLE_PLUGINS, SKILL_COMMANDS, } from "./installer.js";
+import { apply, defaultSelection, InstallerError, normalizeSelection, preview, SELECTABLE_PLUGINS, SKILL_COMMANDS, } from "./installer.js";
 import { LifecycleError } from "./lifecycle.js";
 import { skillsInstallerSpec } from "./package-metadata.js";
 import { applyReconcile, previewReconcile } from "./reconcile.js";
 import { promptText, selectOption, selectOptions } from "./terminal-wizard.js";
-function parseOptions(values, requireScope = true) {
-    const options = { dryRun: false, json: false, selectionFlag: false };
+function parseOptions(values) {
+    const options = {
+        scope: "project",
+        global: false,
+        dryRun: false,
+        json: false,
+        selectionFlag: false,
+    };
     for (let index = 0; index < values.length; index += 1) {
         const value = values[index];
         if (!value.startsWith("--")) {
@@ -17,13 +23,11 @@ function parseOptions(values, requireScope = true) {
                 throw new InstallerError("invalid_input", `Unexpected argument: ${value}`);
             options.name = value;
         }
-        else if (value === "--scope") {
-            const scope = values[++index];
-            if (scope !== "global" && scope !== "project")
-                throw new InstallerError("invalid_input", "--scope must be global or project");
-            if (options.scope)
-                throw new InstallerError("invalid_input", "--scope may be supplied once");
-            options.scope = scope;
+        else if (value === "--global") {
+            if (options.global)
+                throw new InstallerError("invalid_input", "--global may be supplied once");
+            options.global = true;
+            options.scope = "global";
         }
         else if (value === "--dry-run") {
             if (options.dryRun)
@@ -62,7 +66,7 @@ function parseOptions(values, requireScope = true) {
                 throw new InstallerError("invalid_input", "--json may be supplied once");
             options.json = true;
         }
-        else if (["--commands", "--skill-commands", "--package-commands", "--agents", "--plugins"].includes(value)) {
+        else if (["--commands", "--skill-commands", "--agents", "--plugins"].includes(value)) {
             const raw = values[++index];
             if (!raw)
                 throw new InstallerError("invalid_input", `${value} requires a comma-separated value`);
@@ -74,10 +78,7 @@ function parseOptions(values, requireScope = true) {
                     .map((item) => item.trim())
                     .filter(Boolean);
             options.selectionFlag = true;
-            if (value === "--package-commands") {
-                options.commands = [...(options.commands ?? []), ...names];
-            }
-            else if (value === "--skill-commands") {
+            if (value === "--skill-commands") {
                 options.commands = [...(options.commands ?? []), ...names];
             }
             else {
@@ -88,8 +89,6 @@ function parseOptions(values, requireScope = true) {
             throw new InstallerError("invalid_input", `Unknown argument: ${value}`);
         }
     }
-    if (requireScope && !options.scope)
-        throw new InstallerError("invalid_input", "--scope is required");
     return options;
 }
 function helpRows(rows) {
@@ -109,7 +108,7 @@ function rootHelp() {
         "",
         "Commands:",
         ...helpRows([
-            ["install", "Select and deploy package-owned commands, agents, and plugin wrappers."],
+            ["install", "Select and deploy skill commands, agents, and plugin wrappers."],
             [
                 "uninstall",
                 "Archive and remove exact-owned assets while preserving conflicts and user files.",
@@ -127,7 +126,7 @@ function rootHelp() {
         "",
         "Common options:",
         ...helpRows([
-            ["--scope <project|global>", "Required by every command except capabilities."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--dry-run", "Preview a mutation and issue a one-time confirmation digest."],
             ["--confirm <digest>", "Apply the exact unexpired preview after final revalidation."],
             ["--json", "Emit stable machine-readable output when supported."],
@@ -137,9 +136,8 @@ function rootHelp() {
         "",
         "Install selection:",
         ...helpRows([
-            ["--commands <list|none>", "Select command adapters from both command groups."],
+            ["--commands <list|none>", "Select adapters for installed portable skills."],
             ["--skill-commands <list|none>", "Select adapters for installed portable skills."],
-            ["--package-commands <list|none>", "Select adapters for package tools."],
             ["--agents <list|none>", "Select fixed agents."],
             ["--plugins <list|none>", "Select optional plugin wrappers."],
         ]),
@@ -163,20 +161,19 @@ function rootHelp() {
         "",
         "Scope behavior:",
         ...helpRows([
-            ["project", "Targets .opencode under the current directory; run from the project root."],
-            ["global", "Targets ~/.config/opencode and can run from any directory."],
+            ["default", "Targets .opencode under the current directory; run from the project root."],
+            ["--global", "Targets ~/.config/opencode and can run from any directory."],
         ]),
         "",
         "Examples:",
         `  ${shellCommand(["capabilities", "--json"])}`,
-        `  ${shellCommand(["install", "--scope", "global", "--dry-run"])}`,
-        `  ${shellCommand(["doctor", "--scope", "global"])}`,
+        `  ${shellCommand(["install", "--global", "--dry-run"])}`,
+        `  ${shellCommand(["doctor", "--global"])}`,
         `  ${shellCommand([
             "agent",
             "model-set",
             "worker",
-            "--scope",
-            "global",
+            "--global",
             "--model",
             "openai/gpt-5",
             "--variant",
@@ -233,15 +230,14 @@ function contextualHelp(arguments_) {
     const [domain, operation] = arguments_.filter((value) => value !== "--help");
     if (domain === "install")
         return commandHelp("install", "Select and deploy package-owned OpenCode integration assets.", [
-            "skills-opencode install --scope <project|global> --dry-run [selection options]",
-            "skills-opencode install --scope <project|global> --confirm <digest> [selection options]",
+            "skills-opencode install [--global] --dry-run [selection options]",
+            "skills-opencode install [--global] --confirm <digest> [selection options]",
         ], [
-            ["--scope <project|global>", "Choose the deployment scope."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--dry-run", "Preview operations and issue a one-time confirmation digest."],
             ["--confirm <digest>", "Apply the exact unexpired preview."],
-            ["--commands <list|none>", "Select adapters from both command groups."],
+            ["--commands <list|none>", "Select installed-skill adapters."],
             ["--skill-commands <list|none>", "Select installed-skill adapters."],
-            ["--package-commands <list|none>", "Select package-tool adapters."],
             ["--agents <list|none>", "Select fixed agents."],
             ["--plugins <list|none>", "Select optional plugin wrappers."],
             ["--json", "Emit stable machine-readable output."],
@@ -253,11 +249,9 @@ function contextualHelp(arguments_) {
             "Writes occur only after confirmation; the installer never edits opencode.json.",
             "Portable skills are installed separately; restart OpenCode after asset changes.",
         ], [
-            shellCommand(["install", "--scope", "global", "--dry-run"]),
+            shellCommand(["install", "--global", "--dry-run"]),
             shellCommand([
                 "install",
-                "--scope",
-                "project",
                 "--commands",
                 "doctor,reconcile,agent-profiles",
                 "--agents",
@@ -269,10 +263,10 @@ function contextualHelp(arguments_) {
         ]);
     if (domain === "uninstall")
         return commandHelp("uninstall", "Remove package-owned integration assets safely.", [
-            "skills-opencode uninstall --scope <project|global> --dry-run",
-            "skills-opencode uninstall --scope <project|global> --confirm <digest>",
+            "skills-opencode uninstall [--global] --dry-run",
+            "skills-opencode uninstall [--global] --confirm <digest>",
         ], [
-            ["--scope <project|global>", "Choose the deployment scope."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--dry-run", "Preview removals, archives, and conflicts."],
             ["--confirm <digest>", "Apply the exact unexpired preview."],
             ["--json", "Emit stable machine-readable output."],
@@ -282,22 +276,19 @@ function contextualHelp(arguments_) {
             "Preserves modified and user-owned files, worktrees, runtime state, and portable skills.",
             "Remove the plugin config entry and npm dependency only after managed assets.",
         ], [
-            shellCommand(["uninstall", "--scope", "global", "--dry-run"]),
-            shellCommand(["uninstall", "--scope", "project", "--dry-run"]),
+            shellCommand(["uninstall", "--global", "--dry-run"]),
+            shellCommand(["uninstall", "--dry-run"]),
         ]);
     if (domain === "doctor")
-        return commandHelp("doctor", "Inspect integration health without changing state.", ["skills-opencode doctor --scope <project|global> [--json]"], [
-            ["--scope <project|global>", "Choose the scope to inspect."],
+        return commandHelp("doctor", "Inspect integration health without changing state.", ["skills-opencode doctor [--global] [--json]"], [
+            ["--global", "Inspect global scope; project scope is the default."],
             ["--json", "Emit the complete stable machine-readable report."],
             ["--help", "Show this command help and exit."],
         ], [
             "Creates no receipts and starts no recovery, plugin factories, or LSP servers.",
             "Reports versions, ownership, drift, collisions, config, archives, tools, and LSP facts.",
             "Exit status: 0 clean, 1 findings, 2 invalid input or incomplete probing.",
-        ], [
-            shellCommand(["doctor", "--scope", "global"]),
-            shellCommand(["doctor", "--scope", "global", "--json"]),
-        ]);
+        ], [shellCommand(["doctor"]), shellCommand(["doctor", "--global", "--json"])]);
     if (domain === "capabilities")
         return commandHelp("capabilities", "Print the versioned package capability catalog.", ["skills-opencode capabilities [--json]"], [
             ["--json", "Explicitly request stable JSON output; JSON is the default."],
@@ -308,38 +299,35 @@ function contextualHelp(arguments_) {
         ], [shellCommand(["capabilities", "--json"])]);
     if (domain === "reconcile")
         return commandHelp("reconcile", "Classify current and historical assets and retire exact-owned entries.", [
-            "skills-opencode reconcile --scope <project|global> --dry-run",
-            "skills-opencode reconcile --scope <project|global> --confirm <digest>",
+            "skills-opencode reconcile [--global] --dry-run",
+            "skills-opencode reconcile [--global] --confirm <digest>",
         ], [
-            ["--scope <project|global>", "Choose the scope to reconcile."],
+            ["--global", "Reconcile global scope; project scope is the default."],
             ["--dry-run", "Preview classifications, archives, and blockers."],
             ["--confirm <digest>", "Apply the exact unexpired preview."],
             ["--json", "Emit stable machine-readable output."],
             ["--help", "Show this command help and exit."],
         ], [
             "Preview is read-only and blocks Apply on modified managed files or ownership conflicts.",
-            "Confirmed reconcile archives only exact-owned retired assets.",
-            "Never installs, updates, or removes portable skills.",
+            "Confirmed reconcile archives exact-owned retired package assets.",
+            "Marked retired portable skills are removed by the pinned skills CLI.",
         ], [
-            shellCommand(["reconcile", "--scope", "global", "--dry-run"]),
-            shellCommand(["reconcile", "--scope", "project", "--dry-run", "--json"]),
+            shellCommand(["reconcile", "--global", "--dry-run"]),
+            shellCommand(["reconcile", "--dry-run", "--json"]),
         ]);
     if (domain === "agent" && operation === "list")
-        return commandHelp("agent list", "List agent profiles, models, ownership, collisions, and drift.", ["skills-opencode agent list --scope <project|global> [--json]"], [
-            ["--scope <project|global>", "Choose the profile scope."],
+        return commandHelp("agent list", "List agent profiles, models, ownership, collisions, and drift.", ["skills-opencode agent list [--global] [--json]"], [
+            ["--global", "Inspect global scope; project scope is the default."],
             ["--json", "Emit stable machine-readable inventory."],
             ["--help", "Show this command help and exit."],
-        ], ["Read-only inventory; creates no receipts and changes no files or configuration."], [
-            shellCommand(["agent", "list", "--scope", "global"]),
-            shellCommand(["agent", "list", "--scope", "project", "--json"]),
-        ]);
+        ], ["Read-only inventory; creates no receipts and changes no files or configuration."], [shellCommand(["agent", "list", "--global"]), shellCommand(["agent", "list", "--json"])]);
     if (domain === "agent" && operation === "configure")
         return commandHelp("agent configure", "Choose an agent model interactively or with explicit options.", [
-            "skills-opencode agent configure [name] --scope <project|global> --dry-run",
-            "skills-opencode agent configure <name> --scope <project|global> --model <provider/model> [--variant <id>] --dry-run",
-            "skills-opencode agent configure <name> --scope <project|global> --model <provider/model> [--variant <id>] --confirm <digest>",
+            "skills-opencode agent configure [name] [--global] --dry-run",
+            "skills-opencode agent configure <name> [--global] --model <provider/model> [--variant <id>] --dry-run",
+            "skills-opencode agent configure <name> [--global] --model <provider/model> [--variant <id>] --confirm <digest>",
         ], [
-            ["--scope <project|global>", "Choose the profile scope."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--provider <id>", "Provider when --model is not provider/model."],
             ["--model <id>", "Exact provider/model or model paired with --provider."],
             ["--variant <id>", "Set an optional model variant."],
@@ -353,13 +341,12 @@ function contextualHelp(arguments_) {
             "Uses the cached OpenCode model catalog and makes no LLM call.",
             "The preview normally prints an agent model-set Apply command.",
         ], [
-            shellCommand(["agent", "configure", "manager", "--scope", "global", "--dry-run"]),
+            shellCommand(["agent", "configure", "manager", "--global", "--dry-run"]),
             shellCommand([
                 "agent",
                 "configure",
                 "worker",
-                "--scope",
-                "global",
+                "--global",
                 "--model",
                 "openai/gpt-5",
                 "--variant",
@@ -369,10 +356,10 @@ function contextualHelp(arguments_) {
         ]);
     if (domain === "agent" && operation === "model-set")
         return commandHelp("agent model-set", "Set one agent model and optional variant directly.", [
-            "skills-opencode agent model-set <name> --scope <project|global> --model <provider/model> [--variant <id>] --dry-run",
-            "skills-opencode agent model-set <name> --scope <project|global> --model <provider/model> [--variant <id>] --confirm <digest>",
+            "skills-opencode agent model-set <name> [--global] --model <provider/model> [--variant <id>] --dry-run",
+            "skills-opencode agent model-set <name> [--global] --model <provider/model> [--variant <id>] --confirm <digest>",
         ], [
-            ["--scope <project|global>", "Choose the profile scope."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--provider <id>", "Provider when --model is not provider/model."],
             ["--model <id>", "Exact provider/model or model paired with --provider."],
             ["--variant <id>", "Set an optional model variant."],
@@ -390,8 +377,7 @@ function contextualHelp(arguments_) {
                 "agent",
                 "model-set",
                 "worker",
-                "--scope",
-                "global",
+                "--global",
                 "--model",
                 "openai/gpt-5",
                 "--variant",
@@ -402,8 +388,7 @@ function contextualHelp(arguments_) {
                 "agent",
                 "model-set",
                 "manager",
-                "--scope",
-                "global",
+                "--global",
                 "--model",
                 "openai/gpt-5",
                 "--clear-variant",
@@ -412,10 +397,10 @@ function contextualHelp(arguments_) {
         ]);
     if (domain === "agent" && operation === "reconcile")
         return commandHelp("agent reconcile", "Re-render managed agent files from saved profile configuration.", [
-            "skills-opencode agent reconcile --scope <project|global> --dry-run",
-            "skills-opencode agent reconcile --scope <project|global> --confirm <digest>",
+            "skills-opencode agent reconcile [--global] --dry-run",
+            "skills-opencode agent reconcile [--global] --confirm <digest>",
         ], [
-            ["--scope <project|global>", "Choose the profile scope."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--dry-run", "Preview rendered agent changes and conflicts."],
             ["--confirm <digest>", "Apply the exact unexpired preview."],
             ["--json", "Emit stable machine-readable output."],
@@ -424,8 +409,8 @@ function contextualHelp(arguments_) {
             "Uses saved models and variants while preserving package prompts and permissions.",
             "Preserves user-owned files and collisions; writes only after confirmation.",
         ], [
-            shellCommand(["agent", "reconcile", "--scope", "global", "--dry-run"]),
-            shellCommand(["agent", "reconcile", "--scope", "project", "--dry-run", "--json"]),
+            shellCommand(["agent", "reconcile", "--global", "--dry-run"]),
+            shellCommand(["agent", "reconcile", "--dry-run", "--json"]),
         ]);
     if (domain === "agent")
         return groupHelp("agent", "Inspect and manage fixed agents and additional critics.", "skills-opencode agent <command> [options]", [
@@ -437,17 +422,14 @@ function contextualHelp(arguments_) {
             "Prompts and permissions remain package-owned.",
             "Profile configuration changes models, variants, and additional critics.",
             "Mutations use preview and exact confirmation.",
-        ], [
-            shellCommand(["agent", "list", "--scope", "global"]),
-            shellCommand(["agent", "model-set", "--help"]),
-        ]);
+        ], [shellCommand(["agent", "list", "--global"]), shellCommand(["agent", "model-set", "--help"])]);
     if (domain === "critic" && operation === "add")
         return commandHelp("critic add", "Add an additional named critic with a selected model.", [
-            "skills-opencode critic add [name] --scope <project|global> --dry-run",
-            "skills-opencode critic add <name> --scope <project|global> --model <provider/model> [--variant <id>] --dry-run",
-            "skills-opencode critic add <name> --scope <project|global> --model <provider/model> [--variant <id>] --confirm <digest>",
+            "skills-opencode critic add [name] [--global] --dry-run",
+            "skills-opencode critic add <name> [--global] --model <provider/model> [--variant <id>] --dry-run",
+            "skills-opencode critic add <name> [--global] --model <provider/model> [--variant <id>] --confirm <digest>",
         ], [
-            ["--scope <project|global>", "Choose the profile scope."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--provider <id>", "Provider when --model is not provider/model."],
             ["--model <id>", "Exact provider/model or model paired with --provider."],
             ["--variant <id>", "Set an optional model variant."],
@@ -464,20 +446,19 @@ function contextualHelp(arguments_) {
                 "critic",
                 "add",
                 "security",
-                "--scope",
-                "global",
+                "--global",
                 "--model",
                 "anthropic/claude-sonnet-4-6",
                 "--dry-run",
             ]),
-            shellCommand(["critic", "add", "performance", "--scope", "global", "--dry-run"]),
+            shellCommand(["critic", "add", "performance", "--global", "--dry-run"]),
         ]);
     if (domain === "critic" && operation === "remove")
         return commandHelp("critic remove", "Remove a package-managed additional critic.", [
-            "skills-opencode critic remove <name> --scope <project|global> --dry-run",
-            "skills-opencode critic remove <name> --scope <project|global> --confirm <digest>",
+            "skills-opencode critic remove <name> [--global] --dry-run",
+            "skills-opencode critic remove <name> [--global] --confirm <digest>",
         ], [
-            ["--scope <project|global>", "Choose the profile scope."],
+            ["--global", "Use global scope; project scope is the default."],
             ["--dry-run", "Preview critic removal and pool changes."],
             ["--confirm <digest>", "Apply the exact unexpired preview."],
             ["--json", "Emit stable machine-readable output."],
@@ -487,8 +468,8 @@ function contextualHelp(arguments_) {
             "Preserves the fixed critic and user-owned files.",
             "Updates manager and review critic pools after confirmation.",
         ], [
-            shellCommand(["critic", "remove", "security", "--scope", "global", "--dry-run"]),
-            shellCommand(["critic", "remove", "security", "--scope", "project", "--dry-run"]),
+            shellCommand(["critic", "remove", "security", "--global", "--dry-run"]),
+            shellCommand(["critic", "remove", "security", "--dry-run"]),
         ]);
     if (domain === "critic")
         return groupHelp("critic", "Manage additional package-owned critic profiles.", "skills-opencode critic <command> [options]", [
@@ -504,9 +485,6 @@ function contextualHelp(arguments_) {
         ]);
     return undefined;
 }
-function help(arguments_ = []) {
-    return contextualHelp(arguments_) ?? rootHelp();
-}
 async function interactiveInstallerSelection() {
     if (!process.stdin.isTTY || !process.stderr.isTTY)
         throw new InstallerError("terminal_required", "install requires explicit selection flags outside a terminal");
@@ -514,7 +492,6 @@ async function interactiveInstallerSelection() {
         "Portable skills are installed separately through npx skills.",
         "This installer does not install, update, or remove portable skills.",
         "Skill command adapters are OpenCode slash commands that load an already-installed skill with the same name.",
-        "Package command adapters invoke package tools.",
         "Selecting a command adapter does not select or install its skill.",
         "\n",
     ].join("\n"));
@@ -525,10 +502,7 @@ async function interactiveInstallerSelection() {
         return selected;
     };
     const defaults = defaultSelection();
-    const commands = [
-        ...(await group("Skill command adapters", SKILL_COMMANDS, SKILL_COMMANDS)),
-        ...(await group("Package command adapters", PACKAGE_COMMANDS, PACKAGE_COMMANDS)),
-    ];
+    const commands = await group("Skill command adapters", SKILL_COMMANDS, SKILL_COMMANDS);
     const agents = await group("Fixed agents", defaults.agents, defaults.agents);
     const plugins = await group("Selectable plugins", SELECTABLE_PLUGINS, []);
     return normalizeSelection({
@@ -717,13 +691,13 @@ async function runProfile(request, options) {
 }
 function profileConfirmationArguments(request, scope, digest) {
     if (request.action === "reconcile")
-        return ["agent", "reconcile", "--scope", scope, "--confirm", digest];
+        return ["agent", "reconcile", ...scopeArguments(scope), "--confirm", digest];
     if (request.action === "critic-remove")
-        return ["critic", "remove", request.name, "--scope", scope, "--confirm", digest];
+        return ["critic", "remove", request.name, ...scopeArguments(scope), "--confirm", digest];
     const command = request.action === "critic-add"
         ? ["critic", "add", request.name]
         : ["agent", "model-set", request.name];
-    command.push("--scope", scope, "--model", request.model);
+    command.push(...scopeArguments(scope), "--model", request.model);
     if (request.variant)
         command.push("--variant", request.variant);
     else if (request.action === "model-set")
@@ -732,11 +706,36 @@ function profileConfirmationArguments(request, scope, digest) {
     return command;
 }
 async function run(arguments_) {
-    if (arguments_.includes("--help") || arguments_.length === 0) {
-        process.stdout.write(help(arguments_));
+    const removedScope = arguments_.find((value) => value === "--scope" || value.startsWith("--scope="));
+    if (removedScope)
+        throw new InstallerError("invalid_input", "--scope has been removed; omit it for project scope or use --global");
+    if (arguments_.filter((value) => value === "--global").length > 1)
+        throw new InstallerError("invalid_input", "--global may be supplied once");
+    if (arguments_[0] === "capabilities" && arguments_.includes("--global"))
+        throw new InstallerError("invalid_input", "capabilities accepts only --json");
+    if (arguments_.includes("--help")) {
+        const [domain, operation] = arguments_.filter((value) => !value.startsWith("--"));
+        if ((domain === "agent" &&
+            operation &&
+            !["list", "configure", "model-set", "reconcile"].includes(operation)) ||
+            (domain === "critic" && operation && !["add", "remove"].includes(operation)))
+            throw new InstallerError("invalid_input", `Unknown command: ${domain} ${operation}`);
+        const page = contextualHelp(arguments_);
+        if (!page && arguments_[0] !== "--help")
+            throw new InstallerError("invalid_input", `Unknown command: ${arguments_[0]}`);
+        for (const value of arguments_.filter((item) => item.startsWith("--") && item !== "--help"))
+            if (!(page ?? rootHelp()).includes(value))
+                throw new InstallerError("invalid_input", `Unknown argument: ${value}`);
+        process.stdout.write(page ?? rootHelp());
+        return;
+    }
+    if (arguments_.length === 0) {
+        process.stdout.write(rootHelp());
         return;
     }
     if (arguments_.includes("--version")) {
+        if (arguments_.some((value) => value !== "--version" && value !== "--json"))
+            throw new InstallerError("invalid_input", "--version accepts only --json");
         process.stdout.write(arguments_.includes("--json")
             ? `${JSON.stringify({ status: "ok", version: CATALOG.version })}\n`
             : `${CATALOG.version}\n`);
@@ -752,8 +751,9 @@ async function run(arguments_) {
             options.name ||
             options.provider ||
             options.model ||
-            options.variant !== undefined)
-            throw new InstallerError("invalid_input", "doctor accepts only --scope and --json");
+            options.variant !== undefined ||
+            options.selectionFlag)
+            throw new InstallerError("invalid_input", "doctor accepts only --global and --json");
         const report = await collectDoctorFacts(options.scope);
         if (options.json)
             process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -763,15 +763,18 @@ async function run(arguments_) {
         return;
     }
     if (domain === "capabilities") {
-        const options = parseOptions(rest, false);
+        if (operation)
+            rest.unshift(operation);
+        const options = parseOptions(rest);
         if (options.dryRun ||
             options.confirm ||
             options.name ||
             options.provider ||
             options.model ||
             options.variant !== undefined ||
+            options.global ||
             options.selectionFlag)
-            throw new InstallerError("invalid_input", "capabilities accepts only --scope and --json");
+            throw new InstallerError("invalid_input", "capabilities accepts only --json");
         process.stdout.write(`${JSON.stringify({ schema_version: 1, status: "ok", ...CATALOG }, null, 2)}\n`);
         return;
     }
@@ -779,8 +782,12 @@ async function run(arguments_) {
         if (operation)
             rest.unshift(operation);
         const options = parseOptions(rest);
-        if (options.name || options.provider || options.model || options.variant !== undefined)
-            throw new InstallerError("invalid_input", "reconcile accepts only scope and confirmation options");
+        if (options.name ||
+            options.provider ||
+            options.model ||
+            options.variant !== undefined ||
+            options.selectionFlag)
+            throw new InstallerError("invalid_input", "reconcile accepts only --global, --dry-run, --confirm, and --json");
         requireConfirmationMode(options);
         if (options.dryRun) {
             const plan = await previewReconcile(options.scope);
@@ -792,8 +799,7 @@ async function run(arguments_) {
                     confirmationCommand: plan.confirmable
                         ? shellCommand([
                             "reconcile",
-                            "--scope",
-                            options.scope,
+                            ...scopeArguments(options.scope),
                             "--confirm",
                             plan.confirmation_digest ?? plan.digest,
                         ])
@@ -815,9 +821,15 @@ async function run(arguments_) {
         else
             throw new InstallerError("invalid_input", `Unexpected argument: ${operation}`);
         const options = parseOptions(rest);
-        if (options.name || options.provider || options.model || options.variant !== undefined)
-            throw new InstallerError("invalid_input", "Installer accepts only scope and confirmation options");
         const action = domain;
+        if (options.name ||
+            options.provider ||
+            options.model ||
+            options.variant !== undefined ||
+            (action === "uninstall" && options.selectionFlag))
+            throw new InstallerError("invalid_input", action === "install"
+                ? "install does not accept model options or positional arguments"
+                : "uninstall accepts only --global, --dry-run, --confirm, and --json");
         if (action === "install" &&
             options.selectionFlag &&
             (options.commands === undefined ||
@@ -839,8 +851,7 @@ async function run(arguments_) {
                     applied: false,
                     confirmationCommand: shellCommand([
                         action,
-                        "--scope",
-                        options.scope,
+                        ...scopeArguments(options.scope),
                         ...selectionArguments(plan.selection),
                         "--confirm",
                         plan.digest,
@@ -863,8 +874,9 @@ async function run(arguments_) {
             options.name ||
             options.provider ||
             options.model ||
-            options.variant !== undefined)
-            throw new InstallerError("invalid_input", "agent list accepts only --scope");
+            options.variant !== undefined ||
+            options.selectionFlag)
+            throw new InstallerError("invalid_input", "agent list accepts only --global and --json");
         const inventory = await listAgentProfiles(options.scope);
         if (options.json)
             process.stdout.write(`${JSON.stringify({ status: "ok", inventory }, null, 2)}\n`);
@@ -874,6 +886,8 @@ async function run(arguments_) {
     }
     if (domain === "agent" && operation === "configure") {
         const options = parseOptions(rest);
+        if (options.selectionFlag)
+            throw new InstallerError("invalid_input", "agent configure does not accept selection options");
         requireConfirmationMode(options);
         const selected = options.provider && options.model && options.name
             ? {
@@ -889,6 +903,8 @@ async function run(arguments_) {
     }
     if (domain === "agent" && operation === "model-set") {
         const options = parseOptions(rest);
+        if (options.selectionFlag)
+            throw new InstallerError("invalid_input", "agent model-set does not accept selection options");
         const name = validateAgentName(options.name ?? "");
         const model = exactModel(options);
         if (!model)
@@ -898,17 +914,25 @@ async function run(arguments_) {
     }
     if (domain === "agent" && operation === "reconcile") {
         const options = parseOptions(rest);
-        if (options.name || options.provider || options.model || options.variant !== undefined)
-            throw new InstallerError("invalid_input", "agent reconcile accepts only scope and confirmation options");
+        if (options.name ||
+            options.provider ||
+            options.model ||
+            options.variant !== undefined ||
+            options.selectionFlag)
+            throw new InstallerError("invalid_input", "agent reconcile accepts only --global, --dry-run, --confirm, and --json");
         await runProfile({ action: "reconcile" }, options);
         return;
     }
     if (domain === "critic" && (operation === "add" || operation === "remove")) {
         const options = parseOptions(rest);
+        if (options.selectionFlag)
+            throw new InstallerError("invalid_input", `critic ${operation} does not accept selection options`);
         const name = options.name === "critic" || options.name?.startsWith("critic-")
             ? options.name
             : `critic-${options.name ?? ""}`;
         if (operation === "add") {
+            if (options.variant === null)
+                throw new InstallerError("invalid_input", "critic add does not accept --clear-variant");
             const model = exactModel(options);
             if (!model) {
                 const selected = await interactiveSelection(options, "critic-add");
@@ -924,13 +948,16 @@ async function run(arguments_) {
             }
         }
         else {
-            if (options.provider || options.model || options.variant !== undefined)
+            if (options.provider ||
+                options.model ||
+                options.variant !== undefined ||
+                options.selectionFlag)
                 throw new InstallerError("invalid_input", "critic remove does not accept model options");
             await runProfile({ action: "critic-remove", name }, options);
         }
         return;
     }
-    throw new InstallerError("invalid_input", "Use install, uninstall, agent list|configure|model-set|reconcile, or critic add|remove");
+    throw new InstallerError("invalid_input", "Use install, uninstall, doctor, capabilities, reconcile, agent list|configure|model-set|reconcile, or critic add|remove");
 }
 async function main() {
     try {