@ekanos/cli 0.12.0 → 0.14.0

package/dist/index.js

@@ -1,9 +1,22 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import * as fs from 'node:fs';
 import { runAgents } from './commands/agents.js';
+import { TEMPLATE_EDIT_HELP } from './commands/agents-edit.js';
 import { runApps } from './commands/apps.js';
 import { runCatalog } from './commands/catalog.js';
 import { runDev } from './commands/dev.js';
 import { runInit } from './commands/init.js';
+import { runKnowledge } from './commands/knowledge.js';
 import { runLogin } from './commands/login.js';
 import { runLogout } from './commands/logout.js';
 import { runPublish } from './commands/publish.js';
@@ -13,6 +26,7 @@ import { runApprovals, runRuns } from './commands/runs.js';
 import { runSkills } from './commands/skills.js';
 import { runSources } from './commands/sources.js';
 import { runStatus } from './commands/status.js';
+import { TEAM_AGENT_AREAS, usageFor } from './commands/team-agents.js';
 import { runTeams } from './commands/teams.js';
 import { runTest } from './commands/test.js';
 import { runUpgrade } from './commands/upgrade.js';
@@ -27,189 +41,544 @@ import { parseArgv } from './parse-argv.js';
 export { CliContext } from './context.js';
 export { EXIT_CODES, ERROR_CODES } from './exit-codes.js';
 const GLOBAL_SPECS = {
-    json: { type: 'boolean' },
-    help: { type: 'boolean' },
-    version: { type: 'boolean' },
+    json: {
+        type: 'boolean',
+        description: 'One JSON envelope on stdout (on by default when piped or under Claude Code; --no-json forces text)',
+    },
+    help: { type: 'boolean', description: 'Show help for the command' },
+    version: { type: 'boolean', description: 'Print the CLI version' },
+};
+/** The flags most commands share, described once. */
+const HOST = {
+    type: 'string',
+    description: 'Ekanos host URL (else EKANOS_HOST, the "host" in ekanos.json, or the only stored login)',
+};
+const SOURCE = {
+    type: 'string',
+    description: 'The Source to act on (else the "source" in ekanos.json, or your only seat)',
+};
+const DIR = {
+    type: 'string',
+    description: 'Project directory, where ekanos.json and relative paths are read (default: the current one)',
 };
 const COMMAND_SPECS = {
     init: {
-        slug: { type: 'string' },
-        dir: { type: 'string' },
-        force: { type: 'boolean' },
-        yes: { type: 'boolean' },
+        slug: {
+            type: 'string',
+            description: 'Kebab-case id of the integration, e.g. acme-crm',
+        },
+        dir: {
+            type: 'string',
+            description: 'Target directory (default ./<slug>; --dir . scaffolds in place)',
+        },
+        force: {
+            type: 'boolean',
+            description: 'Overwrite files that already exist',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'Accepted for scripts; init never prompts',
+        },
         // Repeatable: each occurrence appends one docs entry (URL or relative
         // path) to the scaffolded ekanos.json.
-        docs: { type: 'string', repeatable: true },
+        docs: {
+            type: 'string',
+            repeatable: true,
+            description: "An http(s) URL or project-relative path to the API's docs, written to ekanos.json",
+        },
     },
     validate: {
-        dir: { type: 'string' },
+        dir: DIR,
     },
     dev: {
-        dir: { type: 'string' },
-        port: { type: 'string' },
-        host: { type: 'string' },
-        force: { type: 'boolean' },
-        start: { type: 'boolean' },
+        dir: DIR,
+        port: { type: 'string', description: 'Dev server port (default 3100)' },
+        host: {
+            type: 'string',
+            description: 'Interface to bind (default 127.0.0.1; anything else is exposed, with a warning)',
+        },
+        force: {
+            type: 'boolean',
+            description: 'Rewrite every generated file even when unchanged',
+        },
+        start: {
+            type: 'boolean',
+            description: 'Start the server even in JSON mode; --no-start only scaffolds',
+        },
     },
     test: {
-        dir: { type: 'string' },
+        dir: DIR,
         // Skips the vitest JSON-reporter injection and the curated failures
         // appendix, reproducing the pre-appendix raw-passthrough behavior —
         // also the escape hatch if the vitest-detection heuristic ever guesses
         // wrong for a project. See `test-report.ts`.
-        raw: { type: 'boolean' },
+        raw: {
+            type: 'boolean',
+            description: 'Run the test script as is, without the failures appendix and its reporter',
+        },
     },
     login: {
-        host: { type: 'string' },
-        force: { type: 'boolean' },
-        claude: { type: 'boolean' },
+        host: {
+            type: 'string',
+            description: 'Ekanos host URL (else EKANOS_HOST, or the only stored login; never ekanos.json)',
+        },
+        force: {
+            type: 'boolean',
+            description: 'Sign in again even when the stored session is valid',
+        },
+        'trust-host': {
+            type: 'boolean',
+            description: 'Sign in to a host you have never logged in to without being asked',
+        },
+        claude: {
+            type: 'boolean',
+            description: 'Add the Ekanos docs to Claude Code without asking; --no-claude skips it',
+        },
     },
     logout: {
-        host: { type: 'string' },
-        all: { type: 'boolean' },
+        host: HOST,
+        all: { type: 'boolean', description: 'Log out of every stored host' },
     },
     whoami: {
-        host: { type: 'string' },
+        host: HOST,
     },
     status: {
-        host: { type: 'string' },
-        dir: { type: 'string' },
-        findings: { type: 'boolean' },
-        all: { type: 'boolean' },
-        watch: { type: 'boolean' },
+        host: HOST,
+        dir: DIR,
+        findings: {
+            type: 'boolean',
+            description: 'Every finding of each version, not just the counts',
+        },
+        all: {
+            type: 'boolean',
+            description: "Expand the Source's other integrations into full version tables",
+        },
+        watch: {
+            type: 'boolean',
+            description: "Wait until this project's current version reaches a gate verdict",
+        },
     },
     sources: {
-        host: { type: 'string' },
-        dir: { type: 'string' },
+        host: HOST,
+        dir: DIR,
+        // `sources products [enable|disable <product>]`.
+        source: SOURCE,
+        yes: {
+            type: 'boolean',
+            description: 'Confirm products disable, scopes remove',
+        },
     },
     catalog: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
     },
     apps: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        'no-wait': { type: 'boolean' },
