@fastagent-sh/fastagent 0.29.0 → 0.30.0

package/dist/cli/program.js

@@ -7,6 +7,7 @@ import { buildProgram } from "./kernel.js";
 import { DEPLOY_HOSTS } from "../deploy/hosts.js";
 import { unsupportedRuntime } from "../runtime.js";
 import { failStartup } from "./fail.js";
+import { CONFIG_FLAG, CONTENT_FLAGS, ENV_FILE_FLAG, INSTANCE_FLAGS, instanceFlags } from "./instance.js";
 // Help groups (clig: most common commands first) — the authoring loop leads, operations close.
 const AGENT_ARG = {
     name: "[agent]",
@@ -44,7 +45,7 @@ const init = {
         {
             flags: "--content <source>",
             description: "a directory or github:owner/repo the agent works on (repeatable): a repository in context.json, a " +
-                "directory of this machine in context.local.json",
+                "directory of this machine in fastagent.json",
             repeatable: true,
         },
         { flags: "--no-install", description: "scaffold everything but skip npm install" },
@@ -70,7 +71,17 @@ const dev = {
         "(src/, fastagent.config.ts, package.json, .secrets/.env) restart the worker once its running messages finish. " +
         "Files the agent writes as work product never trigger a restart.",
     args: [AGENT_ARG],
-    flags: [PORT, BIND, MODEL, { flags: "--no-watch", description: "serve once, no file-watching" }, TUNNEL, NO_INPUT],
+    flags: [
+        PORT,
+        BIND,
+        MODEL,
+        { flags: "--no-watch", description: "serve once, no file-watching" },
+        TUNNEL,
+        NO_INPUT,
+        ...INSTANCE_FLAGS,
+        CONFIG_FLAG,
+        ENV_FILE_FLAG,
+    ],
     examples: [
         { cmd: "fastagent dev" },
         { cmd: "fastagent dev --tunnel", note: "public URL + registered/guided webhooks" },
@@ -82,6 +93,7 @@ const dev = {
         watch: f.watch !== false,
         tunnel: f.tunnel === true,
         input: f.input !== false,
+        instance: instanceFlags(f),
     }),
 };
 const info = {
@@ -91,11 +103,27 @@ const info = {
         "secrets, content — WITHOUT opening or serving it. An unset model or secret is reported, not fatal. " +
         "Run it first when something looks off.",
     args: [AGENT_ARG],
-    flags: [JSON_FLAG, MODEL],
+    flags: [JSON_FLAG, MODEL, ...INSTANCE_FLAGS, CONFIG_FLAG, ENV_FILE_FLAG],
     examples: [{ cmd: "fastagent info" }, { cmd: "fastagent info --json", note: "for CI" }],
     run: async (args, f) => (await import("./commands/info.js")).runInfo(args[0], {
         json: f.json === true,
         model: f.model,
+        instance: instanceFlags(f),
+    }),
+};
+const build = {
+    name: "build",
+    summary: "compile the agent into dist/, the package an app or a host opens",
+    description: "Compile the agent (default .) into dist/: its code with the project's TypeScript (type-checked, per file), its " +
+        "text, skills, prompts, assets and the resources beside its code, and a generated entry (index.js) whose default " +
+        "export is the definition. It refuses what dev refuses, and a type error. dist/ is replaced whole; it holds no " +
+        "secret, state or clone.",
+    args: [AGENT_ARG],
+    flags: [{ flags: "--no-check", description: "emit without type-checking (tsc --noCheck)" }, JSON_FLAG],
+    examples: [{ cmd: "fastagent build" }, { cmd: "fastagent build --json", note: "for CI" }],
+    run: async (args, f) => (await import("./commands/build.js")).runBuild(args[0], {
+        check: f.check !== false,
+        json: f.json === true,
     }),
 };
 const invoke = {
@@ -118,6 +146,9 @@ const invoke = {
         { flags: "--session <id>", description: "continue the session an earlier invoke printed" },
         { flags: "--url <base>", description: "send to the agent served at <base>, over its Agent API" },
         { flags: "--key <key>", description: "the API key for --url (default: the agent's production one)" },
+        ...INSTANCE_FLAGS,
+        CONFIG_FLAG,
+        ENV_FILE_FLAG,
     ],
     examples: [
         { cmd: `fastagent invoke "summarize today's inbox"` },
@@ -132,6 +163,7 @@ const invoke = {
         ...(typeof f.session === "string" ? { session: f.session } : {}),
         ...(typeof f.url === "string" ? { url: f.url } : {}),
         ...(typeof f.key === "string" ? { key: f.key } : {}),
+        instance: instanceFlags(f),
     }),
 };
 const models = {
@@ -139,7 +171,7 @@ const models = {
     summary: 'list the available "provider/modelId" model specs',
     description: 'List every "provider/modelId" spec the agent in this directory can name (pi-ai\'s built-ins, with the models ' +
         "pi's published catalog adds to them, and the providers its fastagent.config.ts declares) — use one with " +
-        "--model or as `model` in fastagent.config.ts. Outside an agent, or with -g, list the built-ins without the " +
+        "--model or as `defaults.model` in fastagent.config.ts. Outside an agent, or with -g, list the built-ins without the " +
         "agent's providers. Every command that opens the agent refreshes the lists, asking at most every 4 hours once " +
         "one is kept; --refresh asks now, and exits 1 when it cannot.",
     args: [{ name: "[search]", description: "case-insensitive substring filter" }],
@@ -161,24 +193,40 @@ const models = {
 };
 const start = {
     name: "start",
-    summary: "run the agent in production posture (opened as dev opens it, no watching)",
-    description: "Run the agent (default .) in production posture — opened as dev opens it (your directory " +
-        "is the agent), just no file-watching. model and http.port come from fastagent.config.ts.",
+    summary: "serve the built dist/ in production posture (no watching)",
+    description: "Serve the agent's dist/ (default .) in production posture, just no file-watching; refuses a " +
+        "missing or stale dist/, naming `fastagent build`. model and http.port come from " +
+        "defaults in fastagent.config.ts, over which --config's fastagent.json sets the instance's own.",
     args: [AGENT_ARG],
-    flags: [PORT, BIND, MODEL, TUNNEL, NO_INPUT],
+    flags: [
+        PORT,
+        BIND,
+        MODEL,
+        TUNNEL,
+        NO_INPUT,
+        ...INSTANCE_FLAGS,
+        {
+            ...CONFIG_FLAG,
+            description: "the instance configuration, a fastagent.json (FASTAGENT_CONFIG); start never reads the project's",
+        },
+        ENV_FILE_FLAG,
+    ],
     examples: [
-        { cmd: "fastagent start" },
+        { cmd: "fastagent start", note: "after fastagent build" },
         { cmd: "fastagent start --tunnel", note: "host a bot from your own box, no deploy" },
     ],
     notes: "Precedence chains:\n" +
         "  port:     --port > PORT env > fastagent.config.ts http.port > 8787\n" +
         "  bind:     --bind > all interfaces (dev: 127.0.0.1)\n" +
-        "  state:    FASTAGENT_STATE_DIR > <agent dir>/.state/production\n" +
+        "  state:    --state > FASTAGENT_STATE_DIR > <root>/.state >\n" +
+        "            <agent dir>/.state/production\n" +
         "            the agent's storage (agent.sqlite), channels, schedules; use a\n" +
         "            mounted volume so a redeploy never wipes it\n" +
-        "  secrets:  FASTAGENT_SECRETS_DIR > <agent dir>/.secrets/production\n" +
+        "  workdir:  --workdir > FASTAGENT_WORKDIR > --root > <agent dir>\n" +
+        "  config:   --config > FASTAGENT_CONFIG > none (never fastagent.json)\n" +
+        "  secrets:  --env-file > FASTAGENT_SECRETS_DIR > <agent dir>/.secrets/production\n" +
         "            .env + auth.json\n" +
-        "  content:  <agent dir>/content/<name> — a clone of github content; a\n" +
+        "  content:  <workdir>/content/<name> — a clone of github content; a\n" +
         "            deployment links content/ to its volume\n" +
         "  auth:     FASTAGENT_AUTH_PATH > <secrets>/auth.json\n" +
         "            (project-level; point it at ~/.fastagent/.secrets/auth.json to\n" +
@@ -189,86 +237,45 @@ const start = {
         model: f.model,
         tunnel: f.tunnel === true,
         input: f.input !== false,
+        instance: instanceFlags(f),
     }),
 };
-const INGRESS = {
-    flags: "--ingress <mode>",
-    description: "Feishu/Lark: set websocket or webhook in the selected environment; webhook also prepares its app now " +
-        "(unset: dev uses websocket, production uses webhook)",
-};
 const CHANNEL_ENVIRONMENT = {
     flags: "--env <environment>",
-    description: "select independent app credentials and onboarding state (default: dev; production uses .secrets/production/.env)",
-};
-const NO_ONBOARD = {
-    flags: "--no-onboard",
-    description: "scaffold only: write the channel file (if missing) and its tools, and skip the app onboarding " +
-        "(Slack: internal-app creation/OAuth; Feishu/Lark: app creation and credential capture)",
-};
-const REPLACE_CONFIG = {
-    flags: "--replace-config",
-    description: "Slack: replace the local App Configuration token pair (repairs automatic dev/deploy Request URL " +
-        "updates after the tokens expire or are revoked; runs on the machine that onboarded the app)",
+    description: "select independent credentials and state (default: dev; production uses .secrets/production/.env)",
 };
 const channelSub = (kind, summary, description, notes) => ({
     name: kind,
     summary,
     description,
     args: [AGENT_ARG],
-    flags: kind === "feishu" || kind === "lark"
-        ? [CHANNEL_ENVIRONMENT, INGRESS, NO_ONBOARD, ...UNATTENDED_SETUP]
-        : kind === "slack"
-            ? [CHANNEL_ENVIRONMENT, NO_ONBOARD, REPLACE_CONFIG, ...UNATTENDED_SETUP]
-            : [CHANNEL_ENVIRONMENT, JSON_FLAG],
-    examples: [
-        { cmd: `fastagent add ${kind}` },
-        ...(kind === "telegram" ? [] : [{ cmd: `fastagent add ${kind} --json`, note: "a coding agent" }]),
-    ],
+    flags: [JSON_FLAG],
+    examples: [{ cmd: `fastagent add ${kind}` }],
     ...(notes ? { notes } : {}),
-    run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], {
-        ingress: f.ingress,
-        environment: f.env,
-        onboard: f.onboard !== false,
-        replaceConfig: f.replaceConfig === true,
-        input: f.input !== false,
-        json: f.json === true,
-        ...(f.check !== undefined ? { check: f.check } : {}),
-        ...(f.timeout !== undefined ? { timeout: f.timeout } : {}),
-        ...(f.ticket !== undefined ? { ticket: f.ticket } : {}),
-    }),
+    run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], { json: f.json === true }),
 });
