@sous-io/sous 0.2.26 → 0.2.27

package/docs/markdown/_sidebar.md

@@ -26,3 +26,4 @@
   - [0005: Follow-ups from the first project on the hand-off](adrs/0005-first-project-follow-ups.md)
   - [0006: `sous repo init` follows `sous-recipes`](adrs/0006-repo-init-model-home.md)
   - [0007: Frozen index entries and tolerant readers](adrs/0007-frozen-index-dependencies.md)
+  - [0009: One whole build, everywhere](adrs/0009-whole-build-everywhere.md)

package/docs/markdown/commands.md

@@ -93,10 +93,21 @@ and the command you want almost always. Takes `--dry-run`.
 
 - `--no-prune`, `--no-compile`: skip one half of the run.
 - `--rebuild`: ignore cached hashes and reprocess every output.
-- `--strict`: fail on any compilation error rather than reporting it and continuing.
+- `--strict`: treat compile warnings as errors (a `.tpl.` file copied without being rendered, a git branch the
+  runtime context could not read).
 - `-w, --watch`: rebuild on every change to a source file, a config layer or a linked checkout.
 
-Before it compiles, a build lists each recipe this project uses that has a newer version within the range
+Before it compiles, a build prepares the project's recipes: it seeds the core recipe, pins any subscription the
+lockfile does not pin yet, restores whatever the store on this machine is missing, and checks upstream for the
+repositories that ask for newer versions. Every command that builds (`init`, `build`, `launch`, `prune`,
+`repo remove`, `repo unlink`, `subscription add`, `subscription remove`, `subscription update`) runs this same
+build, so each one prints the same things.
+
+A compile error (a missing or circular include, a template that fails to render, a file sous cannot read) fails
+the build. Every target is still compiled and every error is listed, then the build exits `1`. An output whose
+target had an error is not written, so the copy from the last good build stays in place.
+
+A build also lists each recipe this project uses that has a newer version within the range
 declared for it, beside the version pinned. It moves no pin; only always-pull moves one. The build reads upstream
 for this at most once per freshness window (`store.freshnessSeconds`, five minutes by default), gives a
 repository three seconds to answer, and otherwise answers from the cached index without a word about the
@@ -106,18 +117,22 @@ Example: `sous build --rebuild`
 
 ### `sous compile`
 Compiles markdown templates into output files, and prunes nothing. Takes `--rebuild`, `--strict`, `--dry-run`
-and `-w, --watch`, each meaning what it means on `build`. Example: `sous compile --strict`
+and `-w, --watch`, each meaning what it means on `build`, and exits `1` after a compile error the way `build`
+does. It does not prepare the recipes first. Example: `sous compile --strict`
 
 ### `sous prune`
-Removes output files no longer in the current config. Takes `--dry-run` only. Example: `sous prune --dry-run`
+Removes output files no longer in the current config. It prepares the recipes first, as `build` does, because
+what counts as current depends on the recipes the lockfile pins. Takes `--dry-run` only. Example:
+`sous prune --dry-run`
 
 ### `sous clear`
 Deletes every file and directory sous has written for the project, and asks first; `-f, --force` answers that
 confirmation ahead of time. Example: `sous clear --force`
 
 ### `sous launch TOOL...`
-Builds this project's outputs, then starts a coding agent configured under `tools` in its config. `--no-build`
-launches without building; `--continuous` restarts the agent whenever it exits.
+Builds this project's outputs, then starts a coding agent configured under `tools` in its config. A build that
+fails starts nothing and exits `1`. `--no-build` launches without building; `--continuous` restarts the agent
+whenever it exits.
 
 Any argument `launch` does not recognize is forwarded to the tool; a flag that collides with one of sous's own
 goes after a bare `--`: `sous launch claude --resume`, `sous launch claude -- -c`.
