@sous-io/sous 0.2.6 → 0.2.8

package/README.md

@@ -36,7 +36,8 @@ npm install -D @sous-io/sous     # the version this project's templates were wri
 A project install pins the sous version a project builds with, and it always does the
 building: a global `sous` run anywhere inside a project that holds `node_modules/@sous-io/sous`
 hands the command to that copy, so `sous`, `npx sous` and a package script all produce the same
-output. When the two versions differ, one line on standard error says which copy ran. Set
+output. When the two versions differ, one line on standard error names the version handed off
+to; `--verbose` announces every hand-off and adds where both installs are. Set
 `SOUS_NO_DELEGATE=1` to run the copy you invoked instead.
 
 Or run it from a clone (useful when developing sous itself):
@@ -57,9 +58,11 @@ sous init
 
 `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`
+schema), a starter prompt at `.sous/memories/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
+files sous keeps local to one machine. A project with a `package.json` also gains `@sous-io/sous`
+as a devDependency at the running version, so the project pins the sous it builds with; run
+your package manager's install afterwards. 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.
 
@@ -72,7 +75,7 @@ export const config = {
   compilation: {
     targets: [
       {
-        entryPoint: "${sousDir}/prompts/AGENTS.md",
+        entryPoint: "${sousDir}/memories/AGENTS.md",
         outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],
       },
     ],
@@ -164,8 +167,9 @@ A recipe's files are reachable without knowing where anything is installed. An `
 path may name a recipe by its namespace, so
 `@~workflow/task-files/_partials/resume-task.md` composes a block published by the recipe
 `workflow/task-files`, at the version your project has pinned, into your own instruction
-file. `@~project/...` names your project's root, and you can define your own aliases with
-an `_aliases` block.
+file. `@~project/...` names your project's root, `@~/...` names your home directory, and you
+can define your own aliases with an `_aliases` block. Either spelling of a file finds it:
+`@shared.md` also finds `shared.tpl.md`, and the other way round.
 
 Sous records every file and directory it writes in a state file, `.sous/sous.state.json` by
 default, which is what lets `prune` and `clear` clean up precisely instead of guessing.

package/bin/run.js

