@sous-io/sous 0.2.3 → 0.2.4

package/README.md

@@ -41,16 +41,22 @@ npm install
 npm link
 ```
 
-Then set up a project. A project needs a `.sous/` directory holding a config file, named
-`sous.config.js`, `sous.config.mjs`, `sous.config.json`, or `sous.config.yaml`:
+Then set up a project:
 
 ```bash
 cd /path/to/your/project
-mkdir .sous
-$EDITOR .sous/sous.config.js
+sous init
 ```
 
-A config that compiles one file:
+`sous init` writes the project's `.sous/` directory and runs the first build. It creates a
+commented `sous.config.js` (pass `--format json` for a JSON config bound to the shipped
+schema), a starter prompt at `.sous/prompts/AGENTS.md` that the config compiles to `AGENTS.md`
+at the project root, the two env files described below, and a `.sous/.gitignore` covering the
+files sous keeps local to one machine. The first build compiles the starter prompt and the
+`core` skills every project gets, and pins them in `.sous/sous.lock.json`. A project that
+already holds a config is left untouched.
+
+The config it writes compiles one file:
 
 ```js
 export const config = {
@@ -59,17 +65,19 @@ export const config = {
   compilation: {
     targets: [
       {
-        entryPoint: "${sousDir}/AGENTS.md",
-        outputs: [{ destinationFile: "${projectRoot}/CLAUDE.md" }],
+        entryPoint: "${sousDir}/prompts/AGENTS.md",
+        outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],
       },
     ],
   },
+  recipeOutputs: { skills: ["${projectRoot}/.claude/skills"] },
 };
 ```
 
 `${sousDir}` is the `.sous/` directory sous found, so a config can name paths relative to
-itself without hardcoding anything machine-specific. One config describes one project. Then
-build:
+itself without hardcoding anything machine-specific. One config describes one project. A
+`.sous/` may hold one config file, named `sous.config.js`, `sous.config.mjs`,
+`sous.config.json`, `sous.config.jsonc` or `sous.config.yaml`. After editing, build:
 
 ```bash
 sous build
@@ -95,6 +103,7 @@ Useful commands:
 
 | Command | What it does |
 |---|---|
+| `sous init` | Set a project up: write `.sous/`, then run the first build |
 | `sous build` | Compile, then prune stale outputs |
 | `sous build --watch` | Rebuild on source changes |
 | `sous compile` | Compile only |

package/docs/markdown/_sidebar.md

@@ -20,3 +20,4 @@
 - **ADRs**
   - [0001: Repositories](adrs/0001-repositories.md)
   - [0002: Recipe answers in the template scope](adrs/0002-recipe-answers-in-templates.md)
+  - [0003: Project setup with sous init](adrs/0003-project-init.md)

package/docs/markdown/commands.md

@@ -46,6 +46,27 @@ Every topic answers to both spellings of its name: `repo` and `repos`, `subscrip
 
 ## Top-level commands
 
+### `sous init [DIRECTORY]`
+Sets a project up for sous: writes its `.sous/` directory, then runs the first build. It is the one command that
+runs before a config exists, and the starting point for a project that has never used sous. It writes a commented
+primary config, a starter prompt at `.sous/prompts/AGENTS.md` that the config compiles to `AGENTS.md` at the
+project root, `.sous/.env` and `.sous/.env.local.example`, and the sous-managed block in `.sous/.gitignore`. The
+first build compiles the starter prompt and the `core` skills, and pins them in `.sous/sous.lock.json`.
+
+A project whose `.sous/` already holds a primary config is refused, and nothing is written. Setting up a directory
+inside a project that is already set up is a question rather than an error, since a subproject may want its own
+instructions; `-y, --yes` answers it ahead of time, and a run with no terminal fails naming that flag.
+
+- `DIRECTORY`: the project directory to set up; the current one by default. `--sous-dir` and `SOUS_DIR` also say
+  where, when no directory is given.
+- `--format <js|json>`: which config to write, `js` by default. The JSON config carries `$schema`, bound to the
+  schema artifact published for the running sous version.
+- `--name <name>`: the display name written into the config; the directory's own name by default.
+- `--no-build`: write the setup without running the first build.
+- `--dry-run`: print the files that would be written without writing them.
+
+Example: `sous init --format json`
+
 ### `sous build`
 Compiles this project's outputs, then removes the ones its config no longer produces. It is compile plus prune,
 and the command you want almost always. Takes `--dry-run`.

package/docs/markdown/config-discovery.md

@@ -57,8 +57,9 @@ first, so setting a location var inside `.env.local` has no effect on discovery.
 
 All are hard `ConfigError`s; sous never guesses:
 
-- **No config found**: the error lists every directory checked during the walk and shows a
-  minimal starter config.
+- **No config found**: the error lists every directory checked during the walk and names the two
+  fixes: run `sous init` in the project's root directory, which writes the config and everything
+  else a first build needs, or pass `--config <path>`.
 - **Multiple primary configs**: two or more of `sous.config.js|mjs|json|jsonc|yaml` in the same
   `.sous/` is an error naming every candidate.
 - **Duplicate layer baseNames**: any two loaded files (primary or conf.d) whose names differ

package/docs/markdown/config-inspection.md

@@ -27,7 +27,10 @@ tooling:
 { "$schema": "./path/to/sous.config.schema.json" }
 ```
 
-The `$schema` key is accepted at the top level and ignored by sous itself.
+The `$schema` key is accepted at the top level and ignored by sous itself. A config written by
+`sous init --format json` binds it to the same artifact as published on GitHub for the running
+version, so an editor resolves it without a path into the installed package; point it at the
+package-local copy instead when the editor should work offline.
 
 ## sous config show
 

package/docs/markdown/configuration.md