@@ -447,8 +462,9 @@ Example: `sous vars ask --namespace workflow --var apiUrl`
 
 A command that succeeds exits `0`. A command line sous could not parse (a missing argument, an unknown flag, a
 value outside a flag's options) exits `2`. Every other failure exits `1`. A broken config halts sous rather than
-producing output built on a guess. Compilation is the one place sous reports a failure and carries on;
-`--strict` on `build` and `compile` turns those reports into a failed run.
+producing output built on a guess. A build with a compile error carries on long enough to compile every target
+and list every error, then exits `1`, leaving the last good copy of each output that had an error;
+`--strict` on `build` and `compile` makes compile warnings fail the run too.
 
 A failure prints one error block, in plain language, and nothing else; a usage mistake gets the command's own
 help under it, on standard error. An error sous raises names the cause and the cure:

package/docs/markdown/repositories-authoring.md

@@ -143,7 +143,7 @@ variables:
 ## Declare dependencies and co-subscriptions
 
 `depends` fetches and pins a recipe whose files stay OUT of a subscriber's output but are addressable from your
-own templates. `subscribes` is a co-subscription: its questions run and its files DO enter the output, which is
+own templates, and from the templates of any project whose lockfile pins it. `subscribes` is a co-subscription: its questions run and its files DO enter the output, which is
 how a curated bundle is built. Both hold plain strings naming their target by where it lives.
 
 ```yaml

package/docs/markdown/repositories.md

@@ -331,9 +331,26 @@ published identity and then the path inside it, on a line of its own:
 ```
 
 The `~` is required. A bare `@path` is always a relative path or a declared alias, so an include
-line can never quietly stop meaning a file on disk. Inside a recipe, `~<namespace>` resolves only
-against that recipe's own `depends` and `subscribes` at the versions the lockfile pins, and the
-path after the recipe name may not be absolute or hold a `.` or `..` segment.
+line can never quietly stop meaning a file on disk. In your own templates, `~<namespace>`
+resolves against every recipe the lockfile pins, whatever brought it in: a recipe you subscribe
+to, a member of a set you subscribe to, or a library another recipe depends on. Inside a recipe,
+it resolves only against that recipe's own `depends` and `subscribes` at the versions the
+lockfile pins. The path after the recipe name may not be absolute or hold a `.` or `..` segment.
+
+An include naming a recipe the lockfile does not pin fails the build. When sous can tell what
+used to bring the recipe in (a switched-off subscription, or an earlier version of a set that
+listed it), the error names it:
+
+```text
+  Error: Include not found: @~workflow/member/memories/member.md
+  in file: .sous/prompts/AGENTS.md
+  namespace: workflow
+  recipe: workflow/member
+  The namespace "workflow" holds no recipe named "workflow/member".
+  Version 1.0.0 of "omakase/house" brought "workflow/member" in, but the version this project
+    pins, 1.1.0, does not, so the lockfile no longer pins it.
+  Subscribe to "workflow/member" directly to keep including it, or remove the include.
+```
 
 ## Where to go next
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "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

@@ -148,8 +148,9 @@ written `@~<namespace>/<recipe>/<path inside that recipe>`:
 
 Scoping is deliberate. A file inside a recipe may address that recipe itself plus the
 recipes it declares under `depends` or `subscribes`; a file in the project's own templates
-may address the project's subscriptions. Anything else is an error naming what was missing,
-so a reference can never quietly pick up a recipe nobody asked for.
+may address every recipe the project's lockfile pins, whatever brought it in. Anything else
+is an error naming what was missing, so a reference can never quietly pick up a recipe
+nobody asked for.
 
 Built-in **aliases** are reserved, always begin with `~`, and are consulted before recipe
 namespaces. There is exactly one:

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

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

package/src/commands/build.ts

@@ -1,23 +1,14 @@
 import { Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
-import { BuildService } from "../lib/build-service.js";
+import { runProjectBuild } from "../lib/build-service.js";
 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 { 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 {
-  footer,
-  heading,
-  log,
-  paragraph,
-  showCommandVars,
-  warning,
-} from "../utils/formatting.js";
+import { log, paragraph, showCommandVars } from "../utils/formatting.js";
 
 export default class Build extends BaseCommand {
   static description =
@@ -49,7 +40,7 @@ export default class Build extends BaseCommand {
       default: false,
     }),
     strict: Flags.boolean({
-      description: "Fail on any compilation error",
+      description: "Treat compile warnings as errors",
       default: false,
     }),
     watch: Flags.boolean({
@@ -71,37 +62,20 @@ export default class Build extends BaseCommand {
       "No Prune": flags["no-prune"],
     });
 
-    // A linked repository is read from a working copy instead of a published
-    // version, so it is announced every single time; a build that silently
-    // produced something different would be far worse than a noisy one.
-    const linked = describeLinkedRepos(this.configContext.sousDir);
-    if (linked.length > 0) warning(linked.join("\n"));
-
-    const repositories = subscriptionServiceFor({
-      configContext: this.configContext,
-      settings: this.settings,
-      shellEnv: this.shellEnv,
-    });
-
-    if (!flags["dry-run"] && !flags["no-compile"]) {
-      await prepareRepositoriesForBuild(repositories);
-    }
-
-    heading("Building");
-
     const buildOptions = {
       strict: flags.strict,
       rebuild: flags.rebuild,
       dryRun: flags["dry-run"],
       noCompile: flags["no-compile"],
       noPrune: flags["no-prune"],
-      configContext: this.configContext,
     };
 
-    const buildService = new BuildService();
-    const success = await buildService.build(this.settings, buildOptions);
-
-    footer();
+    const success = await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      options: buildOptions,
+    });
 
     if (!success && !flags.watch) {
       this.exit(1);
@@ -129,17 +103,23 @@ export default class Build extends BaseCommand {
 
       const watchService = new WatchService();
 
-      // Reruns compile + prune with the command's current settings. Called for
+      // Reruns the build with the command's current settings. Called for
       // partial rebuilds (with the changed file) and, after a clean reload, for
-      // full rebuilds. Owns the "Rebuilding" heading/footer.
+      // full rebuilds, which prepare the recipes again the way the first build did.
       const rebuild = async (changedFile?: string) => {
-        heading("Rebuilding");
-        await buildService.build(this.settings, {
-          ...buildOptions,
-          // --rebuild means full clean build on every trigger; skip partial optimisation
-          changedFile: buildOptions.rebuild ? undefined : changedFile,
+        // A failed rebuild has already listed its errors, and the watch keeps
+        // running so the next save can fix them.
+        await runProjectBuild({
+          settings: this.settings,
+          configContext: this.configContext,
+          shellEnv: this.shellEnv,
+          heading: "Rebuilding",
+          options: {
+            ...buildOptions,
+            // --rebuild means full clean build on every trigger; skip partial optimisation
+            changedFile: buildOptions.rebuild ? undefined : changedFile,
+          },
         });
-        footer();
       };
 
       const { handle, triggerFullRebuild } = startConfigReloadWatch({
@@ -154,6 +134,11 @@ export default class Build extends BaseCommand {
       // and a failure never breaks the watch; the last good answer stands.
       const pollSeconds = resolveStoreSettings(this.settings).watchPollSeconds;
       if (pollSeconds > 0) {
+        const repositories = subscriptionServiceFor({
+          configContext: this.configContext,
+          settings: this.settings,
+          shellEnv: this.shellEnv,
+        });
         const poll = setInterval(() => {
           void repositories
             .checkUpstream()

package/src/commands/compile.ts

@@ -34,7 +34,7 @@ export default class Compile extends BaseCommand {
   static flags = {
     ...BaseCommand.baseFlags,
     strict: Flags.boolean({
-      description: "Fail immediately on any error",
+      description: "Treat compile warnings as errors",
       default: false,
     }),
     rebuild: Flags.boolean({
@@ -113,7 +113,7 @@ export default class Compile extends BaseCommand {
 
     footer();
 
-    if (!success && flags.strict && !flags.watch) {
+    if (!success && !flags.watch) {
       this.exit(1);
     }
 

package/src/commands/init.ts

@@ -17,8 +17,7 @@ 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 { runProjectBuild } from "../lib/build-service.js";
 import {
   CONFIG_FILE_NAMES,
   SOUS_DIR_NAME,
@@ -28,7 +27,6 @@ import {
 } 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,
   SOUS_PACKAGE_NAME,
@@ -45,7 +43,6 @@ import {
   blankLine,
   dryRunNotice,
   footer,
-  heading,
   log,
   paragraph,
   section,
@@ -262,8 +259,8 @@ export default class Init extends BaseCommand {
   }
 
   /**
-   * Adopts the config just written and builds the project with it, in the
-   * same two steps `sous build` takes: the repositories are prepared (which
+   * Adopts the config just written and builds the project with it, through
+   * the same build `sous build` runs: the repositories are prepared (which
    * seeds the core recipe into the store and pins it in the lockfile), then
    * the outputs are compiled.
    *
@@ -274,17 +271,12 @@ export default class Init extends BaseCommand {
       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);
+    const succeeded = await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      heading: "Building the project",
+    });
 
     if (!succeeded) {
       throw new ConfigError(

package/src/commands/launch.ts

@@ -2,7 +2,8 @@ import { Args, Flags } from "@oclif/core";
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import { BaseCommand } from "../base-command.js";
-import { BuildService } from "../lib/build-service.js";
+import { runProjectBuild } from "../lib/build-service.js";
+import { ConfigError } from "../lib/errors.js";
 import { resolveRootScope, resolveTools } from "../lib/settings.js";
 import { displayError, footer, heading, showCommandVars } from "../utils/formatting.js";
 
@@ -85,16 +86,21 @@ export default class Launch extends BaseCommand {
       ...(passThroughArgs.length > 0 && { "Tool Args": passThroughArgs.join(" ") }),
     });
 
-    const buildService = new BuildService();
-
     do {
-      // Build step (unless --no-build)
+      // Build step (unless --no-build). A failed build stops here: the agent
+      // would otherwise start on outputs the build could not bring up to date.
       if (!flags["no-build"]) {
-        heading("Building");
-        await buildService.build(this.settings, {
+        const built = await runProjectBuild({
+          settings: this.settings,
           configContext: this.configContext,
+          shellEnv: this.shellEnv,
         });
-        footer();
+        if (!built) {
+          throw new ConfigError(
+            `The build failed, so ${args.tool} was not started. Fix the errors listed ` +
+              `above, or pass --no-build to start it with the outputs as they are.`
+          );
+        }
       }
 
       // Config-defined args first, then pass-through, then promptFile content

package/src/commands/prune.ts

@@ -1,7 +1,7 @@
 import { Flags } from "@oclif/core";
 import { BaseCommand } from "../base-command.js";
-import { BuildService, resolveStateFilePath } from "../lib/build-service.js";
-import { footer, heading, showCommandVars } from "../utils/formatting.js";
+import { runProjectBuild } from "../lib/build-service.js";
+import { showCommandVars } from "../utils/formatting.js";
 
 export default class Prune extends BaseCommand {
   static description = "Remove output files that are no longer in the current config";
@@ -22,19 +22,22 @@ export default class Prune extends BaseCommand {
   async run(): Promise<void> {
     const { flags } = await this.parse(Prune);
 
-    const stateFilePath = resolveStateFilePath(this.settings, this.configContext);
-
     showCommandVars({
       Project: this.projectLabel,
       Config: this.configContext.configPath,
       "Dry Run": flags["dry-run"],
     });
 
-    heading("Pruning");
-
-    const buildService = new BuildService();
-    await buildService.prune(this.settings, stateFilePath, flags["dry-run"], this.configContext);
-
-    footer();
+    // Prune goes through the same build path as everything else, with the
+    // compile step switched off: what counts as current depends on the recipes
+    // the lockfile pins, so they are restored first, or a recipe missing from
+    // the store would have its outputs pruned as if it were gone.
+    await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      heading: "Pruning",
+      options: { noCompile: true, dryRun: flags["dry-run"] },
+    });
   }
 }

package/src/commands/repo/remove.ts

@@ -14,7 +14,7 @@
 
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
-import { buildProjectOutputs } from "../../lib/build-service.js";
+import { runProjectBuild } from "../../lib/build-service.js";
 import { ConfigError } from "../../lib/errors.js";
 import { resolveRootScope } from "../../lib/settings.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
@@ -175,11 +175,12 @@ export default class RepoRemove extends BaseCommand {
   private async rebuildProject(name: string): Promise<void> {
     await this.reloadDiscoveredConfig();
 
-    heading("Building the project");
-
-    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
-
-    footer();
+    const succeeded = await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      heading: "Building the project",
+    });
 
     if (!succeeded) {
       throw new ConfigError(

package/src/commands/repo/unlink.ts

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
-import { buildProjectOutputs } from "../../lib/build-service.js";
+import { runProjectBuild } from "../../lib/build-service.js";
 import { ConfigError, isConfigError } from "../../lib/errors.js";
 import {
   NonInteractiveError,
@@ -409,11 +409,12 @@ export default class RepoUnlink extends BaseCommand {
   private async rebuildProject(name: string): Promise<void> {
     await this.reloadDiscoveredConfig();
 
-    heading("Building the project");
-
-    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
-
-    footer();
+    const succeeded = await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      heading: "Building the project",
+    });
 
     if (!succeeded) {
       throw new ConfigError(

package/src/commands/subscription/add.ts

@@ -24,7 +24,7 @@
 
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
-import { buildProjectOutputs } from "../../lib/build-service.js";
+import { runProjectBuild } from "../../lib/build-service.js";
 import { ConfigError } from "../../lib/errors.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
 import { formatAskReport } from "../../lib/vars/ask.js";
@@ -267,11 +267,12 @@ export default class SubscriptionAdd extends BaseCommand {
   private async rebuildProject(key: string): Promise<void> {
     await this.reloadDiscoveredConfig();
 
-    heading("Building the project");
-
-    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
-
-    footer();
+    const succeeded = await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      heading: "Building the project",
+    });
 
     if (!succeeded) {
       throw new ConfigError(

package/src/commands/subscription/remove.ts

@@ -12,7 +12,7 @@
 
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
-import { buildProjectOutputs } from "../../lib/build-service.js";
+import { runProjectBuild } from "../../lib/build-service.js";
 import { ConfigError } from "../../lib/errors.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
@@ -163,11 +163,12 @@ export default class SubscriptionRemove extends BaseCommand {
   private async rebuildProject(key: string): Promise<void> {
     await this.reloadDiscoveredConfig();
 
-    heading("Building the project");
-
-    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
-
-    footer();
+    const succeeded = await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      heading: "Building the project",
+    });
 
     if (!succeeded) {
       throw new ConfigError(

package/src/commands/subscription/update.ts

@@ -19,7 +19,7 @@
 
 import { Args, Flags } from "@oclif/core";
 import { BaseCommand } from "../../base-command.js";
-import { buildProjectOutputs } from "../../lib/build-service.js";
+import { runProjectBuild } from "../../lib/build-service.js";
 import { ConfigError } from "../../lib/errors.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
 import { describeUpdateScope } from "../../lib/repos/update-plan.js";
@@ -198,11 +198,12 @@ export default class SubscriptionUpdate extends BaseCommand {
   private async rebuildProject(): Promise<void> {
     await this.reloadDiscoveredConfig();
 
-    heading("Building the project");
-
-    const succeeded = await buildProjectOutputs(this.settings, this.configContext);
-
-    footer();
+    const succeeded = await runProjectBuild({
+      settings: this.settings,
+      configContext: this.configContext,
+      shellEnv: this.shellEnv,
+      heading: "Building the project",
+    });
 
     if (!succeeded) {
       throw new ConfigError(

package/src/lib/build-preparation.ts

@@ -1,9 +1,8 @@
 /**
  * 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.
+ * while it runs. `runProjectBuild` (`build-service.ts`) calls it, and every
+ * command that builds goes through that one function, so the step and its
+ * reporting are the same whichever command the user typed.
  */
 
 import type { SubscriptionService } from "./repos/subscription-service.js";

package/src/lib/build-service.ts

@@ -10,14 +10,16 @@ import { CompilationService, resolveOutputPath } from "./markdown-compiler.js";
 import type { CompilationConfig, CompilationTarget } from "./markdown-compiler.js";
 import { StateService } from "./state.js";
 import { isProtectedPath } from "./state.js";
-import { protectedRepoPaths } from "./repos/links.js";
+import { describeLinkedRepos, protectedRepoPaths } from "./repos/links.js";
+import { subscriptionServiceFor } from "./repos/subscription-service.js";
+import { prepareRepositoriesForBuild } from "./build-preparation.js";
 import {
   noRecipeAnswers,
   resolveRecipeAnswers,
   unansweredWarning,
   type RecipeAnswers,
 } from "./vars/answers.js";
-import { log, warning } from "../utils/formatting.js";
+import { footer, heading, log, warning } from "../utils/formatting.js";
 
 export type BuildOptions = {
   strict?: boolean;
@@ -437,22 +439,64 @@ export class BuildService {
   }
 }
 
+/** What {@link runProjectBuild} is given. */
+export type ProjectBuildInput = {
+  /** The merged project config, reloaded after any change a command made. */
+  settings: Settings;
+  /** Where the active config was discovered. */
+  configContext: ConfigContext;
+  /** The shell environment as it was before the env files were injected. */
+  shellEnv?: NodeJS.ProcessEnv;
+  /** The build's own options; every one defaults to what a plain `sous build` uses. */
+  options?: Omit<BuildOptions, "configContext">;
+  /** The heading printed above the compile and prune step. Defaults to "Building". */
+  heading?: string;
+};
+
 /**
- * Compiles and prunes a project exactly the way `sous build` does with no flags.
+ * The one build every command runs: `build`, `init`, `launch`, `prune`,
+ * `repo remove`, `repo unlink`, `subscription add`, `subscription remove` and
+ * `subscription update` all come through here, so a project is built the same
+ * way whichever of them the user typed.
  *
- * Shared by the subscription commands, which rebuild the project the moment they
- * have changed what it subscribes to: a newly subscribed recipe's files appear,
- * and a removed one's files are pruned, without anyone having to remember a
- * second command. Every option is left at its default on purpose, because the
- * point is to run the ordinary build and nothing else.
+ * In order, it announces every linked repository, prepares the project's
+ * recipes (seeds the core recipe, locks new subscriptions, restores whatever
+ * the store is missing, checks upstream and reports newer versions), and then
+ * compiles and prunes. A dry run prepares nothing, because preparing writes the
+ * lockfile and the store. A partial rebuild in watch mode (one changed source
+ * file) prepares nothing either: the config did not change, so neither did the
+ * recipes it needs.
  *
- * @param settings - The merged project config, reloaded after the change.
- * @param configContext - Where the active config was discovered.
- * @returns True when compile and prune both succeeded.
+ * @param input - The project, the build options and the heading.
+ * @returns True when compile and prune both succeeded; false after any compile error.
  */
-export async function buildProjectOutputs(
-  settings: Settings,
-  configContext: ConfigContext
-): Promise<boolean> {
-  return new BuildService().build(settings, { configContext });
+export async function runProjectBuild(input: ProjectBuildInput): Promise<boolean> {
+  const options = input.options ?? {};
+  const partial = options.changedFile !== undefined;
+
+  // A linked repository is read from a working copy instead of a published
+  // version, so it is announced on every build; a build that silently produced
+  // something different would be far worse than a noisy one.
+  if (!partial) {
+    const linked = describeLinkedRepos(input.configContext.sousDir);
+    if (linked.length > 0) warning(linked.join("\n"));
+  }
+
+  if (!options.dryRun && !partial) {
+    await prepareRepositoriesForBuild(
+      subscriptionServiceFor({
+        configContext: input.configContext,
+        settings: input.settings,
+        ...(input.shellEnv === undefined ? {} : { shellEnv: input.shellEnv }),
+      })
+    );
+  }
+
+  heading(input.heading ?? "Building");
+  const succeeded = await new BuildService().build(input.settings, {
+    ...options,
+    configContext: input.configContext,
+  });
+  footer();
+  return succeeded;
 }

package/src/lib/markdown-compiler.ts

@@ -63,6 +63,11 @@ export type CompilationConfig = {
 };
 
 export type CompilationServiceOptions = {
+  /**
+   * Treat compile warnings as errors. An error always fails the compile; this
+   * only decides whether a warning (a `.tpl.` file copied without being
+   * rendered, a git branch that could not be read) does too.
+   */
   strict?: boolean;
   rebuild?: boolean;
   dryRun?: boolean;
@@ -184,14 +189,26 @@ export class CompilationService {
     this.encoder = get_encoding("o200k_base");
   }
 
-  /** Handle errors according to strict mode. */
+  /**
+   * Records a compile error and prints it. The compile carries on, so every
+   * target is compiled and every error is listed; the output the error belongs
+   * to is not written, and the compile as a whole reports failure.
+   */
   private handleError(message: string): void {
     this.errors.push(message);
     displayError(message);
+  }
 
+  /**
+   * Records a compile warning: printed as a warning, or, in strict mode,
+   * recorded as an error, with everything an error brings.
+   */
+  private handleWarning(message: string): void {
     if (this.strict) {
-      process.exit(1);
+      this.handleError(message);
+      return;
     }
+    warning(message);
   }
 
   /**
@@ -383,7 +400,10 @@ export class CompilationService {
       ).trim();
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      this.handleError(`Failed to resolve current git branch: ${message}`);
+      this.handleWarning(
+        `Sous could not read the current git branch, so the runtime context says ` +
+          `"unknown": ${message}`
+      );
     }
 
     const runtimeHeader = `## Runtime Session Context
@@ -427,6 +447,21 @@ ${taskFileContents}
     fs.writeFileSync(ctx.outputPath, `${runtimeHeader}${taskFileBlock}\n`, "utf8");
   }
 
+  /**
+   * Says that an output was not written because its target had an error, and
+   * what that leaves on disk.
+   *
+   * @param destFile - The output that was not written.
+   */
+  private reportNotWritten(destFile: string): void {
+    const verb = this.dryRun ? "would not be written" : "not written";
+    log(
+      fs.existsSync(destFile)
+        ? `  ✗ ${destFile} (${verb} because of an error; the previous copy stays)`
+        : `  ✗ ${destFile} (${verb} because of an error)`
+    );
+  }
+
   /** Compile a single target, writing to all of its outputs. */
   private async compileTarget(
     target: CompilationTarget,
@@ -445,6 +480,8 @@ ${taskFileContents}
         ? target.includeSourceComments
         : this.includeSourceComments;
 
+    const errorsBefore = this.errors.length;
+
     if (target.runtimeContext) {
       this.generateRuntimeSessionContext(target);
     }
@@ -457,6 +494,11 @@ ${taskFileContents}
       return false;
     }
 
+    // An include that failed left a hole in the assembled content (and in strict
+    // mode, a warning counts as an error), so none of this target's outputs may
+    // be written: the previous copy stays in place.
+    const assembled = this.errors.length === errorsBefore;
+
     // Compute source hash once per target from the assembled content
     const contentHash = hashContent(content);
 
@@ -473,6 +515,12 @@ ${taskFileContents}
       if (resolvedDest === undefined) continue;
       destFile = resolvedDest;
 
+      if (!assembled) {
+        this.reportNotWritten(destFile);
+        allSucceeded = false;
+        continue;
+      }
+
       // A rendered output depends on its variables as much as on its source: a
       // changed answer or `_vars` value with the same template must re-render,
       // so the variable scope is part of a `.tpl.` output's source hash. A
@@ -508,8 +556,15 @@ ${taskFileContents}
       // directly, and it stays as a tripwire in case the resolver ever changes.
       if (isTpl && !output.vars) {
         this.unrenderedTemplates.push(`${target.rootInputPath} → ${destFile}`);
+        // In strict mode this warning is an error, so the output is not written.
+        if (this.strict) {
+          this.reportNotWritten(destFile);
+          allSucceeded = false;
+          continue;
+        }
       }
 
+      const errorsBeforeRender = this.errors.length;
       const resolvedContent = (isTpl && output.vars)
         ? await this.renderContent(
             content,
@@ -522,6 +577,14 @@ ${taskFileContents}
             target.rootInputPath
           )
         : content;
+
+      // A template that failed to render is not written either.
+      if (this.errors.length > errorsBeforeRender) {
+        this.reportNotWritten(destFile);
+        allSucceeded = false;
+        continue;
+      }
+
       const fileContent = resolvedContent;
       const outputDir = path.dirname(destFile);
 
@@ -582,8 +645,11 @@ ${taskFileContents}
   }
 
   /**
-   * Compile all targets from the given config.
-   * Returns true if all targets compiled successfully.
+   * Compile all targets from the given config. Every target is compiled even
+   * after an error, so every error is listed; an output whose target had an
+   * error is not written and keeps its previous copy and its state entry.
+   *
+   * @returns True when nothing reported an error; false after any error.
    */
   async compile(config: CompilationConfig, stateFilePath?: string): Promise<boolean> {
     const stateService = new StateService();
@@ -632,15 +698,7 @@ ${taskFileContents}
           `\nFix: add a '_vars' block to the output (an empty '_vars: {}' is enough to\n` +
           `enable rendering), or rename the source so it does not contain '.tpl.'.`;
 
-        if (this.strict) {
-          // Recorded as a failure rather than exiting here, so state still gets
-          // written and the caller decides the exit code.
-          this.errors.push(message);
-          displayError(message);
-          allSucceeded = false;
-        } else {
-          warning(message);
-        }
+        this.handleWarning(message);
       }
 
       if (this.errors.length > 0) {
@@ -665,7 +723,9 @@ ${taskFileContents}
         await stateService.save(stateFilePath, state);
       }
 
-      return allSucceeded;
+      // Any error fails the compile, including one that belongs to no single
+      // target (a bad config option).
+      return allSucceeded && this.errors.length === 0;
     } finally {
       if (this.encoder) {
         this.encoder.free();

package/src/lib/repos/locked-namespace-resolver.ts

@@ -12,25 +12,37 @@
  *
  *   - a file inside a recipe may address only that recipe's own declared
  *     dependencies (`depends` plus `subscribes`), at their pinned versions;
- *   - a file in the project's own templates may address the project's
- *     subscriptions.
+ *   - a file in the project's own templates may address every recipe the
+ *     lockfile pins, whatever holds it: the project, a set it subscribes to,
+ *     or another recipe's `depends`.
+ *
+ * When a project template names a recipe the lockfile does not pin, the error
+ * says which recipe used to bring it in, when the cached indexes or the config
+ * can tell.
  *
  * A project with no lockfile entries gets no resolver at all, so a project that
  * uses no repositories behaves exactly as it did before: `~` in an include line
  * means an alias and nothing else.
  */
 
+import semver from "semver";
 import type { Settings } from "../settings.js";
+import { resolveStoreRoot } from "../sous-home.js";
 import {
   StaticNamespaceResolver,
+  normalizeRef,
+  type DroppedRecipe,
   type NamespaceResolver,
 } from "./namespace-resolver.js";
 import {
   listLockedRecipes,
-  projectSubscriptionRefs,
+  readProjectLockfile,
   readRecipeManifestIn,
   type LockedRecipeLocation,
 } from "./locked-recipes.js";
+import { createIndexCache } from "./providers/index.js";
+import type { IndexFile } from "./formats/index-file.js";
+import type { Lockfile } from "./formats/lockfile.js";
 
 /** How the project's namespace resolver is built. */
 export type ProjectNamespaceResolverOptions = {
@@ -82,9 +94,125 @@ export function createProjectNamespaceResolver(
     if (declared.length > 0) dependencies[recipe.key] = declared;
   }
 
+  // No `projectScope`: a project template may address every recipe the
+  // lockfile pins, and those are exactly the recipes this resolver knows.
   return new StaticNamespaceResolver({
     recipes,
     dependencies,
-    projectScope: projectSubscriptionRefs(options.settings, locked),
+    explainMissing: (recipe) => explainUnpinnedRecipe(recipe, options),
   });
 }
+
+/**
+ * Why the lockfile does not pin a recipe a project template asked for, when
+ * that can be known without the network. Two things are checked, in order:
+ *
+ *   - a subscription to it (or to its namespace) that is switched off;
+ *   - another published version of a pinned recipe that brought it in, read
+ *     from the cached indexes of the lockfile's repositories. That version may
+ *     declare it directly, or declare a recipe that no longer is pinned either
+ *     and that declares it in turn; the shortest such chain is reported, and
+ *     among the versions of one pinned recipe the newest wins. This is the
+ *     usual story of a set that dropped one of its members, and the members'
+ *     own libraries with it.
+ *
+ * Only ever runs while an error is being reported, so it reads the lockfile
+ * and the cached indexes then rather than on every build.
+ *
+ * @param recipe - The `namespace/recipe` the template asked for.
+ * @param options - The project's `.sous/` directory, its config and the environment.
+ */
+export function explainUnpinnedRecipe(
+  recipe: string,
+  options: Pick<ProjectNamespaceResolverOptions, "sousDir" | "settings" | "env">
+): DroppedRecipe | undefined {
+  const namespace = recipe.slice(0, recipe.indexOf("/"));
+  for (const [key, entry] of Object.entries(options.settings.subscriptions ?? {})) {
+    if (entry?.enabled !== false) continue;
+    const ref = normalizeRef(key);
+    if (ref === recipe || ref === namespace) {
+      return { by: "disabled-subscription", subscription: key };
+    }
+  }
+
+  let lock: Lockfile;
+  try {
+    lock = readProjectLockfile(options.sousDir);
+  } catch {
+    // The build reports a broken lockfile on its own; an error message is no
+    // place to report it a second time.
+    return undefined;
+  }
+
+  const published = publishedVersions(lock, options.env ?? process.env);
+
+  /** What one published version of a recipe declares, as recipe keys. */
+  const declaredBy = (key: string, version: string): string[] =>
+    Object.keys(published.get(key)?.[version]?.dependencies ?? {});
+
+  // Breadth first from every other version of every pinned recipe, through
+  // recipes the lockfile does not pin, so the shortest chain is found first.
+  type Step = { key: string; root: { recipe: string; version: string }; through: string[] };
+  const queue: Step[] = [];
+  for (const holder of Object.keys(lock.recipes).sort()) {
+    const pinned = lock.recipes[holder]!.version;
+    const versions = Object.keys(published.get(holder) ?? {})
+      .filter((version) => version !== pinned && semver.valid(version) !== null)
+      .sort(semver.rcompare);
+    for (const version of versions) {
+      for (const key of declaredBy(holder, version)) {
+        queue.push({ key, root: { recipe: holder, version }, through: [] });
+      }
+    }
+  }
+
+  const seen = new Set<string>();
+  while (queue.length > 0) {
+    const step = queue.shift()!;
+    if (step.key === recipe) {
+      const root = step.root;
+      return {
+        by: "recipe",
+        recipe: root.recipe,
+        declaredAt: root.version,
+        pinned: lock.recipes[root.recipe]!.version,
+        ...(step.through.length > 0 ? { through: step.through } : {}),
+      };
+    }
+    // A pinned recipe is explained by its own entry, and each recipe is
+    // walked once.
+    if (Object.hasOwn(lock.recipes, step.key) || seen.has(step.key)) continue;
+    seen.add(step.key);
+    for (const version of Object.keys(published.get(step.key) ?? {})) {
+      for (const key of declaredBy(step.key, version)) {
+        queue.push({ key, root: step.root, through: [...step.through, step.key] });
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Every published version of every recipe in the cached indexes of the
+ * repositories the lockfile names, keyed by recipe. A repository with no
+ * cached index contributes nothing.
+ *
+ * @param lock - The project's lockfile.
+ * @param env - The environment, which decides where the store is.
+ */
+function publishedVersions(
+  lock: Lockfile,
+  env: NodeJS.ProcessEnv
+): Map<string, IndexFile["recipes"][string]["versions"]> {
+  const cache = createIndexCache({ storeRoot: resolveStoreRoot(env) });
+  const found = new Map<string, IndexFile["recipes"][string]["versions"]>();
+  const identities = new Set(Object.values(lock.repos).map((repo) => repo.identity));
+  for (const identity of [...identities].sort()) {
+    const index = cache.readCached(identity);
+    for (const [key, entry] of Object.entries(index?.recipes ?? {})) {
+      if (!found.has(key)) found.set(key, entry.versions);
+    }
+  }
+  return found;
+}

package/src/lib/repos/locked-recipes.ts

@@ -20,7 +20,6 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import type { Settings } from "../settings.js";
 import { resolveStoreRoot } from "../sous-home.js";
 import { parseLockfile, type LockKind, type Lockfile } from "./formats/lockfile.js";
 import { parseRecipeManifest, type RecipeManifest } from "./formats/recipe-manifest.js";
@@ -34,7 +33,6 @@ import {
 } from "./load-manifest.js";
 import { readEffectiveLinks } from "./links.js";
 import { identitySegments } from "./identity.js";
-import { enabledSubscriptions } from "./defaults.js";
 import { PROJECT_HOLDER } from "./formats/lockfile.js";
 
 /** One locked recipe, together with the directory its files are read from. */
@@ -233,26 +231,6 @@ export function keysHeldBySubscription(lock: Lockfile, key: string): string[] {
     .sort();
 }
 
-/**
- * The refs a project's own templates may address: everything it subscribed to
- * directly. Both sources are read, because a subscription may be written by
- * `sous subscribe` into the managed layer, hand-written in the primary config,
- * or (for an older project) recorded only in the lockfile.
- *
- * @param settings - The merged project config.
- * @param locked - The locked recipes, as returned by listLockedRecipes.
- */
-export function projectSubscriptionRefs(
-  settings: Settings,
-  locked: LockedRecipeLocation[]
-): string[] {
-  const refs = new Set<string>(Object.keys(enabledSubscriptions(settings)));
-  for (const recipe of locked) {
-    if (recipe.requestedBy.includes(PROJECT_HOLDER)) refs.add(recipe.key);
-  }
-  return [...refs].sort();
-}
-
 /**
  * Every locked recipe reachable from a set of keys through the lockfile's
  * holder lists: the keys themselves, whatever they hold, and so on.

package/src/lib/repos/namespace-resolver.ts

@@ -26,10 +26,31 @@ import path from "node:path";
  * the including file:
  *   - a file that lives inside a recipe may address only that recipe's declared
  *     dependencies (`depends` plus `subscribes`) at their pinned versions;
- *   - a file in the project's own templates may address the project's
- *     subscriptions.
+ *   - a file in the project's own templates may address every recipe the
+ *     project's lockfile pins, whatever holds it.
  */
 
+/**
+ * Why a recipe a project template asked for is not pinned any more, when that
+ * can be known. Only ever attached to an answer for a project template.
+ */
+export type DroppedRecipe =
+  /**
+   * Another version of a pinned recipe declares it (in `depends` or
+   * `subscribes`), and the version the lockfile pins does not: the usual story
+   * of a set that dropped one of its members.
+   */
+  | {
+      by: "recipe";
+      recipe: string;
+      declaredAt: string;
+      pinned: string;
+      /** The recipes, no longer pinned either, that the chain ran through, in order. */
+      through?: string[];
+    }
+  /** The project subscribes to it, but the subscription is switched off. */
+  | { by: "disabled-subscription"; subscription: string };
+
 /** A single `~namespace/rest` resolution request. */
 export type NamespaceRequest = {
   /** The namespace name, with the leading `~` already stripped (e.g. `workflow`). */
@@ -59,20 +80,24 @@ export type NamespaceRequest = {
 export type NamespaceResolution =
   /** Ordered absolute paths to try, most preferred first. An empty list means the lookup produced nothing. */
   | { kind: "candidates"; candidates: string[] }
-  /** No such namespace is known at all. `known` lists the namespaces that are. */
-  | { kind: "unknown-namespace"; known: string[] }
+  /**
+   * No such namespace is known at all. `known` lists the namespaces that are.
+   * `dropped` says why a project template's recipe is no longer pinned, when
+   * that can be known.
+   */
+  | { kind: "unknown-namespace"; known: string[]; dropped?: DroppedRecipe }
   /**
    * The namespace exists but holds no such recipe. `recipe` is the fully
    * qualified ref that was asked for; `known` lists the recipe refs the
-   * namespace does hold.
+   * namespace does hold; `dropped` is as above.
    */
-  | { kind: "unknown-recipe"; recipe: string; known: string[] }
+  | { kind: "unknown-recipe"; recipe: string; known: string[]; dropped?: DroppedRecipe }
   /**
    * The recipe exists but the including file is not allowed to address it.
    * `recipe` is the fully qualified ref that was asked for. `includingRecipe`
    * is the ref of the recipe the including file belongs to, or `null` when the
-   * including file is one of the project's own templates (in which case the
-   * project simply does not subscribe to the recipe).
+   * including file is one of the project's own templates (which only happens
+   * when the resolver was given a narrower `projectScope`).
    */
   | { kind: "not-a-dependency"; recipe: string; includingRecipe: string | null }
   /**
@@ -126,6 +151,7 @@ export function formatNamespaceProblem(opts: {
         ? `Available namespaces: ${resolution.known.join(", ")}.`
         : "This project has no recipe namespaces available yet."
     );
+    if (resolution.dropped) lines.push(...describeDropped(resolution.dropped, opts));
   } else if (resolution.kind === "unknown-recipe") {
     lines.push(`recipe: ${resolution.recipe}`);
     lines.push(`The namespace "${opts.namespace}" holds no recipe named "${resolution.recipe}".`);
@@ -134,6 +160,7 @@ export function formatNamespaceProblem(opts: {
         ? `Recipes in this namespace: ${resolution.known.join(", ")}.`
         : `The namespace "${opts.namespace}" currently holds no recipes.`
     );
+    if (resolution.dropped) lines.push(...describeDropped(resolution.dropped, opts));
   } else if (resolution.kind === "not-a-dependency") {
     lines.push(`recipe: ${resolution.recipe}`);
     if (resolution.includingRecipe) {
@@ -144,10 +171,7 @@ export function formatNamespaceProblem(opts: {
         `Add "${resolution.recipe}" to the "depends" list in that recipe's manifest before addressing it as "~${opts.namespace}".`
       );
     } else {
-      lines.push(`This project does not subscribe to "${resolution.recipe}".`);
-      lines.push(
-        `Subscribe to it before addressing it as "~${opts.namespace}" from a project template.`
-      );
+      lines.push(`The project's own templates may not address "${resolution.recipe}".`);
     }
   } else if (resolution.kind === "escapes-recipe") {
     lines.push(`recipe: ${resolution.recipe}`);
@@ -167,6 +191,37 @@ export function formatNamespaceProblem(opts: {
   return lines.map((line) => `  ${line}`).join("\n");
 }
 
+/**
+ * The lines that say why a recipe a project template asked for is no longer
+ * pinned, and what brings it back.
+ *
+ * @param dropped - What is known about how the recipe used to be pinned.
+ * @param opts - The namespace and the rest of the reference, for the recipe's name.
+ */
+function describeDropped(
+  dropped: DroppedRecipe,
+  opts: { namespace: string; rest: string }
+): string[] {
+  const recipe = `${opts.namespace}/${opts.rest.split("/")[0] ?? ""}`;
+  if (dropped.by === "disabled-subscription") {
+    return [
+      `This project subscribes to "${dropped.subscription}", but that subscription is ` +
+        `switched off ("enabled: false"), so the lockfile does not pin "${recipe}".`,
+      `Switch the subscription back on, or remove the include.`,
+    ];
+  }
+  const through =
+    dropped.through === undefined || dropped.through.length === 0
+      ? ""
+      : ` (through ${dropped.through.map((key) => `"${key}"`).join(", ")})`;
+  return [
+    `Version ${dropped.declaredAt} of "${dropped.recipe}" brought "${recipe}" in${through}, but ` +
+      `the version this project pins, ${dropped.pinned}, does not, so the lockfile no longer ` +
+      `pins it.`,
+    `Subscribe to "${recipe}" directly to keep including it, or remove the include.`,
+  ];
+}
+
 /** Options for {@link StaticNamespaceResolver}. */
 export type StaticNamespaceResolverOptions = {
   /**
@@ -186,9 +241,16 @@ export type StaticNamespaceResolverOptions = {
   /**
    * What the project's own templates may address, in the same ref forms as
    * `dependencies`. Omit it to make every known recipe addressable from
-   * project templates (the convenient default for tests).
+   * project templates, which is the rule for a real project: its templates may
+   * address everything its lockfile pins.
    */
   projectScope?: string[];
+  /**
+   * Says why a recipe a project template asked for is not among `recipes`,
+   * when that can be known. Consulted only for a project template's reference
+   * to a recipe the resolver does not know.
+   */
+  explainMissing?: (recipe: string) => DroppedRecipe | undefined;
 };
 
 /**
@@ -196,7 +258,7 @@ export type StaticNamespaceResolverOptions = {
  * recipe refs to directories.
  *
  * It implements the full scoping rule (recipe files see their declared
- * dependencies; project files see the project's subscriptions) without knowing
+ * dependencies; project files see every known recipe, or `projectScope`) without knowing
  * anything about repositories, versions or the store, which makes it the
  * resolver used by tests and a usable core for the real implementation to wrap.
  */
@@ -204,6 +266,7 @@ export class StaticNamespaceResolver implements NamespaceResolver {
   private readonly recipes: Record<string, string>;
   private readonly dependencies: Record<string, string[]>;
   private readonly projectScope?: string[];
+  private readonly explainMissing?: (recipe: string) => DroppedRecipe | undefined;
 
   constructor(options: StaticNamespaceResolverOptions) {
     this.recipes = {};
@@ -212,6 +275,18 @@ export class StaticNamespaceResolver implements NamespaceResolver {
     }
     this.dependencies = options.dependencies ?? {};
     this.projectScope = options.projectScope;
+    this.explainMissing = options.explainMissing;
+  }
+
+  /**
+   * Why a project template's reference names a recipe this resolver does not
+   * know, or undefined when the including file is a recipe's own or nothing is
+   * known.
+   */
+  private droppedFor(recipe: string, fromFile: string): { dropped?: DroppedRecipe } {
+    if (this.explainMissing === undefined || this.includingRecipe(fromFile) !== null) return {};
+    const dropped = this.explainMissing(recipe);
+    return dropped === undefined ? {} : { dropped };
   }
 
   /** Every namespace this resolver knows about, sorted. */
@@ -254,17 +329,27 @@ export class StaticNamespaceResolver implements NamespaceResolver {
   resolve(request: NamespaceRequest): NamespaceResolution {
     const { namespace, rest, fromFile } = request;
 
-    if (!this.knownNamespaces().includes(namespace)) {
-      return { kind: "unknown-namespace", known: this.knownNamespaces() };
-    }
-
     const segments = rest.split("/").filter((segment) => segment.length > 0);
     const recipeName = segments[0] ?? "";
     const ref = `${namespace}/${recipeName}`;
+
+    if (!this.knownNamespaces().includes(namespace)) {
+      return {
+        kind: "unknown-namespace",
+        known: this.knownNamespaces(),
+        ...this.droppedFor(ref, fromFile),
+      };
+    }
+
     const recipeDir = this.recipes[ref];
 
     if (!recipeDir) {
-      return { kind: "unknown-recipe", recipe: ref, known: this.recipesIn(namespace) };
+      return {
+        kind: "unknown-recipe",
+        recipe: ref,
+        known: this.recipesIn(namespace),
+        ...this.droppedFor(ref, fromFile),
+      };
     }
 
     const includingRecipe = this.includingRecipe(fromFile);