@fastagent-sh/fastagent 0.15.0 → 0.16.1

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>;

package/dist/scaffold/init.js

@@ -1,161 +1,118 @@
 /**
- * Init: scaffold a runnable fastagent workspace, offline. Default = a COMPLETE agent (persona.md +
+ * Init: scaffold a runnable fastagent agent, offline. Default = a COMPLETE agent (persona.md +
  * the writing-great-skills skill + a fetch-url code tool + fastagent.config.mjs + package.json +
- * .gitignore); `--minimal` drops the code tool and package.json. persona.md is the agent's identity
- * (prompt segment ①); an existing AGENTS.md is never written or touched — it is project context (②),
- * kept as-is. skills/ and tools/ are the agent's self-editable capabilities (re-read each turn).
+ * .gitignore + .secrets/); `--minimal` drops the code tool and package.json. persona.md is the agent's
+ * identity (prompt segment ①); an existing AGENTS.md is never written or touched — it is project
+ * context (②), kept as-is. skills/ and tools/ are the agent's self-editable capabilities (re-read each
+ * turn).
  *
- * Layout (the jurisdiction rule — core.md scenario grid): the agent kit goes FLAT into `dir` ("a
- * directory is an agent") UNLESS an existing system already CLAIMS the tree — a toolchain config that
- * sweeps files by pattern (tsconfig/framework configs), a deploy manifest (Dockerfile/fly/railway/…),
- * or fastagent's own convention names already occupied (non-empty tools//channels//skills/). Any such
- * signal → the kit defaults into `./agent` (its own namespace; `config.agentDir` points there), so the
- * host's toolchain and the agent's surface never sweep each other. {@link detectHostSignals} detects;
- * the CLI decides (flags override) and reports the reason.
+ * Placement — no detection and no prompt, just a default and one flag. By DEFAULT the whole agent —
+ * definition, config, `.secrets/`, machinery — lands in `<dir>/fastagent/`; the surrounding tree gets
+ * ZERO writes and becomes the workspace the agent works on. `--agent-dir <name>` picks another name for
+ * that directory (`fastagent.config.*` is the marker of what IS an agent, never the name), and `--agent-dir .`
+ * (spelled `--flat`) lands the identical shape in `dir` itself, for the case where the directory IS the
+ * agent (a standalone agent repo, a monorepo package).
+ *
+ * Which of the two a served agent turns out to be is NOT decided here: the workspace is whatever
+ * fastagent is later pointed at (resolvePlacement). This module only chooses where the files land — so
+ * its one placement duty is to refuse a target that the lookup would not return (see below).
  *
  * Scope: init is best-effort atomic for ORDINARY inputs — it never overwrites existing files,
- * preflights non-directory scaffold parents, and rolls back a partial write (one exception: the
- * .gitignore APPEND is not rolled back — idempotent, harmless residue). It does not defend against
+ * preflights non-directory scaffold parents, and rolls back a partial write (files AND the
+ * `fastagent/` tree it created for them, so a retry sees a clean slate). It does not defend against
  * every pathological target state (TOCTOU, FIFOs, disk-full): recover by delete-and-retry.
  *
  * Sibling scaffold modules: add-channel.ts (`add <channel>`), vendor-skill.ts (`add skill`). The files
  * this module writes are real templates under templates/, read through templates.ts.
  */