-/**
- * How an app's setup runs with no one at a terminal: what the person provides is named, and their steps come back with
- * a ticket to check (`add` in docs/cli.md).
- */
-const UNATTENDED_SETUP = [
-    { flags: "--json", description: "the outcome as one JSON object, with what to do next (agent_next_steps)" },
-    { flags: "--check <ticket>", description: "where a setup started without a terminal stands" },
-    { flags: "--timeout <seconds>", description: "how long that setup stays open (default 900)" },
-    { flags: "--ticket <id>", description: "the process that runs a ticket's setup", hidden: true },
-    NO_INPUT,
-];
 const add = {
     name: "add",
     summary: "connect a channel (telegram, slack, feishu, lark) or vendor a skill",
     description: "Scaffold channels/<kind>.ts — first-party adapter glue with the policy to edit in the optional " +
         "route() — or vendor an Agent Skills skill into skills/<name>/.",
     subcommands: [
-        channelSub("telegram", "scaffold the Telegram bot channel (durable turns, live preview)", "Scaffold src/channels/telegram.ts — the Telegram bot channel with durable turns, a live-preview " +
-            "message pump, and an optional route() policy."),
-        channelSub("slack", "scaffold the Slack Events API channel (files, threads, context, live preview)", "Scaffold src/channels/slack.ts plus its tools (src/tools/slack-send.ts, slack-threads.ts), create a single-workspace " +
-            "internal Slack app from a manifest, and install it through OAuth. The channel provides signed " +
-            "Events API ingress, durable turns, files, threads, context, and an edited live preview.", "Automated onboarding requires Slack App Configuration access + refresh tokens and a temporary " +
-            "cloudflared tunnel. They stay in owner-readable local state and are never deployed; --no-onboard " +
-            "keeps the explicit manual/scaffold-only path."),
-        channelSub("feishu", "scaffold the Feishu channel AND create/configure the platform app", "Scaffold src/channels/feishu.ts and create/configure the Feishu app through scan-to-create, writing its " +
-            "credentials to the selected environment. Dev uses WebSocket; deploy --run creates a separate production app for webhook.", "Feishu (open.feishu.cn) is the canonical implementation. WebSocket needs only App ID/Secret and " +
-            "no public URL; webhook additionally captures the Verification Token through a temporary tunnel. " +
-            "The app asks for the scopes that let the agent hear its group chats; any your tenant withholds are named."),
-        channelSub("lark", "scaffold the Lark (international) channel with guided credential setup", "Scaffold src/channels/lark.ts and guide credential setup against the international developer console. " +
-            "Dev uses WebSocket; deploy --run guides setup of a separate production app for webhook.", "Lark international (open.larksuite.com) is Feishu's compatibility profile. WebSocket stops after " +
-            "App ID/Secret validation and a permission check; webhook setup probes config automation and falls " +
-            "back to explicit manual steps on the international config-route 404."),
+        channelSub("telegram", "scaffold the Telegram bot channel (long polling or webhook, durable turns, live preview)", "Scaffold src/channels/telegram.ts — the Telegram bot channel with durable turns, a live-preview " +
+            "message pump, and an optional route() policy — and its send tool. Changes the program only: " +
+            "`fastagent channels setup telegram` sets up the bot and keeps its token."),
+        channelSub("slack", "scaffold the Slack channel (Socket Mode or Events API, files, threads, context, live preview)", "Scaffold src/channels/slack.ts plus its tools (src/tools/slack-send.ts, slack-threads.ts): durable turns, " +
+            "files, threads, context, and an edited live preview, received over Socket Mode or the Events API. Changes " +
+            "the program only: `fastagent channels setup slack` creates the app from a manifest link and keeps its tokens."),
+        channelSub("feishu", "scaffold the Feishu channel (long connection or webhook, durable turns, streaming card)", "Scaffold src/channels/feishu.ts plus its tools (src/tools/feishu-send.ts, feishu-threads.ts). Changes the " +
+            "program only: `fastagent channels setup feishu` creates the app by scan-to-create and keeps its credentials.", "Feishu (open.feishu.cn) is the canonical implementation. A long connection needs only App ID/Secret and " +
+            "no public URL; a webhook additionally needs the Verification Token, which setup captures through a " +
+            "temporary tunnel. The app asks for the scopes that let the agent hear its group chats; any your tenant " +
+            "withholds are named."),
+        channelSub("lark", "scaffold the Lark (international) channel", "Scaffold src/channels/lark.ts plus its tools (src/tools/lark-send.ts, lark-threads.ts). Changes the program " +
+            "only: `fastagent channels setup lark` guides the app's creation on Lark's launcher, checks the App ID " +
+            "and Secret, and keeps them.", "Lark international (open.larksuite.com) is Feishu's compatibility profile. A long connection stops after " +
+            "App ID/Secret validation and a permission check; a webhook tries to capture the Verification Token " +
+            "and asks for it when the international config API answers 404."),
         {
             name: "skill",
             summary: "vendor an Agent Skills skill into skills/<name>/ (copied in, git-tracked)",
@@ -312,24 +319,24 @@ const deploy = {
     flags: [
         {
             flags: "--run",
-            description: "drive the target CLI to completion. Docker builds (pulling the base image) and runs `docker compose up -d`; with a tunnel " +
-                "service, reads its URL and registers webhooks. Fly/Railway provision app/service + volume + " +
+            description: "drive the target CLI to completion. Docker builds (pulling the base image) and runs `docker compose up -d`. Fly/Railway provision app/service + volume + " +
                 "secrets + deploy + webhook setup. AgentCore builds/pushes the arm64 image and deploys the " +
-                "stack (aws + docker CLIs). A model key in the value file travels; any other credential is a login on " +
+                "stack (aws + docker CLIs). A model key is a value of the target (fastagent secrets); any other credential is a login on " +
                 "the deployment itself, which --run starts once the box is up (fastagent login --deployment). " +
                 "Stops at a gate (missing CLI/daemon/login/secret) with one actionable line. Without it: prints " +
                 "the runbook",
         },
+        { flags: "--force", description: "overwrite existing target config/Dockerfile/.dockerignore (else kept)" },
         {
-            flags: "--tunnel",
-            description: "(docker only) add a Quick Tunnel service to generated Compose; generation-only unless combined " +
-                "with --run. Existing Compose stays authoritative",
+            flags: "--config <file>",
+            description: "the instance configuration (a fastagent.json) the deployment runs with, carried in the image; without it, " +
+                "the program's defaults (the project's fastagent.json is the development instance's)",
         },
-        { flags: "--force", description: "overwrite existing target config/Dockerfile/.dockerignore (else kept)" },
         {
             flags: "--into-linked",
-            description: "(railway --run) provision INTO the project this dir is already linked to (skip create); by " +
-                "default --run refuses a pre-existing link (could be unrelated/production)",
+            description: "(railway --run) provision INTO the project this dir is linked to even when it is not the agent's " +
+                "(it holds no service of this name and is not named for it); by default --run refuses that link " +
+                "(could be unrelated/production)",
         },
         {
             flags: "--json",
@@ -350,18 +357,17 @@ const deploy = {
     examples: [
         { cmd: "fastagent deploy fly --run", note: "provision + deploy + webhooks" },
         { cmd: "fastagent deploy fly --run --json", note: "a coding agent" },
-        { cmd: "fastagent deploy docker --tunnel --run", note: "Compose + a public URL" },
+        { cmd: "fastagent deploy docker --run", note: "Compose on this machine" },
         { cmd: "fastagent deploy railway", note: "print the runbook only" },
         { cmd: "fastagent deploy agentcore --run", note: "arm64 image + stack + webhooks" },
     ],
-    notes: "Definition-read-only: the only writes are generated artifacts (never clobbered without " +
-        "--force). A plain redeploy of an already-provisioned agent is just the host's own command " +
-        "(e.g. `railway up`).",
+    notes: "Definition-read-only: the only writes are generated artifacts (never clobbered without --force). A plain " +
+        "redeploy of an already-provisioned agent is just the host's own command (e.g. `railway up`).",
     run: async (args, f) => (await import("./commands/deploy.js")).runDeploy(args[0], args[1], {
         run: f.run === true,
-        tunnel: f.tunnel === true,
         force: f.force === true,
         intoLinked: f.intoLinked === true,
+        ...(typeof f.config === "string" ? { config: f.config } : {}),
         input: f.input !== false,
         json: f.json === true,
         ...(f.check !== undefined ? { check: f.check } : {}),
@@ -435,49 +441,58 @@ const env = {
 const content = {
     name: "content",
     summary: "list, add or remove what the agent works on",
-    description: "Content is a directory the agent works on: a GitHub repository declared " +
-        "by name in context.json, shared with the agent and cloned at content/<name>, or a directory of this " +
-        "machine bound in context.local.json, which never leaves it.",
+    description: "Content is a directory the agent works on: a GitHub repository, cloned at content/<name> in the instance's " +
+        "working directory, or a directory of this machine. The program's context.json declares repositories every " +
+        "instance reaches; an instance's fastagent.json adds its own, repositories and directories, and only adds: a " +
+        "name the program declares is not one it may take.",
     subcommands: [
         {
             name: "list",
             summary: "each content entry and where it is",
             args: [AGENT_ARG],
-            flags: [JSON_FLAG],
+            flags: [JSON_FLAG, ...CONTENT_FLAGS],
             examples: [{ cmd: "fastagent content list" }],
-            run: async (args, f) => (await import("./commands/content.js")).runContentList(args[0], f.json === true),
+            run: async (args, f) => (await import("./commands/content.js")).runContentList(args[0], f.json === true, instanceFlags(f)),
         },
         {
             name: "add",
-            summary: "add a GitHub repository, or bind a directory of this machine, as content",
+            summary: "add a GitHub repository or a directory of this machine as content",
             args: [{ name: "<source>", description: "a directory, or github:owner/repo" }, AGENT_ARG],
             flags: [
                 { flags: "--ref <ref>", description: "a repository: the branch, tag or commit to clone" },
                 { flags: "--name <name>", description: "its name (default: the directory's or repository's)" },
                 { flags: "--description <text>", description: "one sentence for the agent: what it is, how to treat it" },
+                {
+                    flags: "--program",
+                    description: "declare a repository in context.json, for every instance of the program, not in fastagent.json",
+                },
+                ...CONTENT_FLAGS,
             ],
             examples: [
-                { cmd: "fastagent content add ~/code/app", note: "a directory of this machine" },
+                { cmd: "fastagent content add ~/code/app", note: "a directory" },
                 { cmd: "fastagent content add github:acme/docs", note: "a clone" },
+                { cmd: "fastagent content add --program github:acme/docs", note: "for every instance" },
             ],
-            notes: "The root of a GitHub checkout is declared in context.json as that repository, and bound in " +
-                "context.local.json to the checkout, used as it is on this machine. github:owner/repo is cloned into " +
+            notes: "Without --program the entry is written to the instance's fastagent.json (the project's, or the file " +
+                "--config or FASTAGENT_CONFIG names); a deploy does not carry it yet. github:owner/repo is cloned into " +
                 "content/<name> when the agent starts, and brought up to date in place at each start where git can do so " +
-                "without touching the agent's work; so is a declared repository on any machine with no checkout bound. " +
-                "Any other directory is bound in context.local.json only: a deployed instance works without it. A bound " +
-                "directory may not contain the agent directory, nor sit inside it.",
+                "without touching the agent's work. A directory is used as it is, and may not contain the agent directory " +
+                "nor sit inside it.",
             run: async (args, f) => (await import("./commands/content.js")).runContentAdd(args[0], args[1], {
                 ...(typeof f.ref === "string" ? { ref: f.ref } : {}),
                 ...(typeof f.name === "string" ? { name: f.name } : {}),
                 ...(typeof f.description === "string" ? { description: f.description } : {}),
+                ...(f.program === true ? { program: true } : {}),
+                instance: instanceFlags(f),
             }),
         },
         {
             name: "remove",
-            summary: "remove a content entry from both files (a bound directory, and a clone, are left as they are)",
+            summary: "remove a content entry (a directory, and a clone, are left as they are)",
             args: [{ name: "<name>", description: "the entry's name" }, AGENT_ARG],
+            flags: [...CONTENT_FLAGS],
             examples: [{ cmd: "fastagent content remove app" }],
-            run: async (args) => (await import("./commands/content.js")).runContentRemove(args[0], args[1]),
+            run: async (args, f) => (await import("./commands/content.js")).runContentRemove(args[0], args[1], instanceFlags(f)),
         },
     ],
 };
@@ -491,12 +506,11 @@ const schedules = {
             description: "List the schedules this definition declares (defineSchedule in src/schedules/<name>.ts): the next cron " +
                 "instant, how the last run ended and the session its runs continue. The agent's own pending wake-ups are listed too, prefixed " +
                 "`wake`: a different owner (the STATE, not the definition), cancelled by the agent's `unwake` tool or " +
-                "`schedules unwake`. --json adds each schedule's retained fire history. It changes no state; like every " +
-                "command that reads the definition, it regenerates .fastagent/.",
+                "`schedules unwake`. --json adds each schedule's retained fire history. It changes no state.",
             args: [AGENT_ARG],
-            flags: [JSON_FLAG],
+            flags: [JSON_FLAG, ...INSTANCE_FLAGS],
             examples: [{ cmd: "fastagent schedules list" }],
-            run: async (args, flags) => (await import("./commands/schedules.js")).runSchedulesList(args[0], flags.json === true),
+            run: async (args, flags) => (await import("./commands/schedules.js")).runSchedulesList(args[0], flags.json === true, instanceFlags(flags)),
         },
         {
             name: "run",
@@ -514,11 +528,15 @@ const schedules = {
                         "it took after that",
                 },
                 NO_INPUT,
+                ...INSTANCE_FLAGS,
+                CONFIG_FLAG,
+                ENV_FILE_FLAG,
             ],
             examples: [{ cmd: "fastagent schedules run daily-digest" }],
             run: async (args, f) => (await import("./commands/schedules.js")).runScheduleNow(args[0], args[1], {
                 model: f.model,
                 input: f.input !== false,
+                instance: instanceFlags(f),
             }),
         },
         {
@@ -528,8 +546,156 @@ const schedules = {
                 "one set where nobody can message the agent, such as a schedule's own session. It is refused while `dev` " +
                 "or `start` serves this agent, since a serve's clock writes the same store.",
             args: [{ name: "<id>", description: "the wake-up's id" }, AGENT_ARG],
+            flags: [...INSTANCE_FLAGS],
             examples: [{ cmd: "fastagent schedules unwake 3f1c…" }],
-            run: async (args) => (await import("./commands/schedules.js")).runUnwake(args[0], args[1]),
+            run: async (args, f) => (await import("./commands/schedules.js")).runUnwake(args[0], args[1], instanceFlags(f)),
+        },
+    ],
+};
+/**
+ * How an app's setup runs with no one at a terminal: what the person provides is named, and their steps come back with
+ * a ticket to check (`channels setup` in docs/cli.md).
+ */
+const UNATTENDED_SETUP = [
+    { flags: "--json", description: "the outcome as one JSON object, with what to do next (agent_next_steps)" },
+    { flags: "--check <ticket>", description: "where a setup started without a terminal stands" },
+    { flags: "--timeout <seconds>", description: "how long that setup stays open (default 900)" },
+    { flags: "--ticket <id>", description: "the process that runs a ticket's setup", hidden: true },
+    NO_INPUT,
+];
+const channels = {
+    name: "channels",
+    summary: "a channel's platform app, for one instance",
+    subcommands: [
+        {
+            name: "setup",
+            summary: "set up a channel's platform app for one instance, and keep its credentials",
+            description: "Guide a person through creating the platform app (a Slack app from a manifest link, a Telegram bot from " +
+                "BotFather, a Feishu app by scan-to-create, a Lark app on its launcher), ask for the values only they can " +
+                "read off its pages, check each with the platform, and keep them in the instance's value file. Safe to run again: a value already there that the platform still accepts is " +
+                "kept. How the channel receives (webhook or connection) decides which values it needs: --ingress, else what " +
+                "the configuration says, else connection for the development instance and webhook for any other. With no " +
+                "terminal (--json), the values are pasted on a page on this machine for the person a coding agent hands the " +
+                "step to, never in its conversation. With --record-url: read the deployment's /health, and once <name> (slack, " +
+                "or lark where its config API answers 404) is registered there, the platform having reached it at the URL a " +
+                "person saved on its app's page, write that URL into the binding (channels.<name>.app.url) of the " +
+                "configuration --config names, so every later deploy of it reports it registered from the start.",
+            args: [{ name: "<name>", description: "the channel: telegram, slack, feishu or lark" }, AGENT_ARG],
+            flags: [
+                {
+                    flags: "--ingress <mode>",
+                    description: "webhook or connection: set the app up for it, and write it to the configuration",
+                },
+                {
+                    flags: "--config <file>",
+                    description: "the instance configuration: how the channel receives is read from it, and --ingress written to it " +
+                        "(default: the project's fastagent.json, the development instance's)",
+                },
+                {
+                    flags: "--env-file <file>",
+                    description: "the value file the credentials are kept in, which must exist; naming it or --config makes this " +
+                        "another instance than the development one (default: .secrets/.env for dev, else " +
+                        ".secrets/production/.env, created when missing)",
+                },
+                {
+                    flags: "--record-url",
+                    description: "record the URL the deployment confirms, in the configuration --config names",
+                },
+                {
+                    flags: "--url <url>",
+                    description: "with --record-url: where to read its /health (default: the configuration's http.publicUrl)",
+                },
+                ...UNATTENDED_SETUP,
+            ],
+            examples: [
+                { cmd: "fastagent channels setup telegram" },
+                { cmd: "fastagent channels setup slack --json", note: "an agent" },
+                { cmd: "fastagent channels setup slack --config prod.json", note: "a deployment" },
+                { cmd: "fastagent channels setup slack --record-url --config c.json" },
+            ],
+            run: async (args, f) => (await import("./commands/channels.js")).runChannelsSetup(args[0], args[1], {
+                recordUrl: f.recordUrl === true,
+                ...(typeof f.ingress === "string" ? { ingress: f.ingress } : {}),
+                ...(typeof f.config === "string" ? { config: f.config } : {}),
+                ...(typeof f.envFile === "string" ? { envFile: f.envFile } : {}),
+                ...(typeof f.url === "string" ? { url: f.url } : {}),
+                json: f.json === true,
+                input: f.input !== false,
+                ...(f.check !== undefined ? { check: f.check } : {}),
+                ...(f.timeout !== undefined ? { timeout: f.timeout } : {}),
+                ...(f.ticket !== undefined ? { ticket: f.ticket } : {}),
+            }),
+        },
+    ],
+};
+const SECRETS_HOST = {
+    name: "<host>",
+    description: "the target that keeps the values",
+    choices: ["docker", "fly", "railway", "agentcore"],
+};
+const secrets = {
+    name: "secrets",
+    summary: "a deployment's values, on the target that keeps them",
+    subcommands: [
+        {
+            name: "list",
+            summary: "the names the definition declares, and which the target holds",
+            description: "Print every name the deployment declares (the model's key, `needs()`, `context.json`'s variables, MCP " +
+                "references, for the channels its configuration chooses) with whether the target holds a value for it. A value " +
+                "is never read back.",
+            args: [SECRETS_HOST, AGENT_ARG],
+            flags: [
+                { flags: "--config <file>", description: "the configuration the deployment delivers (`deploy --config`)" },
+                JSON_FLAG,
+            ],
+            examples: [{ cmd: "fastagent secrets list fly" }],
+            run: async (args, f) => (await import("./commands/secrets.js")).runSecrets("list", args[0], undefined, args[1], {
+                ...(typeof f.config === "string" ? { config: f.config } : {}),
+                json: f.json === true,
+            }),
+        },
+        {
+            name: "set",
+            summary: "set one value: typed without echo, from standard input, or generated",
+            description: "Set one value on the target, creating the app or service when it does not exist. The value is typed without " +
+                "echo at a terminal, else read from standard input; it is never an argument. --generate sets a random value " +
+                "and prints it once, for what FastAgent makes itself (FASTAGENT_API_KEY).",
+            args: [SECRETS_HOST, { name: "<name>", description: "the environment variable" }, AGENT_ARG],
+            flags: [
+                { flags: "--config <file>", description: "the configuration the deployment delivers (`deploy --config`)" },
+                { flags: "--generate", description: "a random value, printed once" },
+            ],
+            examples: [
+                { cmd: "fastagent secrets set fly OPENAI_API_KEY" },
+                { cmd: "fastagent secrets set fly FASTAGENT_API_KEY --generate" },
+            ],
+            run: async (args, f) => (await import("./commands/secrets.js")).runSecrets("set", args[0], args[1], args[2], {
+                ...(typeof f.config === "string" ? { config: f.config } : {}),
+                generate: f.generate === true,
+            }),
+        },
+        {
+            name: "push",
+            summary: "set every declared value a value file or the environment holds",
+            description: "Set, in one batch, every declared name the source holds a value for, creating the app or service when it does " +
+                "not exist. The source is --env-file, else --from-env (the environment of a command that injected the values: " +
+                "`op run`, `doppler run`, `infisical run`, `dotenvx run`, a CI job), else the production value file " +
+                "(.secrets/production/.env). Names the definition does not declare are not pushed.",
+            args: [SECRETS_HOST, AGENT_ARG],
+            flags: [
+                { flags: "--config <file>", description: "the configuration the deployment delivers (`deploy --config`)" },
+                { flags: "--env-file <file>", description: "the value file to push from, which must exist" },
+                { flags: "--from-env", description: "push from this command's environment" },
+            ],
+            examples: [
+                { cmd: "fastagent secrets push fly" },
+                { cmd: "doppler run -- fastagent secrets push fly --from-env", note: "a secret manager" },
+            ],
+            run: async (args, f) => (await import("./commands/secrets.js")).runSecrets("push", args[0], undefined, args[1], {
+                ...(typeof f.config === "string" ? { config: f.config } : {}),
+                ...(typeof f.envFile === "string" ? { envFile: f.envFile } : {}),
+                fromEnv: f.fromEnv === true,
+            }),
         },
     ],
 };
@@ -537,7 +703,7 @@ const destroy = {
     name: "destroy",
     summary: "delete every AWS resource `deploy agentcore` created for an agent",
     description: "AgentCore only, and it exists because `aws cloudformation delete-stack` is not enough: the S3 " +
-        "artifact bucket and the ECR repository have to exist BEFORE the stack that reads from them, BOTH " +
+        "artifact bucket, the ECR repository and the values secret have to exist BEFORE the stack that reads from them, BOTH " +
         "log groups (the forwarder's and the runtime's own stdout) are created by AWS on first write so no " +
         "template mentions them, and the EventBridge schedules (one per schedule, one per pending wake-up) " +
         "are minted at runtime by the container — left behind, they keep firing into a deleted Lambda. " +
@@ -710,7 +876,7 @@ const mcp = {
         {
             name: "list",
             summary: "inspect declarations and local auth",
-            description: "Read .mcp.json and local grant metadata without contacting servers.",
+            description: "Read the declared MCP servers and local grant metadata without contacting servers.",
             examples: [{ cmd: "fastagent mcp list --json" }],
             args: [AGENT_ARG],
             flags: [CHANNEL_ENVIRONMENT, JSON_FLAG],
@@ -727,7 +893,10 @@ const mcp = {
                 { cmd: "fastagent mcp login linear --scopes read --json" },
                 { cmd: "fastagent mcp login --check <ticket> --json" },
             ],
-            args: [{ name: "[server]", description: "the server name in .mcp.json" }, AGENT_ARG],
+            args: [
+                { name: "[server]", description: "the name of an MCP server the program or the instance declares" },
+                AGENT_ARG,
+            ],
             flags: [
                 CHANNEL_ENVIRONMENT,
                 ...UNATTENDED_SETUP,
@@ -770,6 +939,7 @@ export const specs = [
     models,
     mcp,
     info,
+    build,
     content,
     env,
     invoke,
@@ -777,6 +947,8 @@ export const specs = [
     dev,
     start,
     add,
+    channels,
+    secrets,
     deploy,
     logs,
     destroy,