+        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)',
+        },
     },
     teams: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        connection: { type: 'string' },
-        slug: { type: 'string' },
-        owner: { type: 'string' },
-        role: { type: 'string' },
-        yes: { type: 'boolean' },
+        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: {
+            type: 'string',
+            repeatable: true,
+            description: 'app set: <name>=<value> for a non-secret field',
+        },
+        clear: {
+            type: 'string',
+            repeatable: true,
+            description: "app set: remove this field's saved value",
+        },
+        slug: {
+            type: 'string',
+            description: "create: the team's slug (default: from its name)",
+        },
+        owner: {
+            type: 'string',
+            description: 'create: invite this email as the owner instead of you',
+        },
+        role: {
+            type: 'string',
+            description: 'members invite: the role to invite as (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)',
+        },
         // `teams agents|triggers|links|mcp` (team-agents.ts).
-        as: { type: 'string' },
-        reads: { type: 'string' },
-        writes: { type: 'string' },
-        effect: { type: 'string' },
-        kind: { type: 'string' },
-        mode: { type: 'string' },
-        url: { type: 'string' },
-        auth: { type: 'string' },
-        name: { type: 'string' },
-        cron: { type: 'string' },
-        timezone: { type: 'string' },
-        prompt: { type: 'string' },
-        filter: { type: 'string' },
+        as: {
+            type: 'string',
+            description: 'connect: the member who signs in; agents enable: the member the agent runs as',
+        },
+        // `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, that the
+        // agent may use your connections.
+        'confirm-access': {
+            type: 'boolean',
+            description: 'agents enable|policy: also confirm, as yourself, that it may use your connections',
+        },
+        reads: {
+            type: 'string',
+            description: 'agents policy: auto|approve for every read tool',
+        },
+        writes: {
+            type: 'string',
+            description: 'agents policy: auto|approve for every write tool',
+        },
+        effect: {
+            type: 'string',
+            description: 'Not read: "teams mcp effect" takes the effect as an argument',
+        },
+        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: {
+            type: 'string',
+            description: 'mcp add: none|token|oauth (default oauth)',
+        },
+        name: { type: 'string', description: "mcp add: the server's display name" },
+        cron: {
+            type: 'string',
+            description: 'triggers add schedule: a cron expression',
+        },
+        timezone: {
+            type: 'string',
+            description: 'triggers add schedule: an IANA time zone (default UTC)',
+        },
+        prompt: {
+            type: 'string',
+            description: 'triggers add: 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',
+        },
+        // `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: {
+            type: 'boolean',
+            description: 'triggers add slack: also answer direct messages',
+        },
+        label: {
+            type: 'string',
+            repeatable: true,
+            description: 'triggers add linear: a label that hands an issue to it',
+        },
+        mention: {
+            type: 'boolean',
+            description: 'triggers add linear: --no-mention ignores @mentions',
+        },
+        // `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: {
+            type: 'boolean',
+            description: 'connect: --no-open prints the link without opening a browser',
+        },
+        '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: {
+            type: 'string',
+            description: 'events: since 30m, 24h, 7d or a date',
+        },
+        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: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        reach: { type: 'string' },
-        team: { type: 'string' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        reach: {
+            type: 'string',
+            description: "add: source (every team's drafts) or team (one team's)",
+        },
+        team: {
+            type: 'string',
+            description: "add --reach team, remove: the team's slug",
+        },
+        yes: { type: 'boolean', description: 'remove: confirm' },
     },
     routes: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        label: { type: 'string' },