@@ -39,7 +39,8 @@ export const config = {
 ```
 
 A JSON config may set `"$schema"` to bind the `sous.config.schema.json` artifact shipped with
-sous for editor autocompletion; sous accepts and ignores the key.
+sous for editor autocompletion; sous accepts and ignores the key. `sous init --format json`
+writes one already bound to the copy of that artifact published for the running version.
 
 ?> Configs use `${var}` syntax. Template files use LiquidJS double-brace syntax instead; the two
 are resolved at different stages and never mix.

package/docs/markdown/repositories-quickstart.md

@@ -24,7 +24,10 @@ echo 'name: my-project' > .sous/sous.config.yaml
 ```
 
 Everything else has a default: skills compile into `<project root>/.claude/skills`, and the
-lockfile, the state file and the config layers sous writes land under `.sous/`. `SOUS_HOME` puts
+lockfile, the state file and the config layers sous writes land under `.sous/`. Outside a
+walkthrough, `sous init` writes a fuller starting point (a commented config, a starter prompt,
+the env files and the ignore block) and runs the first build for you; the one-line config is
+used here so that each step shows one thing. `SOUS_HOME` puts
 the machine-wide store somewhere throwaway, so this walkthrough leaves your real one alone. See
 [The config file](configuration.md) for the keys you will want later.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

package/recipes/core/sous-skills/sous.recipe.yaml

@@ -11,7 +11,7 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.3
+version: 0.2.4
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous

package/src/base-command.ts

@@ -40,6 +40,23 @@ import { reportCommandError } from "./utils/command-errors.js";
  * lives in `lib/interactive.ts`, which also treats a truthy `CI` and a
  * non-terminal stdin or stdout the same way.
  */
+/**
+ * What the config-locating flags and environment said on this run, resolved to
+ * absolute paths but not yet turned into a config.
+ */
+export type ConfigLocator = {
+  /** The working directory discovery started from. */
+  cwd: string;
+  /**
+   * The explicit config location, when one was given: the resolved path and
+   * the flag or environment variable that supplied it (`--config`,
+   * `--sous-config`, `SOUS_CONFIG`, `--sous-dir` or `SOUS_DIR`).
+   */
+  primary?: { value: string; source: string };
+  /** The conf.d directory override, when `--sous-confd` or `SOUS_CONFD` gave one. */
+  confDirOverride?: string;
+};
+
 export abstract class BaseCommand extends Command {
   static baseFlags = {
     config: Flags.string({
@@ -60,11 +77,29 @@ export abstract class BaseCommand extends Command {
     "non-interactive": nonInteractiveFlag(),
   };
 
+  /**
+   * Whether a run of this command needs a project config to exist. Every
+   * command that works on a project leaves this true, and a run that finds no
+   * config fails before `run()` with the "No sous config found" block. The one
+   * command whose job is to CREATE the config sets it false: discovery still
+   * runs, so the config-locating flags still say where the project is, but
+   * finding nothing is the expected case rather than an error, and `settings`
+   * stays unset until `adoptConfig` is given the config that was written.
+   */
+  static requiresConfig = true;
+
   protected settings!: Settings;
 
   /** Where the active config was found. */
   protected configContext!: ConfigContext;
 
+  /**
+   * What the config-locating flags and environment said, before discovery
+   * turned it into a config. A command that runs without a config reads the
+   * project's location from here.
+   */
+  protected configLocator!: ConfigLocator;
+
   /** The full discovery result, including how the config was located. */
   protected discovered!: DiscoveredConfig;
 
@@ -142,6 +177,16 @@ export abstract class BaseCommand extends Command {
       [sousDirEnv, "SOUS_DIR"],
     ];
     const primary = primaryCandidates.find(([value]) => value !== undefined);
+    const requiresConfig = (this.constructor as typeof BaseCommand).requiresConfig;
+
+    this.configLocator = {
+      cwd,
+      primary:
+        primary !== undefined
+          ? { value: path.resolve(cwd, expandHome(primary[0] as string)), source: primary[1] }
+          : undefined,
+      confDirOverride,
+    };
 
     let discovered: DiscoveredConfig | null;
 
@@ -150,6 +195,9 @@ export abstract class BaseCommand extends Command {
       try {
         discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
       } catch (error) {
+        // A command that creates the config is pointed at a place with none in
+        // it by design; the flag still says where, so this is not a failure.
+        if (!requiresConfig) return;
         displayError(error instanceof Error ? error.message : String(error), this.errorSink);
         return this.exit(1);
       }
@@ -158,10 +206,29 @@ export abstract class BaseCommand extends Command {
     }
 
     if (!discovered) {
+      if (!requiresConfig) return;
       displayErrorBlock(formatNotFoundMessage(), this.errorSink);
       return this.exit(1);
     }
 
+    await this.adoptConfig(discovered);
+  }
+
+  /** True once a config has been discovered or adopted and its settings loaded. */
+  protected get hasConfig(): boolean {
+    return this.discovered !== undefined;
+  }
+
+  /**
+   * Makes a discovered config THE config for the rest of the run: loads its
+   * env files, enumerates its layers again now that `SOUS_HOME` may have
+   * changed, and loads the settings. `init()` calls it for the config discovery
+   * found; a command that creates a config calls it for the one it wrote, so
+   * both go through the same steps in the same order.
+   *
+   * @param discovered - The config to adopt.
+   */
+  protected async adoptConfig(discovered: DiscoveredConfig): Promise<void> {
     // Inject .sous/.env.local and .sous/.env before anything resolves variables,
     // keeping a copy of what the shell itself set so the variables layer can
     // still tell the two apart.
@@ -172,27 +239,28 @@ export abstract class BaseCommand extends Command {
     // file-settable, and it decides where the store holding a subscribed
     // recipe's config layers is. A first pass already ran during discovery, when
     // only the real environment was known.
+    let refreshed: DiscoveredConfig;
     try {
-      discovered = refreshDiscoveredConfig(discovered);
+      refreshed = refreshDiscoveredConfig(discovered);
     } catch (error) {
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
 
-    this.discovered = discovered;
+    this.discovered = refreshed;
     this.configContext = {
-      sousDir: discovered.sousDir,
-      configPath: discovered.configPath,
-      confDir: discovered.confDir,
-      layerPaths: discovered.layerPaths,
+      sousDir: refreshed.sousDir,
+      configPath: refreshed.configPath,
+      confDir: refreshed.confDir,
+      layerPaths: refreshed.layerPaths,
     };
 
     // Routed through the command's error sink, not stdout: a recipe layer
     // warning must not land in the middle of `sous config show | jq`.
-    for (const notice of discovered.recipeLayerWarnings) warning(notice, this.errorSink);
+    for (const notice of refreshed.recipeLayerWarnings) warning(notice, this.errorSink);
 
     try {
-      this.settings = await loadSettings(discovered);
+      this.settings = await loadSettings(refreshed);
     } catch (error) {
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);

package/src/commands/build.ts

@@ -5,15 +5,12 @@ import { PidService } from "../lib/pid-service.js";
 import { resolveRootScope } from "../lib/settings.js";
 import { describeLinkedRepos } from "../lib/repos/links.js";
 import { resolveStoreSettings } from "../lib/repos/store/settings.js";
-import {
-  subscriptionServiceFor,
-  type SubscriptionService,
-} from "../lib/repos/subscription-service.js";
+import { prepareRepositoriesForBuild } from "../lib/build-preparation.js";
+import { subscriptionServiceFor } from "../lib/repos/subscription-service.js";
 import { buildReloadWatchConfig, startConfigReloadWatch } from "../lib/watch-loop.js";
 import type { WatchHandle } from "../lib/watch-service.js";
 import { WatchService } from "../lib/watch-service.js";
 import {
-  blankLine,
   footer,
   heading,
   log,
@@ -87,7 +84,7 @@ export default class Build extends BaseCommand {
     });
 
     if (!flags["dry-run"] && !flags["no-compile"]) {
-      await this.prepareRepositories(repositories);
+      await prepareRepositoriesForBuild(repositories);
     }
 
     heading("Building");
@@ -196,78 +193,4 @@ export default class Build extends BaseCommand {
       await new Promise(() => {}); // keep process alive
     }
   }
-
-  /**
-   * Gets this project's recipes ready to compile: restores whatever the store is
-   * missing (a fresh clone, or a collected store) and then asks upstream for the
-   * repositories that prefer a newer in-range version.
-   *
-   * Restoring asks nothing and decides nothing; it fetches exactly what the
-   * lockfile pins. An upstream check that fails is reported and then ignored,
-   * because a build must not depend on the network being up.
-   *
-   * @param repositories - The subscription service for this project.
-   */
-  private async prepareRepositories(repositories: SubscriptionService): Promise<void> {
-    const needsRestore = repositories.needsRestore();
-    if (needsRestore) {
-      heading("Restoring recipes");
-      blankLine();
-      paragraph(
-        "This project's lockfile pins recipes that are not in the store on this " +
-          "machine, so they are being fetched at exactly the versions it records."
-      );
-    }
-
-    const { seed, subscriptions, restored, upstream } =
-      await repositories.prepareForBuild();
-
-    // Seeding the packaged core recipe is silent when it works, which is almost
-    // always; it is only worth a word when it could not be done at all.
-    if (seed.skippedBecause !== undefined) warning(seed.skippedBecause);
-
-    // A subscription the lockfile did not pin yet has just been pinned. That is
-    // a change to a committed file, so it is always announced.
-    if (subscriptions.added.length > 0 || subscriptions.moved.length > 0) {
-      heading("Locking subscribed recipes");
-      blankLine();
-      for (const entry of subscriptions.added) {
-        paragraph(`  pinned: ${entry.key} at version ${entry.version}.`);
-      }
-      for (const change of subscriptions.moved) {
-        paragraph(`  ${change.key} moved from version ${change.from} to version ${change.to}.`);
-      }
-      blankLine();
-      paragraph(
-        "The lockfile has been updated. Commit it, so everyone building this project " +
-          "gets exactly these versions."
-      );
-      footer();
-    }
-
-    for (const failure of subscriptions.failed) {
-      warning(
-        `Sous could not work out which version of '${failure.key}' to use, so nothing ` +
-          `from it was compiled.\n${failure.reason}`
-      );
-    }
-
-    if (restored !== undefined && restored.restored.length > 0) {
-      blankLine();
-      for (const key of restored.restored) paragraph(`  restored: ${key}`);
-    }
-
-    for (const change of upstream.updated) {
-      paragraph(`  ${change.key} moved from ${change.from} to ${change.to}.`);
-    }
-
-    for (const failure of upstream.failed) {
-      warning(
-        `Sous could not check the repository '${failure.repo}' for a newer version, so ` +
-          `this build uses the versions it already had.\n${failure.reason}`
-      );
-    }
-
-    if (needsRestore) footer();
-  }
 }

package/src/commands/init.ts

@@ -0,0 +1,269 @@
+/**
+ * `sous init` sets a project up for sous.
+ *
+ * It writes the `.sous/` directory a project needs (a commented primary config,
+ * the starter prompt that config compiles, the two answers files and the
+ * sous-managed ignore block) and then runs the first build, which is what
+ * seeds the `core` recipe and pins it in the lockfile. A project that is
+ * already set up is left exactly as it is.
+ *
+ * This is the one command that runs BEFORE a project config exists, so it
+ * opts out of the config requirement every other command inherits. Discovery
+ * still runs, which is how `--sous-dir` and `SOUS_DIR` say where to write, and
+ * how a run inside an existing project is noticed.
+ */
+
+import path from "node:path";
+import { Args, Flags } from "@oclif/core";
+import { confirm } from "@inquirer/prompts";
+import { BaseCommand } from "../base-command.js";
+import { prepareRepositoriesForBuild } from "../lib/build-preparation.js";
+import { buildProjectOutputs } from "../lib/build-service.js";
+import {
+  CONFIG_FILE_NAMES,
+  SOUS_DIR_NAME,
+  discoverConfig,
+  expandHome,
+  resolveConfigFlag,
+} from "../lib/config-discovery.js";
+import { ConfigError } from "../lib/errors.js";
+import { nonInteractiveError } from "../lib/interactive.js";
+import { subscriptionServiceFor } from "../lib/repos/subscription-service.js";
+import {
+  PROJECT_CONFIG_FORMATS,
+  STARTER_OUTPUT_NAME,
+  STARTER_PROMPT_RELATIVE_PATH,
+  scaffoldProject,
+  sousDirFor,
+  type ProjectConfigFormat,
+} from "../lib/project-scaffold/index.js";
+import { SOUS_VERSION } from "../lib/settings.js";
+import { confirmationFlag } from "../utils/flags.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  heading,
+  log,
+  paragraph,
+  section,
+  showCommandVars,
+  showVariables,
+  warning,
+} from "../utils/formatting.js";
+
+export default class Init extends BaseCommand {
+  static description =
+    "Set a project up for sous: write its .sous/ directory, then run the first build";
+
+  /** This command creates the config; finding none is its normal case. */
+  static override requiresConfig = false;
+
+  static examples = [
+    "<%= config.bin %> init",
+    "<%= config.bin %> init ./my-project",
+    "<%= config.bin %> init --format json",
+    "<%= config.bin %> init --name 'My Project' --no-build",
+    "<%= config.bin %> init --dry-run",
+  ];
+
+  static args = {
+    directory: Args.string({
+      description: "Project directory to set up (defaults to the current one)",
+      required: false,
+    }),
+  };
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    format: Flags.string({
+      description: "Format of the primary config to write",
+      options: [...PROJECT_CONFIG_FORMATS],
+      default: PROJECT_CONFIG_FORMATS[0],
+    }),
+    name: Flags.string({
+      description: "Display name for the project (defaults to the directory's own name)",
+    }),
+    // The one question this command can ask: whether to set up a project
+    // inside another one.
+    yes: confirmationFlag(),
+    "dry-run": Flags.boolean({
+      description: "Print the files that would be written without writing them",
+      default: false,
+    }),
+    "no-build": Flags.boolean({
+      description: "Write the setup without running the first build",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { args, flags } = await this.parse(Init);
+    const dryRun = flags["dry-run"];
+    const format = flags.format as ProjectConfigFormat;
+
+    const sousDir = this.targetSousDir(args.directory);
+    const projectRoot = path.dirname(sousDir);
+
+    showCommandVars({
+      Directory: projectRoot,
+      Config: path.join(sousDir, `sous.config.${format}`),
+      Name: flags.name ?? "(from the directory name)",
+      "Dry Run": dryRun,
+      Build: !dryRun && !flags["no-build"],
+    });
+
+    await this.confirmNesting(projectRoot, flags.yes);
+
+    section("Setting up the project");
+
+    const result = await scaffoldProject({
+      sousDir,
+      format,
+      name: flags.name,
+      dryRun,
+      sousVersion: SOUS_VERSION,
+    });
+
+    for (const file of result.files) {
+      if (result.dryRun) dryRunNotice(`would write ${file}`);
+      else log(`  wrote ${file}`);
+    }
+
+    if (result.dryRun) {
+      blankLine();
+      dryRunNotice("Nothing was written. Run the same command without '--dry-run' to set the project up.");
+      footer();
+      return;
+    }
+
+    if (!flags["no-build"]) {
+      await this.buildProject(result.configPath);
+    }
+
+    section("What was set up");
+    showVariables([
+      { label: "Config", value: result.configPath },
+      { label: "Prompt source", value: path.join(sousDir, STARTER_PROMPT_RELATIVE_PATH) },
+      { label: "Compiled to", value: path.join(projectRoot, STARTER_OUTPUT_NAME) },
+      { label: "Skills", value: path.join(projectRoot, ".claude", "skills") },
+      { label: "Shared answers", value: path.join(sousDir, ".env"), detail: "committed" },
+      {
+        label: "Local answers",
+        value: path.join(sousDir, ".env.local"),
+        detail: "gitignored; .env.local.example shows the layout",
+      },
+    ]);
+
+    blankLine();
+    paragraph(
+      `  ${STARTER_OUTPUT_NAME} and the skills directory are build output, compiled from the ` +
+        `prompt source and from the recipes this project subscribes to; a build recompiles ` +
+        `them. The config explains each of its blocks in its own comments.`
+    );
+
+    footer();
+  }
+
+  /**
+   * Where the `.sous/` directory goes. A directory argument wins; otherwise the
+   * config-locating flags say where the project is, and otherwise it is the
+   * working directory. A path that already names a `.sous/` directory, or a
+   * config file inside one, is honored as such.
+   */
+  private targetSousDir(directory: string | undefined): string {
+    if (directory !== undefined) {
+      return sousDirFor(path.resolve(this.configLocator.cwd, expandHome(directory)));
+    }
+
+    const primary = this.configLocator.primary;
+    if (primary === undefined) return sousDirFor(this.configLocator.cwd);
+
+    const value = primary.value;
+    if (path.basename(value) === SOUS_DIR_NAME) return value;
+    if ((CONFIG_FILE_NAMES as readonly string[]).includes(path.basename(value))) {
+      return path.dirname(value);
+    }
+    return sousDirFor(value);
+  }
+
+  /**
+   * A project set up inside another one is a real choice, not a mistake sous
+   * should prevent: a subproject may want its own instructions. So when a walk
+   * up from the target finds a config in a parent directory, the facts are
+   * stated and the question is asked once; `--yes` answers it ahead of time,
+   * and a run with no terminal fails naming that flag.
+   *
+   * The target's own `.sous/` holding a config is a different case, refused
+   * outright by the scaffold.
+   */
+  private async confirmNesting(projectRoot: string, confirmed: boolean): Promise<void> {
+    const enclosing = discoverConfig(projectRoot);
+    if (enclosing === null || path.dirname(enclosing.sousDir) === projectRoot) return;
+
+    const enclosingRoot = path.dirname(enclosing.sousDir);
+
+    warning(
+      `${projectRoot} is inside a project that is already set up for sous.\n` +
+        `  The enclosing project's config is ${enclosing.configPath}.\n` +
+        `  Setting this directory up too gives it a config of its own: commands run ` +
+        `here will find this one, and commands run from ${enclosingRoot} will keep ` +
+        `finding the other.`
+    );
+
+    if (confirmed) return;
+
+    if (!this.interactive) {
+      throw nonInteractiveError({
+        prompt: `whether to set up ${projectRoot} inside the project at ${enclosingRoot}`,
+        remedy: "pass --yes (also -y, --force) to set it up anyway",
+      });
+    }
+
+    blankLine();
+    const proceed = await confirm({
+      message: `Set up ${projectRoot} as a project of its own?`,
+      default: false,
+    });
+    if (!proceed) {
+      throw new ConfigError(
+        `Nothing was written. Run 'sous init' from a directory outside ${enclosingRoot}, ` +
+          `or pass --yes to set this one up anyway.`
+      );
+    }
+  }
+
+  /**
+   * Adopts the config just written and builds the project with it, in the
+   * same two steps `sous build` takes: the repositories are prepared (which
+   * seeds the core recipe into the store and pins it in the lockfile), then
+   * the outputs are compiled.
+   *
+   * @param configPath - The primary config the scaffold wrote.
+   */
+  private async buildProject(configPath: string): Promise<void> {
+    await this.adoptConfig(
+      resolveConfigFlag(configPath, this.configLocator.cwd, this.configLocator.confDirOverride)
+    );
+
+    await prepareRepositoriesForBuild(
+      subscriptionServiceFor({
+        configContext: this.configContext,
+        settings: this.settings,
+        shellEnv: this.shellEnv,
+      })
+    );
+
+    heading("Building the project");
+
+    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
+
+    if (!succeeded) {
+      throw new ConfigError(
+        `The project is set up, but the first build failed, so its outputs may be ` +
+          `incomplete. Everything 'sous init' wrote is in place; fix what the build ` +
+          `reported above and run 'sous build' again.`
+      );
+    }
+  }
+}

package/src/lib/build-preparation.ts

@@ -0,0 +1,86 @@
+/**
+ * The step that runs before a project's outputs are compiled, and what it says
+ * while it runs. `sous build` runs it on every build, and `sous init` runs it
+ * for the first build of a project it has just set up; both must say the same
+ * things about the same events, so the reporting lives here rather than in
+ * either command.
+ */
+
+import type { SubscriptionService } from "./repos/subscription-service.js";
+import { blankLine, footer, heading, paragraph, warning } from "../utils/formatting.js";
+
+/**
+ * Gets this project's recipes ready to compile: restores whatever the store is
+ * missing (a fresh clone, or a collected store) and then asks upstream for the
+ * repositories that prefer a newer in-range version.
+ *
+ * Restoring asks nothing and decides nothing; it fetches exactly what the
+ * lockfile pins. An upstream check that fails is reported and then ignored,
+ * because a build must not depend on the network being up.
+ *
+ * @param repositories - The subscription service for this project.
+ */
+export async function prepareRepositoriesForBuild(
+  repositories: SubscriptionService
+): Promise<void> {
+  const needsRestore = repositories.needsRestore();
+  if (needsRestore) {
+    heading("Restoring recipes");
+    blankLine();
+    paragraph(
+      "This project's lockfile pins recipes that are not in the store on this " +
+        "machine, so they are being fetched at exactly the versions it records."
+    );
+  }
+
+  const { seed, subscriptions, restored, upstream } =
+    await repositories.prepareForBuild();
+
+  // Seeding the packaged core recipe is silent when it works, which is almost
+  // always; it is only worth a word when it could not be done at all.
+  if (seed.skippedBecause !== undefined) warning(seed.skippedBecause);
+
+  // A subscription the lockfile did not pin yet has just been pinned. That is
+  // a change to a committed file, so it is always announced.
+  if (subscriptions.added.length > 0 || subscriptions.moved.length > 0) {
+    heading("Locking subscribed recipes");
+    blankLine();
+    for (const entry of subscriptions.added) {
+      paragraph(`  pinned: ${entry.key} at version ${entry.version}.`);
+    }
+    for (const change of subscriptions.moved) {
+      paragraph(`  ${change.key} moved from version ${change.from} to version ${change.to}.`);
+    }
+    blankLine();
+    paragraph(
+      "The lockfile has been updated. Commit it, so everyone building this project " +
+        "gets exactly these versions."
+    );
+    footer();
+  }
+
+  for (const failure of subscriptions.failed) {
+    warning(
+      `Sous could not work out which version of '${failure.key}' to use, so nothing ` +
+        `from it was compiled.\n${failure.reason}`
+    );
+  }
+
+  if (restored !== undefined && restored.restored.length > 0) {
+    blankLine();
+    for (const key of restored.restored) paragraph(`  restored: ${key}`);
+  }
+
+  for (const change of upstream.updated) {
+    paragraph(`  ${change.key} moved from ${change.from} to ${change.to}.`);
+  }
+
+  for (const failure of upstream.failed) {
+    warning(
+      `Sous could not check the repository '${failure.repo}' for a newer version, so ` +
+        `this build uses the versions it already had.\n${failure.reason}`
+    );
+  }
+
+  if (needsRestore) footer();
+}

package/src/lib/config-discovery.ts

@@ -371,22 +371,8 @@ export function formatNotFoundMessage(startDir: string = process.cwd()): string
     checked + more,
     "",
     "  To fix this, either:",
-    `    1. Create ${SOUS_DIR_NAME}/${CONFIG_FILE_NAMES[0]} in your project root, or`,
+    `    1. Set the project up: run 'sous init' in its root directory, which writes`,
+    `       ${SOUS_DIR_NAME}/${CONFIG_FILE_NAMES[0]} and everything else a first build needs, or`,
     "    2. Pass the config explicitly: sous <command> --config <path>",
-    "",
-    `  A minimal ${CONFIG_FILE_NAMES[0]}:`,
-    "",
-    "    export const config = {",
-    '      name: "My Project",',
-    '      _vars: { projectRoot: "${sousDir}/.." },',
-    "      compilation: {",
-    "        targets: [",
-    "          {",
-    '            entryPoint: "${sousDir}/AGENTS.md",',
-    '            outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],',
-    "          },",
-    "        ],",
-    "      },",
-    "    };",
   ].join("\n");
 }

package/src/lib/project-scaffold/index.ts

@@ -0,0 +1,251 @@
+/**
+ * Scaffolding a project's `.sous/` directory, which is what `sous init` does.
+ *
+ * The scaffold is planned in memory first, checked against what is already on
+ * disk, and only then written. Once written, the config is read back through
+ * the very loader every command uses, so a scaffold sous itself cannot load is
+ * never reported as a success.
+ *
+ * It refuses to touch a project that is already set up: a `.sous/` directory
+ * holding a primary config is left exactly as it is, and so is any file the
+ * scaffold would otherwise write. The one file it merges rather than replaces
+ * is `.sous/.gitignore`, whose sous-managed block is applied by the same writer
+ * `sous repo link` uses, so running the scaffold over an existing ignore file
+ * never duplicates an entry.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "../errors.js";
+import {
+  CONFIG_FILE_NAMES,
+  ENV_DEFAULTS_NAME,
+  ENV_LOCAL_NAME,
+  SOUS_DIR_NAME,
+  findConfigInSousDir,
+  resolveConfigFlag,
+} from "../config-discovery.js";
+import { applyManagedIgnoreBlock } from "../repos/links.js";
+import { loadSettings } from "../settings.js";
+import {
+  PROJECT_CONFIG_FORMATS,
+  STARTER_PROMPT_RELATIVE_PATH,
+  buildConfigJs,
+  buildConfigJson,
+  buildEnvDefaults,
+  buildEnvLocalExample,
+  buildStarterPrompt,
+  type ProjectConfigFormat,
+  type ProjectScaffoldContext,
+} from "./templates.js";
+
+export * from "./templates.js";
+
+/** What to scaffold, and where. */
+export type ProjectScaffoldOptions = {
+  /**
+   * Absolute path to the `.sous/` directory to create. Its parent is the
+   * project root, which is where the starter prompt compiles to.
+   */
+  sousDir: string;
+  /** Which config format to write. Defaults to the first of `PROJECT_CONFIG_FORMATS`. */
+  format?: ProjectConfigFormat;
+  /** The project's display name. Defaults to the project root's own directory name. */
+  name?: string;
+  /** Work out every file, check the target, but write nothing. */
+  dryRun?: boolean;
+  /** The version of sous doing the scaffolding, named in the generated files. */
+  sousVersion: string;
+};
+
+/** What a scaffold produced. */
+export type ProjectScaffoldResult = {
+  /** The `.sous/` directory the scaffold was written into. */
+  sousDir: string;
+  /** The project root: the parent of `sousDir`. */
+  projectRoot: string;
+  /** Absolute path of the primary config that was written. */
+  configPath: string;
+  /** The format the config was written in. */
+  format: ProjectConfigFormat;
+  /** The display name written into the config. */
+  name: string;
+  /** Paths of every file written, relative to the project root, in the order written. */
+  files: string[];
+  /** True when nothing was actually written. */
+  dryRun: boolean;
+};
+
+/** One planned file: where it goes, and what goes in it. */
+type PlannedFile = {
+  /** Path relative to the project root. */
+  relativePath: string;
+  /** The complete file contents. */
+  contents: string;
+  /**
+   * True for a file whose existing contents were merged into `contents`
+   * rather than a file the scaffold refuses to write over.
+   */
+  merged?: boolean;
+};
+
+/** The file name a config of the given format is written under. */
+export function configFileNameFor(format: ProjectConfigFormat): string {
+  const name = `sous.config.${format}`;
+  /* c8 ignore next 5 */
+  if (!(CONFIG_FILE_NAMES as readonly string[]).includes(name)) {
+    throw new ConfigError(
+      `sous cannot write a '${format}' config: discovery does not recognize ${name}.`
+    );
+  }
+  return name;
+}
+
+/**
+ * Creates a project's `.sous/` directory: a primary config, the starter prompt
+ * it compiles, the two answers files, and the sous-managed block in
+ * `.sous/.gitignore`.
+ *
+ * @param options - What to scaffold, and where.
+ * @throws ConfigError when the target already holds a primary config, or any
+ *   other file the scaffold would write, or when the written config does not
+ *   load.
+ */
+export async function scaffoldProject(
+  options: ProjectScaffoldOptions
+): Promise<ProjectScaffoldResult> {
+  const sousDir = path.resolve(options.sousDir);
+  const projectRoot = path.dirname(sousDir);
+  const format = options.format ?? PROJECT_CONFIG_FORMATS[0];
+  const name = (options.name ?? path.basename(projectRoot)).trim() || path.basename(projectRoot);
+  const dryRun = options.dryRun === true;
+
+  assertNoExistingConfig(sousDir);
+
+  const context: ProjectScaffoldContext = { name, sousVersion: options.sousVersion };
+  const files = planFiles(sousDir, projectRoot, format, context);
+
+  assertNothingWouldBeOverwritten(projectRoot, files);
+
+  const configPath = path.join(sousDir, configFileNameFor(format));
+
+  if (!dryRun) {
+    for (const file of files) {
+      const target = path.join(projectRoot, file.relativePath);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, file.contents, "utf8");
+    }
+    await verifyScaffold(configPath, projectRoot);
+  }
+
+  return {
+    sousDir,
+    projectRoot,
+    configPath,
+    format,
+    name,
+    files: files.map((file) => file.relativePath),
+    dryRun,
+  };
+}
+
+/** Builds every file the scaffold writes, in the order they are written. */
+function planFiles(
+  sousDir: string,
+  projectRoot: string,
+  format: ProjectConfigFormat,
+  context: ProjectScaffoldContext
+): PlannedFile[] {
+  const inSousDir = (name: string): string =>
+    path.relative(projectRoot, path.join(sousDir, name));
+
+  const gitignorePath = path.join(sousDir, ".gitignore");
+  const existingIgnore = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, "utf8")
+    : undefined;
+
+  return [
+    {
+      relativePath: inSousDir(configFileNameFor(format)),
+      contents: format === "json" ? buildConfigJson(context) : buildConfigJs(context),
+    },
+    {
+      relativePath: inSousDir(STARTER_PROMPT_RELATIVE_PATH),
+      contents: buildStarterPrompt(context),
+    },
+    { relativePath: inSousDir(ENV_DEFAULTS_NAME), contents: buildEnvDefaults(context) },
+    {
+      relativePath: inSousDir(`${ENV_LOCAL_NAME}.example`),
+      contents: buildEnvLocalExample(context),
+    },
+    {
+      relativePath: inSousDir(".gitignore"),
+      contents: applyManagedIgnoreBlock(existingIgnore, gitignorePath),
+      merged: true,
+    },
+  ];
+}
+
+/**
+ * Refuses to scaffold a `.sous/` directory that already holds a primary
+ * config. The config is what makes a directory a sous project, so that is what
+ * is checked; a `.sous/` holding only, say, task files is a fine place to set
+ * one up.
+ */
+function assertNoExistingConfig(sousDir: string): void {
+  const existing = findConfigInSousDir(sousDir);
+  if (existing !== null) {
+    throw new ConfigError(
+      `${path.dirname(sousDir)} is already set up for sous.\n` +
+        `  ${existing} exists, and sous will not overwrite it.\n` +
+        `  Edit that config instead, or run 'sous init' in another directory.`
+    );
+  }
+}
+
+/**
+ * Refuses to write over any file the scaffold produces, so a run that fails
+ * here has changed nothing. The merged ignore file is exempt: its existing
+ * lines are carried into what is written.
+ */
+function assertNothingWouldBeOverwritten(projectRoot: string, files: PlannedFile[]): void {
+  const clashes = files
+    .filter((file) => file.merged !== true)
+    .map((file) => path.join(projectRoot, file.relativePath))
+    .filter((target) => fs.existsSync(target));
+
+  if (clashes.length === 0) return;
+
+  throw new ConfigError(
+    `${projectRoot} already holds ${clashes.length === 1 ? "a file" : "files"} that ` +
+      `'sous init' would write, and sous will not overwrite ${clashes.length === 1 ? "it" : "them"}:\n` +
+      clashes.map((target) => `    ${target}`).join("\n") +
+      `\n  Move ${clashes.length === 1 ? "it" : "them"} aside, or run 'sous init' in another directory.`
+  );
+}
+
+/**
+ * Loads the written config through the same loader every command uses, so
+ * the scaffold is never reported as a success unless sous can actually read
+ * it. A failure here is a bug in the scaffold, and is reported as one.
+ */
+async function verifyScaffold(configPath: string, projectRoot: string): Promise<void> {
+  try {
+    await loadSettings(resolveConfigFlag(configPath, projectRoot));
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new ConfigError(
+      `The config 'sous init' wrote at ${configPath} does not load.\n` +
+        `  This is a bug in sous; please report it. The loader said:\n` +
+        `${reason
+          .split("\n")
+          .map((line) => `    ${line}`)
+          .join("\n")}`
+    );
+  }
+}
+
+/** The `.sous/` directory a project root would hold. */
+export function sousDirFor(projectRoot: string): string {
+  return path.join(path.resolve(projectRoot), SOUS_DIR_NAME);
+}

package/src/lib/project-scaffold/templates.ts

@@ -0,0 +1,230 @@
+/**
+ * The files `sous init` writes, as plain string builders.
+ *
+ * As with the repository scaffold, these are deliberately not templates run
+ * through a template engine. A scaffolded project is read by a person before
+ * it is read by a machine, and the comments are what make the first config
+ * legible; a rendering step would only stand between the author of the
+ * scaffold and the person who has to live with the result.
+ *
+ * Every builder returns a complete file, ending in a newline. The JSON config
+ * is the one file that cannot carry a comment: the config schema is strict and
+ * accepts `$schema` but no comment key, so what the JS variant explains in
+ * comments the JSON variant leaves to the documentation.
+ */
+
+import {
+  CONFD_DIR_NAME,
+  ENV_DEFAULTS_NAME,
+  ENV_LOCAL_NAME,
+  SOUS_DIR_NAME,
+} from "../config-discovery.js";
+
+/** The config formats `sous init` can write. The first one is the default. */
+export const PROJECT_CONFIG_FORMATS = ["js", "json"] as const;
+
+/** One of the config formats `sous init` can write. */
+export type ProjectConfigFormat = (typeof PROJECT_CONFIG_FORMATS)[number];
+
+/**
+ * The path, relative to `.sous/`, of the starter prompt the scaffolded config
+ * compiles. It lives under `prompts/` so the source and its compiled output
+ * (`AGENTS.md` at the project root) are never mistaken for one another.
+ */
+export const STARTER_PROMPT_RELATIVE_PATH = "prompts/AGENTS.md";
+
+/** The name of the file the starter prompt is compiled into, at the project root. */
+export const STARTER_OUTPUT_NAME = "AGENTS.md";
+
+/** What every builder needs to know about the project being scaffolded. */
+export type ProjectScaffoldContext = {
+  /** The project's display name, written into the config's `name`. */
+  name: string;
+  /** The version of sous doing the scaffolding, named in the generated files. */
+  sousVersion: string;
+};
+
+/**
+ * Where the JSON Schema for a config of this sous version is published. The
+ * schema ships inside the package too, but an editor resolving `$schema` wants
+ * a URL, and the tagged copy on GitHub is the one that matches this version
+ * for as long as the tag exists.
+ *
+ * @param sousVersion - The running sous version.
+ */
+export function configSchemaUrl(sousVersion: string): string {
+  return `https://raw.githubusercontent.com/sous-io/sous/v${sousVersion}/sous.config.schema.json`;
+}
+
+/**
+ * The primary config as a JavaScript module, commented so a first-time reader
+ * can see what each block is for without opening the documentation.
+ *
+ * @param context - The project being scaffolded.
+ */
+export function buildConfigJs(context: ProjectScaffoldContext): string {
+  return `// The primary sous config for ${context.name}.
+//
+// sous finds this file by walking up from the directory it was run in until it
+// meets a \`${SOUS_DIR_NAME}/\` directory holding a config. Everything a build needs
+// starts here. Drop-in layers under \`${SOUS_DIR_NAME}/${CONFD_DIR_NAME}/\` merge over it, and
+// the layers sous writes for itself go into that directory, never into this
+// file. Written by \`sous init\` (sous ${context.sousVersion}); it is yours now.
+
+export const config = {
+  // Shown in command output. Any string.
+  name: ${JSON.stringify(context.name)},
+
+  // Variables for the rest of this file. \`\${sousDir}\` is this \`${SOUS_DIR_NAME}/\` directory,
+  // injected by sous, so nothing here depends on where the project is checked
+  // out. Reference a variable anywhere below as \`\${name}\`.
+  _vars: {
+    projectRoot: "\${sousDir}/..",
+  },
+
+  // What to compile. Each target reads one source and writes it somewhere. The
+  // starter target renders \`${SOUS_DIR_NAME}/${STARTER_PROMPT_RELATIVE_PATH}\` to the project root.
+  // A line holding only \`@path/to/file.md\` in a source pulls that file in, and a
+  // \`.tpl.\` in a file name turns Liquid templating on for it. Compiled files
+  // are build output: ignore them or commit them, as your team prefers.
+  compilation: {
+    targets: [
+      {
+        entryPoint: "\${sousDir}/${STARTER_PROMPT_RELATIVE_PATH}",
+        outputs: [{ destinationFile: "\${projectRoot}/${STARTER_OUTPUT_NAME}" }],
+      },
+    ],
+  },
+
+  // Where the recipes this project subscribes to write their files. Every
+  // project subscribes to the \`core\` namespace on its own, which is how the
+  // skills that teach an agent about sous reach \`.claude/skills\`. Memories and
+  // prompts have no default home; name one to receive them.
+  recipeOutputs: {
+    skills: ["\${projectRoot}/.claude/skills"],
+    // memories: ["\${projectRoot}/.claude/memories"],
+    // prompts: ["\${projectRoot}/.claude/prompts"],
+  },
+};
+`;
+}
+
+/**
+ * The same primary config as strict JSON, bound to the shipped schema through
+ * `$schema` so an editor can validate and complete it.
+ *
+ * @param context - The project being scaffolded.
+ */
+export function buildConfigJson(context: ProjectScaffoldContext): string {
+  const config = {
+    $schema: configSchemaUrl(context.sousVersion),
+    name: context.name,
+    _vars: {
+      projectRoot: "${sousDir}/..",
+    },
+    compilation: {
+      targets: [
+        {
+          entryPoint: `\${sousDir}/${STARTER_PROMPT_RELATIVE_PATH}`,
+          outputs: [{ destinationFile: `\${projectRoot}/${STARTER_OUTPUT_NAME}` }],
+        },
+      ],
+    },
+    recipeOutputs: {
+      skills: ["${projectRoot}/.claude/skills"],
+    },
+  };
+  return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+/**
+ * The starter prompt the config compiles: a short, real instruction file, so
+ * the first build produces something worth reading rather than a placeholder.
+ *
+ * @param context - The project being scaffolded.
+ */
+export function buildStarterPrompt(context: ProjectScaffoldContext): string {
+  return `# ${context.name}
+
+This file is compiled by sous into \`${STARTER_OUTPUT_NAME}\` at the project root. Edit this
+source, run \`sous build\`, and the compiled copy follows; never edit the compiled copy.
+
+## Working in this project
+
+- Describe the project here: what it is, how it is built, and how it is tested.
+- Split long sections into their own files under \`${SOUS_DIR_NAME}/prompts/\` and pull
+  each one in with a line holding only \`@sections/name.md\`.
+- The skills under \`.claude/skills\` are written by sous from the recipes this
+  project subscribes to. \`sous recipe list\` shows what is available.
+`;
+}
+
+/**
+ * The committed answers file: the layer for what the whole team shares.
+ *
+ * @param context - The project being scaffolded.
+ */
+export function buildEnvDefaults(context: ProjectScaffoldContext): string {
+  return `# ${SOUS_DIR_NAME}/${ENV_DEFAULTS_NAME}
+#
+# Answers to recipe variables that the whole team shares. Commit this file.
+#
+# A recipe this project subscribes to may ask questions (a board name, a
+# ticket prefix, where task files go), and the answers live here as
+# \`KEY=VALUE\` lines. \`sous vars ask\` writes them one question at a time, and
+# \`sous vars list\` shows every variable in play with where its answer came from.
+#
+# Never put a secret, a login or a machine-specific path here. Those belong in
+# \`${SOUS_DIR_NAME}/${ENV_LOCAL_NAME}\`, which is gitignored and overrides this file
+# key for key. Precedence, highest first: your shell, then \`${ENV_LOCAL_NAME}\`,
+# then this file.
+#
+# Written by \`sous init\` (sous ${context.sousVersion}).
+`;
+}
+
+/**
+ * The example for the gitignored answers file, explaining what belongs in the
+ * local layer and how to start one.
+ *
+ * @param context - The project being scaffolded.
+ */
+export function buildEnvLocalExample(context: ProjectScaffoldContext): string {
+  return `# ${SOUS_DIR_NAME}/${ENV_LOCAL_NAME}.example
+#
+# Copy this file to \`${SOUS_DIR_NAME}/${ENV_LOCAL_NAME}\` and fill in your own values:
+#
+#     cp ${SOUS_DIR_NAME}/${ENV_LOCAL_NAME}.example ${SOUS_DIR_NAME}/${ENV_LOCAL_NAME}
+#
+# ...or let sous write it for you, one question at a time:
+#
+#     sous vars ask
+#
+# \`${SOUS_DIR_NAME}/${ENV_LOCAL_NAME}\` is gitignored. It is the layer for anything that
+# differs between people or machines, or must not be committed: your own login
+# and name, absolute paths outside the repository, API tokens.
+#
+# The COMMITTED layer is \`${SOUS_DIR_NAME}/${ENV_DEFAULTS_NAME}\`. Same syntax, but it holds
+# the answers the whole team shares. Never put a secret there.
+#
+# How both files are loaded:
+#   - \`KEY=VALUE\` per line. \`#\` starts a comment. \`export KEY=VALUE\` also works.
+#   - Loaded into the environment before the config resolves any variables.
+#   - Precedence, highest first: your shell, then \`${ENV_LOCAL_NAME}\`, then \`${ENV_DEFAULTS_NAME}\`.
+#     So \`FOO=bar sous build\` overrides \`FOO\` from either file for that one run,
+#     and a key in \`${ENV_LOCAL_NAME}\` overrides the same key in \`${ENV_DEFAULTS_NAME}\`.
+#   - A recipe's variable answers reach its templates on their own. \`sous vars
+#     list\` shows each one, with the environment variable that supplied it.
+#   - The config's own \`_env\` block still works for anything a recipe does not
+#     ask about: \`_env: { myPath: "MY_PATH" }\` makes \`\${myPath}\` available
+#     throughout the config from \`MY_PATH\` in either file.
+#
+# NOT here: the config-location variables \`SOUS_CONFIG\`, \`SOUS_DIR\` and
+# \`SOUS_CONFD\`. Those decide where sous looks for \`${SOUS_DIR_NAME}/\`, so they are
+# read from the real shell environment only; this file is not found until
+# discovery has already run.
+#
+# Written by \`sous init\` (sous ${context.sousVersion}). Add a line per answer below,
+# with a comment saying what it is for.
+`;
+}

package/src/lib/repos/links.ts

@@ -49,12 +49,14 @@ export const IGNORE_BLOCK_END = "# <<< sous managed";
 /**
  * The entries sous keeps inside its managed block in `.sous/.gitignore`. All of
  * them are machine-local: the links map, the build state file, the watcher's
- * PID file, and the directory linked checkouts are cloned into.
+ * PID file, the local answers file, and the directory linked checkouts are
+ * cloned into.
  */
 export const IGNORE_BLOCK_ENTRIES = [
   LINKS_FILENAME,
   "sous.state.json",
   "sous.pid",
+  ".env.local",
   `${REPOS_DIRNAME}/`,
 ] as const;