@thecorporation/cli 26.3.47 → 26.3.48

package/dist/index.js

@@ -4315,7 +4315,11 @@ var init_formation = __esm({
           { flags: "--incorporator-address <address>", description: "Incorporator mailing address (overrides founder)" }
         ],
         handler: formFinalizeHandler,
-        examples: ["corp form finalize"]
+        examples: [
+          "corp form finalize @last:entity",
+          "corp form finalize @last:entity --authorized-shares 10000000 --par-value 0.0001",
+          'corp form finalize @last:entity --company-address "123 Main St,Wilmington,DE,19801" --incorporator-name "Alice Smith"'
+        ]
       },
       {
         name: "form activate",
@@ -4330,7 +4334,11 @@ var init_formation = __esm({
           { flags: "--ein <ein>", description: "EIN to confirm (defaults to a deterministic simulated EIN)" }
         ],
         handler: formActivateHandler,
-        examples: ["corp form activate"]
+        examples: [
+          "corp form activate @last:entity",
+          "corp form activate @last:entity --ein 84-1234567",
+          "corp form activate @last:entity --filing-id DE-2026-0042 --receipt-reference RECEIPT-001"
+        ]
       },
       // ── Auto-generated from OpenAPI ──────────────────────────────
       {
@@ -8455,7 +8463,10 @@ var init_compliance = __esm({
         },
         produces: { kind: "tax_filing" },
         successTemplate: "Tax filing created",
-        examples: ["corp tax file --type 1120 --year 'year'"]
+        examples: [
+          "corp tax file --type 1120 --year 2025",
+          "corp tax file --type 83b --year 2025 --filer-contact-id @last:contact"
+        ]
       },
       // --- tax deadlines ---
       {
@@ -8519,14 +8530,20 @@ var init_compliance = __esm({
         },
         produces: { kind: "deadline" },
         successTemplate: "Deadline tracked",
-        examples: ["corp tax deadline --type 'type' --due-date 'date' --description 'desc'", "corp tax deadline --json"]
+        examples: [
+          'corp tax deadline --type annual_report --due-date 2026-03-31 --description "Delaware annual report due"',
+          'corp tax deadline --type annual_report --due-date 2026-03-31 --description "Delaware annual report" --recurrence annual'
+        ]
       },
       // ── Auto-generated from OpenAPI ──────────────────────────────
       {
         name: "compliance escalations-scan",
         description: "Scan for compliance issues and create escalations",
         route: { method: "POST", path: "/v1/compliance/escalations/scan" },
-        examples: ["corp compliance escalations-scan"],
+        examples: [
+          "corp compliance escalations-scan",
+          "corp compliance escalations-scan --json"
+        ],
         successTemplate: "Escalation scan complete"
       },
       {
@@ -8542,7 +8559,10 @@ var init_compliance = __esm({
           { flags: "--resolve-incident", description: "Resolve Incident" },
           { flags: "--resolve-obligation", description: "Resolve Obligation" }
         ],
-        examples: ["corp compliance escalations-resolve-with-evidence <escalation-id>", "corp compliance escalations-resolve-with-evidence --json"],
+        examples: [
+          "corp compliance escalations-resolve-with-evidence esc_01hx9k3n2p4q7r8s9t0uvwxyz --evidence-type filing --filing-reference DE-2026-0042",
+          'corp compliance escalations-resolve-with-evidence esc_01hx9k3n2p4q7r8s9t0uvwxyz --resolve-incident --notes "Filed on time"'
+        ],
         successTemplate: "Escalations Resolve With Evidence created"
       },
       {
@@ -8559,7 +8579,10 @@ var init_compliance = __esm({
           { flags: "--provides-tools <provides-tools>", description: "Provides Tools" },
           { flags: "--state <state>", description: "State" }
         ],
-        examples: ["corp contractors classify --contractor-name 'contractor-name'", "corp contractors classify --json"],
+        examples: [
+          'corp contractors classify --contractor-name "Jane Doe" --state CA --hours-per-week 20',
+          'corp contractors classify --contractor-name "Acme Services LLC" --duration-months 6 --exclusive-client false'
+        ],
         successTemplate: "Classify created"
       },
       {
@@ -8573,7 +8596,10 @@ var init_compliance = __esm({
           { flags: "--recurrence <recurrence>", description: "Recurrence pattern for a deadline.", choices: ["one_time", "monthly", "quarterly", "annual"] },
           { flags: "--severity <severity>", description: "Risk severity of missing a deadline.", choices: ["low", "medium", "high", "critical"] }
         ],
-        examples: ["corp deadlines --deadline-type 'deadline-type' --description 'description' --due-date one_time", "corp deadlines --json"],
+        examples: [
+          'corp deadlines --deadline-type annual_report --description "Delaware annual report" --due-date 2026-03-31 --recurrence annual',
+          'corp deadlines --deadline-type tax_filing --description "Q1 estimated taxes" --due-date 2026-04-15 --severity high'
+        ],
         successTemplate: "Deadlines created"
       },
       {
@@ -8593,7 +8619,10 @@ var init_compliance = __esm({
           { flags: "--document-type <document-type>", description: "Type of document required", required: true },
           { flags: "--tax-year <tax-year>", description: "Tax Year", required: true, type: "int" }
         ],
-        examples: ["corp tax create-filing --document-type 'document-type' --tax-year 'tax-year'"],
+        examples: [
+          "corp tax create-filing --document-type 1120 --tax-year 2025",
+          "corp tax create-filing --document-type 1065 --tax-year 2025 --json"
+        ],
         successTemplate: "Filings created"
       }
     ];
@@ -8697,7 +8726,10 @@ var init_agents = __esm({
           }
           console.log(chalk9.magenta("\u2500".repeat(40)));
         },
-        examples: ["corp agents show"]
+        examples: [
+          "corp agents show @last:agent",
+          "corp agents show agt_01hx9k3n2p4q7r8s9t0uvwxyz"
+        ]
       },
       // --- agents create ---
       {
@@ -8738,7 +8770,10 @@ var init_agents = __esm({
         },
         produces: { kind: "agent" },
         successTemplate: "Agent created: {name}",
-        examples: ["corp agents create --name 'name' --prompt 'prompt'", "corp agents create --json"]
+        examples: [
+          'corp agents create --name "bookkeeper" --prompt "You manage accounts payable for the company"',
+          'corp agents create --name "compliance-monitor" --prompt "You monitor regulatory deadlines" --model gpt-4o'
+        ]
       },
       // --- agents pause <agent-ref> ---
       {
@@ -8752,7 +8787,10 @@ var init_agents = __esm({
           const result = await ctx.client.updateAgent(resolvedAgentId, { status: "paused" });
           ctx.writer.writeResult(result, `Agent ${resolvedAgentId} paused.`, { jsonOnly: ctx.opts.json });
         },
-        examples: ["corp agents pause <agent-ref>"]
+        examples: [
+          "corp agents pause @last:agent",
+          "corp agents pause agt_01hx9k3n2p4q7r8s9t0uvwxyz"
+        ]
       },
       // --- agents resume <agent-ref> ---
       {
@@ -8779,7 +8817,10 @@ var init_agents = __esm({
             }
           }
         },
-        examples: ["corp agents resume <agent-ref>"]
+        examples: [
+          "corp agents resume @last:agent",
+          "corp agents resume agt_01hx9k3n2p4q7r8s9t0uvwxyz"
+        ]
       },
       // --- agents delete <agent-ref> ---
       {
@@ -8806,7 +8847,10 @@ var init_agents = __esm({
           const result = await ctx.client.deleteAgent(resolvedAgentId);
           ctx.writer.writeResult(result, `Agent ${resolvedAgentId} deleted.`, { jsonOnly: ctx.opts.json });
         },
-        examples: ["corp agents delete <agent-ref>", "corp agents delete --json"]
+        examples: [
+          "corp agents delete @last:agent",
+          "corp agents delete agt_01hx9k3n2p4q7r8s9t0uvwxyz --yes"
+        ]
       },
       // --- agents message <agent-ref> ---
       {
@@ -8837,7 +8881,10 @@ var init_agents = __esm({
             }
           }
         },
-        examples: ["corp agents message <agent-ref>", "corp agents message --json"]
+        examples: [
+          `corp agents message @last:agent --body "Process this month's invoices"`,
+          "corp agents message agt_01hx9k3n2p4q7r8s9t0uvwxyz --body-file ./task.txt"
+        ]
       },
       // --- agents skill <agent-ref> ---
       {
@@ -8866,7 +8913,10 @@ var init_agents = __esm({
           });
           ctx.writer.writeResult(result, `Skill '${ctx.opts.name}' added to agent ${resolvedAgentId}.`, { jsonOnly: ctx.opts.json });
         },
-        examples: ["corp agents skill <agent-ref> --name 'name' --description 'desc'", "corp agents skill --json"]
+        examples: [
+          'corp agents skill @last:agent --name invoice-processing --description "Process AP invoices from email"',
+          'corp agents skill agt_01hx9k3n2p4q7r8s9t0uvwxyz --name bookkeeping --description "Reconcile ledger entries" --instructions-file ./skills/bookkeeping.txt'
+        ]
       },
       // --- agents execution <agent-ref> <execution-id> ---
       {
@@ -8897,7 +8947,10 @@ var init_agents = __esm({
           if (result.completed_at) console.log(`  ${chalk9.bold("Completed:")} ${result.completed_at}`);
           console.log(chalk9.magenta("\u2500".repeat(40)));
         },
-        examples: ["corp agents execution"]
+        examples: [
+          "corp agents execution @last:agent exc_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp agents execution agt_01hx9k3n2p4q7r8s9t0uvwxyz exc_01hx9k3n2p4q7r8s9t0uvwxyz"
+        ]
       },
       // --- agents execution-result <agent-ref> <execution-id> ---
       {
@@ -8921,7 +8974,10 @@ var init_agents = __esm({
           ctx.writer.success(`Result for execution ${executionId}:`);
           printJson(result);
         },
-        examples: ["corp agents execution-result"]
+        examples: [
+          "corp agents execution-result @last:agent exc_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp agents execution-result @last:agent exc_01hx9k3n2p4q7r8s9t0uvwxyz --json"
+        ]
       },
       // --- agents kill <agent-ref> <execution-id> ---
       {
@@ -8949,7 +9005,10 @@ var init_agents = __esm({
           const result = await ctx.client.killAgentExecution(resolvedAgentId, executionId);
           ctx.writer.writeResult(result, `Execution ${executionId} killed.`, { jsonOnly: ctx.opts.json });
         },
-        examples: ["corp agents kill <agent-ref> <execution-id>", "corp agents kill --json"]
+        examples: [
+          "corp agents kill @last:agent exc_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp agents kill @last:agent exc_01hx9k3n2p4q7r8s9t0uvwxyz --yes"
+        ]
       },
       // ── Auto-generated from OpenAPI ──────────────────────────────
       {
@@ -8958,7 +9017,10 @@ var init_agents = __esm({
         route: { method: "GET", path: "/v1/agents/{pos}/executions/{pos2}/logs" },
         args: [{ name: "agent-id", required: true, description: "Agent ID", posKind: "agent" }, { name: "execution-id", required: true, description: "Agent execution ID" }],
         display: { title: "Execution Logs", cols: ["@timestamp>Time", "level>Level", "message>Message"] },
-        examples: ["corp agents executions-logs"]
+        examples: [
+          "corp agents executions-logs @last:agent exc_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp agents executions-logs agt_01hx9k3n2p4q7r8s9t0uvwxyz exc_01hx9k3n2p4q7r8s9t0uvwxyz --json"
+        ]
       },
       // ── Auto-generated from OpenAPI ──────────────────────────────
       {
@@ -8967,7 +9029,10 @@ var init_agents = __esm({
         route: { method: "GET", path: "/v1/agents/{pos}/messages/{pos2}" },
         args: [{ name: "agent-id", required: true, description: "Agent ID", posKind: "agent" }, { name: "message-id", required: true, description: "Message Id" }],
         display: { title: "Agent Message" },
-        examples: ["corp agents messages"]
+        examples: [
+          "corp agents messages @last:agent msg_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp agents messages @last:agent msg_01hx9k3n2p4q7r8s9t0uvwxyz --json"
+        ]
       }
     ];
   }
@@ -11475,7 +11540,10 @@ var init_execution = __esm({
           { flags: "--max-amount-cents <max-amount-cents>", description: "Maximum authorized amount in cents" },
           { flags: "--scope <scope>", description: "Authorization scope", required: true }
         ],
-        examples: ["corp execution approval-artifacts --approver-identity 'approver-identity' --channel 'channel' --intent-type 'intent-type' --scope 'scope'", "corp execution approval-artifacts --json"],
+        examples: [
+          'corp execution approval-artifacts --approver-identity "alice@acme.com" --channel board_vote --intent-type equity_grant --scope entity',
+          'corp execution approval-artifacts --approver-identity "alice@acme.com" --channel written_consent --intent-type equity_grant --scope entity --approved-at 2026-03-01T00:00:00Z'
+        ],
         successTemplate: "Approval Artifacts created"
       },
       {
@@ -11489,7 +11557,10 @@ var init_execution = __esm({
           { flags: "--intent-type <intent-type>", description: "Type of intent", required: true },
           { flags: "--metadata <metadata>", description: "Additional metadata (JSON)" }
         ],
-        examples: ["corp execution intents --description 'description' --intent-type 'intent-type'", "corp execution intents --json"],
+        examples: [
+          'corp execution intents --description "Issue 10,000 options to Alice" --intent-type equity_grant --authority-tier tier_2',
+          'corp execution intents --description "Wire $50,000 to vendor" --intent-type payment --authority-tier tier_1'
+        ],
         successTemplate: "Intents created"
       },
       {
@@ -11505,7 +11576,10 @@ var init_execution = __esm({
           { flags: "--intent-id <intent-id>", description: "Execution intent ID" },
           { flags: "--obligation-type <obligation-type>", description: "Type of obligation", required: true }
         ],
-        examples: ["corp execution obligations --assignee-type internal --description 'description' --obligation-type 'obligation-type'", "corp execution obligations --json"],
+        examples: [
+          'corp execution obligations --assignee-type human --description "Sign equity grant agreement" --obligation-type signature',
+          'corp execution obligations --assignee-type internal --description "File 83(b) election" --obligation-type document --due-date 2026-04-15'
+        ],
         successTemplate: "Obligations created"
       },
       {
@@ -11515,7 +11589,10 @@ var init_execution = __esm({
         entity: true,
         args: [{ name: "packet-id", required: true, description: "Document packet ID" }],
         display: { title: "Execution Packets", cols: ["finalized_at>Finalized At", "items>Items", "manifest_hash>Manifest Hash", "required_signers>Required Signers", "@created_at>Created At", "#entity_id>ID"] },
-        examples: ["corp execution packets", "corp execution packets --json"]
+        examples: [
+          "corp execution packets pkt_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp execution packets pkt_01hx9k3n2p4q7r8s9t0uvwxyz --json"
+        ]
       },
       {
         name: "intents authorize",
@@ -11534,7 +11611,9 @@ var init_execution = __esm({
         options: [
           { flags: "--approval-artifact-id <approval-artifact-id>", description: "Approval artifact ID to bind", required: true }
         ],
-        examples: ["corp intents bind-approval-artifact <intent-id> --approval-artifact-id 'approval-artifact-id'"],
+        examples: [
+          "corp intents bind-approval-artifact @last:intent --approval-artifact-id art_01hx9k3n2p4q7r8s9t0uvwxyz"
+        ],
         successTemplate: "Bind Approval Artifact created"
       },
       {
@@ -11545,7 +11624,9 @@ var init_execution = __esm({
         options: [
           { flags: "--request-id <request-id>", description: "Document request ID", required: true }
         ],
-        examples: ["corp intents bind-document-request <intent-id> --request-id 'request-id'"],
+        examples: [
+          "corp intents bind-document-request @last:intent --request-id req_01hx9k3n2p4q7r8s9t0uvwxyz"
+        ],
         successTemplate: "Bind Document Request created"
       },
       {
@@ -11582,7 +11663,10 @@ var init_execution = __esm({
         entity: true,
         args: [{ name: "intent-id", required: true, description: "Execution intent ID" }],
         display: { title: "Intents Receipts", cols: ["executed_at>Executed At", "idempotency_key>Idempotency Key", "request_hash>Request Hash", "response_hash>Response Hash", "@created_at>Created At", "#intent_id>ID"] },
-        examples: ["corp intents receipts", "corp intents receipts --json"]
+        examples: [
+          "corp intents receipts int_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp intents receipts @last:intent --json"
+        ]
       },
       {
         name: "obligations assign",
@@ -11593,7 +11677,9 @@ var init_execution = __esm({
         options: [
           { flags: "--assignee-id <assignee-id>", description: "ID of the party to assign to", required: true }
         ],
-        examples: ["corp obligations assign <obligation-id> --assignee-id 'assignee-id'"],
+        examples: [
+          "corp obligations assign obl_01hx9k3n2p4q7r8s9t0uvwxyz --assignee-id usr_01hx9k3n2p4q7r8s9t0uvwxyz"
+        ],
         successTemplate: "Assign created"
       },
       {
@@ -11603,7 +11689,10 @@ var init_execution = __esm({
         entity: true,
         args: [{ name: "obligation-id", required: true, description: "Obligation ID" }],
         display: { title: "Obligations Document Requests", cols: ["description>Description", "document_type>Document Type", "fulfilled_at>Fulfilled At", "not_applicable_at>Not Applicable At", "@created_at>Created At", "#entity_id>ID"] },
-        examples: ["corp obligations document-requests", "corp obligations document-requests --json"]
+        examples: [
+          "corp obligations document-requests obl_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp obligations document-requests obl_01hx9k3n2p4q7r8s9t0uvwxyz --json"
+        ]
       },
       {
         name: "obligations create-document-request",
@@ -11615,7 +11704,9 @@ var init_execution = __esm({
           { flags: "--description <description>", description: "Description text", required: true },
           { flags: "--document-type <document-type>", description: "Type of document required", required: true }
         ],
-        examples: ["corp obligations document-requests <obligation-id> --description 'description' --document-type 'document-type'"],
+        examples: [
+          'corp obligations create-document-request obl_01hx9k3n2p4q7r8s9t0uvwxyz --description "Signed equity grant agreement" --document-type equity_grant'
+        ],
         successTemplate: "Document Requests created"
       },
       {
@@ -11652,7 +11743,10 @@ var init_execution = __esm({
         entity: true,
         args: [{ name: "receipt-id", required: true, description: "Execution receipt ID" }],
         display: { title: "Receipts", cols: ["executed_at>Executed At", "idempotency_key>Idempotency Key", "request_hash>Request Hash", "response_hash>Response Hash", "@created_at>Created At", "#intent_id>ID"] },
-        examples: ["corp receipts", "corp receipts --json"]
+        examples: [
+          "corp receipts rcp_01hx9k3n2p4q7r8s9t0uvwxyz",
+          "corp receipts rcp_01hx9k3n2p4q7r8s9t0uvwxyz --json"
+        ]
       },
       // ── Human obligations ───────────────────────────────────────────────
       {
@@ -12123,6 +12217,275 @@ var init_branches = __esm({
   }
 });
 
+// src/registry/completions.ts
+function buildTree(commands) {
+  const topLevelMap = /* @__PURE__ */ new Map();
+  const topLevel = [];
+  for (const cmd of commands) {
+    if (cmd.hidden) continue;
+    const parts = cmd.name.split(" ");
+    const opts = ["--json"];
+    if (cmd.entity) opts.push("--entity-id");
+    if (cmd.dryRun) opts.push("--dry-run");
+    for (const o of cmd.options ?? []) {
+      if (o.hidden) continue;
+      const longFlag = o.flags.split(/\s+/).find((f) => f.startsWith("--"));
+      if (longFlag) {
+        opts.push(longFlag.replace(/<[^>]*>|\[[^\]]*\]/, "").trim());
+      }
+    }
+    const node = {
+      name: parts[parts.length - 1],
+      description: cmd.description,
+      options: opts,
+      subcmds: []
+    };
+    if (parts.length === 1) {
+      topLevelMap.set(parts[0], node);
+      topLevel.push(node);
+    } else {
+      const parentName = parts[0];
+      let parent = topLevelMap.get(parentName);
+      if (!parent) {
+        parent = { name: parentName, description: "", options: [], subcmds: [] };
+        topLevelMap.set(parentName, parent);
+        topLevel.push(parent);
+      }
+      parent.subcmds.push(node);
+    }
+  }
+  return topLevel;
+}
+function generateBash(commands) {
+  const tree = buildTree(commands);
+  const lines = [
+    "# corp bash completion",
+    "# Source this file or add to ~/.bash_completion.d/",
+    "#   source <(corp completions --shell bash)",
+    "",
+    "_corp_completions() {",
+    "  local cur prev words cword",
+    "  _init_completion 2>/dev/null || {",
+    "    COMPREPLY=()",
+    '    cur="${COMP_WORDS[COMP_CWORD]}"',
+    '    prev="${COMP_WORDS[COMP_CWORD-1]}"',
+    '    words=("${COMP_WORDS[@]}")',
+    "    cword=$COMP_CWORD",
+    "  }",
+    "",
+    '  local subcommand=""',
+    '  local subsubcommand=""',
+    '  if [[ ${#words[@]} -ge 2 ]]; then subcommand="${words[1]}"; fi',
+    '  if [[ ${#words[@]} -ge 3 ]]; then subsubcommand="${words[2]}"; fi',
+    ""
+  ];
+  const topNames = tree.map((n) => n.name).join(" ");
+  lines.push(`  local top_commands="${topNames}"`);
+  lines.push("");
+  lines.push('  case "$subcommand" in');
+  for (const parent of tree) {
+    if (parent.subcmds.length > 0) {
+      const subNames = parent.subcmds.map((s3) => s3.name).join(" ");
+      lines.push(`    ${parent.name})`);
+      lines.push(`      local ${parent.name}_subcmds="${subNames}"`);
+      lines.push(`      case "$subsubcommand" in`);
+      for (const child of parent.subcmds) {
+        const childFlags = child.options.join(" ");
+        lines.push(`        ${child.name})`);
+        lines.push(`          COMPREPLY=( $(compgen -W "${childFlags}" -- "$cur") )`);
+        lines.push("          return 0 ;;");
+      }
+      const parentFlags = parent.options.join(" ");
+      lines.push("        *)");
+      if (parent.options.length > 0) {
+        lines.push(`          COMPREPLY=( $(compgen -W "${parent.subcmds.map((s3) => s3.name).join(" ")} ${parentFlags}" -- "$cur") )`);
+      } else {
+        lines.push(`          COMPREPLY=( $(compgen -W "$${parent.name}_subcmds" -- "$cur") )`);
+      }
+      lines.push("          return 0 ;;");
+      lines.push("      esac ;;");
+    } else {
+      const flags = parent.options.join(" ");
+      lines.push(`    ${parent.name})`);
+      lines.push(`      COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )`);
+      lines.push("      return 0 ;;");
+    }
+  }
+  lines.push("    *)");
+  lines.push('      COMPREPLY=( $(compgen -W "$top_commands" -- "$cur") )');
+  lines.push("      return 0 ;;");
+  lines.push("  esac");
+  lines.push("}");
+  lines.push("");
+  lines.push("complete -F _corp_completions corp");
+  lines.push("complete -F _corp_completions npx corp");
+  return lines.join("\n");
+}
+function escapeZshDesc(s3) {
+  return s3.replace(/'/g, "'\\''").replace(/:/g, "\\:");
+}
+function generateZsh(commands) {
+  const tree = buildTree(commands);
+  const lines = [
+    "#compdef corp",
+    "# corp zsh completion",
+    "# Add to your fpath and run: compdef _corp corp",
+    '#   eval "$(corp completions --shell zsh)"',
+    "",
+    "_corp() {",
+    "  local state",
+    "  local -a top_commands",
+    ""
+  ];
+  lines.push("  top_commands=(");
+  for (const node of tree) {
+    lines.push(`    '${node.name}:${escapeZshDesc(node.description)}'`);
+  }
+  lines.push("  )");
+  lines.push("");
+  lines.push("  _arguments -C \\");
+  lines.push("    '(-h --help)'{-h,--help}'[Show help]' \\");
+  lines.push("    '(-V --version)'{-V,--version}'[Show version]' \\");
+  lines.push("    '(-q --quiet)'{-q,--quiet}'[Quiet output]' \\");
+  lines.push("    '1: :->cmd' \\");
+  lines.push("    '*: :->args'");
+  lines.push("");
+  lines.push("  case $state in");
+  lines.push("    cmd)");
+  lines.push("      _describe 'command' top_commands ;;");
+  lines.push("    args)");
+  lines.push("      case $words[2] in");
+  for (const parent of tree) {
+    lines.push(`        ${parent.name})`);
+    if (parent.subcmds.length > 0) {
+      lines.push("          local -a subcmds");
+      lines.push("          subcmds=(");
+      for (const child of parent.subcmds) {
+        lines.push(`            '${child.name}:${escapeZshDesc(child.description)}'`);
+      }
+      lines.push("          )");
+      lines.push("          if (( CURRENT == 3 )); then");
+      lines.push("            _describe 'subcommand' subcmds");
+      lines.push("          else");
+      lines.push("            case $words[3] in");
+      for (const child of parent.subcmds) {
+        const argSpec = child.options.map((f) => `'${f}[option]'`).join(" \\\n                ");
+        lines.push(`              ${child.name})`);
+        lines.push(`                _arguments ${argSpec} ;;`);
+      }
+      lines.push("            esac");
+      lines.push("          fi ;;");
+    } else {
+      const argSpec = parent.options.map((f) => `'${f}[option]'`).join(" \\\n            ");
+      if (argSpec) {
+        lines.push(`          _arguments ${argSpec} ;;`);
+      } else {
+        lines.push("          ;; # no options");
+      }
+    }
+  }
+  lines.push("      esac ;;");
+  lines.push("  esac");
+  lines.push("}");
+  lines.push("");
+  lines.push("_corp");
+  return lines.join("\n");
+}
+function generateFish(commands) {
+  const tree = buildTree(commands);
+  const lines = [
+    "# corp fish completion",
+    "# Save to ~/.config/fish/completions/corp.fish",
+    "#   corp completions --shell fish > ~/.config/fish/completions/corp.fish",
+    ""
+  ];
+  lines.push("complete -c corp -f");
+  lines.push("");
+  for (const node of tree) {
+    const desc = node.description.replace(/'/g, "\\'");
+    lines.push(`complete -c corp -n '__fish_use_subcommand' -a '${node.name}' -d '${desc}'`);
+  }
+  lines.push("");
+  for (const parent of tree) {
+    const parentName = parent.name;
+    if (parent.subcmds.length > 0) {
+      for (const child of parent.subcmds) {
+        const desc = child.description.replace(/'/g, "\\'");
+        lines.push(
+          `complete -c corp -n "__fish_seen_subcommand_from ${parentName}; and not __fish_seen_subcommand_from ${parent.subcmds.map((s3) => s3.name).join(" ")}" -a '${child.name}' -d '${desc}'`
+        );
+      }
+      lines.push("");
+      for (const child of parent.subcmds) {
+        for (const flag of child.options) {
+          const long = flag.replace(/^--/, "");
+          lines.push(
+            `complete -c corp -n "__fish_seen_subcommand_from ${parentName}; and __fish_seen_subcommand_from ${child.name}" -l '${long}'`
+          );
+        }
+        if (child.options.length > 0) lines.push("");
+      }
+    } else {
+      for (const flag of parent.options) {
+        const long = flag.replace(/^--/, "");
+        lines.push(
+          `complete -c corp -n "__fish_seen_subcommand_from ${parentName}" -l '${long}'`
+        );
+      }
+      if (parent.options.length > 0) lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+function makeCompletionsCommand(allCommands) {
+  return {
+    name: "completions",
+    description: "Generate shell completion scripts",
+    local: true,
+    options: [
+      {
+        flags: "--shell <shell>",
+        description: "Shell type (bash, zsh, fish)",
+        choices: ["bash", "zsh", "fish"],
+        required: true
+      }
+    ],
+    examples: [
+      "corp completions --shell bash",
+      "corp completions --shell zsh",
+      "corp completions --shell fish",
+      "source <(corp completions --shell bash)",
+      'eval "$(corp completions --shell zsh)"',
+      "corp completions --shell fish > ~/.config/fish/completions/corp.fish"
+    ],
+    handler: async (ctx) => {
+      const shell = ctx.opts.shell;
+      const cmds = allCommands.filter((c) => c.name !== "completions");
+      let script;
+      switch (shell) {
+        case "bash":
+          script = generateBash(cmds);
+          break;
+        case "zsh":
+          script = generateZsh(cmds);
+          break;
+        case "fish":
+          script = generateFish(cmds);
+          break;
+        default:
+          ctx.writer.error(`Unknown shell: ${shell}. Choose bash, zsh, or fish.`);
+          process.exit(1);
+      }
+      process.stdout.write(script + "\n");
+    }
+  };
+}
+var init_completions = __esm({
+  "src/registry/completions.ts"() {
+    "use strict";
+  }
+});
+
 // src/registry/index.ts
 var registry_exports = {};
 __export(registry_exports, {
@@ -12254,7 +12617,7 @@ function generateSchema(commands, programName, version) {
     commands: topLevel
   };
 }
-var registry;
+var baseRegistry, registry;
 var init_registry = __esm({
   "src/registry/index.ts"() {
     "use strict";
@@ -12274,7 +12637,8 @@ var init_registry = __esm({
     init_secret_proxies();
     init_treasury();
     init_branches();
-    registry = [
+    init_completions();
+    baseRegistry = [
       ...workspaceCommands,
       ...entityCommands,
       ...formationCommands,
@@ -12292,6 +12656,10 @@ var init_registry = __esm({
       ...treasuryCommands,
       ...branchCommands
     ];
+    registry = [
+      ...baseRegistry,
+      makeCompletionsCommand(baseRegistry)
+    ];
   }
 });
 
@@ -12617,7 +12985,9 @@ init_api_client();
 init_references();
 function buildCLI(commands, version) {
   const program2 = new Command();
-  program2.name("corp").description("corp \u2014 Corporate governance from the terminal").version(version).enablePositionalOptions();
+  program2.name("corp").description(
+    'The Corporation CLI \u2014 form entities, manage cap tables, govern, and operate.\n\nQuick start:\n  corp form --type llc --name "My LLC" --member "Alice,a@co.com,member,100"\n  corp cap-table\n  corp next\n\nDocs: https://docs.thecorporation.ai'
+  ).version(version).enablePositionalOptions();
   program2.option("-q, --quiet", "Only output the resource ID (for scripting)");
   program2.action(() => {
     program2.outputHelp();
@@ -12638,6 +13008,61 @@ function buildCLI(commands, version) {
       children.get(parent).push(def);
     }
   }
+  const commandGroupOrder = {
+    // Core workflow — formation & entity management
+    form: 0,
+    entities: 1,
+    contacts: 2,
+    // Cap table
+    "cap-table": 10,
+    "safe-notes": 11,
+    "share-transfers": 12,
+    valuations: 13,
+    // Governance
+    governance: 20,
+    // Finance
+    finance: 30,
+    // Compliance & tax
+    tax: 40,
+    deadlines: 41,
+    // Status / context / actions
+    status: 50,
+    context: 51,
+    use: 52,
+    next: 53,
+    obligations: 54,
+    "human-obligations": 55,
+    digest: 56,
+    // Services & work items
+    services: 60,
+    "work-items": 61,
+    contracts: 62,
+    // Agents
+    agents: 70,
+    // Admin / config / setup (last)
+    billing: 80,
+    "api-keys": 81,
+    link: 82,
+    claim: 83,
+    feedback: 84,
+    resolve: 85,
+    find: 86,
+    approvals: 87,
+    receipts: 88,
+    config: 90,
+    setup: 91,
+    schema: 92,
+    serve: 93,
+    demo: 94,
+    chat: 95,
+    completions: 96
+  };
+  topLevel.sort((a, b) => {
+    const ga = commandGroupOrder[a.name] ?? 75;
+    const gb = commandGroupOrder[b.name] ?? 75;
+    if (ga !== gb) return ga - gb;
+    return a.name.localeCompare(b.name);
+  });
   const parentCmds = /* @__PURE__ */ new Map();
   for (const def of topLevel) {
     const cmd = wireCommand(program2, def);