@ekanos/cli 0.15.0 → 0.17.0

package/dist/index.js

@@ -9,12 +9,16 @@ var __rest = (this && this.__rest) || function (s, e) {
         }
     return t;
 };
+import { isRepoRoot } from '@ekanos/integration-schema/repo';
 import * as fs from 'node:fs';
+import * as path from 'node:path';
 import { runAgents } from './commands/agents.js';
 import { TEMPLATE_EDIT_HELP } from './commands/agents-edit.js';
 import { runApps } from './commands/apps.js';
+import { runAudiences } from './commands/audiences.js';
 import { runCatalog } from './commands/catalog.js';
 import { runDev } from './commands/dev.js';
+import { EXPERIENCE_COMMANDS } from './commands/index-experience.js';
 import { runInit } from './commands/init.js';
 import { runKnowledge } from './commands/knowledge.js';
 import { runLogin } from './commands/login.js';
@@ -33,11 +37,13 @@ import { runUpgrade } from './commands/upgrade.js';
 import { runUse } from './commands/use.js';
 import { runValidate } from './commands/validate.js';
 import { runWhoami } from './commands/whoami.js';
+import { runWorkflows } from './commands/workflows.js';
 import { CliContext } from './context.js';
 import { SDK_DOCS_URL, docsPage } from './docs-links.js';
-import { toCliError, usageError } from './errors.js';
-import { EXIT_CODES } from './exit-codes.js';
+import { preconditionError, toCliError, usageError } from './errors.js';
+import { detectInvocation, setInvocation } from './invocation.js';
 import { parseArgv } from './parse-argv.js';
