@fastagent-sh/fastagent 0.24.3 → 0.25.0

package/dist/cli/program.js

@@ -5,10 +5,12 @@
 import { fastagentVersion } from "../version.js";
 import { buildProgram } from "./kernel.js";
 import { DEPLOY_HOSTS } from "../deploy/hosts.js";
+import { unsupportedRuntime } from "../runtime.js";
+import { failStartup } from "./fail.js";
 // Help groups (clig: most common commands first) — the authoring loop leads, operations close.
-const DIR_ARG = {
-    name: "[dir]",
-    description: "workspace directory (the agent is here, or in a directory inside it)",
+const AGENT_ARG = {
+    name: "[agent]",
+    description: "the agent directory, the one holding fastagent.config.ts",
     default: ".",
 };
 const MODEL = {
@@ -25,13 +27,6 @@ const BIND = {
     flags: "--bind <addr>",
     description: "bind address (dev defaults to 127.0.0.1; start defaults to all interfaces, which containers need)",
 };
-const NO_INVOKE = {
-    flags: "--no-invoke",
-    description: "do not serve POST /invoke on this run, nor POST /run — both are unauthenticated and run a turn with the " +
-        "agent's full tools, so a serve meant to be reached only through its channels' signed webhooks should withhold " +
-        "them (fastagent.config.ts http.invoke: false is the same choice, but it travels into a deployed image; this " +
-        "flag outranks http.run: true, because a flag is what a definition you cannot edit still answers to)",
-};
 const TUNNEL = {
     flags: "--tunnel",
     description: "expose a public HTTPS URL via a Cloudflare quick tunnel (needs cloudflared) and auto-register " +
@@ -40,51 +35,42 @@ const TUNNEL = {
 };
 const init = {
     name: "init",
-    summary: "scaffold a runnable agent and install its dependencies",
-    description: "Scaffold a runnable agent and run npm install. The agent ALWAYS goes into a subdirectory of dir " +
-        "(default .): ./fastagent/, or --agent-dir <name> — the rest of the directory gets zero writes, and " +
-        "it is the WORKSPACE the agent works ON when you point fastagent there. Content is a " +
-        "self-iterating agent: APPEND_SYSTEM.md (its standing instructions), a writing-great-skills " +
-        "example skill, a fetch-url code tool, config, package.json, .gitignore. An existing AGENTS.md is " +
-        "kept as project context.",
-    args: [DIR_ARG],
+    summary: "create an agent in a directory of its own and install its dependencies",
+    description: "Create an agent in dir, which must be new or empty, then run npm install there. Content is a " +
+        "self-iterating agent: SYSTEM.md (its system prompt), a writing-great-skills " +
+        "example skill, config, package.json, .gitignore.",
+    args: [{ name: "<dir>", description: "the new agent's directory (created when missing)" }],
     flags: [
+        {
+            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",
+            repeatable: true,
+        },
         { flags: "--no-install", description: "scaffold everything but skip npm install" },
-        { flags: "--agent-dir <name>", description: "name the agent directory (default fastagent)" },
     ],
     examples: [
-        { cmd: "fastagent init", note: "the agent lands in ./fastagent/" },
-        { cmd: "fastagent init my-project", note: "my-project/fastagent/ (created)" },
-        { cmd: "fastagent init . --agent-dir bot", note: "./bot/ — any name works" },
+        { cmd: "fastagent init my-agent", note: "an agent that only talks" },
+        { cmd: "fastagent init reviewer --content ~/code/app", note: "works on ~/code/app" },
+        { cmd: "fastagent init triage --content github:acme/app", note: "works on a clone" },
     ],
-    notes: "An agent is a directory holding a fastagent.config.ts — never its NAME, so --agent-dir can call it " +
-        "anything (the name decides only which agent answers when a workspace holds several: see " +
-        "FASTAGENT_AGENT). What the agent works ON (its cwd, where its AGENTS.md context is read from) is " +
-        "the agent directory's parent — the project you ran init in — whether you point fastagent at the " +
-        "project or at the agent directory. A directory resolves to ONE agent, at it or one level inside.",
+    notes: "An agent is a directory holding a fastagent.config.ts, and it is also the agent's working directory. " +
+        "It lives in a directory of its own, never inside a project or another agent: what it works on is declared " +
+        "as its content. Add a directory it only knows later with `fastagent content add <dir> --readonly`.",
     run: async (args, f) => (await import("./commands/init.js")).runInit(args[0], {
         install: f.install !== false,
-        agentDir: typeof f.agentDir === "string" ? f.agentDir : undefined,
+        content: f.content ?? [],
     }),
 };
 const dev = {
     name: "dev",
     summary: "serve the agent locally, restarting on code edits",
-    description: "Assemble the agent in dir (default .) and serve a local HTTP channel. SYSTEM.md/APPEND_SYSTEM.md/" +
-        "AGENTS.md/skills/prompts " +
-        "are re-read every turn (edits go live next turn); edits to code inputs — tools/, channels/, " +
-        "fastagent.config.ts, package.json, .secrets/.env — restart the worker. Files the agent writes as " +
-        "work product never trigger a restart.",
-    args: [DIR_ARG],
-    flags: [
-        PORT,
-        BIND,
-        MODEL,
-        { flags: "--no-watch", description: "serve once, no file-watching" },
-        TUNNEL,
-        NO_INVOKE,
-        NO_INPUT,
-    ],
+    description: "Open the agent (default .) and serve its channels, schedules and wake-ups. SYSTEM.md, AGENTS.md, " +
+        "skills/ and prompts/ are re-read for every message (edits go live with the next one); edits to code inputs " +
+        "(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],
     examples: [
         { cmd: "fastagent dev" },
         { cmd: "fastagent dev --tunnel", note: "public URL + registered/guided webhooks" },
@@ -95,29 +81,16 @@ const dev = {
         model: f.model,
         watch: f.watch !== false,
         tunnel: f.tunnel === true,
-        ...(f.invoke === false ? { invoke: false } : {}),
         input: f.input !== false,
     }),
 };
-const chat = {
-    name: "chat",
-    summary: "open the SAME assembled agent in pi's interactive TUI",
-    description: "Open the SAME assembled agent in pi's interactive TUI (the real harness, not a crude REPL) — to " +
-        "try it locally before serving. Same model/tool/skill/auth resolution as dev; pi handles " +
-        "rendering, sessions, and /resume natively (its /login writes to the same fastagent auth file).",
-    args: [DIR_ARG],
-    flags: [MODEL],
-    examples: [{ cmd: "fastagent chat" }],
-    run: async (args, f) => (await import("./commands/chat.js")).runChat(args[0], { model: f.model }),
-};
 const info = {
     name: "info",
-    summary: "print what the directory assembles into, without serving",
-    description: "Print what dir (default .) ASSEMBLES into — model, prompt, context files (AGENTS.md), skills, " +
-        "tools (+ collisions), channels, schedules, sessions, load diagnostics — WITHOUT serving. " +
-        "Read-only (never creates sessions / writes .gitignore); an unset model is reported, not fatal. " +
+    summary: "print what the directory builds into, without serving",
+    description: "Print what the agent (default .) builds into — model, tools, extensions, channels, schedules, commands, " +
+        "secrets, content — WITHOUT opening or serving it. An unset model or secret is reported, not fatal. " +
         "Run it first when something looks off.",
-    args: [DIR_ARG],
+    args: [AGENT_ARG],
     flags: [JSON_FLAG, MODEL],
     examples: [{ cmd: "fastagent info" }, { cmd: "fastagent info --json", note: "for CI" }],
     run: async (args, f) => (await import("./commands/info.js")).runInfo(args[0], {
@@ -125,71 +98,74 @@ const info = {
         model: f.model,
     }),
 };
-const tool = {
-    name: "tool",
-    summary: "run one tool directly with JSON args — no model, no server, no tokens",
-    description: "Run one tool (from tools/ or config.tools) directly with JSON args — no model, no server, no " +
-        "tokens. Fast feedback while authoring a tool.",
-    args: [
-        { name: "<name>", description: "the tool name as served (see `fastagent info`)" },
-        { name: "[json-args]", description: "the tool's arguments as a JSON object", default: "{}" },
-        DIR_ARG,
-    ],
-    examples: [{ cmd: `fastagent tool add '{"a":2,"b":3}'` }],
-    notes: "Mounts the same tool set dev/start serve (all coding tools + config.tools + discovered tools/, " +
-        "deduped), so a shadowed or broken tool is surfaced here exactly as it would be when serving.",
-    run: async (args) => (await import("./commands/tool.js")).runTool(args[0], args[1], args[2]),
-};
 const invoke = {
     name: "invoke",
-    summary: "run ONE turn against the assembled agent and exit",
-    description: "Run ONE turn against the assembled agent and exit — no server, no TUI. The reply streams to " +
-        "stdout, tool/diagnostics to stderr, a failed turn exits non-zero. The all-agent counterpart of " +
-        "`tool`, for CI smoke and quick checks. Same model resolution as dev.",
-    args: [{ name: "<message>", description: "the user message for the turn" }, DIR_ARG],
-    flags: [MODEL, NO_INPUT],
-    examples: [{ cmd: `fastagent invoke "summarize today's inbox"` }],
+    summary: "send ONE message to the agent and exit",
+    description: "Send ONE message to the agent and exit — no server. The answer streams to stdout, tool/diagnostics to " +
+        "stderr; --json prints the receipt and the message's events as JSON lines instead. A message that does not " +
+        "complete exits non-zero. Each run starts a new session and prints its id on stderr; --session <id> sends " +
+        "the message into that session instead, continuing it. Sessions are kept in <state>/invoke.sqlite, apart " +
+        "from the storage a serve holds, so it runs beside `dev`; one invoke of an agent runs at a time. Same model " +
+        "resolution as dev, a continued session included. --url <base> sends it to a served agent instead, over its " +
+        "Agent API, with the same output and exit code: a deployment checked as the agent was before it, with the " +
+        "key --key gives or the first FASTAGENT_API_KEY in .secrets/production/.env, which deploy writes. For CI " +
+        "smoke and quick checks, by a person or a coding agent.",
+    args: [{ name: "<message>", description: "the message to send" }, AGENT_ARG],
+    flags: [
+        MODEL,
+        NO_INPUT,
+        { flags: "--json", description: "the receipt and the message's events as JSON lines on stdout" },
+        { 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)" },
+    ],
+    examples: [
+        { cmd: `fastagent invoke "summarize today's inbox"` },
+        { cmd: `fastagent invoke "remember 42"`, note: "prints its session's id" },
+        { cmd: `fastagent invoke --session <id> "which number?"` },
+        { cmd: `fastagent invoke --url https://a.fly.dev "hello"`, note: "a deployment" },
+    ],
     run: async (args, f) => (await import("./commands/invoke.js")).runInvoke(args[0], args[1], {
         model: f.model,
         input: f.input !== false,
+        json: f.json === true,
+        ...(typeof f.session === "string" ? { session: f.session } : {}),
+        ...(typeof f.url === "string" ? { url: f.url } : {}),
+        ...(typeof f.key === "string" ? { key: f.key } : {}),
     }),
 };
 const models = {
     name: "models",
     summary: 'list the available "provider/modelId" model specs',
-    description: 'List every "provider/modelId" spec the agent in this directory can name (pi\'s built-ins, the model ' +
-        "catalogs and models.json files, its own over the machine's) — use one with --model or as `model` in " +
-        "fastagent.config.ts. Outside an agent, or with -g, list the machine's.",
+    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 " +
+        "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" }],
     flags: [
-        {
-            flags: "--refresh",
-            description: "fetch the model catalog first, into the agent's models-store.json (with -g, the machine's)",
-        },
-        { flags: "-g, --global", description: "the machine's catalog, ~/.fastagent/models-store.json" },
+        { flags: "-g, --global", description: "the built-ins, without the agent's providers" },
+        { flags: "--refresh", description: "fetch the model lists now, even when the kept ones are fresh" },
+        { flags: "--json", description: "the specs as JSON: spec, provider, id and name of each (its id, unnamed)" },
     ],
     examples: [
         { cmd: "fastagent models", note: "all specs" },
         { cmd: "fastagent models claude", note: "filter; provider-name matches rank first" },
-        { cmd: "fastagent models --refresh", note: "models newer than the installed pi" },
+        { cmd: "fastagent models --refresh gpt", note: "a model released since the last refresh" },
     ],
-    notes: "A refresh asks pi.dev for the providers the scope's credentials authenticate (the agent's, or with -g the " +
-        "global auth.json and environment) and writes the answer to models-store.json. The agent's is part of the " +
-        "definition: commit it, and it ships with a deploy. The machine's (-g) is read by every agent here and does " +
-        "not ship. Nothing refreshes on its own.",
     run: async (args, f) => (await import("./commands/models.js")).runModels(args[0], {
-        refresh: f.refresh === true,
         global: f.global === true,
+        refresh: f.refresh === true,
+        json: f.json === true,
     }),
 };
 const start = {
     name: "start",
-    summary: "run the agent in production posture (same assembly as dev, no watching)",
-    description: "Run the agent in dir (default .) in production posture — the SAME assembly as dev (your directory " +
-        "is the agent), just no file-watching. No build step: start reads the definition directly; " +
-        "model/http come from fastagent.config.ts (frozen by git).",
-    args: [DIR_ARG],
-    flags: [PORT, BIND, MODEL, TUNNEL, NO_INVOKE, NO_INPUT],
+    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.",
+    args: [AGENT_ARG],
+    flags: [PORT, BIND, MODEL, TUNNEL, NO_INPUT],
     examples: [
         { cmd: "fastagent start" },
         { cmd: "fastagent start --tunnel", note: "host a bot from your own box, no deploy" },
@@ -197,39 +173,37 @@ const start = {
     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" +
-        "  /invoke:  --no-invoke > fastagent.config.ts http.invoke > served\n" +
-        "  /run:     --no-invoke > fastagent.config.ts http.run > http.invoke\n" +
-        "            (with GET /routines; both only where routines/ declares something)\n" +
-        "  state:    FASTAGENT_STATE_DIR > <agent dir>/.state — mutable machine state\n" +
-        "            (sessions, channel state, schedule state); point it at a mounted\n" +
-        "            volume so a redeploy that replaces the directory never wipes it\n" +
-        "  secrets:  FASTAGENT_SECRETS_DIR > <agent dir>/.secrets — .env + auth.json\n" +
-        "  sessions: <state>/sessions — no separate knob; move the state root\n" +
+        "  state:    FASTAGENT_STATE_DIR > <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" +
+        "            .env + auth.json\n" +
+        "  content:  <agent dir>/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" +
-        "            share one credential across projects)\n" +
-        "  endpoints: FASTAGENT_MODELS_PATH > ~/.fastagent/models.json, under the agent's\n" +
-        "            own models.json (the machine's; it does not ship with a deploy)",
+        "            share one credential across projects)",
     run: async (args, f) => (await import("./commands/start.js")).runStart(args[0], {
         port: f.port,
         bind: f.bind,
         model: f.model,
         tunnel: f.tunnel === true,
-        ...(f.invoke === false ? { invoke: false } : {}),
         input: f.input !== false,
     }),
 };
 const INGRESS = {
     flags: "--ingress <mode>",
-    description: "Feishu/Lark ingress: websocket or webhook (interactive when omitted)",
+    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 GROUP_BEHAVIOR = {
-    flags: "--group-behavior <behavior>",
-    description: "Slack/Feishu/Lark groups: context (recommended) or mentions (least privilege)",
+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: "Slack: scaffold only; skip internal-app creation/OAuth",
+    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",
@@ -240,42 +214,61 @@ const channelSub = (kind, summary, description, notes) => ({
     name: kind,
     summary,
     description,
-    args: [DIR_ARG],
+    args: [AGENT_ARG],
     flags: kind === "feishu" || kind === "lark"
-        ? [INGRESS, GROUP_BEHAVIOR]
+        ? [CHANNEL_ENVIRONMENT, INGRESS, NO_ONBOARD, ...UNATTENDED_SETUP]
         : kind === "slack"
-            ? [GROUP_BEHAVIOR, NO_ONBOARD, REPLACE_CONFIG]
-            : [],
-    examples: [{ cmd: `fastagent add ${kind}` }],
+            ? [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" }]),
+    ],
     ...(notes ? { notes } : {}),
     run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], {
         ingress: f.ingress,
-        groupBehavior: f.groupBehavior,
+        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 } : {}),
     }),
 });
+/**
+ * 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 channels/telegram.ts — the Telegram bot channel with durable turns, a live-preview " +
+        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)", "Choose group visibility, scaffold channels/slack.ts plus slack-send.ts, create a single-workspace " +
+        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", "Choose WebSocket or webhook, scaffold channels/feishu.ts, and create/configure the Feishu app " +
-            "through scan-to-create, writing the matching credentials to .env.", "Feishu (open.feishu.cn) is the canonical implementation. WebSocket needs only App ID/Secret and " +
+        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. " +
-            "Context-aware groups (recommended) request admin approval for im:message.group_msg before publish."),
-        channelSub("lark", "scaffold the Lark (international) channel with guided credential setup", "Choose WebSocket or webhook, scaffold channels/lark.ts, and guide credential setup against the " +
-            "international developer console.", "Lark international (open.larksuite.com) is Feishu's compatibility profile. WebSocket stops after " +
-            "App ID/Secret validation; webhook and recommended context-aware group setup probe config " +
-            "automation and fall back to explicit manual steps on the international config-route 404."),
+            "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."),
         {
             name: "skill",
             summary: "vendor an Agent Skills skill into skills/<name>/ (copied in, git-tracked)",
@@ -285,7 +278,7 @@ const add = {
                     description: "a git ref (owner/repo/path, github default), a local path (./x, /abs), or a bare name " +
                         "from your global skill dirs (~/.agents/skills, ~/.pi/agent/skills)",
                 },
-                DIR_ARG,
+                AGENT_ARG,
             ],
             flags: [
                 { flags: "--update", description: "overwrite an existing skill (re-fetch from source); review with git diff" },
@@ -297,7 +290,9 @@ const add = {
             notes: "Writing your own skill needs no command: create skills/<name>/SKILL.md with name + " +
                 "description frontmatter; it's auto-discovered. `add skill` is only for vendoring an " +
                 "existing one.",
-            run: async (args, f) => (await import("./commands/add.js")).runAddSkill(args[0], args[1], { update: f.update === true }),
+            run: async (args, f) => (await import("./commands/add.js")).runAddSkill(args[0], args[1], {
+                update: f.update === true,
+            }),
         },
     ],
 };
@@ -306,16 +301,18 @@ const deploy = {
     summary: "generate deploy artifacts + a runbook for docker, fly, railway, or agentcore (--run drives it)",
     description: "Generate Dockerfile/.dockerignore plus the target config and print an ordered runbook. " +
         "docker: fastagent.compose.yml, loopback port, persistent state volume. fly: fly.toml " +
-        "(autostop=suspend, state→volume). railway: railway.json (healthcheck /health); its " +
-        "volume/variables/App-Sleeping are dashboard/CLI steps the runbook states. agentcore: one " +
+        "(autostop=suspend, state→volume). railway: no config file; its volume/variables/App-Sleeping " +
+        "are dashboard/CLI steps the runbook states. agentcore: one " +
         "CloudFormation stack (AWS Bedrock AgentCore Runtime + forwarder Lambda for webhooks + " +
-        "EventBridge rules for schedules; linux/arm64 image built locally). Durable ingress " +
-        "remains operator-owned (agentcore's forwarder URL is the exception — the stack owns it).",
-    args: [{ name: "<host>", description: "deploy target", choices: [...DEPLOY_HOSTS] }, DIR_ARG],
+        "the alarms the container sets for schedules and wake-ups; linux/arm64 image built locally). Durable ingress " +
+        "remains operator-owned (agentcore's forwarder URL is the exception — the stack owns it). " +
+        "Production values come from .secrets/production/.env, never the dev file. Interactive --run creates " +
+        "a separate Feishu/Lark production app when its credentials are missing.",
+    args: [{ name: "<host>", description: "deploy target", choices: [...DEPLOY_HOSTS] }, AGENT_ARG],
     flags: [
         {
             flags: "--run",
-            description: "drive the target CLI to completion. Docker runs `docker compose up -d --build`; with a tunnel " +
+            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 + " +
                 "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 " +
@@ -334,16 +331,31 @@ const deploy = {
             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)",
         },
+        {
+            flags: "--json",
+            description: "with --run, for a coding agent: the deploy runs in a process of its own and the command returns its " +
+                "ticket, handing each step only a person can take (a host sign-in, a production app, the box's model " +
+                "login) to its user",
+        },
+        { flags: "--check <ticket>", description: "where a deploy started with --json stands" },
+        {
+            flags: "--code <code>",
+            description: "with --check: the code a host's approval page showed, when it could not reach this machine",
+        },
+        { flags: "--timeout <seconds>", description: "how long a deploy started with --json stays open (default 3600)" },
+        { flags: "--stop", description: "with --check: stop that deploy where it is (can leave the host half-changed)" },
+        { flags: "--ticket <id>", description: "the process that runs a ticket's deploy", hidden: true },
         NO_INPUT,
     ],
     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 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 routine redeploy of an already-provisioned agent is just the host's own command " +
+        "--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,
@@ -351,61 +363,190 @@ const deploy = {
         force: f.force === true,
         intoLinked: f.intoLinked === true,
         input: f.input !== false,
+        json: f.json === true,
+        ...(f.check !== undefined ? { check: f.check } : {}),
+        ...(f.code !== undefined ? { code: f.code } : {}),
+        ...(f.timeout !== undefined ? { timeout: f.timeout } : {}),
+        ...(f.ticket !== undefined ? { ticket: f.ticket } : {}),
+        stop: f.stop === true,
     }),
 };
-const routine = {
-    name: "routine",
-    summary: "run and inspect the units of work this definition declares: run now, fire history, what exists",
+const env = {
+    name: "env",
+    summary: "add, remove or list the commands the agent runs: its environment",
+    description: "The agent's environment is the `environment` of its context.json: `packages`, each a name from mise's registry " +
+        "or written with aqua:, github:, gitlab:, conda:, npm: or pypi:, with a version; `aptPackages`, Debian " +
+        "packages the image installs; and `variables`, the environment variables its commands read, each declared by " +
+        "name with a description (its value goes in .secrets/.env, never in context.json; every one is required). " +
+        "Variables are edited in context.json by hand. Nothing is locked: each place installs the newest release a " +
+        "version allows when it first needs a package, and the image installs every package when it is built. Run in " +
+        "the agent directory (the current one). The first change adds mise to the agent's package.json (one optional " +
+        "package per platform; npm installs this machine's), so nothing has to be installed first.",
     subcommands: [
         {
-            name: "run",
-            summary: "run ONE routine's turn immediately, without waiting for a clock",
-            description: "Run ONE routine's turn immediately (authoring loop, like invoke) — runs routines/<name>.ts now, " +
-                "whether or not it declares a cron. Reply→stdout; does NOT advance its fire state.",
-            args: [{ name: "<name>", description: "the routine name (routines/<name>.ts)" }, DIR_ARG],
-            flags: [MODEL, NO_INPUT],
-            examples: [{ cmd: "fastagent routine run daily-digest" }],
-            run: async (args, f) => (await import("./commands/routine-run.js")).runRoutine(args[0], args[1], {
-                model: f.model,
-                input: f.input !== false,
+            name: "add",
+            summary: "add packages: installed here first, then declared",
+            args: [{ name: "<packages...>", description: "name[@version] (default latest), or apt:<name> for the image" }],
+            examples: [
+                { cmd: "fastagent env add gh@2", note: "a CLI from mise's registry" },
+                { cmd: "fastagent env add npm:prettier@3", note: "an npm package" },
+                { cmd: "fastagent env add python uv pypi:markitdown", note: "PyPI, with its runtime" },
+                { cmd: "fastagent env add apt:chromium", note: "installed by the image" },
+            ],
+            run: async (args) => (await import("./commands/env.js")).runEnvAdd(args[0]),
+        },
+        {
+            name: "remove",
+            summary: "remove packages, by the name they are declared with",
+            args: [{ name: "<packages...>", description: "a declared package, or apt:<name>" }],
+            examples: [{ cmd: "fastagent env remove gh apt:chromium" }],
+            run: async (args) => (await import("./commands/env.js")).runEnvRemove(args[0]),
+        },
+        {
+            name: "list",
+            summary: "the declared packages and their versions, the variables and whether each has a value",
+            flags: [{ flags: "--json", description: "the packages, apt packages and variables as JSON" }],
+            examples: [{ cmd: "fastagent env list" }, { cmd: "fastagent env list --json" }],
+            run: async (_args, f) => (await import("./commands/env.js")).runEnvList({ json: f.json === true }),
+        },
+        {
+            name: "install",
+            summary: "install what context.json declares here, at the newest release each version allows",
+            description: "Install the agent's mise (adding it to package.json when it is not there), then every package context.json " +
+                "declares, at the newest release its version allows: a newer one where one is out. Not needed day to day " +
+                "(`add` installs what it adds, and every start installs what is missing): it is for a newer release, and " +
+                "for a clone that has not installed its mise yet.",
+            examples: [{ cmd: "fastagent env install", note: "after a clone, or for newer releases" }],
+            run: async () => (await import("./commands/env.js")).runEnvInstall(),
+        },
+        {
+            name: "exec",
+            summary: "run a command in the environment, with the agent's .secrets/.env",
+            args: [{ name: "<command...>", description: "the command and its arguments, after --", verbatim: true }],
+            examples: [{ cmd: "fastagent env exec -- gh --version" }],
+            run: async (args) => (await import("./commands/env.js")).runEnvExec(args[0]),
+        },
+    ],
+    notes: "`dev`, `start` and `invoke` install the declared packages that have no install here yet, and " +
+        "put them first on the PATH of what the agent runs; one already installed is kept, so a start needs no network. " +
+        "`dev` restarts when context.json changes. Apt packages are installed in the image; on Debian or Ubuntu a start " +
+        "here names the missing ones.",
+};
+const content = {
+    name: "content",
+    summary: "list, add or remove what the agent works on and knows",
+    description: "Content is a directory the agent works on (or only knows, with --readonly): 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.",
+    subcommands: [
+        {
+            name: "list",
+            summary: "each content entry, where it is, and whether the agent works on it or only knows it",
+            args: [AGENT_ARG],
+            flags: [JSON_FLAG],
+            examples: [{ cmd: "fastagent content list" }],
+            run: async (args, f) => (await import("./commands/content.js")).runContentList(args[0], f.json === true),
+        },
+        {
+            name: "add",
+            summary: "add a GitHub repository, or bind a directory of this machine, as content",
+            args: [{ name: "<source>", description: "a directory, or github:owner/repo" }, AGENT_ARG],
+            flags: [
+                { flags: "--readonly", description: "the agent knows it and does not write it" },
+                { 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" },
+            ],
+            examples: [
+                { cmd: "fastagent content add ~/code/app", note: "works on" },
+                { cmd: "fastagent content add ~/handbook --readonly", note: "knows" },
+                { cmd: "fastagent content add github:acme/docs --readonly", note: "knows a clone" },
+            ],
+            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 " +
+                "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.",
+            run: async (args, f) => (await import("./commands/content.js")).runContentAdd(args[0], args[1], {
+                readonly: f.readonly === true,
+                ...(typeof f.ref === "string" ? { ref: f.ref } : {}),
+                ...(typeof f.name === "string" ? { name: f.name } : {}),
+                ...(typeof f.description === "string" ? { description: f.description } : {}),
             }),
         },
         {
-            name: "history",
-            summary: "print the recent fires of a routine",
-            description: "Print a routine's recent fires: when each fired, completed/failed/skipped/interrupted, and how long it " +
-                'took — the answer to "did last night\'s run silently fail?". What the run SAID is in its session, a ' +
-                "JSON-lines journal under the state root's sessions/ — which this command points at. Read-only.",
-            args: [{ name: "<name>", description: "the routine name" }, DIR_ARG],
-            flags: [{ flags: "--json", description: "the full records" }],
-            examples: [{ cmd: "fastagent routine history daily-digest" }],
-            run: async (args, flags) => (await import("./commands/routine.js")).runRoutineHistory(args[0], args[1], flags.json === true),
+            name: "remove",
+            summary: "remove a content entry from both files (a bound directory, and a clone, are left as they are)",
+            args: [{ name: "<name>", description: "the entry's name" }, AGENT_ARG],
+            examples: [{ cmd: "fastagent content remove app" }],
+            run: async (args) => (await import("./commands/content.js")).runContentRemove(args[0], args[1]),
         },
+    ],
+};
+const schedules = {
+    name: "schedules",
+    summary: "what will wake this agent up: list, run a schedule now, cancel a wake-up",
+    subcommands: [
         {
             name: "list",
-            summary: "every declared routine, and when (or whether) a clock fires it",
-            description: "List the routines this definition declares: the next cron instant for each that has one, and " +
-                '"on demand" for each that does not — those are reached by name (POST /run, `routine run`). The agent\'s ' +
-                "own pending wake-ups are listed too, prefixed `wake`: a different owner (the STATE, not the " +
-                "definition), and only the agent cancels them (the `unwake` tool). Read-only.",
-            args: [DIR_ARG],
+            summary: "every schedule (src/schedules/<name>.ts) and wake-up, with when it runs next",
+            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/.",
+            args: [AGENT_ARG],
             flags: [JSON_FLAG],
-            examples: [{ cmd: "fastagent routine list" }],
-            run: async (args, flags) => (await import("./commands/routine.js")).runRoutineList(args[0], flags.json === true),
+            examples: [{ cmd: "fastagent schedules list" }],
+            run: async (args, flags) => (await import("./commands/schedules.js")).runSchedulesList(args[0], flags.json === true),
+        },
+        {
+            name: "run",
+            summary: "fire one schedule now, as its clock would",
+            description: "Fire the schedule <name> now, the way its clock would: in its own session, with its claim and outcome " +
+                "recorded (`schedules list` shows them). The answer goes to stdout, the fire's log to stderr; it exits " +
+                "non-zero unless its message completed. It opens the instance's storage, so it is refused while `dev` or " +
+                "`start` serves this agent, and they are refused while it runs; it is refused too while the instance holds " +
+                "messages a stopped serve left unfinished, which it would run and cut off: serve them to their end first.",
+            args: [{ name: "<name>", description: "the schedule, as src/schedules/<name>.ts names it" }, AGENT_ARG],
+            flags: [
+                {
+                    flags: MODEL.flags,
+                    description: "the default model, as for dev: the schedule's session takes it at its first fire, and keeps the one " +
+                        "it took after that",
+                },
+                NO_INPUT,
+            ],
+            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,
+            }),
+        },
+        {
+            name: "unwake",
+            summary: "cancel one of the agent's pending wake-ups",
+            description: "Cancel the pending wake-up <id> (`schedules list` shows the ids), whatever session set it: the way to " +
+                "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],
+            examples: [{ cmd: "fastagent schedules unwake 3f1c…" }],
+            run: async (args) => (await import("./commands/schedules.js")).runUnwake(args[0], args[1]),
         },
     ],
 };
 const destroy = {
     name: "destroy",
-    summary: "delete every AWS resource `deploy agentcore` created for a workspace",
+    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 " +
         "log groups (the forwarder's and the runtime's own stdout) are created by AWS on first write so no " +
-        "template mentions them, and a wake alarm is minted at runtime by the container — a schedule that " +
-        "keeps retrying into a deleted Lambda. " +
-        "Derives the same names from dir that deploy did. Without --run it deletes nothing and reports what " +
+        "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. " +
+        "Derives the same names from the agent directory that deploy did. Without --run it deletes nothing and reports what " +
         "is out there.",
-    args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, DIR_ARG],
+    args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, AGENT_ARG],
     flags: [{ flags: "--run", description: "actually delete. Without it, this is a read-only inventory" }],
     // The other hosts need no command of their own, and saying which one to use belongs where it can be READ:
     // `<host>` has `choices`, so a `destroy fly` never reaches the command body.
@@ -428,10 +569,10 @@ const destroy = {
 const logs = {
     name: "logs",
     summary: "find and tail a deployed host's application logs",
-    description: "Find the CloudWatch log group for the AgentCore stack derived from dir, then run aws logs tail. " +
+    description: "Find the CloudWatch log group for the AgentCore stack derived from the agent directory, then run aws logs tail. " +
         "The default Runtime source shows the agent process's own stdout/stderr; the forwarder source shows " +
         "the Lambda ingress transport logs.",
-    args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, DIR_ARG],
+    args: [{ name: "<host>", description: "deployed host", choices: ["agentcore"] }, AGENT_ARG],
     flags: [
         { flags: "--source <source>", description: "agentcore log source: runtime (default) or forwarder" },
         { flags: "--since <duration>", description: "history window accepted by AWS CLI (for example 30m or 2h)" },
@@ -441,7 +582,7 @@ const logs = {
         { cmd: "fastagent logs agentcore --follow", note: "the agent process" },
         { cmd: "fastagent logs agentcore --source forwarder --follow", note: "Lambda ingress" },
     ],
-    notes: "Read-only. Run it against the same workspace passed to deploy so it derives the same CloudFormation " +
+    notes: "Read-only. Run it against the same agent directory passed to deploy so it derives the same CloudFormation " +
         "stack name. It never changes FASTAGENT_LOG_LEVEL: AgentCore keeps start's production default, and " +
         "setting that environment knob to debug exposes the existing detailed turn trace when needed.",
     run: async (args, f) => (await import("./commands/logs.js")).runLogs(args[0], args[1], {
@@ -450,26 +591,42 @@ const logs = {
         follow: f.follow === true,
     }),
 };
+const GLOBAL_AUTH = {
+    flags: "-g, --global",
+    description: "the global ~/.fastagent/.secrets/auth.json, which every agent here reads for a provider it has no other credential for",
+};
 const login = {
     name: "login",
-    summary: "authenticate a model provider (subscription/OAuth or API key)",
-    description: "Authenticate a model provider into the project-level <agent dir>/.secrets/auth.json (outside an " +
-        "agent it writes the global ~/.fastagent/.secrets/auth.json, and says so): pick a method " +
-        "(subscription/OAuth or API " +
-        "key), then a provider that offers it (configured status shown). [provider] takes the method from " +
-        "what that provider supports, asked only when both. An agent READS the global store for a provider it has " +
-        "no other credential for (its own file, a models.json key, an env variable), so `-g` logs in once for every " +
-        "agent on this machine; it warns when an env variable already authenticates the provider.",
-    args: [{ name: "[provider]", description: "provider id (skip the provider menu)" }],
+    summary: "sign in to a model provider (an account or an API key)",
+    description: "Sign in to a model provider into the agent's <agent dir>/.secrets/auth.json (outside an agent it writes the " +
+        "global ~/.fastagent/.secrets/auth.json, and says so), as pi's /login does: how to sign in (an account or an API " +
+        "key), then the provider, each with what authenticates it now. [provider] (its id or name) skips the provider " +
+        "menu; how is asked only when it offers both. An agent READS the global store for a provider it has no other " +
+        "credential for (its own file, a provider in its config that authenticates itself, an env variable), so `-g` " +
+        "signs in once for every agent on this machine; it warns when an env variable already authenticates the " +
+        "provider. Without a terminal (or with --no-input or --json), for a script or a coding agent, nothing is asked " +
+        "and nothing waits: a provider or --method not given is answered with the choices and a command for each (exit " +
+        "2); an account's sign-in starts in a process of its own and the command returns its address and a ticket at " +
+        "once, for the person to sign in at and `login --check <ticket>` to follow; an API key is named, for the person " +
+        "to set in the agent's .secrets/.env themselves.",
+    args: [{ name: "[provider]", description: "provider id or name (skip the provider menu)" }],
     flags: [
+        GLOBAL_AUTH,
+        { flags: "--method <how>", description: "account or api-key, for a provider that offers both" },
+        { flags: "--json", description: "the outcome as one JSON object, with what to do next (agent_next_steps)" },
+        { flags: "--check <ticket>", description: "where a sign-in started without a terminal stands" },
         {
-            flags: "-g, --global",
-            description: `store in ~/.fastagent/.secrets/auth.json — every agent here reads it for a provider it has no other credential for`,
+            flags: "--code <address>",
+            description: "with --check: the address the browser ended on, when it could not reach this machine",
         },
         {
-            flags: "--deployment [host]",
-            description: "log in this agent's deployment instead, on the box itself (docker, fly, railway, agentcore); the host may be left out " +
-                "when the agent dir holds one host's deploy artifacts",
+            flags: "--timeout <seconds>",
+            description: "how long the sign-in stays open (default 600 without a terminal)",
+        },
+        { flags: "--ticket <id>", description: "the process that runs a ticket's sign-in", hidden: true },
+        {
+            flags: "--deployment <host>",
+            description: "log in this agent's deployment on <host> instead, on the box itself (docker, fly, railway, agentcore)",
         },
         { flags: "--stdio", description: "the box's half of --deployment", hidden: true },
         { flags: "--if-missing", description: "with --stdio: keep a stored credential for the provider", hidden: true },
@@ -477,23 +634,78 @@ const login = {
     ],
     examples: [
         { cmd: "fastagent login" },
-        { cmd: "fastagent login openai" },
-        { cmd: "fastagent login openai -g" },
-        { cmd: "fastagent login openai-codex --deployment fly", note: "on the box" },
+        { cmd: "fastagent login openai", note: "ChatGPT, or an API key" },
+        { cmd: "fastagent login openai -g", note: "for every agent here" },
+        { cmd: "fastagent login openai --method account --json", note: "an agent" },
+        { cmd: "fastagent login --check 3f9a0c1d2e4b5a67 --json", note: "then" },
+        { cmd: "fastagent login openai --deployment fly", note: "on the box" },
     ],
-    notes: "The positional is the PROVIDER (not a dir) — `cd` into your agent before logging in. " +
+    notes: "The positional is the PROVIDER (not a dir) — `cd` into your agent before logging in. Exit status: 0 signed in " +
+        "or waiting on the person (need_user_action), 1 cancelled, failed or expired, 2 a provider or method not given. " +
         "--deployment runs the login on the deployed box through the host's own shell (docker compose exec, fly ssh, " +
         "railway ssh, AgentCore's command shell); this terminal shows it, opens the browser, and catches the browser's " +
         "return to localhost (or asks you to paste that address when its port is taken). The box keeps the credential, " +
-        "so it is the only holder of that grant, and logging in again replaces it there.",
+        "so it is the only holder of that grant, and logging in again replaces it there. Without a terminal, an " +
+        "account's sign-in on the box returns a ticket as a local one does, its process holding the box's shell; an API " +
+        "key is named, for the person to set in .secrets/production/.env before the next deploy carries it.",
     run: async (args, f) => (await import("./commands/login.js")).runLogin(args[0], {
         global: f.global === true,
         input: f.input !== false,
+        json: f.json === true,
+        ...(f.method !== undefined ? { method: f.method } : {}),
+        ...(f.timeout !== undefined ? { timeout: f.timeout } : {}),
+        ...(f.check !== undefined ? { check: f.check } : {}),
+        ...(f.code !== undefined ? { code: f.code } : {}),
+        ...(f.ticket !== undefined ? { ticket: f.ticket } : {}),
         ...(f.deployment !== undefined ? { deployment: f.deployment } : {}),
         stdio: f.stdio === true,
         ifMissing: f.ifMissing === true,
     }),
 };
+const logout = {
+    name: "logout",
+    summary: "remove a provider's stored credential",
+    description: "Remove the credential `login` stored for a provider, from the agent's <agent dir>/.secrets/auth.json (outside " +
+        "an agent, or with -g, the global file), as pi's /logout does: a menu of the providers stored there, or the one " +
+        "named. Environment variables, and the grant at the provider, are left as they are.",
+    args: [{ name: "[provider]", description: "provider id or name (required without a terminal)" }],
+    flags: [GLOBAL_AUTH, NO_INPUT],
+    examples: [{ cmd: "fastagent logout" }, { cmd: "fastagent logout openai-codex" }],
+    run: async (args, f) => (await import("./commands/logout.js")).runLogout(args[0], {
+        global: f.global === true,
+        input: f.input !== false,
+    }),
+};
+const auth = {
+    name: "auth",
+    summary: "check a model provider's credential (for scripts and agents)",
+    subcommands: [
+        {
+            name: "check",
+            summary: "is a provider ready: prints ready, not_ready or invalid",
+            description: "Check what authenticates a provider for the agent here (outside an agent, or with -g, for the global " +
+                "file), as pi's `auth check` does: prints ready, not_ready or invalid, and exits 0, 1 or 2. --model names " +
+                "the provider by a model of it; a login due a refresh is refreshed, as a message would. --json prints " +
+                "{status, provider, authType | reason, source, path}.",
+            flags: [
+                { flags: "--provider <id>", description: "the provider to check" },
+                { flags: "--model <provider/modelId>", description: "the provider of this model" },
+                GLOBAL_AUTH,
+                JSON_FLAG,
+            ],
+            examples: [
+                { cmd: "fastagent auth check --provider openai" },
+                { cmd: "fastagent auth check --model openai/gpt-5.5 --json" },
+            ],
+            run: async (_args, f) => (await import("./commands/auth.js")).runAuthCheck({
+                ...(f.provider !== undefined ? { provider: f.provider } : {}),
+                ...(f.model !== undefined ? { model: f.model } : {}),
+                global: f.global === true,
+                json: f.json === true,
+            }),
+        },
+    ],
+};
 /**
  * Registration order = help order — the ORIGINAL usage wall's order, kept verbatim (this is a commander refactor of
  * the same CLI, not a redesign).
@@ -502,17 +714,19 @@ export const specs = [
     init,
     models,
     info,
-    tool,
+    content,
+    env,
     invoke,
-    routine,
+    schedules,
     dev,
-    chat,
     start,
     add,
     deploy,
     logs,
     destroy,
     login,
+    logout,
+    auth,
 ];
 /** The production program assembly (specs + the top-level examples/docs). */
 export function buildCliProgram(overrides = {}) {
@@ -528,5 +742,9 @@ export function buildCliProgram(overrides = {}) {
 }
 /** Parse and run one CLI invocation (`argv` = process.argv). */
 export async function runCli(argv) {
+    // Before any command loads the storage: an older Bun fails that import with a message that says nothing of Bun.
+    const unsupported = unsupportedRuntime();
+    if (unsupported !== undefined)
+        failStartup(new Error(unsupported));
     await buildCliProgram({ version: await fastagentVersion() }).parseAsync([...argv]);
 }