@@ -20,6 +20,19 @@ if (!handedOff) {
   const { register } = await import("tsx/esm/api");
   register();
 
+  // `sous --version` is answered here rather than by oclif, whose answer is
+  // its user agent string. Plain, it is the version alone; `--verbose` adds
+  // the package, where it is installed, the platform and the Node build.
+  const argv = process.argv.slice(2);
+  const { isVersionRequest, printVersion } = await import("../src/lib/version-report.ts");
+  if (isVersionRequest(argv)) {
+    printVersion(argv, ownRoot);
+  } else {
+    await runCommand();
+  }
+}
+
+async function runCommand() {
   const { execute, settings } = await import("@oclif/core");
 
   // tsx (above) already makes .ts imports work, so oclif's own auto-transpile

package/docs/markdown/README.md

@@ -34,18 +34,29 @@ Sous installs three ways, and they work together:
   directory the way Node resolves a package, so a copy hoisted to a monorepo root is found from
   any package inside it.
 
-When the two versions differ, one sentence on standard error names the copy that ran and the
-one you invoked; standard output is untouched, so a piped command prints exactly what it always
-did. Set `SOUS_DEBUG` and the sentence prints on every hand-off. Set `SOUS_NO_DELEGATE` to
-anything but `0`, `false`, `no` or `off` to run the copy you invoked instead, for debugging a
-broken project install or for deliberately using the global one:
+When the two versions differ, one line on standard error names the version handed off to;
+standard output is untouched, so a piped command prints exactly what it always did. Add
+`--verbose` to any command, or set `SOUS_DEBUG`, and every hand-off is announced, with where
+both installs are and how to keep the invoked one running. Set
+`SOUS_NO_DELEGATE` to anything but `0`, `false`, `no` or `off` to run the copy you invoked
+instead, for debugging a broken project install or for deliberately using the global one:
 
 ```term
 $ sous --version
-Running the project's own sous 0.2.4 from /work/app/node_modules/@sous-io/sous instead of the sous 0.3.0 you invoked; set SOUS_NO_DELEGATE=1 to run the one you invoked.
-@sous-io/sous/0.2.4 linux-x64 node-v22.21.0
+Handing off to the project-level Sous install: v0.2.4
+v0.2.4
+$ sous --version --verbose
+Handing off to the project-level Sous install: v0.2.4
+    Project install: /work/app/node_modules/@sous-io/sous
+    Invoked install: v0.3.0 at /usr/lib/node_modules/@sous-io/sous
+Set SOUS_NO_DELEGATE=1 to run the invoked install instead.
+v0.2.4
+    Package : @sous-io/sous
+    Install : /work/app/node_modules/@sous-io/sous
+    Platform: linux-x64
+    Node    : v22.21.0
 $ SOUS_NO_DELEGATE=1 sous --version
-@sous-io/sous/0.3.0 linux-x64 node-v22.21.0
+v0.3.0
 ```
 
 ## Where to look

package/docs/markdown/_sidebar.md

@@ -22,3 +22,4 @@
   - [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)
   - [0004: A global sous defers to the project's install](adrs/0004-project-install-handoff.md)
+  - [0005: Follow-ups from the first project on the hand-off](adrs/0005-first-project-follow-ups.md)

package/docs/markdown/commands.md

@@ -38,7 +38,8 @@ under [When sous cannot ask](repositories-consuming.md#when-sous-cannot-ask).
 
 Help has four spellings. `sous --help` prints the root screen; `sous repo add --help`, `sous repo add -h` and
 `sous help repo add` all print that one command's. `sous help` alone lists the topics and commands, and
-`sous --version` prints the version, platform and Node build.
+`sous --version` prints the version alone, as `v1.2.3`; `sous --version --verbose` adds the package name, where
+it is installed, the platform and the Node build under it.
 
 Every topic answers to both spellings of its name: `repo` and `repos`, `subscription` and `subscriptions`,
 `namespace` and `namespaces`, `recipe` and `recipes`, `lock` and `locks`, `vars` and `var`, `config` and
@@ -49,9 +50,11 @@ Every topic answers to both spellings of its name: `repo` and `repos`, `subscrip
 ### `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`.
+primary config, a starter prompt at `.sous/memories/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`. A
+project that has a `package.json` also gains `@sous-io/sous` in its `devDependencies`, at exactly the running
+version, unless it already depends on it; nothing is installed, so run your package manager's install afterwards.
+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
@@ -339,7 +342,7 @@ No expected failure prints a stack trace. A failure sous did not expect prints t
 asking you to set `SOUS_DEBUG=1` and run the command again. Set `SOUS_DEBUG` to anything but `0`, `false`, `no`
 or `off` and every reported failure prints its stack to standard error underneath the message:
 `SOUS_DEBUG=1 sous build`. The one other thing it changes is that every hand-off to a project's own install
-announces itself, not only one between different versions.
+announces itself in full, not only one between different versions; `--verbose` does the same.
 
 `SOUS_NO_DELEGATE` is the other environment variable every command reads. Set it the same way and the copy of
 sous you invoked runs the command, even inside a project that installs its own `@sous-io/sous`; see

package/package.json

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

package/recipes/core/sous-skills/skills/about-liquid-templates/SKILL.tpl.md

@@ -93,8 +93,8 @@ Include another file at render time (path **relative to the template file's dire
 
 `render` resolves paths relative to the template file. For files outside that tree, use
 a recipe reference (`@~<namespace>/<recipe>/...`), a path **alias** (`@~project/...`, or a
-user-defined alias) or a `@`-prefixed `${var}` path; the same resolution as `@include`
-(see below) works in `render` too.
+user-defined alias), a home-relative path (`@~/...`) or a `@`-prefixed `${var}` path; the
+same resolution as `@include` (see below) works in `render` too.
 
 To prevent template sequences from being processed in a code example, wrap the block in
 `raw` / `endraw` tag blocks. These blocks cannot be nested: the first `endraw`
@@ -156,6 +156,13 @@ namespaces. There is exactly one:
 
 - `@~project/...` → the consuming project's root.
 
+A bare `@~/...` is not an alias: the sigil followed only by a separator is the home
+directory, so `@~/notes/context.md` includes a file from your home directory.
+
+An include finds a file by either spelling. `@shared.md` finds `shared.tpl.md` when that is
+what exists, and `@notes.tpl.md` finds `notes.md`; the spelling written is tried first. So a
+file can be turned into a template, or back, without touching the lines that include it.
+
 Everything else sous once shipped inside its own package is published as a recipe now, so
 a recipe reference is what reaches it.
 

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

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

package/src/commands/init.ts

@@ -31,10 +31,12 @@ import { nonInteractiveError } from "../lib/interactive.js";
 import { subscriptionServiceFor } from "../lib/repos/subscription-service.js";
 import {
   PROJECT_CONFIG_FORMATS,
+  SOUS_PACKAGE_NAME,
   STARTER_OUTPUT_NAME,
   STARTER_PROMPT_RELATIVE_PATH,
   scaffoldProject,
   sousDirFor,
+  type PackageJsonOutcome,
   type ProjectConfigFormat,
 } from "../lib/project-scaffold/index.js";
 import { SOUS_VERSION } from "../lib/settings.js";
@@ -50,8 +52,28 @@ import {
   showCommandVars,
   showVariables,
   warning,
+  type VariableEntry,
 } from "../utils/formatting.js";
 
+/**
+ * The "Dependency" row of the summary: where sous now sits in the project's
+ * package.json, or nothing when the project has no package.json.
+ */
+function dependencyRow(outcome: PackageJsonOutcome): VariableEntry[] {
+  if (outcome.kind === "absent") return [];
+  const value = `${SOUS_PACKAGE_NAME} ${outcome.range}`;
+  if (outcome.kind === "present") {
+    return [{ label: "Dependency", value, detail: `already in ${outcome.section} in package.json` }];
+  }
+  return [
+    {
+      label: "Dependency",
+      value,
+      detail: "added to devDependencies in package.json; run your package manager's install to fetch it",
+    },
+  ];
+}
+
 export default class Init extends BaseCommand {
   static description =
     "Set a project up for sous: write its .sous/ directory, then run the first build";
@@ -129,6 +151,11 @@ export default class Init extends BaseCommand {
       if (result.dryRun) dryRunNotice(`would write ${file}`);
       else log(`  wrote ${file}`);
     }
+    if (result.packageJson.kind === "added") {
+      const what = `${SOUS_PACKAGE_NAME} ${result.packageJson.range} to devDependencies in package.json`;
+      if (result.dryRun) dryRunNotice(`would add ${what}`);
+      else log(`  added ${what}`);
+    }
 
     if (result.dryRun) {
       blankLine();
@@ -147,6 +174,7 @@ export default class Init extends BaseCommand {
       { 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") },
+      ...dependencyRow(result.packageJson),
       { label: "Shared answers", value: path.join(sousDir, ".env"), detail: "committed" },
       {
         label: "Local answers",

package/src/lib/include-resolver.ts

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { expandHome } from "./config-discovery.js";
 import type { NamespaceResolution, NamespaceResolver } from "./repos/namespace-resolver.js";
 
 /**
@@ -10,8 +11,11 @@ import type { NamespaceResolution, NamespaceResolver } from "./repos/namespace-r
  * that exists on disk; if none exist, it errors listing every candidate tried.
  *
  * Resolution pipeline for a raw path P (with leading `@` already stripped):
- *   1. Substitute ${vars} in P. If the result is absolute, it is the sole
- *      candidate (feature: `@${sousRootPath}/x.md`).
+ *   1. Substitute ${vars} in P, then expand a leading `~/` to the home
+ *      directory (the `~` sigil on its own, with nothing but a separator after
+ *      it, names no alias or namespace, so `@~/notes/x.md` is unambiguous). If
+ *      the result is absolute, it is the sole candidate (feature:
+ *      `@${sousRootPath}/x.md`).
  *   2. Split the first segment (up to the first `/` or `:`) as the alias key,
  *      the remainder as `rest`. If the key is a registered alias, push
  *      join(base, rest) for EACH base in the alias's ordered array.
@@ -19,10 +23,16 @@ import type { NamespaceResolution, NamespaceResolver } from "./repos/namespace-r
  *      for the recipe namespace named by the key (minus the `~`) and push its
  *      candidates. Aliases are consulted first, so `~project` keeps meaning
  *      the built-in alias even if a namespace of that name exists.
- *   4. Always push the relative candidate: join(baseDir, P) — the FULL path
+ *   4. Always push the relative candidate: join(baseDir, P), the FULL path
  *      including the alias segment. This lets an alias augment a real relative
  *      directory of the same name (e.g. `@stuff/x` tries the alias bases, then
  *      `./stuff/x`).
+ *   5. Follow every candidate with its `.tpl.` twin: `x.md` is followed by
+ *      `x.tpl.md`, and `x.tpl.md` by `x.md`. The literal spelling is always
+ *      tried first, and the twin comes right after it (not after every other
+ *      candidate), so an alias base still beats the relative fallback. A
+ *      writer therefore never has to know whether an included file has been
+ *      turned into a template or back.
  *
  * A key WITHOUT the `~` sigil never reaches the namespace resolver: a bare
  * `@path` is always a relative path or a declared alias, so include lines never
@@ -48,6 +58,39 @@ export function substituteVars(str: string, scope: Record<string, string>): stri
   return str.replace(/\$\{([^}]+)\}/g, (match, name: string) => scope[name] ?? match);
 }
 
+/** The marker that makes a file a template, always right before the final extension. */
+const TEMPLATE_MARKER = ".tpl";
+
+/**
+ * The `.tpl.` twin of a path: `x.md` gives `x.tpl.md`, `x.tpl.md` gives `x.md`,
+ * and a path with no extension has no twin.
+ *
+ * @param filePath - Any path, absolute or not.
+ * @returns The twin, or undefined when there is none.
+ */
+export function templateTwin(filePath: string): string | undefined {
+  const dir = path.dirname(filePath);
+  const base = path.basename(filePath);
+  const ext = path.extname(base);
+  if (ext === "" || ext === base) return undefined;
+  const stem = base.slice(0, -ext.length);
+  const twin = stem.endsWith(TEMPLATE_MARKER)
+    ? `${stem.slice(0, -TEMPLATE_MARKER.length)}${ext}`
+    : `${stem}${TEMPLATE_MARKER}${ext}`;
+  return path.join(dir, twin);
+}
+
+/** Every candidate followed by its `.tpl.` twin, de-duplicated, order kept. */
+function withTemplateTwins(candidates: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const candidate of candidates) {
+    out.push(candidate);
+    const twin = templateTwin(candidate);
+    if (twin !== undefined) out.push(twin);
+  }
+  return [...new Set(out)];
+}
+
 /**
  * Split an include path into its leading alias key and the remainder. The key
  * is the run of characters up to the first `/` or `:` separator.
@@ -115,11 +158,11 @@ export type IncludeResolution = {
 export function resolveInclude(rawPath: string, opts: IncludeResolveOptions): IncludeResolution {
   const aliases = opts.aliases ?? {};
   const scope = opts.scope ?? {};
-  const substituted = substituteVars(rawPath, scope);
+  const substituted = expandHome(substituteVars(rawPath, scope));
 
-  // 1. Substituted to an absolute path → that is the only candidate.
+  // 1. Substituted (or home-expanded) to an absolute path → that, and its twin.
   if (path.isAbsolute(substituted)) {
-    return { candidates: [path.normalize(substituted)] };
+    return { candidates: withTemplateTwins([path.normalize(substituted)]) };
   }
 
   const candidates: string[] = [];
@@ -151,8 +194,8 @@ export function resolveInclude(rawPath: string, opts: IncludeResolveOptions): In
   // 4. Relative fallback: the FULL substituted path under the including dir.
   candidates.push(path.resolve(opts.baseDir, substituted));
 
-  // De-dupe, preserving order.
-  return { candidates: [...new Set(candidates)], namespaceIssue };
+  // 5. Each candidate's `.tpl.` twin right after it; de-duped, order kept.
+  return { candidates: withTemplateTwins(candidates), namespaceIssue };
 }
 
 /**
@@ -169,7 +212,7 @@ export function resolveIncludeCandidates(rawPath: string, opts: IncludeResolveOp
 /**
  * Expand a leading alias segment in a path or glob pattern to one candidate
  * per alias base, in the alias's base order. Used for config entry paths
- * (`entryGlob`/watch patterns), where — unlike @include resolution — there is
+ * (`entryGlob`/watch patterns), where, unlike @include resolution, there is
  * no including file to supply a relative fallback, so a non-alias path is
  * returned unchanged as the sole candidate.
  *

package/src/lib/project-install.d.mts

@@ -6,6 +6,7 @@
 export const PACKAGE_NAME: "@sous-io/sous";
 export const NO_DELEGATE_ENV: "SOUS_NO_DELEGATE";
 export const DEBUG_ENV: "SOUS_DEBUG";
+export const VERBOSE_FLAG: "--verbose";
 
 export type ProjectInstall =
   | { same: true; root: string }
@@ -13,19 +14,27 @@ export type ProjectInstall =
 
 export type HandoffPlan =
   | { kind: "run-self" }
-  | { kind: "hand-off"; install: Extract<ProjectInstall, { same: false }>; notice: string | undefined };
+  | { kind: "hand-off"; install: Extract<ProjectInstall, { same: false }>; notice: string[] };
 
 export function isEnvFlagOn(value: string | undefined): boolean;
 export function binEntryOf(pkg: unknown): string | undefined;
 export function findProjectInstall(startDir: string, ownRoot: string): ProjectInstall | undefined;
+export function formatHandoffNotice(input: {
+  install: Extract<ProjectInstall, { same: false }>;
+  ownVersion: string;
+  ownRoot: string;
+  verbose: boolean;
+}): string[];
 export function planHandoff(input: {
   cwd: string;
   ownRoot: string;
   env: Record<string, string | undefined>;
+  argv?: readonly string[];
 }): HandoffPlan;
 export function handOffToProjectInstall(input: {
   ownRoot: string;
   cwd?: string;
   env?: Record<string, string | undefined>;
+  argv?: readonly string[];
   stderr?: { write(chunk: string): unknown };
 }): Promise<boolean>;

package/src/lib/project-install.mjs

@@ -27,8 +27,11 @@
  *   - Anything unreadable or ambiguous means "run the copy that was invoked".
  *     A hand-off is a convenience; a refusal to run is not.
  *   - `SOUS_NO_DELEGATE` (anything but 0/false/no/off) runs the invoked copy.
- *   - The notice goes to stderr, so piped stdout stays clean, and only when
- *     the two versions differ; `SOUS_DEBUG` prints it on every hand-off.
+ *   - The notice goes to stderr, so piped stdout stays clean. It prints when
+ *     the two versions differ, and on every hand-off under `SOUS_DEBUG` or
+ *     with `--verbose` anywhere on the command line. Plain, it is one line
+ *     naming the version handed off to; verbose (`--verbose` or `SOUS_DEBUG`)
+ *     it adds where both installs are and how to keep the invoked one running.
  */
 
 import fs from "node:fs";
@@ -44,6 +47,9 @@ export const NO_DELEGATE_ENV = "SOUS_NO_DELEGATE";
 /** The environment variable that makes every hand-off announce itself. */
 export const DEBUG_ENV = "SOUS_DEBUG";
 
+/** The flag that makes the notice say where both installs are. */
+export const VERBOSE_FLAG = "--verbose";
+
 /**
  * Whether an on/off environment variable is on: set to anything but an empty
  * string, `0`, `false`, `no` or `off` (case-insensitive, whitespace trimmed).
@@ -129,29 +135,43 @@ function describeInstall(candidate, ownRoot) {
   return { same: false, root, version: typeof pkg.version === "string" ? pkg.version : "unknown", bin };
 }
 
+/**
+ * The lines the notice is made of: one line naming the version handed off to,
+ * and, when verbose, where both installs are and how to keep the invoked one
+ * running. Plain text, because this prints before tsx exists; the block
+ * mirrors the shape `showVariables` gives a key and value list.
+ */
+export function formatHandoffNotice({ install, ownVersion, ownRoot, verbose }) {
+  const lines = [`Handing off to the project-level Sous install: v${install.version}`];
+  if (verbose) {
+    lines.push(
+      `    Project install: ${install.root}`,
+      `    Invoked install: v${ownVersion} at ${ownRoot}`,
+      `Set ${NO_DELEGATE_ENV}=1 to run the invoked install instead.`
+    );
+  }
+  return lines;
+}
+
 /**
  * Decides what the invoked install should do, without doing it.
  *
  * Returns `{ kind: "run-self" }` when the invoked copy runs the command, or
  * `{ kind: "hand-off", install, notice }` naming the project copy to import
- * and the sentence to print on stderr first (undefined when nothing is said).
+ * and the lines to print on stderr first (an empty list when nothing is said).
  */
-export function planHandoff({ cwd, ownRoot, env }) {
+export function planHandoff({ cwd, ownRoot, env, argv = [] }) {
   if (isEnvFlagOn(env[NO_DELEGATE_ENV])) return { kind: "run-self" };
   const install = findProjectInstall(cwd, ownRoot);
   if (!install || install.same) return { kind: "run-self" };
 
   const ownPkg = readPackageJson(ownRoot);
   const ownVersion = typeof ownPkg?.version === "string" ? ownPkg.version : "unknown";
-  const differ = ownVersion !== install.version;
-  let notice;
-  if (differ) {
-    notice =
-      `Running the project's own sous ${install.version} from ${install.root} instead of the ` +
-      `sous ${ownVersion} you invoked; set ${NO_DELEGATE_ENV}=1 to run the one you invoked.`;
-  } else if (isEnvFlagOn(env[DEBUG_ENV])) {
-    notice = `Running the project's own sous ${install.version} from ${install.root}.`;
-  }
+  const verbose = isEnvFlagOn(env[DEBUG_ENV]) || argv.includes(VERBOSE_FLAG);
+  const announce = ownVersion !== install.version || verbose;
+  const notice = announce
+    ? formatHandoffNotice({ install, ownVersion, ownRoot: realpathOr(ownRoot), verbose })
+    : [];
   return { kind: "hand-off", install, notice };
 }
 
@@ -165,11 +185,12 @@ export async function handOffToProjectInstall({
   ownRoot,
   cwd = process.cwd(),
   env = process.env,
+  argv = process.argv.slice(2),
   stderr = process.stderr,
 }) {
-  const plan = planHandoff({ cwd, ownRoot, env });
+  const plan = planHandoff({ cwd, ownRoot, env, argv });
   if (plan.kind !== "hand-off") return false;
-  if (plan.notice) stderr.write(`${plan.notice}\n`);
+  for (const line of plan.notice) stderr.write(`${line}\n`);
   await import(pathToFileURL(plan.install.bin).href);
   return true;
 }

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

@@ -8,10 +8,16 @@
  *
  * 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
+ * scaffold would otherwise write. Two files are merged rather than replaced:
+ * `.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.
+ * never duplicates an entry; and the project's `package.json`, when there is
+ * one, which gains `@sous-io/sous` as a devDependency at the running version
+ * unless it already depends on it. A project that installs sous pins the
+ * version its templates were written against, and a global sous hands off to
+ * that copy, so the dependency is what makes every build of the project use
+ * one version. Nothing is installed: the project's own package manager does
+ * that, and sous does not guess which one it is.
  */
 
 import fs from "node:fs";
@@ -41,6 +47,15 @@ import {
 
 export * from "./templates.js";
 
+/** The npm package a scaffolded project is made to depend on. */
+export const SOUS_PACKAGE_NAME = "@sous-io/sous";
+
+/** What the scaffold did about the project's package.json. */
+export type PackageJsonOutcome =
+  | { kind: "absent" }
+  | { kind: "present"; path: string; range: string; section: "dependencies" | "devDependencies" }
+  | { kind: "added"; path: string; range: string };
+
 /** What to scaffold, and where. */
 export type ProjectScaffoldOptions = {
   /**
@@ -72,6 +87,8 @@ export type ProjectScaffoldResult = {
   name: string;
   /** Paths of every file written, relative to the project root, in the order written. */
   files: string[];
+  /** Whether `@sous-io/sous` was added to the project's package.json, was already there, or there is no package.json. */
+  packageJson: PackageJsonOutcome;
   /** True when nothing was actually written. */
   dryRun: boolean;
 };
@@ -124,6 +141,8 @@ export async function scaffoldProject(
 
   const context: ProjectScaffoldContext = { name, sousVersion: options.sousVersion };
   const files = planFiles(sousDir, projectRoot, format, context);
+  const dependency = planPackageJson(projectRoot, options.sousVersion);
+  if (dependency.file !== undefined) files.push(dependency.file);
 
   assertNothingWouldBeOverwritten(projectRoot, files);
 
@@ -145,10 +164,72 @@ export async function scaffoldProject(
     format,
     name,
     files: files.map((file) => file.relativePath),
+    packageJson: dependency.outcome,
     dryRun,
   };
 }
 
+/**
+ * Works out the package.json edit: nothing when the project has no
+ * package.json or already depends on sous, otherwise the file rewritten with
+ * `@sous-io/sous` in `devDependencies` at exactly the running version. The
+ * file's own indentation and trailing newline are kept, and `devDependencies`
+ * stays sorted the way npm keeps it. A package.json that is not JSON is
+ * refused by name, before anything is written.
+ */
+function planPackageJson(
+  projectRoot: string,
+  sousVersion: string
+): { file?: PlannedFile; outcome: PackageJsonOutcome } {
+  const packageJsonPath = path.join(projectRoot, "package.json");
+  if (!fs.existsSync(packageJsonPath)) return { outcome: { kind: "absent" } };
+
+  const raw = fs.readFileSync(packageJsonPath, "utf8");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new ConfigError(
+      `'sous init' would add ${SOUS_PACKAGE_NAME} to ${packageJsonPath}, but could not read it as JSON.\n` +
+        `  ${(error as Error).message}\n` +
+        `  Fix the file, or run 'sous init' in a directory without a package.json.`
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ConfigError(
+      `'sous init' would add ${SOUS_PACKAGE_NAME} to ${packageJsonPath}, but it does not hold a JSON object.`
+    );
+  }
+  const pkg = parsed as Record<string, unknown>;
+
+  for (const section of ["dependencies", "devDependencies"] as const) {
+    const deps = pkg[section];
+    if (typeof deps === "object" && deps !== null && SOUS_PACKAGE_NAME in deps) {
+      const range = String((deps as Record<string, unknown>)[SOUS_PACKAGE_NAME]);
+      return { outcome: { kind: "present", path: packageJsonPath, range, section } };
+    }
+  }
+
+  const existing =
+    typeof pkg.devDependencies === "object" && pkg.devDependencies !== null
+      ? (pkg.devDependencies as Record<string, unknown>)
+      : {};
+  const devDependencies = Object.fromEntries(
+    Object.entries({ ...existing, [SOUS_PACKAGE_NAME]: sousVersion }).sort(([a], [b]) =>
+      a < b ? -1 : a > b ? 1 : 0
+    )
+  );
+
+  const indent = raw.match(/^(\s+)"/m)?.[1] ?? "  ";
+  const newline = raw.endsWith("\n") ? "\n" : "";
+  const contents = JSON.stringify({ ...pkg, devDependencies }, null, indent) + newline;
+
+  return {
+    file: { relativePath: "package.json", contents, merged: true },
+    outcome: { kind: "added", path: packageJsonPath, range: sousVersion },
+  };
+}
+
 /** Builds every file the scaffold writes, in the order they are written. */
 function planFiles(
   sousDir: string,

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

@@ -28,10 +28,12 @@ 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.
+ * compiles. It lives under `memories/`, the directory for what a build composes
+ * into an agent's always-loaded instruction file, 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";
+export const STARTER_PROMPT_RELATIVE_PATH = "memories/AGENTS.md";
 
 /** The name of the file the starter prompt is compiled into, at the project root. */
 export const STARTER_OUTPUT_NAME = "AGENTS.md";
@@ -152,7 +154,7 @@ source, run \`sous build\`, and the compiled copy follows; never edit the compil
 ## 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
+- Split long sections into their own files under \`${SOUS_DIR_NAME}/memories/\` 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.

package/src/lib/version-report.ts

@@ -0,0 +1,90 @@
+/**
+ * What `sous --version` prints.
+ *
+ * oclif answers `--version` with its user agent string (package, version,
+ * platform and Node build on one line). Sous answers it itself, in bin/run.js,
+ * before oclif is loaded: the version alone, or with `--verbose` the same facts
+ * as a key and value list, so a person asking "which sous is this?" gets one
+ * short line and a person asking "where is it?" gets the rest.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import { log, showVariables } from "../utils/formatting.js";
+
+/** The one flag oclif treats as a version request, and so does sous. */
+export const VERSION_FLAG = "--version";
+
+/** The flag that adds where the install is, the platform and the Node build. */
+export const VERBOSE_FLAG = "--verbose";
+
+/** The facts a version report is made of. */
+export type VersionFacts = {
+  /** The npm package name. */
+  name: string;
+  /** The package version. */
+  version: string;
+  /** The absolute path of the install answering. */
+  root: string;
+  /** The platform and architecture, the way oclif spells them. */
+  platform: string;
+  /** The Node build, with its leading `v`. */
+  node: string;
+};
+
+/** Whether the command line is a version request: `--version` as its first word. */
+export function isVersionRequest(argv: readonly string[]): boolean {
+  return argv[0] === VERSION_FLAG;
+}
+
+/** Reads the facts about the install rooted at `packageRoot`. */
+export function readVersionFacts(packageRoot: string): VersionFacts {
+  const pkg = JSON.parse(fs.readFileSync(`${packageRoot}/package.json`, "utf8")) as {
+    name?: unknown;
+    version?: unknown;
+  };
+  return {
+    name: typeof pkg.name === "string" ? pkg.name : "unknown",
+    version: typeof pkg.version === "string" ? pkg.version : "unknown",
+    root: packageRoot,
+    platform: `${os.platform()}-${os.arch()}`,
+    node: process.version,
+  };
+}
+
+/**
+ * Prints the report: the version on its own line, and with `verbose` the
+ * facts under it as a key and value list.
+ *
+ * @param facts - What to report.
+ * @param verbose - Whether to print the facts under the version.
+ * @param write - Where each line goes; standard output by default.
+ */
+export function printVersionReport(
+  facts: VersionFacts,
+  verbose: boolean,
+  write: (line: string) => void = log
+): void {
+  write(`v${facts.version}`);
+  if (!verbose) return;
+  showVariables(
+    {
+      Package: facts.name,
+      Install: facts.root,
+      Platform: facts.platform,
+      Node: facts.node,
+    },
+    { write }
+  );
+}
+
+/**
+ * Answers a version request from the command line: `sous --version`, or
+ * `sous --version --verbose`.
+ *
+ * @param argv - The command line after the program name.
+ * @param packageRoot - The root of the install answering.
+ */
+export function printVersion(argv: readonly string[], packageRoot: string): void {
+  printVersionReport(readVersionFacts(packageRoot), argv.includes(VERBOSE_FLAG));
+}