-        webhook: { type: 'string' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        label: { type: 'string', description: 'set: a name for the value' },
+        webhook: {
+            type: 'string',
+            description: 'webhook: which webhook, when the integration has several',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'remove: confirm; webhook: replace the live URL, revoking it',
+        },
     },
     agents: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
         // Not `--version`: that is global, and prints the CLI's own version.
-        to: { type: 'string' },
-        'base-version': { type: 'string' },
-        overwrite: { type: 'boolean' },
-        out: { type: 'string' },
-        yes: { type: 'boolean' },
-        force: { type: 'boolean' },
-        claude: { type: 'boolean' },
+        to: {
+            type: 'string',
+            description: 'publish, rollback: the version teams run',
+        },
+        'base-version': {
+            type: 'string',
+            description: 'apply: the version your edit starts from (refused when the host has moved on)',
+        },
+        overwrite: {
+            type: 'boolean',
+            description: 'apply: replace a newer version on the host anyway',
+        },
+        out: {
+            type: 'string',
+            description: 'pull: where to write the template (default agents/<key>)',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'publish, rollback, archive, --publish: confirm (needed in a script or agent run)',
+        },
+        all: {
+            type: 'boolean',
+            description: 'list: include archived agents',
+        },
+        force: {
+            type: 'boolean',
+            description: 'init: replace the skills and CLAUDE.md that exist; pull: overwrite local files that differ',
+        },
+        claude: {
+            type: 'boolean',
+            description: 'init: add the docs to Claude Code without asking; --no-claude skips it',
+        },
         // `agents test <key> --team <slug> --prompt|--input [--follow]`.
-        team: { type: 'string' },
-        prompt: { type: 'string' },
-        input: { type: 'string' },
-        follow: { type: 'boolean' },
+        team: { type: 'string', description: 'test: the team to run the draft on' },
+        prompt: {
+            type: 'string',
+            description: 'test: the message; triggers add: what the agent is told',
+        },
+        input: { type: 'string', description: 'test: a JSON file to run with' },
+        follow: {
+            type: 'boolean',
+            description: 'test: wait for the run and print its result',
+        },
         // `apply`: `--no-skills` skips pushing the skill folders beside the agent.
-        skills: { type: 'boolean' },
+        skills: {
+            type: 'boolean',
+            description: 'apply: --no-skills skips pushing <dir>/skills/<slug>/',
+        },
         // policy | triggers | links | overrides
-        event: { type: 'string' },
-        filter: { type: 'string', repeatable: true },
-        disabled: { type: 'boolean' },
-        cron: { type: 'string' },
-        timezone: { type: 'string' },
-        kind: { type: 'string' },
-        mode: { type: 'string' },
-        reads: { type: 'string' },
-        writes: { type: 'string' },
-        publish: { type: 'boolean' },
+        event: {
+            type: 'string',
+            description: 'triggers add event: <product>.<event>',
+        },
+        filter: {
+            type: 'string',
+            repeatable: true,
+            description: 'triggers add event: field=a,b (repeat for more fields)',
+        },
+        disabled: {
+            type: 'boolean',
+            description: 'triggers add: store the trigger turned off',
+        },
+        cron: {
+            type: 'string',
+            description: 'triggers add schedule: a cron expression',
+        },
+        timezone: {
+            type: 'string',
+            description: 'triggers add schedule: an IANA time zone',
+        },
+        kind: { type: 'string', description: 'links: talk|delegate' },
+        mode: {
+            type: 'string',
+            description: 'links add: await|handoff, for a delegate link',
+        },
+        reads: {
+            type: 'string',
+            description: 'policy: auto|approve for every read tool',
+        },
+        writes: {
+            type: 'string',
+            description: 'policy: auto|approve for every write tool',
+        },
+        publish: {
+            type: 'boolean',
+            description: 'policy, triggers, links, overrides: publish the new version too (with --yes)',
+        },
+        // `publish | rollback` (and `--publish`): also confirm, as yourself, on
+        // every team where the agent runs as you.
+        'confirm-access': {
+            type: 'boolean',
+            description: 'publish, rollback, --publish: also confirm, as yourself, on every team where it runs as you',
+        },
     },
     skills: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        team: { type: 'string' },