-import { access, appendFile, lstat, mkdir, readdir, rm, writeFile } from "node:fs/promises";
-import { dirname, join, relative } from "node:path";
-import { WORKSPACE_CONFIG_NAMES } from "../engines/pi/config.js";
-import { detectRuntime, readPackageJson } from "../runtime.js";
-import { loadRootIgnore } from "../workspace.js";
-import { baseTemplate, configTemplate, packageJson, personaTemplate, toPackageName } from "./templates.js";
+import { lstat, mkdir, readdir, rm, rmdir, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { AGENT_CONFIG_NAMES, DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentDefinitionOwner, agentsAt, displayPath, exists, } from "../paths.js";
+import { baseTemplate, packageJson, toPackageName } from "./templates.js";
 import { fastagentVersion } from "../version.js";
-/** Filename marks of a system that claims files by pattern (a build toolchain — F2 in the jurisdiction
- *  rule). Not JS-only: a Python/Go/Rust/JVM/Ruby/PHP project's build system claims its tree exactly the
- *  same way — an AGENTS.md-carrying Go repo must not get a flat kit (with a package.json!) in its root.
- *  Deliberately absent: `Makefile` (too generic — notes/dotfiles repos carry one without a toolchain). */
-const TOOLCHAIN_RE = /^(tsconfig\.json|(next|vite|astro|svelte|nuxt|remix|webpack|rollup)\.config\.[cm]?[jt]s|go\.mod|Cargo\.toml|pyproject\.toml|setup\.py|requirements\.txt|Gemfile|pom\.xml|build\.gradle(\.kts)?|composer\.json|CMakeLists\.txt)$/;
-/** Filename marks of a deploy manifest — the tree ships as a non-agent unit (F4). */
-const DEPLOY_RE = /^(Dockerfile|fly\.toml|railway\.toml|vercel\.json|netlify\.toml)$/;
-/**
- * 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 async function detectHostSignals(dir) {
-    // Only ENOENT/ENOTDIR mean "nothing there" (fresh dir → flat). A real IO failure (EACCES…) must
-    // surface, not silently decide the layout — init is about to write into this directory anyway.
-    const absent = (err) => {
-        const code = err.code;
-        if (code === "ENOENT" || code === "ENOTDIR")
-            return [];
-        throw err;
-    };
-    const signals = [];
-    const entries = await readdir(dir, { withFileTypes: true }).catch(absent);
-    for (const e of entries) {
-        if (e.isFile() && (TOOLCHAIN_RE.test(e.name) || DEPLOY_RE.test(e.name)))
-            signals.push(e.name);
-    }
-    for (const name of ["tools", "channels", "skills"]) {
-        const st = await lstat(join(dir, name)).catch((err) => {
-            absent(err);
-            return undefined;
-        });
-        // Dotfiles (.DS_Store, .gitkeep) are not agent surface — the loaders would never scan them, so
-        // they must not count as "occupied" either (the signal mirrors what fastagent would actually scan).
-        const occupants = st?.isDirectory()
-            ? (await readdir(join(dir, name)).catch(absent)).filter((f) => !f.startsWith("."))
-            : [];
-        if (occupants.length > 0)
-            signals.push(`${name}/`);
-    }
-    return signals.sort();
+/** 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 function agentDirName(raw) {
+    if (raw === undefined)
+        return DEFAULT_AGENT_DIRNAME;
+    const trimmed = raw.replace(/^\.[/\\]/, "");
+    return trimmed === "" ? raw : trimmed;
 }
-/** 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 function nextStepCd(cwd, dir) {
-    const rel = relative(cwd, dir);
-    if (rel === "")
+/** 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 function agentDirNameError(name) {
+    if (name === "." || (name !== "" && name !== ".." && name === basename(name)))
         return undefined;
-    // "Climbs out" is a path-SEGMENT check — rel is ".." or starts with "../" (or "..\" on Windows). A
-    // bare startsWith("..") would wrongly flag an in-cwd directory literally named "..agent".
-    const escapes = rel === ".." || /^\.\.[/\\]/.test(rel);
-    return escapes ? dir : rel;
-}
-/** Does a path exist? (async; shared with the sibling scaffold modules). */
-export async function exists(p) {
-    return access(p).then(() => true, () => false);
+    return (`must be a single directory name (or "." for the target itself) — a path would put the agent outside ` +
+        `the target directory, where fastagent would not find it`);
 }
 /**
- * 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 async function scaffoldWorkspace(dir, options = {}) {
+export async function scaffoldAgent(dir, options = {}) {
     const minimal = options.minimal ?? false;
-    const kit = options.agentDir ?? "."; // where the agent's own surface lands
+    const root = agentDirName(options.agentDir);
+    const flat = root === ".";
+    const invalid = agentDirNameError(root);
+    if (invalid)
+        throw new Error(`agentDir "${root}" ${invalid}`);
     const skill = (name) => ({
-        rel: join(kit, "skills", "writing-great-skills", name),
+        rel: join(root, "skills", "writing-great-skills", name),
         content: baseTemplate(`skills/writing-great-skills/${name}`),
     });
     const files = [
         // ① identity. AGENTS.md is deliberately NOT scaffolded: a fresh agent has no project context, and
-        // an existing repo already owns its AGENTS.md (kept untouched, read as ② context from cwd).
-        { rel: join(kit, "persona.md"), content: personaTemplate(options.agentDir) },
+        // an existing repo already owns its AGENTS.md (kept untouched, read as ② context from the workspace).
+        { rel: join(root, "persona.md"), content: baseTemplate("persona.md") },
         // The example skill: how to author skills well — the core of self-iteration. Markdown, so it
         // ships in --minimal too. Vendored verbatim from mattpocock/skills (MIT); LICENSE sits beside it.
         skill("SKILL.md"),
         skill("GLOSSARY.md"),
         skill("LICENSE"),
-        // Run-root pieces: the config (carrying agentDir when the kit is a subdir), secrets hygiene, env template.
-        { rel: "fastagent.config.mjs", content: configTemplate(options.agentDir) },
-        { rel: ".gitignore", content: baseTemplate(options.agentDir ? "gitignore.agentdir-root" : "gitignore") },
-        { rel: ".env.example", content: baseTemplate("env.example") },
+        { rel: join(root, "fastagent.config.mjs"), content: baseTemplate("fastagent.config.mjs") },
+        // Two ignore files, scaffolded ONCE and owned by the author from then on — no command rewrites,
+        // reads or verifies them. The agent's own covers node_modules/machinery/a stray .env; `.secrets/`
+        // carries its own because the root file is the one the author has reason to edit, and git's
+        // nested-ignore precedence keeps the credentials protected whatever happens up there.
+        { rel: join(root, ".gitignore"), content: baseTemplate("gitignore") },
+        { rel: join(root, SECRETS_DIRNAME, ".gitignore"), content: baseTemplate("secrets.gitignore") },
+        { rel: join(root, SECRETS_DIRNAME, ".env.example"), content: baseTemplate("env.example") },
     ];
     if (!minimal) {
-        files.push({ rel: join(kit, "tools", "fetch-url.ts"), content: baseTemplate("tools/fetch-url.ts") }, 
-        // The kit's own manifest: in the agentDir layout the agent self-contains its deps, so the host's
-        // package.json/lockfile is never touched. The name says WHOSE agent it is (the workspace's), not
-        // which subdirectory it happens to live in.
+        files.push({ rel: join(root, "tools", "fetch-url.ts"), content: baseTemplate("tools/fetch-url.ts") }, 
+        // The agent's own manifest, named after the directory it serves (`<dir>-agent`) — except when it
+        // IS that directory, where it takes the name straight.
         {
-            rel: join(kit, "package.json"),
-            content: packageJson(options.agentDir ? `${toPackageName(dir)}-agent` : toPackageName(dir), await fastagentVersion()),
-        }, ...(options.agentDir ? [{ rel: join(kit, ".gitignore"), content: baseTemplate("gitignore.kit") }] : []));
+            rel: join(root, "package.json"),
+            content: packageJson(flat ? toPackageName(dir) : `${toPackageName(dir)}-agent`, await fastagentVersion()),
+        });
     }
-    // Guard on the ownership marker: a config means "already a fastagent workspace". Fail visibly
-    // rather than double-initialize. (AGENTS.md is NOT a marker — it is context, adopted untouched.)
-    const conflicts = [];
-    for (const name of WORKSPACE_CONFIG_NAMES)
-        if (await exists(join(dir, name)))
-            conflicts.push(name);
-    if (conflicts.length > 0) {
-        throw new Error(`"${dir}" already has ${conflicts.join(", ")} — already a fastagent workspace`);
+    // Inside another agent's DEFINITION (its `skills/`, `tools/`, `channels/` or `schedules/`): the outer
+    // agent would load the new one as its own content. Note what this deliberately ALLOWS — a package
+    // inside an agent's repository, which is the author's tree and not part of what that agent loads.
+    const owner = agentDefinitionOwner(dir);
+    if (owner) {
+        throw new Error(`"${dir}" is inside the definition of the agent at ${owner} — an agent scaffolded here would be ` +
+            `part of THAT agent's surface, not one of its own. Init outside it.`);
     }
-    // Never merge the kit into an existing NON-EMPTY directory (a host repo may own an unrelated `agent/`
-    // — common in AI products): wx would keep its files, but persona.md/skills/ landing inside someone
-    // else's code dir is a silent mix. Refuse with the way out. Dotfiles (.DS_Store, .gitkeep) don't
-    // count — same rule as detectHostSignals' occupation check. A SYMLINKED kit path slips past this
-    // readdir (it follows links) — deliberate: the parent preflight below lstat-rejects it before any write.
-    if (options.agentDir) {
-        const occupants = (await readdir(join(dir, kit)).catch(() => [])).filter((f) => !f.startsWith("."));
-        if (occupants.length > 0) {
-            throw new Error(`"${kit}" already exists and is not empty — if it is unrelated to the agent, pick another name ` +
-                `(--agent-dir <name>) or go flat (--flat); to adopt it as the kit, empty it first`);
-        }
-    }
-    // Was the target non-empty BEFORE we wrote anything? (missing dir = empty).
-    const intoNonEmpty = (await readdir(dir).catch(() => [])).length > 0;
-    // Preflight scaffold parent dirs: a pre-existing non-directory there would make mkdir fail mid-loop
-    // AFTER the first write, leaving a half-scaffold. Detect it before any write (lstat, not stat: a
-    // symlinked parent must be rejected, not followed — it would write outside the workspace).
+    // Preflight scaffold parent dirs FIRST: a pre-existing non-directory there would make mkdir fail
+    // mid-loop AFTER the first write, leaving a half-scaffold — and a file or symlink named `fastagent`
+    // must be named as such here, before the occupancy check below tries to read it as a directory
+    // (lstat, not stat: a symlinked parent must be rejected, not followed — it would write outside the
+    // agent dir).
     const parents = new Set();
     for (const file of files) {
         let p = dirname(file.rel);
@@ -170,80 +127,99 @@ export async function scaffoldWorkspace(dir, options = {}) {
             throw new Error(`cannot scaffold: "${rel}" exists and is not a directory (a regular file or symlink) — remove it, or init elsewhere`);
         }
     }
+    // Refuse an occupied agent dir. A config inside means it IS an agent already (name the marker so the
+    // message is actionable); any other content means an unfinished agent or something unrelated, and
+    // landing persona.md beside it would be a silent mix. Only ENOENT reads as "empty" — any other fault
+    // (EACCES…) must surface here rather than as a raw errno mid-write.
+    // (AGENTS.md outside is NOT a marker — it is context, adopted untouched.)
+    // `.DS_Store`/`.gitkeep`/`.keep` are not evidence of anyone's content: Finder noise, and the standard
+    // way to commit an empty directory (someone reserving the name in git ahead of init).
+    const occupants = (await readdir(join(dir, root)).catch((e) => {
+        if (e.code === "ENOENT")
+            return [];
+        throw e;
+    })).filter((f) => ![".DS_Store", ".gitkeep", ".keep"].includes(f));
+    // Could `dir` still SELECT the agent this run creates? SIBLINGS are fine — several agents at one level
+    // is a supported shape (different roles driving one repository), picked between by FASTAGENT_AGENT or
+    // the default name. A SHADOW is not: a config AT `dir` wins over everything inside it, so scaffolding
+    // under one (or scaffolding one over existing children) makes an agent the lookup can never return.
+    // The target itself is never in the way — a config already there means "already an agent", which the
+    // refusal below says in those words.
+    const existing = agentsAt(dir).filter((a) => a !== resolve(dir, root));
+    const shadowed = flat
+        ? existing // the new agent lands AT `dir` and hides everything inside it
+        : existing.filter((a) => a === resolve(dir)); // an agent AT `dir` hides the new one inside it
+    if (shadowed.length > 0) {
+        throw new Error(`"${dir}" already resolves to ${shadowed.map((a) => displayPath(process.cwd(), a) ?? a).join(", ")} — ` +
+            `an agent scaffolded ${flat ? "here" : `in ./${root}/`} would be hidden by it and never served ` +
+            `from "${dir}" (an agent AT a directory wins over any inside it). Use that agent, move it away, ` +
+            `or init in a different directory.`);
+    }
+    // ONE coordinate system for both refusals — `displayPath` is the shared policy (relative inside the
+    // cwd, absolute when it climbs out); the earlier pair mixed an absolute path with a basename-relative
+    // one, in adjacent branches of the same command.
+    const target = displayPath(process.cwd(), join(dir, root)) ?? join(dir, root);
+    const config = occupants.filter((f) => AGENT_CONFIG_NAMES.includes(f));
+    if (config.length > 0) {
+        throw new Error(`"${target}" already has ${config.join(", ")} — already a fastagent agent`);
+    }
+    // Only a SUBDIRECTORY target must be empty. `.` is a directory being adopted — content is expected,
+    // and every existing file is kept below.
+    if (!flat && occupants.length > 0) {
+        throw new Error(`"${target}" already holds ${occupants.join(", ")} — move it away first, or run ` +
+            `\`fastagent init\` in a different directory`);
+    }
+    // Which directories were OURS to create? "Empty" is not ownership: a user may have pre-created any of
+    // them (`--agent-dir .` adopts a directory that can already carry an empty `skills/` or `.secrets/`),
+    // and the rollback below must delete only what THIS run made. Recorded before the first write, since
+    // afterwards the two are indistinguishable.
+    const preexisting = new Set();
+    for (const rel of parents)
+        if (await exists(join(dir, rel)))
+            preexisting.add(rel);
+    const agentDirExisted = await exists(join(dir, root));
     await mkdir(dir, { recursive: true });
     const created = [];
-    const skipped = [];
-    const patched = [];
-    const warnings = [];
-    // ONE rollback scope: any failure removes files written THIS run (guard + wx guarantee they are
-    // ours), so scaffoldWorkspace is atomic — except the .gitignore APPEND below, which is not rolled
-    // back (the residue is idempotent, harmless ignore lines; removing someone else's file's tail is riskier).
+    const kept = [];
+    // ONE rollback scope: any failure removes what THIS run created — files AND the directories it made
+    // for them. Leaving the empty dirs behind would be worse than untidy: the occupancy refusal above
+    // would then report the next `init` as occupied, blaming the user for our own debris.
+    //
+    // `wx` never clobbers. A subdirectory target was proven empty, so EEXIST means a concurrent writer —
+    // an error. `.` is a directory being adopted, so an existing `.gitignore`/`package.json` is the
+    // author's — keep it and report it.
     try {
         for (const file of files) {
             const abs = join(dir, file.rel);
             await mkdir(dirname(abs), { recursive: true });
             try {
-                await writeFile(abs, file.content, { flag: "wx" }); // wx: never clobber
+                await writeFile(abs, file.content, { flag: "wx" });
                 created.push(file.rel);
             }
-            catch (error) {
-                if (error.code === "EEXIST")
-                    skipped.push(file.rel);
-                else
-                    throw error;
+            catch (e) {
+                if (!flat || e.code !== "EEXIST")
+                    throw e;
+                kept.push(file.rel);
             }
         }
-        // Ignore ownership follows layout jurisdiction. Run-root state/secrets live at `dir`, so the ROOT
-        // .gitignore owns `.env` + `.fastagent`. The kit's npm deps live where the kit lives: flat → root
-        // `node_modules/`; agentDir → `<agentDir>/.gitignore` owns its own `node_modules/`. This avoids
-        // patching a host repo's root ignore with agent-internal dependency paths while still preventing the
-        // post-init 25k-file untracked flood.
-        const coveredBy = (ig, p) => (ig?.ignores(p) ?? false) || (ig?.ignores(`${p}/`) ?? false);
-        const rootIgnore = await loadRootIgnore(dir);
-        const rootRequired = [
-            { path: ".env", pattern: ".env" },
-            { path: ".fastagent", pattern: ".fastagent" },
-            ...(!minimal && !options.agentDir ? [{ path: "node_modules", pattern: "node_modules/" }] : []),
-        ];
-        const rootNeed = rootRequired.filter((e) => !coveredBy(rootIgnore, e.path));
-        if (rootNeed.length > 0) {
-            await appendFile(join(dir, ".gitignore"), `\n# fastagent\n${rootNeed.map((e) => e.pattern).join("\n")}\n`);
-            patched.push(".gitignore");
-            // A .fastagentignore is applied LAST and can re-include what .gitignore excludes — the append
-            // cannot fix that, so re-check and keep it a visible warning instead of false assurance.
-            const after = await loadRootIgnore(dir);
-            const still = rootNeed.filter((e) => !coveredBy(after, e.path)).map((e) => e.path);
-            if (still.length > 0) {
-                warnings.push(`your .gitignore/.fastagentignore does not exclude ${still.map((s) => `"${s}"`).join(", ")} — a deploy that copies the directory may ship secrets/state`);
-            }
-        }
-        if (!minimal && options.agentDir) {
-            // Deliberately checks ONLY the kit's own ignore, not the root: the kit is the portable agent
-            // directory, and its dependency ignore must travel WITH it (a fresh kit .gitignore carries
-            // node_modules/ unconditionally for the same reason) — a root-level `node_modules/` that happens
-            // to cover it today doesn't survive the kit being copied out of the host repo.
-            const kitIgnore = await loadRootIgnore(join(dir, kit));
-            if (!coveredBy(kitIgnore, "node_modules")) {
-                const rel = join(kit, ".gitignore");
-                await appendFile(join(dir, rel), `\n# fastagent\nnode_modules/\n`);
-                patched.push(rel);
-            }
-        }
-        // A kept package.json won't carry the tool's deps — the example tool would not resolve. The install
-        // command matches the workspace's runtime (bun.lock → bun add).
-        const keptPkg = join(kit, "package.json");
-        if (!minimal && skipped.includes(keptPkg)) {
-            const kitAbs = join(dir, kit);
-            const add = detectRuntime(kitAbs, await readPackageJson(kitAbs)).runtime === "bun" ? "bun add" : "npm install";
-            warnings.push(`kept the existing ${keptPkg} — run \`${add} @fastagent-sh/fastagent\` there so the example tool resolves`);
-        }
     }
     catch (error) {
-        // Best-effort rollback of a partial scaffold: a file that won't delete is left behind (the original
-        // error below is the one worth surfacing — a cleanup failure must not mask it).
+        // Best-effort rollback of a partial scaffold: anything that won't delete is left behind (the
+        // original error below is the one worth surfacing — a cleanup failure must not mask it). Files
+        // first, then the directories THIS RUN created, deepest first; `rmdir` additionally removes only
+        // what is empty, so a pre-existing sibling inside one of ours is never touched. The agent root goes
+        // last, and only when this run created it — "empty" was never proof of ownership. (Reaching here at all takes a
+        // real fs fault: the occupancy refusal above proved the target empty, so nothing else can fail
+        // mid-loop. The covered case is a permission fault before the first write.)
         for (const rel of created.reverse())
             await rm(join(dir, rel), { force: true }).catch(() => { });
+        for (const rel of [...parents].sort((a, b) => b.split(sep).length - a.split(sep).length)) {
+            if (rel !== root && !preexisting.has(rel))
+                await rmdir(join(dir, rel)).catch(() => { });
+        }
+        if (!agentDirExisted)
+            await rmdir(join(dir, root)).catch(() => { });
         throw error;
     }
-    return { dir, complete: !minimal, agentDir: options.agentDir, created, skipped, patched, intoNonEmpty, warnings };
+    return { dir, complete: !minimal, agentDir: root, created, kept };
 }

package/dist/scaffold/templates/env.example

@@ -1,5 +1,5 @@
-# Environment for this agent. Copy to .env (gitignored) and uncomment what you need.
-# Everything here is OPTIONAL — the defaults work without a .env.
+# Environment for this agent. Copy to .env IN THIS DIRECTORY (.secrets/.env — gitignored, managed by
+# fastagent) and uncomment what you need. Everything here is OPTIONAL — the defaults work without a .env.
 
 # --- Model auth ---
 # Pick auth once: `fastagent login` (a subscription/OAuth provider like openai-codex, or an API key),
@@ -8,6 +8,11 @@
 # OPENAI_API_KEY=
 # ANTHROPIC_API_KEY=
 
+# --- Which agent (only when a workspace holds several) ---
+# FASTAGENT_AGENT names the agent directory to serve. It CANNOT be set here: placement resolves before
+# this file is read (it is what decides whose .env this is). Put it in your shell, an .envrc, or the
+# command: `FASTAGENT_AGENT=pm fastagent dev`.
+
 # --- Model selection (overrides fastagent.config) ---
 # Precedence: --model flag > FASTAGENT_MODEL > config. `fastagent dev` writes your first-run pick to
 # fastagent.config; set it here to override per-environment.
@@ -16,9 +21,13 @@
 # --- Serving (fastagent start) ---
 # Port precedence: --port > PORT > config.http.port > 8787
 # PORT=8787
-# Machine-state root: sessions, auth.json, and channel state all derive from it.
-# Default: <dir>/.fastagent. Point it at a mounted volume so a redeploy that replaces the
-# directory keeps conversations and credentials.
-# FASTAGENT_STATE_DIR=/data/fastagent
+# Machine-state root: sessions, schedule state, and channel state derive from it.
+# Default: <agent dir>/.state. Point it at a mounted volume so a redeploy that replaces the
+# directory keeps conversations.
+# FASTAGENT_STATE_DIR=/data/.state
+# Secrets home (this .env + auth.json). Default: <agent dir>/.secrets. Deployments point it at
+# the volume so a rotated OAuth credential persists across restarts. Set HERE it moves only
+# auth.json — a value inside .env cannot relocate the .env being read.
+# FASTAGENT_SECRETS_DIR=/data/.secrets
 # Override just the sessions path (default: <state root>/sessions):
 # FASTAGENT_SESSIONS_DIR=/data/sessions

package/dist/scaffold/templates/fastagent.config.mjs

@@ -1,6 +1,6 @@
 // fastagent.config.mjs — deployment choices only (model / http; code tools auto-discover from tools/).
 // Your agent's identity lives in persona.md; its capabilities in skills/ + tools/ — never here.
-// An AGENTS.md at the workspace root (yours or the host repo's) is read as project context.
+// An AGENTS.md in the WORKSPACE (the directory the agent is started in) is read as project context.
 // Model precedence: `--model` flag > FASTAGENT_MODEL env > this default.
 // No model is preset: `fastagent dev` shows the full model catalog (models you already have
 // credentials for come first; picking one that needs auth logs you in inline) and writes your choice

package/dist/scaffold/templates/gitignore

@@ -1,8 +1,16 @@
-# secrets — never commit (kept out of git and any deploy copy)
-.env
+# This file is yours — fastagent writes it once, at `init`, and never touches git again.
+# (`.secrets/` carries its own, so the credentials stay protected however you edit this one.)
+
+# dependencies (reinstalled at deploy). No trailing slash on purpose: `node_modules/` matches only a
+# DIRECTORY, so a symlinked one (pnpm, a shared store) would show up as untracked.
+node_modules
 
-# dependencies (reinstalled at deploy)
-node_modules/
+# machine state: sessions, channel state, schedule state
+.state
+.cache
 
-# fastagent machine state (dev/start sessions + project-level auth.json credentials)
-.fastagent/
+# fastagent reads the agent's env from .secrets/.env (which un-ignores its own .env.example). A bare
+# .env at THIS level is the file habit puts here — `dev` says so when it finds one; this keeps it
+# uncommittable meanwhile.
+.env
+.env.*

package/dist/scaffold/templates/persona.md

@@ -1,10 +1,12 @@
 # Persona
 
-You are this workspace's agent. This file is your identity — it overrides the engine's default identity line, and it is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart. Your `read` / `write` / `edit` / `bash` tools operate at the workspace root you were started in; if the workspace has an `AGENTS.md`, it is project context — read it to learn the project's conventions.
+You are this workspace's agent. This file is your identity — it overrides the engine's default identity line, and it is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart.
+
+Your definition is this directory: `persona.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on, and where your `read` / `write` / `edit` / `bash` tools operate. It may be this same directory, or the one containing it; `fastagent info` prints both. If the workspace has an `AGENTS.md`, it is project context — read it to learn the project's conventions.
 
 You can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
 
-- A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
+- A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Only the `skills/` next to this file is scanned. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
 - A standing instruction or fact → edit this file.
 
 Keep both lean: include only what changes your behavior, and delete what no longer earns its place.

package/dist/scaffold/templates/secrets.gitignore

@@ -0,0 +1,5 @@
+# fastagent-managed secrets: everything here stays on this machine —
+# except the template, which travels with the agent.
+*
+!.gitignore
+!.env.example