+import { unknownCommand } from './unknown-command.js';
 export { CliContext } from './context.js';
 export { EXIT_CODES, ERROR_CODES } from './exit-codes.js';
 const GLOBAL_SPECS = {
@@ -61,12 +67,44 @@ const DIR = {
     type: 'string',
     description: 'Project directory, where ekanos.json and relative paths are read (default: the current one)',
 };
+/**
+ * Where a secret comes from without a terminal (`secret-input.ts`), for every
+ * command that takes one. Never a value: a secret in argv lands in shell
+ * history and the process list.
+ */
+const SECRET_INPUT = {
+    'secret-env': {
+        type: 'string',
+        description: 'The secret, from this environment variable (its NAME, never the value)',
+    },
+    'secret-file': {
+        type: 'string',
+        description: 'The secret, from this file: yours, mode 600, not a symlink',
+    },
+    'secret-stdin': {
+        type: 'boolean',
+        description: 'The secret, piped in on stdin',
+    },
+    'set-secret': {
+        type: 'string',
+        repeatable: true,
+        description: 'One field of a form: <field>=env:<NAME> | file:<path> | stdin',
+    },
+    browser: {
+        type: 'boolean',
+        description: 'Type the secret into a one-time form in your browser on this computer (never shown to the run that asked)',
+    },
+};
 const COMMAND_SPECS = {
     init: {
         slug: {
             type: 'string',
             description: 'Kebab-case id of the integration, e.g. acme-crm',
         },
+        kind: {
+            type: 'string',
+            description: 'What to scaffold: integration (default), experience (widgets and workflows that depend on integrations) or repo (one repo holding many of both)',
+        },
         dir: {
             type: 'string',
             description: 'Target directory (default ./<slug>; --dir . scaffolds in place)',
@@ -103,7 +141,11 @@ const COMMAND_SPECS = {
         },
         start: {
             type: 'boolean',
-            description: 'Start the server even in JSON mode; --no-start only scaffolds',
+            description: 'Start the server even in JSON mode or under an agent (non-interactive runs only scaffold and print the command); --no-start only scaffolds',
+        },
+        'contracts-dir': {
+            type: 'string',
+            description: 'Experiences: a directory of <integration>.contract.json files to resolve integrations from (offline registry)',
         },
     },
     test: {
@@ -165,179 +207,271 @@ const COMMAND_SPECS = {
         source: SOURCE,
         yes: {
             type: 'boolean',
-            description: 'Confirm products disable, scopes remove',
+            description: 'Confirm products disable, scopes remove, roles delete',
         },
+        // `sources roles create|update`.
+        'display-name': {
+            type: 'string',
+            description: "roles create|update: the role's display name",
+        },
+        description: {
+            type: 'string',
+            description: "roles create|update: the role's description",
+        },
+        level: {
+            type: 'string',
+            description: 'roles create|update: its level, 1 to 1000; lower ranks higher (default 100)',
+        },
+        permission: {
+            type: 'string',
+            repeatable: true,
+            description: 'roles create|update: a permission it holds (update: replaces them all)',
+        },
+        grant: {
+            type: 'string',
+            repeatable: true,
+            description: 'roles update: add this permission',
+        },
+        revoke: {
+            type: 'string',
+            repeatable: true,
+            description: 'roles update: take this permission away',
+        },
+        // `sources people`.
+        search: {
+            type: 'string',
+            description: 'people: only those whose name or email matches',
+        },
+        page: { type: 'string', description: 'people: which page, from 1' },
     },
-    catalog: {
-        host: HOST,
-        source: SOURCE,
-        dir: DIR,
-    },
-    apps: {
+    audiences: {
         host: HOST,
         source: SOURCE,
         dir: DIR,
-        'no-wait': {
+        yes: {
             type: 'boolean',
-            description: 'connect: print the links and return without waiting',
+            description: 'set: confirm dropping a product people then stop seeing',
         },
-        yes: {
+        name: { type: 'string', description: 'set: rename the audience' },
+        description: {
+            type: 'string',
+            description: 'create|set: what the audience is for',
+        },
+        products: {
+            type: 'string',
+            description: 'create|set: the products it shows, as a,b (set: replaces them; none empties it)',
+        },
+        widgets: {
+            type: 'string',
+            repeatable: true,
+            description: 'create|set: <product>=<id>,<id> shows only those widgets of the product (<product>= lifts the rule)',
+        },
+        tools: {
+            type: 'string',
+            repeatable: true,
+            description: 'create|set: <product>=<name>,<name> allows only those tools of the product (<product>= lifts the rule)',
+        },
+        default: {
             type: 'boolean',
-            description: 'disconnect: confirm without the question (needed in a script or agent run)',
+            description: 'create|set: new teams of the Source start on it',
+        },
+        'all-entitled': {
+            type: 'boolean',
+            description: 'create|set: show every product the Source has, now and later (--no-all-entitled turns it off)',
         },
     },
-    teams: {
+    catalog: {
         host: HOST,
         source: SOURCE,
         dir: DIR,
-        connection: {
+    },
+    apps: Object.assign({ host: HOST, source: SOURCE, dir: DIR, 'no-wait': {
+            type: 'boolean',
+            description: 'connect: print the links and return without waiting',
+        }, yes: {
+            type: 'boolean',
+            description: 'disconnect: confirm without the question (needed in a script or agent run)',
+        }, set: {
+            type: 'string',
+            repeatable: true,
+            description: 'set, connect: <name>=<value> for a field that is not a secret (set: clientId)',
+        } }, SECRET_INPUT),
+    teams: Object.assign(Object.assign({ host: HOST, source: SOURCE, dir: DIR, connection: {
             type: 'string',
             description: 'connect, app set: which of the integration\'s connections (e.g. "agent" for Linear\'s agent)',
-        },
+        }, 
         // `teams app set`: which fields to enter, non-secret values, removals.
         field: {
             type: 'string',
             repeatable: true,
             description: 'app set: enter just this field at your terminal',
-        },
-        set: {
+        }, set: {
             type: 'string',
             repeatable: true,
-            description: 'app set: <name>=<value> for a non-secret field',
-        },
-        clear: {
+            description: 'app set, connect: <name>=<value> for a field that is not a secret (a list as a,b)',
+        }, self: {
+            type: 'boolean',
+            description: 'members add: you join the team now, with no invitation email',
+        }, 
+        // `teams audience`.
+        member: {
+            type: 'string',
+            description: "audience: one member's own audience, by email",
+        }, inherit: {
+            type: 'boolean',
+            description: "audience --member: clear their own audience so the team's applies",
+        } }, SECRET_INPUT), { clear: {
             type: 'string',
             repeatable: true,
             description: "app set: remove this field's saved value",
-        },
-        slug: {
+        }, slug: {
             type: 'string',
             description: "create: the team's slug (default: from its name)",
-        },
-        owner: {
+        }, owner: {
             type: 'string',
             description: 'create: invite this email as the owner instead of you',
-        },
-        role: {
+        }, role: {
             type: 'string',
-            description: 'members invite: the role to invite as (default member)',
-        },
-        yes: {
+            description: 'members add, members invite: the role to give (default member)',
+        }, yes: {
             type: 'boolean',
-            description: 'Confirm a change that removes, pauses, revokes or opens something up (members remove, webhook, disconnect, agents disable, triggers add slack, triggers remove|rotate, links remove, mcp remove, scope set that drops a scope)',
-        },
+            description: 'Confirm a change that removes, pauses, revokes or opens something up (members remove, leave, groups delete, groups members remove, webhook, disconnect, agents disable|archive, mcp detach, triggers add slack|disable, triggers edit of a slack audience, triggers remove|rotate, links remove, mcp remove, scope set that drops a scope)',
+        }, 
         // `teams agents|triggers|links|mcp` (team-agents.ts).
         as: {
             type: 'string',
-            description: 'connect: the member who signs in; agents enable: the member the agent runs as',
-        },
+            description: 'connect: the member who signs in; agents enable: the member the agent runs as (chosen once, when it is turned on)',
+        }, 
         // `teams agents enable|pin … --draft`: test the unpublished draft there.
         draft: {
             type: 'boolean',
             description: "agents enable|pin: put this team alone on the template's unpublished draft",
-        },
-        // `teams agents enable|policy`: also confirm, as yourself, what the
-        // agent may use (whoever sets it up confirms it, plan 247.2).
+        }, 
+        // `teams agents enable|policy|create|apply`: also confirm, as yourself,
+        // what the agent may use (whoever sets it up confirms it, plan 247.2).
         'confirm-access': {
             type: 'boolean',
-            description: 'agents enable|policy: also confirm, as yourself, what it may use',
-        },
-        reads: {
+            description: 'agents enable|policy|create|apply: also confirm, as yourself, what it may use',
+        }, 
+        // `teams agents create|apply`: the agent.json, read as `agents apply`
+        // reads it (team-agents-define.ts).
+        from: {
+            type: 'string',
+            description: 'agents create: the agent directory or agent.json',
+        }, personal: {
+            type: 'boolean',
+            description: 'agents create|apply: your own agent, which acts for you and only you change',
+        }, 'base-version': {
+            type: 'string',
+            description: 'agents apply: the agent version your edit starts from ("teams agents show")',
+        }, overwrite: {
+            type: 'boolean',
+            description: 'agents apply: replace a newer version on the host anyway',
+        }, skills: {
+            type: 'boolean',
+            description: 'agents create|apply: --no-skills skips pushing <dir>/skills/<slug>/ as team skills',
+        }, reads: {
             type: 'string',
             description: 'agents policy: auto|approve for every read tool',
-        },
-        writes: {
+        }, writes: {
             type: 'string',
             description: 'agents policy: auto|approve for every write tool',
-        },
-        effect: {
+        }, effect: {
             type: 'string',
             description: 'Not read: "teams mcp effect" takes the effect as an argument',
-        },
-        kind: { type: 'string', description: 'links add: talk|delegate' },
-        mode: {
+        }, agent: {
+            type: 'string',
+            description: 'mcp refresh: list again the tools of every server this agent has',
+        }, kind: { type: 'string', description: 'links add: talk|delegate' }, mode: {
             type: 'string',
             description: 'links add: await|handoff, for a delegate link',
-        },
-        url: { type: 'string', description: "mcp add: the server's URL" },
-        auth: {
+        }, url: { type: 'string', description: "mcp add: the server's URL" }, auth: {
             type: 'string',
             description: 'mcp add: none|token|oauth (default oauth)',
-        },
-        name: { type: 'string', description: "mcp add: the server's display name" },
-        cron: {
+        }, name: {
             type: 'string',
-            description: 'triggers add schedule: a cron expression',
-        },
-        timezone: {
+            description: "mcp add: the server's display name; groups update: the group's new name",
+        }, 
+        // `teams groups create|update`.
+        description: {
             type: 'string',
-            description: 'triggers add schedule: an IANA time zone (default UTC)',
-        },
-        prompt: {
+            description: "groups create|update: the group's description",
+        }, products: {
             type: 'string',
-            description: 'triggers add: what the agent is told when it fires',
-        },
+            description: 'groups create|update: the products it narrows to, comma-separated (none: no narrowing)',
+        }, 
+        // `teams disconnect|health <team> <product> --mine`: the caller's own.
+        mine: {
+            type: 'boolean',
+            description: "disconnect, health <product>: your own personal connection, never another member's",
+        }, 
+        // `teams health <team> <product> --run`.
+        run: {
+            type: 'boolean',
+            description: "health: run the integration's health check now",
+        }, cron: {
+            type: 'string',
+            description: 'triggers add|edit schedule: a cron expression',
+        }, timezone: {
+            type: 'string',
+            description: 'triggers add|edit schedule: an IANA time zone (default UTC)',
+        }, prompt: {
+            type: 'string',
+            description: 'triggers add|edit: what the agent is told when it fires',
+        }, 
         // Repeatable `field=value`, or one JSON object — as at the template level.
         filter: {
             type: 'string',
             repeatable: true,
-            description: 'triggers add event: field=a,b (repeatable) or one JSON object',
-        },
+            description: 'triggers add|edit event: field=a,b (repeatable) or one JSON object',
+        }, 
         // `teams <area> … --team <slug>`: the team, in place of the positional.
         team: {
             type: 'string',
             description: 'The team, in place of the <team> argument (teams <area> … --team <slug>)',
-        },
+        }, 
         // `teams triggers add … slack|linear`: where it answers. `--no-mention`
         // is the negation of `mention`.
         channel: {
             type: 'string',
             repeatable: true,
-            description: 'triggers add slack: a channel it answers in (#name or id)',
-        },
-        dms: {
+            description: 'triggers add|edit slack: a channel it answers in (#name or id); edit replaces the list',
+        }, dms: {
             type: 'boolean',
-            description: 'triggers add slack: also answer direct messages',
-        },
-        label: {
+            description: 'triggers add|edit slack: also answer direct messages (edit: --no-dms stops)',
+        }, label: {
             type: 'string',
             repeatable: true,
-            description: 'triggers add linear: a label that hands an issue to it',
-        },
-        mention: {
+            description: 'triggers add|edit linear: a label that hands an issue to it; edit replaces the list',
+        }, mention: {
             type: 'boolean',
-            description: 'triggers add linear: --no-mention ignores @mentions',
-        },
+            description: 'triggers add|edit linear: --no-mention ignores @mentions (edit: --mention answers them)',
+        }, 
         // `teams connect`: `--no-wait`, `--no-open` (the negation of `open`),
         // `--link-only`.
         'no-wait': {
             type: 'boolean',
             description: 'connect: print the sign-in link and return at once',
-        },
-        open: {
+        }, open: {
             type: 'boolean',
             description: 'connect: --no-open prints the link without opening a browser',
-        },
-        'link-only': {
+        }, 'link-only': {
             type: 'boolean',
             description: "connect: print the team's page instead of connecting",
-        },
+        }, 
         // `teams events <team> [--product] [--since] [--limit]`.
         product: {
             type: 'string',
             description: 'events: only this product (or name it after the team)',
-        },
-        since: {
+        }, since: {
             type: 'string',
             description: 'events: since 30m, 24h, 7d or a date',
-        },
-        limit: { type: 'string', description: 'events: how many, 1 to 100' },
+        }, limit: { type: 'string', description: 'events: how many, 1 to 100' }, 
         // `teams connect --reconnect`.
         reconnect: {
             type: 'boolean',
             description: 'connect: connect again though it reads as connected (revoked or expired)',
-        },
-    },
+        } }),
     reviewers: {
         host: HOST,
         source: SOURCE,
@@ -542,6 +676,51 @@ const COMMAND_SPECS = {
             description: 'edit: a file with the reply to send instead',
         },
     },