-        out: { type: 'string' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        team: {
+            type: 'string',
+            description: "That team's own skills instead of the Source's",
+        },
+        out: {
+            type: 'string',
+            description: 'pull: where to write the skill folder',
+        },
+        force: {
+            type: 'boolean',
+            description: 'pull: overwrite local files that differ from the host',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'archive: confirm (needed in a script or agent run)',
+        },
+    },
+    knowledge: {
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        team: {
+            type: 'string',
+            description: "That team's collection instead of General",
+        },
+        out: { type: 'string', description: 'pull: where to write the articles' },
+        force: {
+            type: 'boolean',
+            description: 'pull: overwrite local files that differ from the host',
+        },
+        prune: {
+            type: 'boolean',
+            description: 'push: also delete the articles an earlier push of this folder made whose files are gone (never ones written or edited in the app)',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'push --prune: delete without asking (needed in a script or agent run)',
+        },
     },
     runs: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        team: { type: 'string' },
-        agent: { type: 'string' },
-        prompt: { type: 'string' },
-        input: { type: 'string' },
-        follow: { type: 'boolean' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        team: { type: 'string', description: 'The team whose runs these are' },
+        agent: { type: 'string', description: "list: only this agent's runs" },
+        status: {
+            type: 'string',
+            description: 'list: only runs in this status (running, awaiting_approval, completed, failed, cancelled)',
+        },
+        since: {
+            type: 'string',
+            description: 'list: only runs started since 30m, 24h, 7d or a date',
+        },
+        prompt: { type: 'string', description: 'start: the message' },
+        input: { type: 'string', description: 'start: a JSON file to run with' },
+        follow: {
+            type: 'boolean',
+            description: 'start: wait for the run and print its result',
+        },
+        // `runs cancel <run-id> --yes`.
+        yes: { type: 'boolean', description: 'cancel: confirm' },
     },
     approvals: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        team: { type: 'string' },
