maqcli 0.2.0

package/dist/core/catalog.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Model catalog + cheapest-master resolver — the "$0 intelligence layer".
+ *
+ * The master's own thinking (Scout summaries, Plan candidates, Verify review)
+ * should cost as close to $0 as possible. This module answers "what is the
+ * cheapest capable master model available right now?" by inspecting the
+ * environment (provider API keys, a local Ollama, and — preferred — any
+ * already-authenticated worker CLI whose subscription the user already pays
+ * for). Heavy Worker executions stay BYO-key; only the light master loop is
+ * auto-optimized here.
+ *
+ * Ranking (best first) balances marginal cost against quality:
+ *   1. an authenticated worker CLI (reuse the user's existing subscription; $0 marginal)
+ *   2. a free-tier cloud key (Groq / Gemini Flash)
+ *   3. a local Ollama model ($0, uses local compute)
+ *   4. the cheapest paid key (gpt-4o-mini / claude-3-5-haiku)
+ *   5. the offline heuristic provider (always available, $0, deterministic)
+ */
+import type { DetectedAgent } from "./types.js";
+export type CostClass = "free-local" | "free-tier" | "byo-subscription" | "paid" | "offline";
+export interface MasterOption {
+    /** Provider name for config (`provider`). */
+    provider: string;
+    /** Model name for config (`cheapModel`). For CLI it's `cli:<agent>`. */
+    model: string;
+    label: string;
+    costClass: CostClass;
+    /** USD per 1M input/output, 0 for free/local. */
+    pricePer1MIn: number;
+    pricePer1MOut: number;
+    available: boolean;
+    reason: string;
+}
+export interface CatalogEnv {
+    OPENAI_API_KEY?: string;
+    ANTHROPIC_API_KEY?: string;
+    GROQ_API_KEY?: string;
+    GEMINI_API_KEY?: string;
+    GOOGLE_API_KEY?: string;
+    OLLAMA_HOST?: string;
+    MAQ_PROVIDER_BASE_URL?: string;
+}
+export declare function resolveEnv(env?: NodeJS.ProcessEnv): CatalogEnv;
+/**
+ * Build the ranked list of master options given the environment + detected
+ * agents. Only `available: true` options can actually be used now.
+ */
+export declare function masterOptions(env?: CatalogEnv, agents?: DetectedAgent[]): MasterOption[];
+/** The single cheapest available master option (never throws; heuristic is the floor). */
+export declare function cheapestMaster(env?: CatalogEnv, agents?: DetectedAgent[]): MasterOption;

package/dist/core/catalog.js

@@ -0,0 +1,103 @@
+/**
+ * Model catalog + cheapest-master resolver — the "$0 intelligence layer".
+ *
+ * The master's own thinking (Scout summaries, Plan candidates, Verify review)
+ * should cost as close to $0 as possible. This module answers "what is the
+ * cheapest capable master model available right now?" by inspecting the
+ * environment (provider API keys, a local Ollama, and — preferred — any
+ * already-authenticated worker CLI whose subscription the user already pays
+ * for). Heavy Worker executions stay BYO-key; only the light master loop is
+ * auto-optimized here.
+ *
+ * Ranking (best first) balances marginal cost against quality:
+ *   1. an authenticated worker CLI (reuse the user's existing subscription; $0 marginal)
+ *   2. a free-tier cloud key (Groq / Gemini Flash)
+ *   3. a local Ollama model ($0, uses local compute)
+ *   4. the cheapest paid key (gpt-4o-mini / claude-3-5-haiku)
+ *   5. the offline heuristic provider (always available, $0, deterministic)
+ */
+import { detectAgents } from "./registry.js";
+import { priceFor } from "./cost.js";
+/** Preferred lightest master model per detected CLI agent. */
+const CLI_MODEL_HINT = {
+    gemini: "cli:gemini",
+    "claude-code": "cli:claude-code",
+    codex: "cli:codex",
+    opencode: "cli:opencode",
+    "amazon-q": "cli:amazon-q",
+    aider: "cli:aider",
+};
+export function resolveEnv(env = process.env) {
+    return {
+        OPENAI_API_KEY: env.OPENAI_API_KEY,
+        ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY,
+        GROQ_API_KEY: env.GROQ_API_KEY,
+        GEMINI_API_KEY: env.GEMINI_API_KEY,
+        GOOGLE_API_KEY: env.GOOGLE_API_KEY,
+        OLLAMA_HOST: env.OLLAMA_HOST,
+        MAQ_PROVIDER_BASE_URL: env.MAQ_PROVIDER_BASE_URL,
+    };
+}
+/**
+ * Build the ranked list of master options given the environment + detected
+ * agents. Only `available: true` options can actually be used now.
+ */
+export function masterOptions(env = resolveEnv(), agents = detectAgents()) {
+    const out = [];
+    // 1. Authenticated worker CLIs (reuse existing subscription; $0 marginal).
+    for (const a of agents) {
+        if (a.installed && a.authenticated && CLI_MODEL_HINT[a.name]) {
+            out.push({
+                provider: CLI_MODEL_HINT[a.name],
+                model: CLI_MODEL_HINT[a.name],
+                label: `${a.name} (headless CLI as master)`,
+                costClass: "byo-subscription",
+                pricePer1MIn: 0,
+                pricePer1MOut: 0,
+                available: true,
+                reason: "authenticated CLI reused for master thinking ($0 marginal)",
+            });
+        }
+    }
+    // 2. Free-tier cloud keys.
+    if (env.GROQ_API_KEY) {
+        out.push(opt("groq", "llama-3.3-70b-versatile", "Groq (free tier)", "free-tier", true, "GROQ_API_KEY present"));
+    }
+    if (env.GEMINI_API_KEY || env.GOOGLE_API_KEY) {
+        // Reached via an OpenAI-compatible/LiteLLM proxy; label reflects the free tier.
+        out.push(opt("openai-compatible", "gemini-2.0-flash", "Gemini Flash (free tier via proxy)", "free-tier", Boolean(env.MAQ_PROVIDER_BASE_URL), env.MAQ_PROVIDER_BASE_URL ? "Gemini key + proxy base URL present" : "set MAQ_PROVIDER_BASE_URL to a Gemini-compatible proxy"));
+    }
+    // 3. Local Ollama ($0, local compute).
+    out.push(opt("ollama", "llama3.1", "Ollama (local, $0)", "free-local", Boolean(env.OLLAMA_HOST), env.OLLAMA_HOST ? "OLLAMA_HOST set" : "start Ollama and/or set OLLAMA_HOST"));
+    // 4. Cheapest paid keys.
+    if (env.OPENAI_API_KEY) {
+        const p = priceFor("gpt-4o-mini");
+        out.push({ provider: "openai", model: "gpt-4o-mini", label: "OpenAI gpt-4o-mini", costClass: "paid", pricePer1MIn: p.in, pricePer1MOut: p.out, available: true, reason: "OPENAI_API_KEY present" });
+    }
+    if (env.ANTHROPIC_API_KEY) {
+        const p = priceFor("claude-3-5-haiku");
+        out.push({ provider: "anthropic", model: "claude-3-5-haiku-latest", label: "Anthropic Claude Haiku", costClass: "paid", pricePer1MIn: p.in, pricePer1MOut: p.out, available: true, reason: "ANTHROPIC_API_KEY present" });
+    }
+    // 5. Offline heuristic (always).
+    out.push({ provider: "heuristic", model: "heuristic-local", label: "Offline heuristic ($0, deterministic)", costClass: "offline", pricePer1MIn: 0, pricePer1MOut: 0, available: true, reason: "always available; no network or key" });
+    return out.sort((a, b) => rank(a) - rank(b));
+}
+function opt(provider, model, label, costClass, available, reason) {
+    return { provider, model, label, costClass, pricePer1MIn: 0, pricePer1MOut: 0, available, reason };
+}
+/** Lower rank = preferred. Available options always beat unavailable ones. */
+function rank(o) {
+    const classRank = {
+        "byo-subscription": 0,
+        "free-tier": 1,
+        "free-local": 2,
+        paid: 3,
+        offline: 4,
+    };
+    return (o.available ? 0 : 100) + classRank[o.costClass];
+}
+/** The single cheapest available master option (never throws; heuristic is the floor). */
+export function cheapestMaster(env = resolveEnv(), agents = detectAgents()) {
+    const avail = masterOptions(env, agents).filter((o) => o.available);
+    return avail[0];
+}

package/dist/core/command-catalog.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Command catalog — the machine-readable menu the app uses to "pitch" the CLI
+ * to a user: what commands exist, what each does, which args to prompt for, and
+ * whether an action is destructive (confirm first). Also carries a catalog of
+ * the AI worker CLIs' own commands/flags so the app can surface them.
+ *
+ * Non-Master edition: the app renders `maqCommands` as selectable actions and
+ * prompts for `args` / `needsInput`. Master edition: the app is a terminal and
+ * the user types freely; this catalog powers autocomplete.
+ */
+export type ArgType = "string" | "enum" | "boolean" | "path";
+export interface CommandArg {
+    name: string;
+    type: ArgType;
+    required?: boolean;
+    choices?: string[];
+    description: string;
+}
+export interface MaqCommand {
+    name: string;
+    category: "pipeline" | "session" | "model" | "agents" | "memory" | "system" | "control";
+    summary: string;
+    usage: string;
+    /** What free-text the app should collect before running (a task, a query, none). */
+    needsInput: "task" | "query" | "none";
+    args: CommandArg[];
+    destructive?: boolean;
+}
+export declare const maqCommands: MaqCommand[];
+export interface AiCliEntry {
+    name: string;
+    bin: string;
+    /** Headless invocation MAQ uses; {task} is substituted. */
+    headless: string;
+    /** Notable interactive/slash commands the app can surface. */
+    commands: string[];
+    notes: string;
+}
+/** Catalog of AI worker CLIs' own commands/flags (verified 2026-07-01). */
+export declare const aiCliCatalog: AiCliEntry[];
+export declare function commandCatalog(): {
+    maq: MaqCommand[];
+    aiClis: AiCliEntry[];
+};

package/dist/core/command-catalog.js

@@ -0,0 +1,86 @@
+/**
+ * Command catalog — the machine-readable menu the app uses to "pitch" the CLI
+ * to a user: what commands exist, what each does, which args to prompt for, and
+ * whether an action is destructive (confirm first). Also carries a catalog of
+ * the AI worker CLIs' own commands/flags so the app can surface them.
+ *
+ * Non-Master edition: the app renders `maqCommands` as selectable actions and
+ * prompts for `args` / `needsInput`. Master edition: the app is a terminal and
+ * the user types freely; this catalog powers autocomplete.
+ */
+export const maqCommands = [
+    { name: "run", category: "pipeline", summary: "Run a task through Scout→Plan→Execute→Verify.", usage: 'maq run "<task>" [--target t] [--provider p] [--model m] [--dry-run] [--audit]', needsInput: "task",
+        args: [
+            { name: "target", type: "enum", choices: ["auto", "claude-code", "codex", "gemini", "opencode", "aider", "amazon-q", "none"], description: "worker CLI (or none for raw)" },
+            { name: "provider", type: "string", description: "override model provider for this run" },
+            { name: "model", type: "string", description: "override tier model for this run" },
+            { name: "dry-run", type: "boolean", description: "plan without executing" },
+            { name: "audit", type: "boolean", description: "write hash-chained audit log" },
+        ] },
+    { name: "scout", category: "pipeline", summary: "Read-only recon; structured findings (0 tokens).", usage: 'maq scout "<task>"', needsInput: "task", args: [] },
+    { name: "plan", category: "pipeline", summary: "Verifier-gated candidate plan.", usage: 'maq plan "<task>"', needsInput: "task", args: [] },
+    { name: "verify", category: "pipeline", summary: "Run project tests / cross-model review.", usage: "maq verify [--cwd d]", needsInput: "none", args: [] },
+    { name: "swarm", category: "pipeline", summary: "Run several tasks across parallel workers, then join.", usage: 'maq swarm "<t1>" "<t2>" … [--target t] [--concurrency N]', needsInput: "none", args: [{ name: "concurrency", type: "string", description: "max parallel workers" }] },
+    { name: "interactive", category: "pipeline", summary: "Attach a steerable interactive worker (stdin steering).", usage: "maq interactive [-t agent]", needsInput: "task", args: [{ name: "target", type: "enum", choices: ["auto", "claude-code", "codex", "gemini"], description: "agent CLI" }] },
+    { name: "detect", category: "system", summary: "Scan for installed/authenticated worker CLIs.", usage: "maq detect", needsInput: "none", args: [] },
+    { name: "doctor", category: "system", summary: "One-shot health: provider, agents, connectivity, skills.", usage: "maq doctor", needsInput: "none", args: [] },
+    { name: "probe", category: "system", summary: "Connectivity tier probe (STUN/UDP + TCP + LAN).", usage: "maq probe", needsInput: "none", args: [] },
+    { name: "config", category: "system", summary: "Read/update configuration.", usage: "maq config [get|set|path|reset]", needsInput: "none", args: [] },
+    { name: "models", category: "model", summary: "Show/optimize the master model ($0 layer).", usage: "maq models [list|cheapest|auto]", needsInput: "none", args: [{ name: "sub", type: "enum", choices: ["", "list", "cheapest", "auto"], description: "subcommand" }] },
+    { name: "sessions", category: "session", summary: "List/inspect/control daemon sessions.", usage: "maq sessions [<id>] [pause|resume|cancel]", needsInput: "none", args: [] },
+    { name: "agents", category: "agents", summary: "Named agent profiles + tool restrictions.", usage: "maq agents [list|init|show <n>]", needsInput: "none", args: [] },
+    { name: "skills", category: "agents", summary: "Tier-aware skills/rules injected into planning.", usage: "maq skills [list|init|path] [--tier]", needsInput: "none", args: [] },
+    { name: "tools", category: "agents", summary: "Safe tool registry (read_file/list_dir/grep_text/…).", usage: "maq tools [<name>] [--args JSON]", needsInput: "none", args: [] },
+    { name: "subagent", category: "agents", summary: "Run an isolated sub-agent; returns a concise summary.", usage: 'maq subagent "<task>"', needsInput: "task", args: [] },
+    { name: "memory", category: "memory", summary: "Recall memory store (injected into planning).", usage: "maq memory [store|recall|list]", needsInput: "query", args: [] },
+    { name: "flow", category: "control", summary: "Scheduled agent sessions (run under the daemon).", usage: "maq flow [list|add|remove]", needsInput: "none", args: [] },
+    { name: "audit", category: "control", summary: "Verify a run's hash-chained audit log.", usage: "maq audit verify <run-dir>", needsInput: "none", args: [] },
+];
+/** Catalog of AI worker CLIs' own commands/flags (verified 2026-07-01). */
+export const aiCliCatalog = [
+    {
+        name: "claude-code",
+        bin: "claude",
+        headless: 'claude -p "{task}" --output-format json',
+        commands: ["-p/--print (headless)", "--output-format json|stream-json", "--json-schema", "/clear", "/compact [instructions]", "/model", "/review", "/agents", "/mcp", "/resume"],
+        notes: "Stable JSON stream (json / stream-json). Slash commands control session without a model call.",
+    },
+    {
+        name: "codex",
+        bin: "codex",
+        headless: 'codex exec --json "{task}"',
+        commands: ["exec (headless)", "--json", "--output-schema", "app-server (remote TUI)"],
+        notes: "Use exec --json for scripted runs. No fully stable event stream historically — MAQ normalizes stdout as fallback.",
+    },
+    {
+        name: "gemini",
+        bin: "gemini",
+        headless: 'gemini -p "{task}"',
+        commands: ["-p (prompt)", "/tools", "/mcp", "/memory", "/stats", "custom TOML commands", "checkpointing", "sandbox (docker/podman)"],
+        notes: "5 subcommand groups, 30+ flags, 25+ REPL slash commands, Skills framework, GEMINI.md.",
+    },
+    {
+        name: "opencode",
+        bin: "opencode",
+        headless: 'opencode run "{task}"',
+        commands: ["run", "serve"],
+        notes: "Open-source multi-provider agent CLI.",
+    },
+    {
+        name: "aider",
+        bin: "aider",
+        headless: 'aider --message "{task}"',
+        commands: ["--message", "--yes", "/add", "/drop", "/commit", "/diff"],
+        notes: "Pair-programming CLI; git-native.",
+    },
+    {
+        name: "amazon-q",
+        bin: "q",
+        headless: 'q chat "{task}"',
+        commands: ["chat", "/tools", "/context"],
+        notes: "Amazon Q Developer CLI.",
+    },
+];
+export function commandCatalog() {
+    return { maq: maqCommands, aiClis: aiCliCatalog };
+}

package/dist/core/completion.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module completion
+ *
+ * Shell completion generator for the maq CLI.
+ * Produces completion scripts for bash, zsh, fish, and PowerShell.
+ * Also provides runtime shell detection.
+ *
+ * Zero npm dependencies. ESM module.
+ */
+/** Supported shell types for completion generation. */
+export type Shell = "bash" | "zsh" | "fish" | "powershell";
+/**
+ * Generates a shell completion script for the given shell.
+ * The returned string can be written to a file or eval'd directly.
+ */
+export declare function generateCompletion(shell: Shell): string;
+/**
+ * Attempts to detect the current shell from environment variables.
+ * Returns `null` if the shell cannot be determined.
+ *
+ * On Unix: reads `$SHELL` and matches the basename.
+ * On Windows: checks for `$PSModulePath` (PowerShell indicator).
+ */
+export declare function detectShell(): Shell | null;

package/dist/core/completion.js

@@ -0,0 +1,309 @@
+/**
+ * @module completion
+ *
+ * Shell completion generator for the maq CLI.
+ * Produces completion scripts for bash, zsh, fish, and PowerShell.
+ * Also provides runtime shell detection.
+ *
+ * Zero npm dependencies. ESM module.
+ */
+// ── Command Definitions ─────────────────────────────────────────────
+const TOP_LEVEL_COMMANDS = [
+    "detect",
+    "scout",
+    "plan",
+    "run",
+    "verify",
+    "serve",
+    "sessions",
+    "models",
+    "probe",
+    "skills",
+    "subagent",
+    "tools",
+    "doctor",
+    "agents",
+    "memory",
+    "swarm",
+    "interactive",
+    "flow",
+    "audit",
+    "config",
+    "board",
+    "init",
+    "logs",
+    "stop",
+    "cost",
+    "help",
+    "version",
+];
+const SUBCOMMANDS = {
+    config: ["get", "set", "path", "reset"],
+    models: ["list", "cheapest", "auto"],
+    skills: ["init", "path"],
+    agents: ["list", "init", "show"],
+    memory: ["store", "recall", "list"],
+    flow: ["list", "add", "remove"],
+    board: ["show", "list", "tail"],
+    cost: ["report", "reset"],
+};
+const RUN_FLAGS = [
+    "--target",
+    "--dry-run",
+    "--provider",
+    "--model",
+    "--audit",
+    "--json",
+    "--cwd",
+];
+// ── Public API ──────────────────────────────────────────────────────
+/**
+ * Generates a shell completion script for the given shell.
+ * The returned string can be written to a file or eval'd directly.
+ */
+export function generateCompletion(shell) {
+    switch (shell) {
+        case "bash":
+            return generateBash();
+        case "zsh":
+            return generateZsh();
+        case "fish":
+            return generateFish();
+        case "powershell":
+            return generatePowerShell();
+    }
+}
+/**
+ * Attempts to detect the current shell from environment variables.
+ * Returns `null` if the shell cannot be determined.
+ *
+ * On Unix: reads `$SHELL` and matches the basename.
+ * On Windows: checks for `$PSModulePath` (PowerShell indicator).
+ */
+export function detectShell() {
+    const env = typeof process !== "undefined" ? process.env : {};
+    // Windows: PowerShell sets PSModulePath
+    if (env.PSModulePath) {
+        return "powershell";
+    }
+    const shellPath = env.SHELL;
+    if (!shellPath) {
+        return null;
+    }
+    const basename = shellPath.split("/").pop() ?? "";
+    if (basename === "bash" || basename.startsWith("bash")) {
+        return "bash";
+    }
+    if (basename === "zsh" || basename.startsWith("zsh")) {
+        return "zsh";
+    }
+    if (basename === "fish" || basename.startsWith("fish")) {
+        return "fish";
+    }
+    return null;
+}
+// ── Generators ──────────────────────────────────────────────────────
+function generateBash() {
+    const cmds = TOP_LEVEL_COMMANDS.join(" ");
+    const flags = RUN_FLAGS.join(" ");
+    const subcases = Object.entries(SUBCOMMANDS)
+        .map(([cmd, subs]) => `      ${cmd}) COMPREPLY=( $(compgen -W "${subs.join(" ")}" -- "$cur") ) ;;`)
+        .join("\n");
+    return `# maq bash completion — generated by maq completion bash
+# Add to ~/.bashrc: eval "$(maq completion bash)"
+
+_maq_completions() {
+  local cur prev words cword
+  _init_completion || return
+
+  local commands="${cmds}"
+  local run_flags="${flags}"
+
+  if [[ $cword -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "$commands" -- "$cur") )
+    return
+  fi
+
+  local cmd="\${words[1]}"
+
+  # Subcommand completion
+  case "$cmd" in
+${subcases}
+  esac
+
+  # Flag completion for run
+  if [[ "$cmd" == "run" && "$cur" == -* ]]; then
+    COMPREPLY=( $(compgen -W "$run_flags" -- "$cur") )
+    return
+  fi
+}
+
+complete -F _maq_completions maq
+`;
+}
+function generateZsh() {
+    const cmds = TOP_LEVEL_COMMANDS.map((c) => `'${c}:${descriptionFor(c)}'`).join("\n      ");
+    const subcmdFunctions = Object.entries(SUBCOMMANDS)
+        .map(([cmd, subs]) => {
+        const subList = subs.map((s) => `'${s}'`).join(" ");
+        return `  ${cmd})
+      _values 'subcommand' ${subList}
+      ;;`;
+    })
+        .join("\n    ");
+    const flags = RUN_FLAGS.map((f) => `'${f}[${flagDescriptionFor(f)}]'`).join("\n        ");
+    return `#compdef maq
+# maq zsh completion — generated by maq completion zsh
+# Add to ~/.zshrc: eval "$(maq completion zsh)"
+
+_maq() {
+  local -a commands
+  commands=(
+      ${cmds}
+  )
+
+  _arguments -C \\
+    '1:command:->cmd' \\
+    '*::arg:->args'
+
+  case $state in
+  cmd)
+    _describe 'maq command' commands
+    ;;
+  args)
+    local cmd=\${words[1]}
+    case $cmd in
+    ${subcmdFunctions}
+    run)
+      _arguments \\
+        ${flags}
+      ;;
+    esac
+    ;;
+  esac
+}
+
+compdef _maq maq
+`;
+}
+function generateFish() {
+    const lines = [
+        "# maq fish completion — generated by maq completion fish",
+        "# Save to ~/.config/fish/completions/maq.fish",
+        "",
+        "# Disable file completions by default",
+        "complete -c maq -f",
+        "",
+        "# Top-level commands",
+    ];
+    for (const cmd of TOP_LEVEL_COMMANDS) {
+        lines.push(`complete -c maq -n '__fish_use_subcommand' -a '${cmd}' -d '${descriptionFor(cmd)}'`);
+    }
+    lines.push("");
+    lines.push("# Subcommands");
+    for (const [cmd, subs] of Object.entries(SUBCOMMANDS)) {
+        for (const sub of subs) {
+            lines.push(`complete -c maq -n '__fish_seen_subcommand_from ${cmd}' -a '${sub}'`);
+        }
+    }
+    lines.push("");
+    lines.push("# Run flags");
+    for (const flag of RUN_FLAGS) {
+        lines.push(`complete -c maq -n '__fish_seen_subcommand_from run' -l '${flag.replace(/^--/, "")}' -d '${flagDescriptionFor(flag)}'`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function generatePowerShell() {
+    const cmdList = TOP_LEVEL_COMMANDS.map((c) => `'${c}'`).join(", ");
+    const flagList = RUN_FLAGS.map((f) => `'${f}'`).join(", ");
+    const subcmdCases = Object.entries(SUBCOMMANDS)
+        .map(([cmd, subs]) => {
+        const subList = subs.map((s) => `'${s}'`).join(", ");
+        return `        '${cmd}' {
+            @(${subList}) | Where-Object { $_ -like "$wordToComplete*" } |
+              ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+          }`;
+    })
+        .join("\n");
+    return `# maq PowerShell completion — generated by maq completion powershell
+# Add to $PROFILE: maq completion powershell | Invoke-Expression
+
+Register-ArgumentCompleter -Native -CommandName 'maq' -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+
+  $commands = @(${cmdList})
+  $runFlags = @(${flagList})
+
+  $tokens = $commandAst.ToString().Split(' ', [System.StringSplitOptions]::RemoveEmptyEntries)
+  $tokenCount = $tokens.Count
+
+  # Complete top-level command
+  if ($tokenCount -le 1 -or ($tokenCount -eq 2 -and $wordToComplete)) {
+    $commands | Where-Object { $_ -like "$wordToComplete*" } |
+      ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+    return
+  }
+
+  $cmd = $tokens[1]
+
+  # Subcommand completion
+  switch ($cmd) {
+${subcmdCases}
+    'run' {
+      if ($wordToComplete.StartsWith('-')) {
+        $runFlags | Where-Object { $_ -like "$wordToComplete*" } |
+          ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+      }
+    }
+  }
+}
+`;
+}
+// ── Helpers ─────────────────────────────────────────────────────────
+/** Returns a short description for a top-level command. */
+function descriptionFor(cmd) {
+    const descriptions = {
+        detect: "Detect project type and environment",
+        scout: "Scan repository and gather context",
+        plan: "Generate an execution plan",
+        run: "Execute a task through the pipeline",
+        verify: "Verify the last execution result",
+        serve: "Start the maq API server",
+        sessions: "List and manage sessions",
+        models: "List and configure models",
+        probe: "Probe model capabilities",
+        skills: "Manage reusable skills",
+        subagent: "Spawn and manage sub-agents",
+        tools: "List available tools",
+        doctor: "Diagnose installation issues",
+        agents: "Manage agent configurations",
+        memory: "Store and recall agent memory",
+        swarm: "Orchestrate multi-agent swarms",
+        interactive: "Start interactive REPL mode",
+        flow: "Manage multi-step workflows",
+        audit: "View and replay audit logs",
+        config: "Get and set configuration",
+        board: "Inspect the shared board",
+        init: "Initialize a new .maq directory",
+        logs: "View session logs",
+        stop: "Stop running agents or server",
+        cost: "View and reset cost tracking",
+        help: "Show help for a topic",
+        version: "Print version information",
+    };
+    return descriptions[cmd] ?? cmd;
+}
+/** Returns a short description for a run flag. */
+function flagDescriptionFor(flag) {
+    const descriptions = {
+        "--target": "Target file or directory",
+        "--dry-run": "Preview without executing",
+        "--provider": "LLM provider to use",
+        "--model": "Specific model to use",
+        "--audit": "Enable audit logging",
+        "--json": "Output as JSON",
+        "--cwd": "Working directory",
+    };
+    return descriptions[flag] ?? flag;
+}

package/dist/core/complexity.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Task complexity classifier (deterministic, zero-token).
+ *
+ * Used to gate the cost/quality dial: trivial tasks skip the Scout+Plan phases
+ * and go straight to Execute; complex tasks get the full pipeline. This is the
+ * lever that keeps multi-agent overhead (which can reach ~15x single-turn
+ * tokens) from being paid on work that does not need it.
+ */
+import type { Complexity } from "./types.js";
+export interface ComplexityResult {
+    complexity: Complexity;
+    score: number;
+    reasons: string[];
+}
+export declare function classifyComplexity(task: string, fileHints?: string[]): ComplexityResult;
+/** Whether the Scout+Plan pre-flight phases should run for this complexity. */
+export declare function shouldRunPreflight(complexity: Complexity): boolean;