@fastagent-sh/fastagent 0.14.0 → 0.16.0

package/dist/scaffold/add-channel.js

@@ -1,16 +1,15 @@
 /**
  * `fastagent add <channel>`: drop a `channels/<kind>.ts` adapter-glue file (+ any companion tool, +
- * `.env.example` vars) into an existing workspace. `add` checks and guides; it never bootstraps a
- * workspace (that is `init`'s job). Each channel's template files live in its own bundle at
- * src/channels/<kind>/scaffold/, read here at scaffold time.
+ * `.secrets/.env.example` vars) into an existing agent. `add` checks and guides; it never
+ * bootstraps an agent (that is `init`'s job). Each channel's template files live in its own bundle
+ * at src/channels/<kind>/scaffold/, read here at scaffold time.
  */
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { detectRuntime } from "../runtime.js";
-import { assertInsideWorkspace } from "../workspace.js";
-import { channelBundleFiles, channelTemplate } from "./templates.js";
-import { exists } from "./init.js";
-import { parseEnvContent } from "../env.js";
+import { SECRETS_DIRNAME, assertInsideAgentDir, exists } from "../paths.js";
+import { baseTemplate, channelBundleFiles, channelTemplate } from "./templates.js";
+import { dotEnvPath, envExamplePath, parseEnvContent } from "../env.js";
 const CHANNEL_SCAFFOLDS = {
     github: {
         env: [
@@ -21,8 +20,8 @@ const CHANNEL_SCAFFOLDS = {
                 generate: true,
             },
         ],
-        // `{channel}` / `{tools}` are path placeholders the CLI resolves to the real workspace-relative
-        // location (agentDir-aware) — the CLI holds no channel-private filenames.
+        // `{channel}` / `{tools}` are path placeholders the CLI resolves to the real agent-dir-relative
+        // location — the CLI holds no channel-private filenames.
         steps: [
             "edit {channel} — map events to intents in on()",
             "add the webhook in your repo (Settings → Webhooks): Payload URL = <public-url>/webhook, content type application/json",
@@ -43,11 +42,39 @@ const CHANNEL_SCAFFOLDS = {
             "the agent can send messages or files back by calling the scaffolded {tools}/telegram-send.ts tool",
         ],
     },
+    slack: {
+        env: [
+            { name: "SLACK_BOT_TOKEN", hint: "Slack app → rotating Bot User OAuth access token", required: true },
+            {
+                name: "SLACK_BOT_REFRESH_TOKEN",
+                hint: "Slack OAuth bot refresh token (required when token rotation is enabled)",
+                required: false,
+            },
+            {
+                name: "SLACK_BOT_TOKEN_EXPIRES_AT",
+                hint: "Slack rotating bot access-token expiry (epoch milliseconds)",
+                required: false,
+            },
+            { name: "SLACK_CLIENT_ID", hint: "Slack app OAuth client ID (for bot-token rotation)", required: false },
+            {
+                name: "SLACK_CLIENT_SECRET",
+                hint: "Slack app OAuth client secret (for bot-token rotation)",
+                required: false,
+            },
+            { name: "SLACK_SIGNING_SECRET", hint: "Slack app → Basic Information → App Credentials", required: true },
+        ],
+        steps: [
+            "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write, channels:history, groups:history, mpim:history",
+            "enable Agents (agent_view) and token rotation; subscribe app_home_opened, app_context_changed, app_mention, message.im, message.channels, message.groups, message.mpim; set Request URL to <public-url>/slack",
+            "reinstall the app after changing scopes, then invite it to each channel it should read",
+            "the agent can send messages or files by calling the scaffolded {tools}/slack-send.ts tool",
+        ],
+    },
     // Feishu is the canonical engine/cloud; Lark international reuses its protocol through a degraded
     // compatibility profile. Each remains its own channel KIND: route, env, state, console, onboarding.
-    // No `generate` in either: every value comes FROM the platform (a locally generated Encrypt Key
-    // would break inbound events until mirrored in the console). `add feishu` scan-creates the app;
-    // Lark lacks that control-plane capability, so `add lark` guides console credential collection.
+    // This table is the webhook setup; continuous mode below selects only App ID/Secret. No `generate`
+    // in either: values come FROM the platform. `add feishu` scan-creates the app; Lark lacks that
+    // control-plane capability, so `add lark` guides console credential collection.
     feishu: {
         env: [
             {
@@ -72,8 +99,8 @@ const CHANNEL_SCAFFOLDS = {
             },
         ],
         steps: [
-            "optional before publishing: add the sensitive im:message.group_msg permission (tenant-admin approval) to receive unmentioned managed-thread continuations and buffer other group discussion",
-            "PUBLISH the app version on the page the CLI opened — the switch to webhook mode takes effect on publish (one click, once ever; no API for it)",
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (the CLI adds it to the app draft when supported); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
+            "PUBLISH the app version in the developer console after permission approval — the switch to webhook mode takes effect on publish (one click, once ever; no API for it)",
             "edit {channel} — routing policy (the header walks through the console setup, for hand-made apps)",
             "the event Request URL is auto-registered by `dev --tunnel` / `deploy --run`",
             "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
@@ -96,7 +123,7 @@ const CHANNEL_SCAFFOLDS = {
         ],
         steps: [
             "finish the console setup: enable Bot and add the required permissions + im.message.receive_v1 event listed in {channel} (do not publish yet)",
-            "optional before publishing: add the sensitive im:message.group_msg permission (tenant-admin approval) to receive unmentioned managed-thread continuations and buffer other group discussion",
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (add it manually if Lark's config API fallback was used); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
             "run `fastagent dev --tunnel` and keep it running; if auto-registration reports a config-API 404, manually switch Subscription mode to webhook, set its printed https://…/lark Request URL, save, then create + publish a version",
             "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
         ],
@@ -104,18 +131,62 @@ const CHANNEL_SCAFFOLDS = {
 };
 /** The channel kinds `fastagent add <kind>` can scaffold. */
 export const CHANNEL_KINDS = Object.keys(CHANNEL_SCAFFOLDS);
-/** The env vars + next-step lines a scaffolded channel needs (for the CLI to print). */
-export function channelSetup(kind) {
-    const { env, steps } = CHANNEL_SCAFFOLDS[kind];
-    return { env, steps };
+const WEBSOCKET_SETUPS = {
+    feishu: {
+        env: CHANNEL_SCAFFOLDS.feishu.env.filter((entry) => ["FEISHU_APP_ID", "FEISHU_APP_SECRET"].includes(entry.name)),
+        steps: [
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (the CLI adds it to the app draft when supported); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
+            "PUBLISH the app version in the developer console after permission approval — long-connection event subscriptions become active with the published version",
+            "edit {channel} — routing policy (the scaffold is already set to WebSocket ingress)",
+            "run `fastagent dev` without --tunnel; deployments must keep one process running (no scale-to-zero)",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/feishu-send.ts tool",
+        ],
+    },
+    lark: {
+        env: CHANNEL_SCAFFOLDS.lark.env.filter((entry) => ["LARK_APP_ID", "LARK_APP_SECRET"].includes(entry.name)),
+        steps: [
+            "before publishing: approve the sensitive im:message.group_msg permission for context-aware groups (add it manually if Lark's config API fallback was used); it delivers all group messages so bare replies in the agent's own threads can invoke and other unsummoned discussion can buffer. im:message:readonly is requested alongside it so a thread's opening ask can carry the message it quotes; both need the same approval",
+            "in Events & Callbacks choose long connection, subscribe im.message.receive_v1, then create + publish a version",
+            "edit {channel} — routing policy (the scaffold is already set to WebSocket ingress)",
+            "run `fastagent dev` without --tunnel; deployments must keep one process running (no scale-to-zero)",
+            "the agent can push messages from scheduled turns via the scaffolded {tools}/lark-send.ts tool",
+        ],
+    },
+};
+/** The mode-specific env vars + next-step lines a scaffolded channel needs. */
+export function channelSetup(kind, ingress = "webhook", groupBehavior) {
+    const behavior = groupBehavior ?? "context";
+    const setup = ingress === "websocket" && (kind === "feishu" || kind === "lark")
+        ? WEBSOCKET_SETUPS[kind]
+        : CHANNEL_SCAFFOLDS[kind];
+    if ((kind === "feishu" || kind === "lark") && behavior === "mentions") {
+        return {
+            env: setup.env,
+            steps: setup.steps.map((step) => step.includes("im:message.group_msg")
+                ? "group behavior: mention-only — do not grant im:message.group_msg; bare thread replies and group context buffering remain disabled. im:message:readonly is independent of this choice: add it if you want an @mention to carry the message it quotes (without it that quote degrades to a marker)"
+                : step),
+        };
+    }
+    if (kind === "slack" && behavior === "mentions") {
+        return {
+            env: setup.env,
+            steps: [
+                "Slack Bot Token Scopes: app_mentions:read, assistant:write, chat:write, im:history, files:read, files:write (no channel/group/mpim history scopes)",
+                "enable Agents (agent_view) and token rotation; subscribe app_home_opened, app_context_changed, app_mention, and message.im; set Request URL to <public-url>/slack",
+                "group behavior: mention-only — bare thread replies and unsummoned group context remain disabled",
+                ...setup.steps.slice(2),
+            ],
+        };
+    }
+    return { env: setup.env, steps: setup.steps };
 }
 /**
  * Append a channel's env vars (commented placeholders + hints) to `.env.example`, so a developer who
  * copies it to `.env` finds the vars already there. No-op when there is no `.env.example` or the block
  * is already present. Placeholders only — no real secret lands in the committable template.
  */
-export async function appendChannelEnv(dir, kind) {
-    const file = join(dir, ".env.example");
+export async function appendChannelEnv(dir, kind, ingress = "webhook") {
+    const file = envExamplePath(dir);
     let current;
     try {
         current = await readFile(file, "utf8");
@@ -131,7 +202,9 @@ export async function appendChannelEnv(dir, kind) {
     // Hint on its OWN line above the placeholder (like the base env.example template) — never inline
     // after `=`: loadEnvFile does not strip trailing comments, so an uncommented `KEY=   # hint` (or a
     // value pasted before the `#`) would carry the hint text into the parsed value.
-    const block = `\n${marker}\n${CHANNEL_SCAFFOLDS[kind].env.map((e) => `# ${e.hint}\n# ${e.name}=`).join("\n")}\n`;
+    const block = `\n${marker}\n${channelSetup(kind, ingress)
+        .env.map((e) => `# ${e.hint}\n# ${e.name}=`)
+        .join("\n")}\n`;
     await appendFile(file, block);
     return true;
 }
@@ -146,15 +219,42 @@ function mentionsEnvName(content, name) {
     return content.split("\n").some((line) => new RegExp(`^\\s*#?\\s*${name}\\s*=`).test(line));
 }
 /**
- * Append generated channel secrets to the run-root `.env` (never `.env.example`) after the CLI has
- * verified that `.env` is gitignored. Existing non-empty values are kept — EXCEPT the names listed in
+ * Append generated channel secrets to the agent's `.env` (`.secrets/.env` — never `.env.example`)
+ * Existing non-empty values are kept — EXCEPT the names listed in
  * `overwrite`: those are authoritative (e.g. the credentials of an app `add feishu` JUST minted —
  * skipping them for a stale value would silently discard a fresh, unrecoverable secret). Manual values
  * (e.g. TELEGRAM_BOT_TOKEN from BotFather) are added only as commented placeholders, so the file is
  * ready to edit while no fake secret is committed to the user's mental model.
  */
-export async function appendChannelDotEnv(dir, kind, generated, overwrite = []) {
-    const file = join(dir, ".env");
+export async function appendChannelDotEnv(dir, kind, generated, overwrite = [], ingress = "webhook") {
+    const file = dotEnvPath(dir);
+    const secretsDir = dirname(file);
+    await mkdir(secretsDir, { recursive: true });
+    // THE one exception to "fastagent has no opinion about git": the directory it writes secrets into
+    // carries its own `.gitignore`. `init` writes it, and so does this — the reachable case where it is
+    // missing (a hand-made agent) is exactly the one where the next line mints an unrecoverable app
+    // secret. `wx`, so a file the author wrote is never touched; the accepted cost is that someone who
+    // DELETED it to track secrets deliberately gets it back once. The risk is not symmetric — that is an
+    // annoyance; the other way is a published credential.
+    //
+    // Scoped to the DEFAULT `<agentDir>/.secrets`, which is fastagent's own directory. A dir named by
+    // `FASTAGENT_SECRETS_DIR` belongs to the operator, and this template is `*` plus two negations —
+    // dropping it there would hide that directory's OTHER contents from their `git add`, which is a
+    // bigger harm than the one it prevents, and inflicted on a path they chose deliberately. They get the
+    // fact instead, and own the decision.
+    const owned = secretsDir === join(dir, SECRETS_DIRNAME);
+    let unprotectedSecretsDir;
+    if (owned) {
+        // Only EEXIST is tolerable (already protected, or a concurrent writer). A permission/disk failure on
+        // the file that keeps credentials out of git must surface, not be swallowed.
+        await writeFile(join(secretsDir, ".gitignore"), baseTemplate("secrets.gitignore"), { flag: "wx" }).catch((e) => {
+            if (e.code !== "EEXIST")
+                throw e;
+        });
+    }
+    else if (!(await exists(join(secretsDir, ".gitignore")))) {
+        unprotectedSecretsDir = secretsDir;
+    }
     let current = "";
     try {
         current = await readFile(file, "utf8");
@@ -163,14 +263,15 @@ export async function appendChannelDotEnv(dir, kind, generated, overwrite = [])
         if (e.code !== "ENOENT")
             throw e;
     }
-    const alreadySet = CHANNEL_SCAFFOLDS[kind].env
+    const env = channelSetup(kind, ingress).env;
+    const alreadySet = env
         .filter((e) => !overwrite.includes(e.name) && hasActiveEnvValue(current, e.name))
         .map((e) => e.name);
     const lines = [];
     const written = [];
     const contentLines = current.split("\n");
     let replacedInPlace = false;
-    for (const e of CHANNEL_SCAFFOLDS[kind].env) {
+    for (const e of env) {
         if (alreadySet.includes(e.name))
             continue;
         const value = generated[e.name];
@@ -216,7 +317,7 @@ export async function appendChannelDotEnv(dir, kind, generated, overwrite = [])
             await appendFile(file, `${prefix}${marker}\n${lines.join("\n")}\n`);
         }
     }
-    return { written, alreadySet };
+    return { written, alreadySet, unprotectedSecretsDir };
 }
 /** The path `add <kind>` scaffolds to. */
 function channelPath(dir, kind) {
@@ -230,10 +331,10 @@ export async function channelExists(dir, kind) {
  * Scaffold `channels/<kind>.ts` into {@link dir}. Never clobbers an existing file (the glue is
  * authored content). The wx write is the TOCTOU safety net behind {@link channelExists}.
  */
-export async function scaffoldChannel(dir, kind) {
+export async function scaffoldChannel(dir, kind, options = {}) {
     const channelsDir = join(dir, "channels");
-    // Don't write through a channels/ symlink that escapes the workspace; an in-workspace one is fine.
-    await assertInsideWorkspace(dir, "channels");
+    // Don't write through a channels/ symlink that escapes the agent dir; one inside it is fine.
+    await assertInsideAgentDir(dir, "channels");
     const file = channelPath(dir, kind);
     if (await exists(file)) {
         throw new Error(`${file} already exists — edit it, or remove it to re-scaffold`);
@@ -242,8 +343,42 @@ export async function scaffoldChannel(dir, kind) {
     // `channel.ts` is THE adapter (→ channels/<kind>.ts); any other .ts in the bundle is a companion tool
     // (→ tools/<name>, never clobbering an authored one).
     for (const name of channelBundleFiles(kind)) {
-        const content = channelTemplate(kind, name);
+        let content = channelTemplate(kind, name);
         if (name === "channel.ts") {
+            if ((kind === "feishu" || kind === "lark") && options.ingress === "websocket") {
+                const factory = `${kind}Channel`;
+                const wsFactory = `${kind}WebSocketChannel`;
+                let configured = content
+                    .replace(`import { ${factory} }`, `import { ${wsFactory} }`)
+                    .replace(`export default ${factory}({`, `export default ${wsFactory}({`);
+                if (configured === content)
+                    throw new Error(`${kind} channel template has no factory anchors`);
+                const prefix = kind === "feishu" ? "FEISHU" : "LARK";
+                const exportAt = configured.indexOf("export default");
+                const importEnd = configured.indexOf("\n\n");
+                if (exportAt < 0 || importEnd < 0)
+                    throw new Error(`${kind} channel template header anchors are missing`);
+                const brand = kind === "feishu" ? "Feishu" : "Lark";
+                configured =
+                    `${configured.slice(0, importEnd)}\n\n` +
+                        `// ${brand} WebSocket long connection: the process connects OUT to the platform, so no public URL,\n` +
+                        `// Verification Token, Encrypt Key, or --tunnel is needed. In Events & Callbacks choose long\n` +
+                        `// connection, subscribe im.message.receive_v1, then publish the app version. Keep one process\n` +
+                        `// running in production: scale-to-zero/App Sleeping would disconnect ingress.\n` +
+                        configured.slice(exportAt);
+                configured = configured
+                    .split("\n")
+                    .filter((line) => !line.includes(`verificationToken: process.env.${prefix}_VERIFICATION_TOKEN`) &&
+                    !line.includes(`encryptKey: process.env.${prefix}_ENCRYPT_KEY`))
+                    .join("\n");
+                content = configured;
+            }
+            if (kind === "slack" && options.groupBehavior === "mentions") {
+                const configured = content.replace('groupBehavior: "context"', 'groupBehavior: "mentions"');
+                if (configured === content)
+                    throw new Error("slack channel template has no groupBehavior anchor");
+                content = configured;
+            }
             await writeFile(file, content, { flag: "wx" });
             continue;
         }
@@ -256,7 +391,7 @@ export async function scaffoldChannel(dir, kind) {
     return file;
 }
 /**
- * Verify the workspace is ready to host a channel: an ESM package.json that declares
+ * Verify the AGENT DIR is ready to host a channel: an ESM package.json that declares
  * `@fastagent-sh/fastagent` (the channel file imports it). `add` checks and guides, never bootstraps — that
  * is `init`'s job.
  */
@@ -268,11 +403,11 @@ export async function assertChannelReady(dir) {
     }
     catch (e) {
         if (e.code === "ENOENT") {
-            // `dir` is where the kit lives (agentDir when set) — "run init" is only the right advice when no
-            // workspace exists yet; a kit missing its manifest (e.g. a --minimal init) needs the manifest, not init.
-            throw new Error(`${dir}: no package.json — a channel adapter is code and needs the kit's own manifest. ` +
-                `Run \`fastagent init\` for a fresh workspace, or add a package.json with @fastagent-sh/fastagent there ` +
-                `(a --minimal init has none)`);
+            // `dir` is the AGENT dir, so `fastagent init` here would nest a second agent inside it — the
+            // right remedy is the missing manifest (a --minimal init writes none), or init in the workspace.
+            throw new Error(`${dir}: no package.json — a channel adapter is code and needs the agent's own manifest. ` +
+                `Add a package.json declaring @fastagent-sh/fastagent there (a --minimal init writes none), ` +
+                `or run \`fastagent init\` in the workspace for a fresh agent`);
         }
         throw e;
     }

package/dist/scaffold/init.d.ts

@@ -1,54 +1,45 @@
+/** The agent directory name for a raw `--agent-dir` value: the default when unset, and `./bot` read as
+ *  `bot` — `basename` already says that is what it means, so rejecting the spelling would be pedantry. */
+export declare function agentDirName(raw: string | undefined): string;
+/** Why `name` cannot be an agent directory name, or undefined when it can. It must stay ONE segment
+ *  inside the target: anything else (a separator, `..`, an absolute path) would land the agent where the
+ *  one-level lookup cannot see it — an agent nothing would ever serve.
+ *
+ *  Returns the CONSTRAINT, not a sentence: the CLI prefixes the flag it owns and reports it as the usage
+ *  error it is (exit 2), while {@link scaffoldAgent} prefixes the option name for a programmatic caller,
+ *  who never passed a flag and should not be told to fix one. */
+export declare function agentDirNameError(name: string): string | undefined;
 export interface ScaffoldOptions {
     /** Scaffold the markdown-only unit (no package.json, no tool, no install) instead of a complete agent. */
     minimal?: boolean;
-    /**
-     * Place the agent kit (persona.md/skills/tools/package.json) in this subdirectory (e.g. "./agent")
-     * instead of flat in `dir`; the config is written at the root with `agentDir` pointing there.
-     * Undefined = flat. The CLI decides (jurisdiction detection + flags); this stays mechanical.
-     */
+    /** The agent directory's name inside `dir` — default {@link DEFAULT_AGENT_DIRNAME}, `"."` for `dir`
+     *  itself. ONE path segment: a separator or `..` would put the agent outside the directory the author
+     *  named, where the one-level lookup could never find it. */
     agentDir?: string;
 }
 export interface ScaffoldResult {
     dir: string;
     /** Whether a complete (code-tool) agent was scaffolded (false for --minimal). */
     complete: boolean;
-    /** The kit subdirectory in effect (relative, e.g. "./agent"); undefined = flat. */
-    agentDir?: string;
-    /** Files written by this run (relative paths). */
+    /** The agent dir relative to `dir`: the {@link ScaffoldOptions.agentDir} that was used. */
+    agentDir: string;
+    /** Files written by this run (relative to `dir`). */
     created: string[];
-    /** Files that already existed and were kept untouched (e.g. a pre-existing .gitignore). */
-    skipped: string[];
-    /** Kept ignore files appended with missing fastagent excludes (root .gitignore: .env/.fastagent, plus
-     *  node_modules/ in the flat layout; kit .gitignore in the agentDir layout: node_modules/). */
-    patched: string[];
-    /** True if the target already had content before this run (init into an existing/non-empty dir). */
-    intoNonEmpty: boolean;
-    /** Non-fatal advisories the caller MUST surface. */
-    warnings: string[];
+    /** Files that already existed and were KEPT untouched. Only reachable with `agentDir: "."` (a
+     *  subdirectory target is proven empty first): adopting a directory means its `.gitignore`/
+     *  `package.json` are the author's. The caller surfaces them — silently skipping a file the user
+     *  expected would be worse. */
+    kept: string[];
 }
 /**
- * Jurisdiction signals: evidence that an existing system already claims this tree, so a flat agent kit
- * would put each side's files under the other's jurisdiction (host tsc sweeps agent .ts; fastagent
- * scans host tools/). Three classes, derived from the actual failure modes — a toolchain config, a
- * deploy manifest, or fastagent's convention names already occupied. Any hit → the kit defaults into
- * `./agent`. Deliberately NOT signals: "dir is non-empty", "has package.json", "has src/" — markdown
- * and loose scripts are claimed by nobody, and "a directory is an agent" stays the default. Known
- * tradeoff, decided for visibility: a HAND-BUILT agent dir (skills//tools/ authored for the agent, no
- * config yet) also hits the occupation signal and defaults to ./agent — wrong for that case, but the
- * reason is printed and `--flat` overrides; the reverse default would silently mis-scan a host's dirs.
- */
-export declare function detectHostSignals(dir: string): Promise<string[]>;
-/** The `cd` target to show in `init`'s next-steps: the relative path when the target is inside `cwd`,
- *  the absolute path when it climbs out (a `../../..` is noise), or undefined when already in `cwd`. */
-export declare function nextStepCd(cwd: string, dir: string): string | undefined;
-/** Does a path exist? (async; shared with the sibling scaffold modules). */
-export declare function exists(p: string): Promise<boolean>;
-/**
- * Scaffold a runnable workspace into {@link dir} (created if missing). Default is a complete agent
- * (persona.md + the writing-great-skills skill + a code tool + package.json); `--minimal` drops the
- * code tool and package.json. The kit goes flat into `dir`, or into {@link ScaffoldOptions.agentDir}
- * (config at the root pointing there). Refuses only an existing fastagent.config.* (the ownership
- * marker — already a workspace); every other pre-existing file (AGENTS.md, .gitignore, package.json)
- * is kept, never overwritten — an existing AGENTS.md is the project's context, adopted as-is.
+ * Scaffold a runnable agent into `<dir>/<agentDir>/` — or into `dir` itself when `agentDir` is `"."`
+ * (both created if missing). Default is a complete agent (persona.md + the writing-great-skills skill +
+ * a code tool + package.json); `--minimal` drops the code tool and package.json.
+ *
+ * A SUBDIRECTORY target must be empty (any content there is an unfinished agent or something unrelated,
+ * and landing persona.md beside it would be a silent mix), while `"."` is a directory being adopted —
+ * content is expected. So `"."` KEEPS every file that already exists (reported, never overwritten, never
+ * verified) and refuses only on a config, which means the directory is already an agent. An existing
+ * AGENTS.md is untouched either way: that is the project's context, adopted as-is.
  */
-export declare function scaffoldWorkspace(dir: string, options?: ScaffoldOptions): Promise<ScaffoldResult>;
+export declare function scaffoldAgent(dir: string, options?: ScaffoldOptions): Promise<ScaffoldResult>;