-        reason: { type: 'string' },
-        body: { type: 'string' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        team: { type: 'string', description: 'The team whose runs wait on these' },
+        reason: { type: 'string', description: 'approve, reject: why' },
+        body: {
+            type: 'string',
+            description: 'edit: a file with the reply to send instead',
+        },
     },
     use: {
-        host: { type: 'string' },
-        dir: { type: 'string' },
+        host: HOST,
+        dir: DIR,
     },
     publish: {
-        host: { type: 'string' },
-        source: { type: 'string' },
-        dir: { type: 'string' },
-        yes: { type: 'boolean' },
+        host: HOST,
+        source: SOURCE,
+        dir: DIR,
+        yes: {
+            type: 'boolean',
+            description: 'Publish to the ekanos.json source without asking (needed in a script with several seats)',
+        },
     },
     upgrade: {
-        dir: { type: 'string' },
-        host: { type: 'string' },
-        check: { type: 'boolean' },
-        yes: { type: 'boolean' },
+        dir: DIR,
+        host: HOST,
+        check: {
+            type: 'boolean',
+            description: 'Report current and target versions; change nothing',
+        },
+        yes: {
+            type: 'boolean',
+            description: 'Upgrade without asking (needed outside a terminal)',
+        },
         // `--no-verify` is the negation of this — parse-argv's `--no-<bool>`
         // convention (same as `--no-json`/`--no-start`), not a flag of its own.
-        verify: { type: 'boolean' },
+        verify: {
+            type: 'boolean',
+            description: '--no-verify skips the validate and test run after installing',
+        },
     },
 };
 /** Commands that take positional arguments, and what each means, in order. Every other command is positional-free. */
 const POSITIONAL_COMMANDS = {
     use: ['source-slug'],
+    // `sources scopes add <scope> <product>` is the longest form.
+    sources: ['subcommand', 'verb', 'product-or-scope', 'product-slug'],
     catalog: ['product-slug'],
     apps: ['subcommand', 'product-slug'],
     // `teams agents policy <team> <key> set <tool> auto` is the longest form.
@@ -225,6 +594,7 @@ const POSITIONAL_COMMANDS = {
     reviewers: ['subcommand', 'email'],
     routes: ['subcommand', 'product-or-event-id', 'value', 'team-slug'],
     skills: ['subcommand', 'slug-or-path'],
+    knowledge: ['subcommand', 'path-or-query'],
     runs: ['subcommand', 'agent-key-or-run-id'],
     approvals: ['subcommand', 'approval-id'],
     // `triggers <key> add event <trigger-key>` is the longest form: five tokens.
@@ -243,7 +613,8 @@ const USAGE = [
     '             appendix from a JSON reporter report; --raw skips that and',
     '             the reporter injection entirely.',
     '  login      Authenticate against an Ekanos host in a browser (--host <url>;',
-    '             offers to add the Ekanos docs to Claude Code: --claude|--no-claude)',
+    '             offers to add the Ekanos docs to Claude Code: --claude|--no-claude;',
+    '             a host you have never used asks first, or needs --trust-host)',
     '  logout     Revoke and delete the stored session (--host <url> | --all)',
     '  whoami     Print the identity the stored session authenticates as, plus',
     '             a compact list of the sources you hold a seat on',
@@ -251,53 +622,120 @@ const USAGE = [
     '             (--findings for full gate findings, --all to expand other',
     '             integrations in the source, --watch to block until this',
     "             project's current version reaches a gate verdict)",
-    '  sources    List every source you hold a developer/source-admin seat on',
+    '  sources    List every source you hold a developer/source-admin seat on |',
+    '             products [--source <slug>] (each product, Experience or',
+    '             Integration, and whether it is enabled for the Source) |',
+    '             products enable <product> | products disable <product> --yes',
+    '             (a super-admin grant: an "ekanos login" session is refused',
+    '             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',
     '             ("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) | connect <product> [--no-wait] (one',
+    '             at your terminal, Enter keeps a saved value) | connect',
+    '             <product> [--no-wait] (one',
     "             connection for the whole Source, used by the Source's provided",
-    '             agents in every team) | disconnect <product> | list',
+    '             agents in every team) | disconnect <product> [--yes] (a',
+    '             script or agent run needs --yes) | list',
     "  teams      A Source's teams, for the Source admin:",
     '             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 role <team> <email> <role> | members remove <team>',
     "             <email> --yes | roles list <team> (each role's permissions) |",
-    '             connect <team> <product> (the link a member opens to sign in',
-    '             an integration, and whether it is connected) |',
-    '             list | show <team> <product> (a checklist: fields, callback',
+    '             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;',
+    "             --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",
+    '             it again when it reads as connected but is broken: a revoked or',
+    '             expired sign-in) |',
+    '             connect <team> slack|linear-app [--as <member-email>] (installs',
+    '             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) |",
+    '             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>] (takes the secrets at your terminal) |',
-    '             webhook <team> <product> [<webhook-id>] [--yes] (URL shown once)',
+    '             [--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) |',
+    '             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',
+    '             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 enable <team> <key> [--as <member-email>]',
-    '             | agents disable|unpin <team> <key> | agents pin <team> <key> <version>',
+    '             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 enable <team> <key> [--as <member-email>]',
+    '             [--draft] [--confirm-access] (--confirm-access: runs as you and',
+    '             confirms it may use your connections) | agents confirm <team> <key>',
+    '             (you, the person it runs as, confirm it may use your connections;',
+    '             nobody else can; on an agent held on an earlier version it moves',
+    '             it to the version waiting) | agents disable <team> <key> --yes | 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',
+    '             following)',
     '             | agents policy <team> <key> [set <tool> auto|approve | unset <tool>]',
-    '             [--reads auto|approve] [--writes auto|approve]',
-    '             triggers list|add|remove <team> <key> … | links list|add|remove',
+    '             [--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>',
+    "             [--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',
     '             <team> <from-key> [<to-key> --kind talk|delegate --mode await|handoff]',
-    '             | mcp list|add|status|token|effect <team> [<server-key> …]',
-    '             (see "ekanos teams --help")',
+    '             (remove <link-id|to-key> [--kind <kind>] --yes)',
+    '             | mcp list|add|status|token|effect|remove <team> [<server-key> …]',
+    '             (remove needs --yes)',
+    '             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:',
     '             list | add <email> --reach source|team [--team <slug>] |',
-    '             remove <email> [--team <slug>]',
+    '             remove <email> [--team <slug>] --yes',
     "  routes     Route a Source connection's events to teams, for the Source admin:",
     '             list [<product>] | options <product> | set <product> <value> <team>',
-    '             [--label <name>] | remove <product> <value> | webhook <product>',
-    '             [--webhook <id>] (URL shown once) | unrouted [<product>] |',
+    '             [--label <name>] | remove <product> <value> --yes | webhook',
+    '             <product> [--webhook <id>] [--yes] (URL saved to a 0600 file, never printed; --yes',
+    '             replaces a live one, revoking it) | unrouted [<product>] |',
     '             replay <event-id>',
     "  agents     The source's agent templates, held by Ekanos:",
     '             init [<dir>] [--claude|--no-claude] (skills + docs MCP for designing',
     '             agents with Claude; offers to add the docs to Claude Code)',
-    '             list | show <key> | pull <key> [--out <dir>]',
+    '             list [--all] (--all: archived agents too) | show <key> |',
+    '             pull <key> [--out <dir>] [--force] (--force: overwrite local',
+    '             files that differ; without it the pull refuses and writes nothing)',
     '             apply <dir|file> [--base-version <n>] [--overwrite]',
-    '             publish <key> [--to <n>] --yes | rollback <key> --to <n> --yes',
+    '             archive <key> --yes (refused while any team has it on; lists',
+    '             each team and the command to turn it off) | unarchive <key>',
+    '             publish <key> [--to <n>] [--confirm-access] --yes | rollback <key>',
+    '             --to <n> [--confirm-access] --yes (a team whose person confirmed less',
+    '             than the version reaches is held on its earlier version until they',
+    '             confirm; --confirm-access: you confirm, and move, every team where',
+    '             it runs as you; the output lists every other team held, and the command)',
     '             test <key> --team <slug> (--prompt "…" | --input <file.json>)',
     '             [--follow] (runs the latest, unpublished version on one team;',
-    '             same grant, policy, approvals and audit; marked as a test)',
+    '             same grant, policy, approvals and audit; marked as a test; to',
+    '             test a tool the draft adds, first "teams agents pin <team> <key>',
+    '             --draft", which also works before anything is published)',
     '             apply also pushes <dir>/skills/<slug>/ folders first and names',
     '             them in the agent (--no-skills skips that)',
     '             Edit one template in place (stores a draft version; --publish',
@@ -305,7 +743,8 @@ const USAGE = [
     '             policy <key> [set <tool> auto|approve | unset <tool>]',
     '               [--reads auto|approve] [--writes auto|approve]',
     '             triggers <key> [list | add event <k> --event <slug.event>',
-    '               [--filter field=a,b]... | add schedule <k> --cron "<expr>"',
+    "               [--filter field=a,b]... (or one --filter '<json>') | add",
+    '               schedule <k> --cron "<expr>"',
     '               [--timezone <tz>] --prompt <text> | add webhook <k> --prompt',
     '               <text> | remove <k>] [--prompt <text>] [--disabled]',
     '             links <key> [list | add <to-key> --kind talk|delegate',
@@ -318,11 +757,29 @@ const USAGE = [
     '             push <dir> [--team <t>] (a new version, live at once; created',
     '             on first push, "unchanged" when identical; --team: that team\'s',
     '             own skill, no other team sees it) | pull <slug> [--out <dir>]',
+    '             [--force] (refuses to overwrite a local file that differs)',
+    '             | archive <slug> [--team <t>] --yes (refused while an agent',
+    '             names it or a team agent has it attached; lists each and the',
+    '             command that stops it) | unarchive <slug> [--team <t>]',
+    "  knowledge  The Source's Knowledge base (markdown articles), for the Source admin:",
+    '             list [--team <t>] | push <dir> [--team <t>] (each .md file an',
+    '             article: title from frontmatter or the first heading, tags from',
+    '             frontmatter; upserts by path, "unchanged" when identical;',
+    '             --prune [--yes] also deletes the articles an earlier push of',
+    '             this folder made whose files are gone, never ones written or',
+    '             edited in the app) |',
+    "             search <query> --team <t> (as that team's agents search: its",
+    '             articles plus General) | pull [--team <t>] [--out <dir>]',
+    '             [--force] (refuses to overwrite a local file that differs)',
+    "             Without --team: General, which every team's agents granted",
+    '             search_knowledge read.',
     "  runs       Run and inspect a team's agents, as the Source admin:",
     '             start <agent-key> --team <slug> (--prompt "…" | --input',
-    '             <file.json>) [--follow] | list --team <slug> [--agent <key>] |',
+    '             <file.json>) [--follow] | list --team <slug> [--agent <key>]',
+    '             [--status <status>] [--since 24h|7d|<date>] |',
     '             show <run-id> --team <slug> (--json: transcript, tool calls,',
-    '             how each was authorized, approvals)',
+    '             how each was authorized, approvals) | cancel <run-id> --team',
+    '             <slug> [--yes] (stops a live run; asks first, --yes in a script)',
     "  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)',
@@ -340,12 +797,15 @@ 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, runs, approvals, use, publish, upgrade):',
+    'Host resolution (logout, whoami, status, sources, catalog, apps, teams, reviewers, routes, agents, skills, knowledge, runs, approvals, 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',
     '  EKANOS_HOST, else the sole stored login) — it is the verb that creates',
-    '  credentials, so a committed file must never choose where they go.',
+    '  credentials, so a committed file must never choose where they go. A',
+    '  host you have never logged in to is shown with its sign-in domain and',
+    '  asked about first (--trust-host when nobody can be asked). A remote',
+    '  http:// host is refused by every verb that sends credentials.',
     '',
     'Publish targeting (see "ekanos sources" / "ekanos use"):',
     '  publish refuses (FORBIDDEN) a source you hold no seat on. With multiple',
@@ -457,6 +917,8 @@ export async function run(argv, options = {}) {
                     host: parsed.flags.host,
                     force: parsed.flags.force === true,
                     claude: parsed.flags.claude,
+                    trustHost: parsed.flags['trust-host'] === true,
+                    confirmHost: options.confirm,
                     cwd,
                     env,
                     stdinIsTTY: options.stdinIsTTY,
@@ -488,6 +950,9 @@ export async function run(argv, options = {}) {
             case 'sources':
                 return await runSources(ctx, {
                     host: parsed.flags.host,
+                    positionals: parsed.positionals,
+                    source: parsed.flags.source,
+                    yes: parsed.flags.yes === true,
                     dir,
                     env,
                 });
@@ -512,6 +977,7 @@ export async function run(argv, options = {}) {
                     askSecret: options.askSecret,
                     confirm: options.confirm,
                     noWait: parsed.flags['no-wait'] === true,
+                    yes: parsed.flags.yes === true,
                 });
             case 'teams':
                 return await runTeams(ctx, {
@@ -523,12 +989,18 @@ export async function run(argv, options = {}) {
                     owner: parsed.flags.owner,
                     role: parsed.flags.role,
                     yes: parsed.flags.yes === true,
+                    noWait: parsed.flags['no-wait'] === true,
+                    noOpen: parsed.flags.open === false,
+                    linkOnly: parsed.flags['link-only'] === true,
+                    reconnect: parsed.flags.reconnect === true,
                     flags: parsed.flags,
                     dir,
                     env,
                     stdinIsTTY: options.stdinIsTTY,
                     ask: options.ask,
                     askSecret: options.askSecret,
+                    openUrl: options.openUrl,
+                    pollDelayMs: options.pollDelayMs,
                 });
             case 'reviewers':
                 return await runReviewers(ctx, {
@@ -537,6 +1009,7 @@ export async function run(argv, options = {}) {
                     positionals: parsed.positionals,
                     reach: parsed.flags.reach,
                     team: parsed.flags.team,
+                    yes: parsed.flags.yes === true,
                     dir,
                     env,
                 });
@@ -547,6 +1020,7 @@ export async function run(argv, options = {}) {
                     positionals: parsed.positionals,
                     label: parsed.flags.label,
                     webhook: parsed.flags.webhook,
+                    yes: parsed.flags.yes === true,
                     dir,
                     env,
                 });
@@ -561,6 +1035,7 @@ export async function run(argv, options = {}) {
                     overwrite: parsed.flags.overwrite === true,
                     out: parsed.flags.out,
                     yes: parsed.flags.yes === true,
+                    all: parsed.flags.all === true,
                     force: parsed.flags.force === true,
                     claude: parsed.flags.claude,
                     skills: parsed.flags.skills,
@@ -575,6 +1050,7 @@ export async function run(argv, options = {}) {
                     reads: parsed.flags.reads,
                     writes: parsed.flags.writes,
                     publish: parsed.flags.publish === true,
+                    confirmAccess: parsed.flags['confirm-access'] === true,
                     dir,
                     env,
                     stdinIsTTY: options.stdinIsTTY,
@@ -592,14 +1068,19 @@ export async function run(argv, options = {}) {
                     positionals: parsed.positionals,
                     team: parsed.flags.team,
                     agent: parsed.flags.agent,
+                    status: parsed.flags.status,
+                    since: parsed.flags.since,
                     prompt: parsed.flags.prompt,
                     input: parsed.flags.input,
                     follow: parsed.flags.follow === true,
                     reason: parsed.flags.reason,
                     body: parsed.flags.body,
+                    yes: parsed.flags.yes === true,
                     dir,
                     env,
                     sleep: options.sleep,
+                    stdinIsTTY: options.stdinIsTTY,
+                    confirm: options.confirm,
                 });
             case 'skills':
                 return await runSkills(ctx, {
@@ -609,8 +1090,28 @@ export async function run(argv, options = {}) {
                     target: parsed.positionals[1],
                     team: parsed.flags.team,
                     out: parsed.flags.out,
+                    force: parsed.flags.force === true,
+                    yes: parsed.flags.yes === true,
+                    dir,
+                    env,
+                    stdinIsTTY: options.stdinIsTTY,
+                    confirm: options.confirm,
+                });
+            case 'knowledge':
+                return await runKnowledge(ctx, {
+                    host: parsed.flags.host,
+                    source: parsed.flags.source,
+                    subcommand: parsed.positionals[0],
+                    target: parsed.positionals[1],
+                    team: parsed.flags.team,
+                    out: parsed.flags.out,
+                    force: parsed.flags.force === true,
+                    prune: parsed.flags.prune === true,
+                    yes: parsed.flags.yes === true,
                     dir,
                     env,
+                    stdinIsTTY: options.stdinIsTTY,
+                    confirm: options.confirm,
                 });
             case 'use':
                 return await runUse(ctx, {
@@ -729,12 +1230,83 @@ function emitHelp(ctx) {
     });
     return ctx.succeed({ usage: USAGE, commands: COMMANDS, docs: SDK_DOCS_URL }, `${USAGE}${DOCS_FOOTER}`);
 }
+/** The per-area usage a command's own parser already gives, shown in its help too. */
+const COMMAND_DETAILS = {
+    teams: () => TEAM_AGENT_AREAS.map(usageFor),
+    agents: () => Object.entries(TEMPLATE_EDIT_HELP).map(([area, examples]) => `${area}: ${examples}`),
+};
+/** A command's block of the top-level usage: its line and the indented ones under it. */
+function commandUsage(command) {
+    const lines = USAGE.split('\n');
+    const start = lines.findIndex((line) => line.startsWith(`  ${command} `));
+    if (start === -1)
+        return '';
+    const end = lines.findIndex((line, index) => index > start && !line.startsWith('             '));
+    return lines.slice(start, end === -1 ? undefined : end).join('\n');
+}
+function optionLabel(name, spec) {
+    if (spec.type === 'boolean')
+        return `--${name}`;
+    return `--${name} <value>${spec.repeatable ? '…' : ''}`;
+}
+/**
+ * `ekanos <command> --help`: the command's block of the usage (its
+ * subcommands, each described), the per-area usage its parser gives, and
+ * every flag with its description. The JSON envelope carries the same, so an
+ * agent reading it is not left with flag names only.
+ */
 function emitCommandHelp(ctx, command) {
     var _a;
-    const specs = (_a = COMMAND_SPECS[command]) !== null && _a !== void 0 ? _a : {};
+    var _b, _c, _d;
+    const specs = (_b = COMMAND_SPECS[command]) !== null && _b !== void 0 ? _b : {};
     const flags = Object.keys(specs).map((name) => `--${name}`);
-    const help = `Usage: ekanos ${command} [${flags.join('] [')}]`;
-    ctx.emitClaudeCodeHint({ tool: 'ekanos', command, flags });
-    return ctx.succeed({ command, flags }, help);
+    const usage = commandUsage(command);
+    const details = (_c = (_a = COMMAND_DETAILS[command]) === null || _a === void 0 ? void 0 : _a.call(COMMAND_DETAILS)) !== null && _c !== void 0 ? _c : [];
+    const options = [
+        ...Object.entries(specs),
+        ...Object.entries(GLOBAL_SPECS),
+    ].map(([name, spec]) => { var _a; return ({
+        flag: `--${name}`,
+        label: optionLabel(name, spec),
+        takesValue: spec.type === 'string',
+        repeatable: spec.repeatable === true,
+        description: (_a = spec.description) !== null && _a !== void 0 ? _a : '',
+    }); });
+    const positionals = (_d = POSITIONAL_COMMANDS[command]) !== null && _d !== void 0 ? _d : [];
+    const synopsis = [
+        `ekanos ${command}`,
+        positionals.length === 0
+            ? ''
+            : positionals.length === 1
+                ? ` <${positionals[0]}>`
+                : ` <${positionals[0]}> …`,
+        ' [options]',
+    ].join('');
+    const docs = docsPage('cli/commands', command);
+    const width = Math.min(26, Math.max(...options.map((option) => option.label.length)));
+    const human = [
+        `Usage: ${synopsis}`,
+        ...(usage ? ['', usage] : []),
+        ...(details.length > 0 ? ['', ...details] : []),
+        '',
+        'Options:',
+        ...options.map((option) => option.label.length > width
+            ? `  ${option.label}\n  ${' '.repeat(width)}  ${option.description}`
+            : `  ${option.label.padEnd(width)}  ${option.description}`),
+        '',
+        `Docs: ${docs}`,
+    ].join('\n');
+    ctx.emitClaudeCodeHint({ tool: 'ekanos', command, flags, usage });
+    return ctx.succeed({
+        command,
+        flags,
+        usage,
+        details,
+        options: options.map((_a) => {
+            var { label: _label } = _a, option = __rest(_a, ["label"]);
+            return option;
+        }),
+        docs,
+    }, human);
 }
 //# sourceMappingURL=index.js.map