+    workflows: {
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        team: { type: 'string', description: 'The team whose workflows these are' },
+        all: { type: 'boolean', description: 'list: include archived workflows' },
+        out: {
+            type: 'string',
+            description: 'pull: where to write workflow.json (default workflows/<name>)',
+        },
+        force: {
+            type: 'boolean',
+            description: 'pull: overwrite a local workflow.json that differs',
+        },
+        update: {
+            type: 'string',
+            description: 'apply: the workflow (id or name) to replace; without it apply creates a draft',
+        },
+        'confirm-access': {
+            type: 'boolean',
+            description: 'enable: approve, as yourself, what its Custom Code reaches (hosts, writes)',
+        },
+        'dry-run': {
+            type: 'boolean',
+            description: 'run: rehearse it (writes recorded, not sent; gates pass); a draft may run so',
+        },
+        input: {
+            type: 'string',
+            description: 'run --dry-run: a JSON file read as the sample trigger.*',
+        },
+        follow: {
+            type: 'boolean',
+            description: 'run: wait, printing each step, until it ends or waits on a gate',
+        },
+        workflow: {
+            type: 'string',
+            description: "runs list: only this workflow's runs (id or name)",
+        },
+        status: {
+            type: 'string',
+            description: 'runs list: only runs in this status (running, waiting_approval, completed, rejected, failed, canceled)',
+        },
+        reason: { type: 'string', description: 'approvals reject: why' },
+        yes: { type: 'boolean', description: 'runs cancel: confirm' },
+    },
     use: {
         host: HOST,
         dir: DIR,
@@ -554,6 +733,14 @@ const COMMAND_SPECS = {
             type: 'boolean',
             description: 'Publish to the ekanos.json source without asking (needed in a script with several seats)',
         },
+        'dry-run': {
+            type: 'boolean',
+            description: 'Experiences and repos: gate, build and pack every package under .ekanos/publish/, publish nothing (publishing an experience is not supported by the host yet)',
+        },
+        all: {
+            type: 'boolean',
+            description: 'In a repo: publish every package',
+        },
     },
     upgrade: {
         dir: DIR,
@@ -577,9 +764,12 @@ const COMMAND_SPECS = {
 /** Commands that take positional arguments, and what each means, in order. Every other command is positional-free. */
 const POSITIONAL_COMMANDS = {
     use: ['source-slug'],
+    // In a repo: `publish <package>...` (repeatable, see VARIADIC_COMMANDS).
+    publish: ['package'],
     // `sources scopes add <scope> <product>` is the longest form.
     sources: ['subcommand', 'verb', 'product-or-scope', 'product-slug'],
     catalog: ['product-slug'],
+    audiences: ['subcommand', 'audience'],
     apps: ['subcommand', 'product-slug'],
     // `teams agents policy <team> <key> set <tool> auto` is the longest form.
     teams: [
@@ -597,15 +787,37 @@ const POSITIONAL_COMMANDS = {
     knowledge: ['subcommand', 'path-or-query'],
     runs: ['subcommand', 'agent-key-or-run-id'],
     approvals: ['subcommand', 'approval-id'],
+    // `workflows runs show <run-id>` is the longest form.
+    workflows: ['subcommand', 'workflow-or-verb', 'id'],
     // `triggers <key> add event <trigger-key>` is the longest form: five tokens.
     agents: ['subcommand', 'key-or-path', 'action', 'arg', 'value'],
 };
+for (const command of EXPERIENCE_COMMANDS) {
+    COMMAND_SPECS[command.name] = command.specs;
+    if (command.positionals)
+        POSITIONAL_COMMANDS[command.name] = command.positionals;
+}
+/** Commands that act on one package: refused at a repo root, with the way in. */
+const REPO_ROOT_REFUSED = new Set([
+    'validate',
+    'test',
+    'check',
+    'build',
+    'sync',
+    'add',
+    'codegen',
+    'contract',
+]);
+/** Commands whose last positional repeats. */
+const VARIADIC_COMMANDS = new Set(['publish']);
 const COMMANDS = Object.keys(COMMAND_SPECS);
 const USAGE = [
     'Usage: ekanos <command> [options]',
     '',
     'Commands:',
-    '  init       Scaffold a new integration project into ./<slug> (--slug <slug> --yes)',
+    '  init       Scaffold a new integration project into ./<slug> (--slug <slug> --yes);',
+    '             --kind experience for an experience, --kind repo for a repo of many',
+    ...EXPERIENCE_COMMANDS.flatMap((command) => command.usage),
     '  validate   Validate ekanos.json + the integration definition (--json)',
     '  dev        Scaffold .ekanos/harness and run it with your own Next',
     '  test       Run the project test script via its package manager (--json).',
@@ -630,13 +842,35 @@ const USAGE = [
     '             and pointed at /admin) | scopes (each product scope: its',
     '             products and how many teams hold it; a team sees in the app',
     "             only its scopes' products) | scopes add <scope> <product> |",
-    '             scopes remove <scope> <product> --yes',
-    '  catalog    What a source can already use, and how to set it up',
+    '             scopes remove <scope> <product> --yes | roles [list] (the roles',
+    '             every team of the Source hands out, each with its level and',
+    '             permissions) | roles create <name> [--display-name <text>]',
+    '             [--description <text>] [--level <n>] [--permission <p>]… |',
+    '             roles update <role> [--display-name] [--description] [--level]',
+    '             [--permission <p>]… (replaces) [--grant <p>]… [--revoke <p>]… |',
+    '             roles delete <role> [--yes] (owner, admin and member are system',
+    "             roles: never changed or deleted; a held role isn't deleted) |",
+    '             people [--search <text>] [--page <n>] (everyone with access, one',
+    '             row per person, with their teams and role on each)',
+    "  audiences  A source's audiences, for its Source admin (they replace product",
+    '             scopes): list | show <audience> | create <name> [--products a,b |',
+    '             --all-entitled] [--description <text>] [--default] [--widgets',
+    '             <product>=<id>,…]… [--tools <product>=<name>,…]… | set <audience>',
+    '             [--name] [--description] [--default] [--all-entitled] [--products',
+    '             a,b|none] [--widgets …]… [--tools …]… [--yes] (--products replaces;',
+    '             dropping a product needs --yes). A team or member is put on one',
+    '             with "teams audience <team> [<audience>] [--member <email>]"',
+    '  catalog    What a source can already use, and how to set it up:',
+    '             Experiences, then Integrations; one product shows its tools',
+    '             with their inputs and whose connection agent runs use',
     '             ("ekanos catalog [<product-slug>] --source <slug>", --json)',
     "  apps       The Source's app for an integration teams sign in through:",
     '             show <product> | set <product> (Source admin; takes the secret',
-    '             at your terminal, Enter keeps a saved value) | connect',
-    '             <product> [--no-wait] (one',
+    '             at your terminal, Enter keeps a saved value; without one,',
+    '             --set clientId=<id> and --secret-env <NAME> | --secret-file',
+    '             <path> | --secret-stdin | --browser) | connect',
+    '             <product> [--no-wait] [--set <field>=<value>]… [--set-secret',
+    '             <field>=env:<NAME>|file:<path>|stdin]… [--browser] (one',
     "             connection for the whole Source, used by the Source's provided",
     '             agents in every team) | disconnect <product> [--yes] (a',
     '             script or agent run needs --yes) | list',
@@ -644,15 +878,32 @@ const USAGE = [
     '             create <name> [--slug <slug>] [--owner <email>] (you own it',
     '             unless --owner, who is invited as owner) |',
     '             rename <team> <name> (the slug follows the name, as in the app) |',
-    '             members list <team> | members invite <team> <email> [--role',
-    '             <role>] (default member; sends the invitation email) |',
+    '             members list <team> | members add <team> --self | <email>',
+    '             [--role <role>] (a member now, no email: you, or someone with',
+    '             an Ekanos account on the Source) | members invite <team> <email>',
+    '             [--role <role>] (default member; sends the invitation email) |',
     '             members role <team> <email> <role> | members remove <team>',
-    "             <email> --yes | roles list <team> (each role's permissions) |",
+    '             <email> --yes | members resend <team> <email> (a live',
+    '             invitation is resent, an expired one renewed) |',
+    "             roles list <team> (each role's permissions) |",
+    '             leave <team> [--yes] (you leave it; never the primary owner) |',
+    '             groups list <team> | groups create <team> <name> [--description',
+    '             <text>] [--products <slug,slug>] | groups update <team> <group>',
+    '             [--name <name>] [--description <text>] [--products <slug,…>|none]',
+    '             | groups delete <team> <group> [--yes] | groups members',
+    '             add|remove <team> <group> <email> (leave, groups delete and',
+    '             remove ask first; a script or agent run needs --yes) |',
+    '             health <team> [<product>] [--run] (each connected integration',
+    '             and its health; --run checks one now; <product> --mine: your own',
+    '             personal connection, any seat, as a member) | workspace list <team> |',
+    '             workspace default <team> <workspace> (where the team lands) |',
     '             connect <team> <product> [--connection <id>] [--as',
-    '             <member-email>] [--no-wait] [--no-open] [--link-only]',
-    '             [--reconnect] (connects',
-    "             it: asks the form's fields at your terminal, or opens the",
-    '             sign-in for you or the member --as names and waits;',
+    '             <member-email>] [--set <field>=<value>]… [--no-wait] [--no-open]',
+    '             [--link-only] [--reconnect] (connects',
+    "             it: asks the form's fields at your terminal or takes them from",
+    '             --set (a list as a,b; secrets and JSON only at a prompt; an optional',
+    '             one can be skipped), then opens the sign-in for you — your own',
+    '             connection, for a personal product — or the member --as names, and waits;',
     "             --connection agent installs the team's Linear agent (its own",
     '             Linear app, as a member), which @mention and assign triggers',
     "             need; --link-only prints the team's page; --reconnect connects",
@@ -662,30 +913,52 @@ const USAGE = [
     '             Slack, or the Ekanos Agents app for Linear, which slack and',
     '             linear triggers answer through; same link-and-wait) |',
     "             disconnect <team> <product> --yes (takes the team's connection",
-    "             and its tokens down; its own app's saved fields stay) |",
+    "             and its tokens down; its own app's saved fields stay; --mine:",
+    "             your own personal connection, never another member's) |",
     '             list | show <team> (one screen: members, each integration and',
     '             whose connection it is, each agent live or the next step) |',
     '             show <team> <product> (a checklist: fields, callback',
     '             URLs, webhooks, connect link) | app set <team> <product>',
     '             [--connection <id>] [--field <name>]… [--set <name>=<value>]…',
-    '             [--clear <name>]… (any one field at a time; a field you skip',
-    '             keeps its saved value; secrets only at your terminal) |',
+    '             [--clear <name>]… [--set-secret <name>=env:<NAME>|file:<path>|stdin]…',
+    '             [--browser] (any one field at a time; a field you skip keeps',
+    '             its saved value; a secret at your terminal, from the',
+    '             environment, a private file, stdin or a browser form, never',
+    '             as an argument) |',
+    '             llm-key show <team> | llm-key set <team> [--secret-env <NAME> |',
+    '             --secret-file <path> | --secret-stdin | --browser] | llm-key',
+    "             remove <team> --yes (the team's own Anthropic key, as its",
+    '             settings page sets it; show gives only its last four characters) |',
     '             webhook <team> <product> [<webhook-id>] [--yes] (URL saved to a 0600 file under ~/.ekanos/secrets, never printed) |',
     '             events <team> [<product>] [--product <slug>] [--since 24h|7d|<date>]',
     '             [--limit <n>] (the integration events recorded for the team, each',
     '             with its status, last error and the runs it started, or why none did)',
-    '             | scope show <team> (the product scopes it holds and the products',
+    '             | audience <team> [<audience>] [--member <email> [--inherit]] [--yes]',
+    "             (the audience a team starts its members on; a member's own, a Source",
+    "             admin's only, overrides it; --inherit clears it; moving people to an",
+    '             audience that shows less needs --yes)',
+    '             | scope show <team> (DEPRECATED, use audience: the product scopes it holds and the products',
     '             it sees in the app) | scope set <team> <scope> [<scope>…] [--yes]',
     '             (replaces them; dropping one needs --yes)',
     "             A team's agents, for the Source admin (teams <area> <verb> <team> …):",
     '             agents list <team> | agents show <team> <key> (is it live, and if',
     '             not, why: each connection and whose it is, each trigger and how its',
     '             events arrive, last event and run, one Next command)',
+    '             | agents create <team> --from <dir|agent.json> [--personal]',
+    "             [--confirm-access] [--no-skills] (the team's own agent, or with",
+    '             --personal your own, from the agent.json "agents apply" reads;',
+    '             you become its creator, so you must be an active member of the',
+    '             team; it starts as a draft) | agents apply <team> <dir|agent.json>',
+    '             [--personal] [--base-version <n>] [--overwrite] [--confirm-access]',
+    '             (creates it, or changes it from the same file; a personal agent',
+    "             is its creator's alone to change)",
     '             | agents enable <team> <key> [--as <member-email>]',
     '             [--draft] [--confirm-access] (--confirm-access: you also confirm',
     '             what it may use) | agents confirm <team> <key> (you confirm what',
     '             it may use, as yourself: whoever sets an agent up confirms it, never',
     '             a team member) | agents disable <team> <key> --yes | agents',
+    '             archive <team> <key> [--yes] (off the list; runs and setup kept) |',
+    '             agents unarchive <team> <key> (back, paused) | agents',
     '             unpin <team> <key> | agents pin <team> <key> <version> | agents pin',
     '             <team> <key> --draft (this team only runs the unpublished draft, by',
     '             hand, every write waiting; the next publish puts it back to',
@@ -694,17 +967,29 @@ const USAGE = [
     '             [--reads auto|approve] [--writes auto|approve] [--confirm-access]',
     '             | agents skills <team> <key> [add|remove <skill>] (where the',
     '             template allows team skills; its own skills stay)',
-    '             triggers list|add|remove <team> <key> … (add … event <id>',
+    '             | agents tags <team> <key> [add|remove <tag>] (labels that grant',
+    '             nothing; a tag the team lacks is made)',
+    '             triggers list|add|remove <team> <key> … (add … schedule --cron',
+    '             <expr> [--timezone <zone>] --prompt <text> | add … webhook --prompt',
+    '             <text> (its token saved to a 0600 file, never printed; a personal',
+    "             agent's webhook acts as its creator) | add … event <id>",
     "             [--filter field=a,b]… or --filter '<json>'; remove <trigger-id|key> --yes;",
     '             add … slack --channel',
     '             <#name|id>… [--dms] --yes | add … linear [--label <name>]…',
     '             [--no-mention], once installed with teams connect) | triggers',
     "             rotate <team> <key> <trigger-key|id> [--yes] (a webhook trigger's",
-    '             new token, the old one revoked; saved to a 0600 file, never printed) | links list|add|remove',
+    '             new token, the old one revoked; saved to a 0600 file, never printed)',
+    '             | triggers enable|disable <team> <key> <trigger-id|key> (disable',
+    '             asks first, --yes in a script) | triggers edit <team> <key>',
+    '             <trigger-id|key> [--prompt …] [--cron … --timezone …] [--filter …]',
+    '             [--channel …] [--dms|--no-dms] [--label …] [--mention|--no-mention]',
+    '             (in place: a webhook keeps its URL and token) | links list|add|remove',
     '             <team> <from-key> [<to-key> --kind talk|delegate --mode await|handoff]',
     '             (remove <link-id|to-key> [--kind <kind>] --yes)',
-    '             | mcp list|add|status|token|effect|remove <team> [<server-key> …]',
-    '             (remove needs --yes)',
+    '             | mcp list|add|status|token|effect|refresh|remove <team> [<server-key> …]',
+    '             (remove needs --yes; refresh <team> --agent <key>: every server it',
+    '             has) | mcp attach|detach <team> <server-key> <agent-key> (detach',
+    '             asks first, --yes in a script; where the template allows)',
     '             Every area also takes the team as --team <slug>.',
     '             ("ekanos teams --help" spells out each area)',
     '  reviewers  Who decides agent reply drafts, for the Source admin:',
@@ -782,8 +1067,29 @@ const USAGE = [
     "  approvals  What a team's agent runs wait on: list --team <slug> |",
     '             approve|reject <id> --team <slug> [--reason "…"] |',
     '             edit <id> --team <slug> --body <file> (edit & send a reply draft)',
+    '             The Source admin sees all; any other seat holder only what they',
+    "             may decide (managing or reviewing the team's agents, a named",
+    "             reviewer, a personal agent's creator). The first decision wins.",
+    "  workflows  A team's workflows, for the Source admin (each takes --team <slug>;",
+    '             a workflow is named by its id or its name):',
+    '             list [--all] | show <workflow> (status, trigger, Custom Code review',
+    '             state, recent runs; --json: the definition) | pull <workflow>',
+    '             [--out <dir>] [--force] (writes workflow.json, the JSON the editor',
+    '             saves) | apply <file|dir> [--update <workflow>] (a new draft, or',
+    "             that workflow's definition replaced; the editor's checks: shape,",
+    '             tool effects, Custom Code security review, approval gates before',
+    '             writes) | enable <workflow> [--confirm-access] (activation re-checks',
+    '             it; Custom Code that writes or reaches a host needs your approval,',
+    '             asked at a terminal) | disable <workflow> | run <workflow>',
+    '             [--dry-run [--input <file.json>]] [--follow] (a live run needs it',
+    '             on; --dry-run records writes instead of sending them) |',
+    '             runs list [--workflow <workflow>] [--status <status>] | runs show',
+    '             <run-id> | runs cancel <run-id> [--yes] | approvals list |',
+    '             approvals approve|reject <id> [--reason "…"]',
     '  use        Set this project\'s publish target ("ekanos use <source-slug>")',
-    '  publish    Validate, pack and submit the integration to an Ekanos host',
+    '  publish    Validate, pack and submit the integration to an Ekanos host.',
+    '             In a repo: publish [<package>...] | --all [--dry-run] (integrations',
+    '             first, each package gated, artifacts under .ekanos/publish/)',
     '  upgrade    Move this toolchain to a coherent target version, with',
     '             verify-and-rollback (--check --yes --no-verify --host <url>)',
     '',
@@ -796,7 +1102,7 @@ const USAGE = [
     '  bare "ekanos upgrade" MUTATES the project (installs the target versions,',
     '  verifies with validate + the test script, rolls back on any failure).',
     '',
-    'Host resolution (logout, whoami, status, sources, catalog, apps, teams, reviewers, routes, agents, skills, knowledge, runs, approvals, use, publish, upgrade):',
+    'Host resolution (logout, whoami, status, sources, catalog, apps, teams, reviewers, routes, agents, skills, knowledge, runs, approvals, workflows, use, publish, upgrade):',
     '  --host, else EKANOS_HOST, else the "host" field in ekanos.json, else the',
     '  sole stored login. "ekanos publish" saves host and source to ekanos.json.',
     '  "ekanos login" never reads ekanos.json for a host (--host, else',
@@ -825,16 +1131,17 @@ const USAGE = [
  * `process.exit`, so this stays fully testable.
  */
 export async function run(argv, options = {}) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     const jsonFlag = scanJsonFlag(argv);
+    setInvocation((_a = options.invocation) !== null && _a !== void 0 ? _a : detectInvocation((_b = options.env) !== null && _b !== void 0 ? _b : process.env), COMMANDS);
     const ctx = new CliContext({
         jsonFlag,
         stdout: options.stdout,
         stderr: options.stderr,
         env: options.env,
     });
-    const cwd = (_a = options.cwd) !== null && _a !== void 0 ? _a : process.cwd();
-    const env = (_b = options.env) !== null && _b !== void 0 ? _b : process.env;
+    const cwd = (_c = options.cwd) !== null && _c !== void 0 ? _c : process.cwd();
+    const env = (_d = options.env) !== null && _d !== void 0 ? _d : process.env;
     try {
         // `--version` is global and verb-independent, so it is answered before the
         // command is even resolved: `ekanos --version` and `ekanos validate
@@ -853,36 +1160,35 @@ export async function run(argv, options = {}) {
                 tool: 'ekanos',
                 error: 'unknown-command',
                 commands: COMMANDS,
-                usage: USAGE,
+                help: 'ekanos --help',
             });
             throw usageError(`Unknown command or flag "${argv[0]}".`, `Run one of: ${COMMANDS.join(', ')}. See "ekanos --help".`);
         }
         if (!COMMANDS.includes(command)) {
-            ctx.emitClaudeCodeHint({
-                tool: 'ekanos',
-                error: 'unknown-command',
-                given: command,
-                commands: COMMANDS,
-                usage: USAGE,
-            });
-            throw usageError(`Unknown command "${command}".`, `Run one of: ${COMMANDS.join(', ')}. See "ekanos --help".`);
+            const unknown = unknownCommand(command, rest, COMMANDS);
+            ctx.emitClaudeCodeHint(Object.assign(Object.assign({ tool: 'ekanos', error: 'unknown-command', given: command }, (unknown.suggestion ? { suggestion: unknown.suggestion } : {})), { commands: COMMANDS, help: 'ekanos --help' }));
+            throw unknown.error;
         }
         const specs = Object.assign(Object.assign({}, GLOBAL_SPECS), COMMAND_SPECS[command]);
         const parsed = parseArgv(rest, specs);
         if (parsed.flags.help === true) {
             return emitCommandHelp(ctx, command);
         }
-        const positionalNames = (_c = POSITIONAL_COMMANDS[command]) !== null && _c !== void 0 ? _c : [];
+        const positionalNames = (_e = POSITIONAL_COMMANDS[command]) !== null && _e !== void 0 ? _e : [];
         if (positionalNames.length === 0 && parsed.positionals.length > 0) {
             throw usageError(`"${command}" takes no positional arguments (got "${parsed.positionals[0]}").`, `Pass options as flags, e.g. "--dir <path>". See "ekanos ${command} --help".`);
         }
-        if (parsed.positionals.length > positionalNames.length) {
+        if (parsed.positionals.length > positionalNames.length &&
+            !VARIADIC_COMMANDS.has(command)) {
             const usage = positionalNames.map((name) => `<${name}>`).join(' ');
             throw usageError(`"${command}" takes at most ${positionalNames.length} positional ` +
                 `argument${positionalNames.length === 1 ? '' : 's'} (${usage}), ` +
                 `got ${parsed.positionals.length}.`, `e.g. "ekanos ${command} ${usage}". See "ekanos ${command} --help".`);
         }
-        const dir = (_d = parsed.flags.dir) !== null && _d !== void 0 ? _d : cwd;
+        const dir = (_f = parsed.flags.dir) !== null && _f !== void 0 ? _f : cwd;
+        if (REPO_ROOT_REFUSED.has(command) && isRepoRoot(path.resolve(dir))) {
+            throw preconditionError(`"${command}" works on one package, and ${dir} is a repo root.`, `Run it inside a package (cd integrations/<slug> or cd experiences/<slug>), or use "ekanos publish --all" for the whole repo.`);
+        }
         switch (command) {
             case 'init':
                 return await runInit(ctx, {
@@ -892,6 +1198,7 @@ export async function run(argv, options = {}) {
                     force: parsed.flags.force === true,
                     yes: parsed.flags.yes === true,
                     docs: parsed.flags.docs,
+                    kind: parsed.flags.kind,
                     stdinIsTTY: options.stdinIsTTY,
                 });
             case 'validate':
@@ -903,6 +1210,7 @@ export async function run(argv, options = {}) {
                     host: parsed.flags.host,
                     force: parsed.flags.force === true,
                     start: parsed.flags.start,
+                    contractsDir: parsed.flags['contracts-dir'],
                     env,
                 });
             case 'test':
@@ -952,6 +1260,19 @@ export async function run(argv, options = {}) {
                     positionals: parsed.positionals,
                     source: parsed.flags.source,
                     yes: parsed.flags.yes === true,
+                    flags: parsed.flags,
+                    dir,
+                    env,
+                    stdinIsTTY: options.stdinIsTTY,
+                    ask: options.ask,
+                });
+            case 'audiences':
+                return await runAudiences(ctx, {
+                    host: parsed.flags.host,
+                    source: parsed.flags.source,
+                    positionals: parsed.positionals,
+                    yes: parsed.flags.yes === true,
+                    flags: parsed.flags,
                     dir,
                     env,
                 });
@@ -977,6 +1298,10 @@ export async function run(argv, options = {}) {
                     confirm: options.confirm,
                     noWait: parsed.flags['no-wait'] === true,
                     yes: parsed.flags.yes === true,
+                    flags: parsed.flags,
+                    readStdin: options.readStdin,
+                    openUrl: options.openUrl,
+                    secretFormTimeoutMs: options.secretFormTimeoutMs,
                 });
             case 'teams':
                 return await runTeams(ctx, {
@@ -1000,6 +1325,8 @@ export async function run(argv, options = {}) {
                     askSecret: options.askSecret,
                     openUrl: options.openUrl,
                     pollDelayMs: options.pollDelayMs,
+                    readStdin: options.readStdin,
+                    secretFormTimeoutMs: options.secretFormTimeoutMs,
                 });
             case 'reviewers':
                 return await runReviewers(ctx, {
@@ -1112,6 +1439,30 @@ export async function run(argv, options = {}) {
                     stdinIsTTY: options.stdinIsTTY,
                     confirm: options.confirm,
                 });
+            case 'workflows':
+                return await runWorkflows(ctx, {
+                    host: parsed.flags.host,
+                    source: parsed.flags.source,
+                    positionals: parsed.positionals,
+                    team: parsed.flags.team,
+                    all: parsed.flags.all === true,
+                    out: parsed.flags.out,
+                    force: parsed.flags.force === true,
+                    update: parsed.flags.update,
+                    confirmAccess: parsed.flags['confirm-access'] === true,
+                    dryRun: parsed.flags['dry-run'] === true,
+                    input: parsed.flags.input,
+                    follow: parsed.flags.follow === true,
+                    workflow: parsed.flags.workflow,
+                    status: parsed.flags.status,
+                    reason: parsed.flags.reason,
+                    yes: parsed.flags.yes === true,
+                    dir,
+                    env,
+                    sleep: options.sleep,
+                    stdinIsTTY: options.stdinIsTTY,
+                    confirm: options.confirm,
+                });
             case 'use':
                 return await runUse(ctx, {
                     host: parsed.flags.host,
@@ -1125,6 +1476,9 @@ export async function run(argv, options = {}) {
                     source: parsed.flags.source,
                     dir,
                     yes: parsed.flags.yes === true,
+                    dryRun: parsed.flags['dry-run'] === true,
+                    packages: parsed.positionals,
+                    all: parsed.flags.all === true,
                     env,
                     stdinIsTTY: options.stdinIsTTY,
                     confirm: options.confirm,
@@ -1140,9 +1494,21 @@ export async function run(argv, options = {}) {
                     stdinIsTTY: options.stdinIsTTY,
                     confirm: options.confirm,
                 });
-            default:
+            default: {
+                const experienceCommand = EXPERIENCE_COMMANDS.find((candidate) => candidate.name === command);
+                if (experienceCommand) {
+                    return await experienceCommand.run(ctx, {
+                        flags: parsed.flags,
+                        positionals: parsed.positionals,
+                        passthrough: parsed.passthrough,
+                        dir,
+                        cwd,
+                        env,
+                    });
+                }
                 // Unreachable — COMMANDS gate above — but keeps the switch total.
                 throw usageError(`Unknown command "${command}".`, `Run one of: ${COMMANDS.join(', ')}.`);
+            }
         }
     }
     catch (error) {
@@ -1221,11 +1587,12 @@ function emitVersion(ctx) {
 }
 const DOCS_FOOTER = `\nDocs: ${SDK_DOCS_URL} (commands: ${docsPage('cli/commands')})`;
 function emitHelp(ctx) {
+    // Short on purpose: the command list and where each command's usage is.
+    // The full usage is already the result, and a hint line is not a manual.
     ctx.emitClaudeCodeHint({
         tool: 'ekanos',
         commands: COMMANDS,
-        usage: USAGE,
-        exitCodes: EXIT_CODES,
+        help: 'ekanos <command> --help',
     });
     return ctx.succeed({ usage: USAGE, commands: COMMANDS, docs: SDK_DOCS_URL }, `${USAGE}${DOCS_FOOTER}`);
 }