@sous-io/sous 0.2.29 → 0.2.31

package/README.md

@@ -40,6 +40,18 @@ output. When the two versions differ, one line on standard error names the versi
 to; `--verbose` announces every hand-off and adds where both installs are. Set
 `SOUS_NO_DELEGATE=1` to run the copy you invoked instead.
 
+To update, run `sous update`. It updates the global install, the project's own install, or both
+(whichever this directory has), through the package manager that installed each one (npm, pnpm or
+Yarn), and asks before each one. By default each install moves to the newest version in its current
+major; `--major` goes past it, `--version <version|range|tag>` picks one (a downgrade included),
+`--global` and `--project` narrow the run, `--yes` answers every question and `--dry-run` only
+prints the plan. After a project update, the new copy builds the project, so its lockfile moves to
+the new version too.
+
+```bash
+sous update --dry-run     # show what would be installed where, and install nothing
+```
+
 Or run it from a clone (useful when developing sous itself):
 
 ```bash

package/docs/markdown/README.md

@@ -59,6 +59,58 @@ $ SOUS_NO_DELEGATE=1 sous --version
 v0.3.0
 ```
 
+### Updating
+
+`sous update` moves each copy of sous to a newer version (or one you choose) through the package
+manager that installed it, so you never need to remember which one that was or its syntax:
+
+- **Outside a project**, or in a project that does not install sous, it updates the global install.
+  Each of npm, pnpm and Yarn classic is asked where its global packages live, and every global
+  install found is updated with its own manager (`npm i -g`, `pnpm add -g`, `yarn global add`).
+- **In a project that installs sous**, it updates the project's install with the project's own
+  manager (`npm i -D -E`, `pnpm add -D -E`, `yarn add -D -E`), which pins the exact version in
+  `package.json` and updates the lockfile. A dependency declared under `dependencies` stays there.
+  It updates the global install as well when there is one. A Yarn Plug'n'Play project, which has
+  no `node_modules`, counts as installing sous when its `package.json` declares it and a `.pnp.cjs`
+  sits beside it or above it; the installed version is read from `yarn.lock`.
+- **After a project update**, the newly installed copy builds the project, so
+  `.sous/sous.lock.json` pins the core recipe at the new version. Under Yarn Plug'n'Play, Yarn
+  runs that build (`yarn run --binaries-only sous build`). `--no-build` skips it.
+
+Under Yarn Plug'n'Play, sous runs only from a copy Yarn has unpacked; from inside Yarn's zip cache
+it fails with `EBADF: bad file descriptor`. Unpack it in `package.json`, then run `yarn install`:
+
+```json
+"dependenciesMeta": { "@sous-io/sous": { "unplugged": true } }
+```
+
+`update` always runs in the copy you invoked, never handed off to the project's own; a project copy
+may be too old to have the command. A project config this copy cannot load (one written for a newer
+sous, say) is a warning rather than a stop, since installing a newer copy may be the fix.
+
+Every plan is worked out before anything is installed, and each install prints its plan and asks
+its own question. Each is judged on its own version:
+
+- By default, the newest published version in the install's current major (for a 0.x install,
+  anything below 1.0.0). A default run never downgrades.
+- `--major`: the newest published version, whatever its major.
+- `--version <version|range|tag>`: exactly that version, the newest one in that range, or the one a
+  dist-tag such as `next` points at. This is how you downgrade, and the plan says when it is one.
+- `--prerelease` counts prerelease versions, and is on by default when the installed version is a
+  prerelease; `--no-prerelease` switches it off.
+- `--global` or `--project` updates only that install; `-y, --yes` answers every question;
+  `--dry-run` prints the plans, with the command each would run, and installs nothing.
+
+A copy run through `npx`, or one managed by Volta or by a manager sous does not drive, is listed
+with the command to run by hand, and the rest are still updated. A package manager's own failure
+is printed as the manager reported it; sous never retries with `sudo`.
+
+```term
+$ sous update --dry-run
+// every install's plan, and nothing installed
+$ sous update --global --yes
+```
+
 ## Where to look
 
 - Watch the [animated introduction](../) for the full pitch

package/docs/markdown/_sidebar.md

@@ -28,3 +28,5 @@
   - [0007: Frozen index entries and tolerant readers](adrs/0007-frozen-index-dependencies.md)
   - [0008: One ref parser, told where the ref came from](adrs/0008-one-ref-parser.md)
   - [0009: One whole build, everywhere](adrs/0009-whole-build-everywhere.md)
+  - [0010: The index describes each version's dependencies and questions](adrs/0010-index-describes-recipes.md)
+  - [0011: `sous update` updates sous through the package managers](adrs/0011-self-update.md)

package/docs/markdown/commands.md

@@ -146,6 +146,27 @@ so it works offline. `--limit <n>` sets how many matches to show, defaulting to
 only installed recipes and adds an Installed column. Also spelled `sous repo search`.
 Example: `sous search task --limit 50`
 
+### `sous update`
+Updates sous itself: the global install, this project's own install, or both, each through the package manager
+that installed it. It works outside a project too, and it always runs in the copy you invoked, never handed off
+to the project's own. Every plan is printed before anything is installed, and each install asks its own
+question. After a project update the new copy builds the project, so the lockfile pins the core recipe at the new
+version. A project config this copy cannot load is one warning, not a stop. Takes `-y, --yes` and `--dry-run`
+(which also prints the command each install would run). See [Updating](README.md#updating).
+
+- `--major`: install the newest published version, whatever its major. By default each install moves to the
+  newest version in its current major, and never down.
+- `--version <version|range|tag>`: install exactly this version, the newest in this range, or the one this
+  dist-tag names. This is how you downgrade.
+- `--prerelease`, `--no-prerelease`: count prerelease versions as candidates, or not. On by default when the
+  installed version is a prerelease. `--pre` is the same flag.
+- `--global`, `--project`: update only that install.
+- `--no-build`: update the project install without building the project afterwards.
+
+`--major` and `--version` exclude each other, and so do `--global` and `--project`.
+
+Example: `sous update --version next --dry-run`
+
 ### `sous help [COMMAND]`
 Prints the help for sous, or for one command or topic. Works from any directory, including one with no config
 above it. Example: `sous help repo add`
@@ -347,8 +368,9 @@ optionally carrying an `@<range>` and a `repo:` qualifier; see
 ### `sous subscription add REF`
 Subscribes this project to a recipe, or to a whole namespace of them, then builds the project so the recipe's
 files are on disk when the command returns. Also spelled `sous subscribe`. Takes `-y, --yes`, `--no-build`, and
-`--dry-run`, which also prints the questions of every recipe this machine already holds; a recipe not held here
-yet is named instead, because a dry run downloads nothing.
+`--dry-run`, which also prints every question the recipes would ask. A dry run downloads nothing, so a recipe
+not on this machine is described from its repository's index; one whose index entry predates the release that
+began recording questions there is named instead.
 
 - `--prerelease`: let prerelease versions take part in range matching.
 - `--always-pull`: install a newer in-range version whenever one exists, rather than holding the lock.
@@ -409,10 +431,13 @@ Lists the recipes the trusted repositories publish, across every namespace, with
 `namespace show` prints. Example: `sous recipe list --installed --latest`
 
 ### `sous recipe show REF`
-Describes one recipe completely: its repository and location, every published version, its dependencies as
-declared and as resolved at release time, the questions it asks with the environment variable each answer is
-stored under, and the directories its files are written into. `REF` is `namespace/recipe`, a recipe name alone,
-or either with a `repository:` qualifier. Example: `sous recipe show sous-recipes:core/about-sous`
+Describes one recipe completely: its repository and location, every published version, its dependencies (the
+manifest entry bringing each one in, such as a whole namespace, whether it is a co-subscription or a build
+dependency, and the version it was released against), every recipe a subscription to it would install, every
+question that would ask, laid out as `sous subscription add --dry-run` lays them out, and the directories its
+files are written into. Everything but the files comes from the index, so a recipe nothing has installed yet
+is described in full, offline. `REF` is `namespace/recipe`, a recipe name alone, or either with a
+`repository:` qualifier. Example: `sous recipe show omakase/house`
 
 ## lock
 

package/docs/markdown/repositories-authoring.md

@@ -243,9 +243,13 @@ this release's scope** is fine: the release depends on the last published versio
 ```
 
 Each version's resolved dependencies are written into the index, so a consumer installing that version gets what
-it was published with rather than ranges re-resolved months later. A published version never changes: its content
-hash and its dependencies are carried forward exactly as published, and a disagreement is an error telling you
-to bump rather than republish ([what is checked](repositories-file-formats.md#sousindexjson)). A version counts
+it was published with rather than ranges re-resolved months later. Each dependency also records the manifest
+entry that brought it in and whether it is a co-subscription or a build dependency, and each version records the
+variable definitions its manifest publishes, so `sous recipe show` and `sous subscription add --dry-run` can say
+what a recipe installs and asks before anything is fetched. A published version never changes: its content
+hash, its dependencies and its variable definitions are carried forward exactly as published, and a
+disagreement is an error telling you to bump rather than republish
+([what is checked](repositories-file-formats.md#sousindexjson)). A version counts
 as published once its tag exists, and the tags are the backstop, so a tagged version missing from the index is
 rebuilt from it, dependencies included, whenever the index is regenerated, which only happens on a run that
 publishes something. A bump edits the manifest in place, so comments, field order and layout survive; a folded

package/docs/markdown/repositories-consuming.md

@@ -65,22 +65,35 @@ The cache can be behind what a repository has published since. Every one of thes
 `sous recipe list --installed --latest` is the out-of-date view: every installed recipe, with
 upstream's newest version beside the installed one.
 
-Read `sous recipe show` before subscribing: every published version, what it depends on (as
-declared, beside the version the index resolved it to), and its questions and files once it has
-them here.
+Read `sous recipe show` before subscribing. It works offline, from the index alone: every published
+version, what the version depends on (the manifest entry that brings each dependency in, whether it
+is a co-subscription whose files land here or a build dependency, and the version it was released
+against), every recipe a subscription would install, and every question that would ask. Only the
+files it publishes wait until it is installed. A preset set, a recipe that only bundles others,
+reads like this:
 
 ```term
-$ sous recipe show workflow/qa-variables
-    Latest version : 0.1.0
+$ sous recipe show omakase/house
+    Latest version : 1.0.0
     Pinned version : this project pins none
     Subscribed     : no
-  Dependency          Declared as                     Resolved to  Repository       Kind
-  ------------------  ------------------------------  -----------  ---------------  ----------------
-  workflow/qa-helper  not declared in the manifest    0.1.0        this repository  unknown
-  The recipe's own files are not on this machine, so the questions it asks and the files it
-    publishes are not known here. Subscribing to it fetches them.
+  Dependency       Declared as                     Resolved to  Repository       Kind
+  ---------------  ------------------------------  -----------  ---------------  ----------------
+  tools/lint       tools/lint                      1.0.0        this repository  build dependency
+  workflow/notes   the whole 'workflow' namespace  1.0.0        this repository  co-subscription
+  workflow/review  the whole 'workflow' namespace  1.0.0        this repository  co-subscription
+➔ What subscribing asks you:
+  These recipes ask 3 questions, 3 of which nothing answers yet.
+  workflow/notes asks 1 question:
+    notesDir
+      about       : Where the notes skill keeps its notes.
+      stored-as   : SOUS_VAR_NOTES_DIR
+      answered    : no, and this recipe requires an answer
 ```
 
+?> A recipe released before sous recorded questions in the index is described from its files
+instead, so its questions are listed once it is installed, and named as unknown until then.
+
 ## Subscribe to a recipe
 
 ```bash
@@ -206,8 +219,9 @@ stored value nothing reads. Names are camelCase, as the recipe declares them; th
 `namespace/recipe.name` key works too when two recipes publish the same name, and everything after
 the first `=` is the answer. `--answers-file answers.yaml` reads a YAML or JSON file of them.
 
-?> A dry run downloads nothing, so a recipe your machine does not hold yet has no manifest to read
-and its questions cannot be listed; the run still succeeds and names them.
+?> A dry run downloads nothing. A recipe your machine does not hold yet is described from the
+questions its repository's index records; one released before sous recorded questions there cannot
+be, so the run still succeeds and names it.
 
 ## See what you have
 

package/docs/markdown/repositories-file-formats.md

@@ -201,8 +201,16 @@ fetches only this file; nothing more is downloaded until a project subscribes.
   "namespaces": { "quality": { "description": "Recipes that exercise the edges." } },
   "recipes": { "quality/qa-remote-dep": { "path": "recipes/quality/qa-remote-dep",
     "versions": { "0.1.0": {
-      "dependencies": { "workflow/qa-helper": { "version": "0.1.0" },
-        "workflow/sub-agent-delegation": { "range": "^1.0", "repo": "github.com/sous-io/sous-recipes" } },
+      "dependencies": {
+        "workflow/qa-helper": { "version": "0.1.0", "declared": "workflow", "kind": "subscribes" },
+        "workflow/sub-agent-delegation": { "range": "^1.0", "repo": "github.com/sous-io/sous-recipes",
+          "declared": "github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0",
+          "kind": "depends" } },
+      "depends": [ "github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0" ],
+      "subscribes": [ "workflow" ],
+      "variables": [ { "name": "qaNotesDir", "type": "path", "prompt": "Where should notes go?",
+        "description": "The directory QA notes are written to.", "example": "docs/qa",
+        "default": ".sous/qa-notes", "required": true, "secret": false, "scope": "shared" } ],
       "hash": "sha256-46e75442aeb368116c8830ad382707759f1ecd03974c4b5d42a5fabffce0324f",
       "prerelease": false, "releasedAt": "2026-09-12T07:06:33.236Z",
       "tag": "quality/qa-remote-dep@0.1.0"
@@ -216,12 +224,30 @@ fetches only this file; nothing more is downloaded until a project subscribes.
 | `recipes` | top level | Keyed `namespace/recipe`; a recipe whose namespace is not declared is an error. Each entry carries `path` (the recipe folder), `description`, and `versions`, keyed by exact version |
 | `hash`, `tag` | per version | The content hash verified after every fetch, and the tag, which must be exactly `namespace/recipe@version` so a version can never point at a branch |
 | `prerelease`, `releasedAt`, `seeded` | per version | Whether ranges skip it unless a subscription opts in, when it was released, and whether it is the copy sous folds in from its own package |
+| `dependencies` | per version | What the version was released against, keyed `namespace/recipe`; see below |
+| `variables` | per version | The version's variable definitions, exactly as its manifest publishes them (see [Variable definitions](#variable-definitions)), with `required`, `secret` and `scope` filled in; `[]` when it asks nothing |
+| `depends`, `subscribes` | per version | The version's manifest lists, exactly as written; `[]` when empty |
 
 Dependencies are resolved at release time and keyed `namespace/recipe`. An entry carries `version` (a
 sibling, resolved exactly) or `range` plus `repo` (the identity of the repository publishing it, whose own
 index resolves the range); at least one is required. Installing a version installs these rather than
 re-resolving the manifest's ranges.
 
+**Each version describes itself.** So that a recipe can be described before anything is fetched, every
+version a release records carries more than its dependencies. Each dependency records `declared`, the
+manifest entry that brings it in exactly as written (a recipe such as `workflow/qa-helper@^1.0`, a whole
+namespace such as `workflow`, or a locator), and `kind`: `subscribes` for a co-subscription, whose files
+land and whose questions are asked, or `depends` for a build dependency. When several entries cover one
+recipe, an entry naming it wins over a namespace, and it is a co-subscription when any entry covering it is
+one. The version records `variables`, its manifest's definitions, and `depends` and `subscribes`, its
+manifest's lists as written; the lists are what a consumer walks, because a namespace of another repository
+has no recipe key to record it under. All of them are written even when empty (`"dependencies": {}`,
+`"variables": []`), so "none" reads differently from "not recorded". From these, `sous recipe show` and
+`sous subscription add --dry-run` list everything a subscription installs and every question it asks, and
+the resolver walks a recipe whose files are not on the machine from its index entry just as it would walk
+its manifest. A version recorded before a release wrote these fields keeps its entry as it is; its questions
+are known only once its files are fetched, and the dry run names it as such.
+
 **A published version's entry is frozen.** Its dependencies are resolved once, when the version is first
 recorded, and every later release carries the entry forward exactly as published, like its hash; releasing
 other recipes, adding a recipe to a namespace it subscribes to, or raising a sibling it names changes nothing
@@ -234,9 +260,13 @@ against the repository as it stood at that tag, then frozen the same way. An ent
 recorded dependencies carries none, stays that way, and installs by resolving its manifest's ranges.
 
 **Fields this sous does not know are kept, not refused.** A later sous may add fields to the index, at any
-level. This one reads such an index, validates every field it defines as strictly as before, and ignores the
-rest; a release it runs carries a published version's entry forward with those fields intact. A sous older
-than the one that began tolerating unknown fields refuses the whole index once a repository publishes one.
+level, recorded variable definitions included. This one reads such an index, validates every field it
+defines as strictly as before, and ignores the rest; a release it runs carries a published version's entry
+forward with those fields intact.
+
+!> A sous older than 0.2.26, the first to tolerate unknown fields, refuses the whole index of any
+repository released with `declared`, `kind`, `variables`, `depends` or `subscribes` in it, the official
+one included. A project pinned to such a sous fails to read that index until it moves to 0.2.26 or later.
 
 **The `seeded` field.** Sous ships the `core` recipe in its own npm package, so a project can build before
 reaching the network. That copy is folded into the official repository's index in memory and resolved like

package/docs/markdown/repositories-variables.md

@@ -12,7 +12,10 @@ a separate, ceremony-free system; see [Variables](config-variables.md). The two
 
 A definition ships inside the recipe that needs it, in its manifest's `variables:` array, so it versions,
 resolves, pins and trusts like the rest of the recipe; every field it can carry is listed in
-[Variable definitions](repositories-file-formats.md#variable-definitions).
+[Variable definitions](repositories-file-formats.md#variable-definitions). `sous repo release` also copies
+each version's definitions into the repository's index, which is how `sous recipe show` and
+`sous subscription add --dry-run` list a recipe's questions before its files are on your machine. The index
+holds definitions only, never an answer; answers come from the ladder below and nowhere else.
 
 A definition is in play when your lockfile pins the recipe that declares it, whether you subscribed to that
 recipe or a dependency pulled it in. A recipe the store does not hold yet contributes nothing rather than

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.29",
+  "version": "0.2.31",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -60,6 +60,7 @@
     "jsonc-parser": "^3.3.1",
     "liquidjs": "^10.25.0",
     "minimatch": "^10.2.4",
+    "package-manager-detector": "^1.8.0",
     "semver": "^7.8.5",
     "tiktoken": "^1.0.22",
     "tsx": "^4",

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

@@ -65,10 +65,13 @@ contribute: https://github.com/harbor-labs/team-recipes/blob/main/CONTRIBUTING.m
 A recipe's version lives in its manifest, which is the source of truth. A version is **published**
 once a git tag shaped `namespace/recipe@version` exists for it (for example
 `review/checklist@1.2.0`). The index records each published version with its content hash, its
-tag and the exact versions of its dependencies at release time; for the length of one release
-commit it also records the version each manifest declares, whose tag that release cuts next. A
-published version never changes: new files need a new version, and a release refuses to publish
-different content under a version already tagged. A lost index is rebuilt from the tags.
+tag, the exact versions of its dependencies at release time (each with the manifest entry that
+brought it in and whether it is a co-subscription or a build dependency) and the variable
+definitions it publishes, which is how a project lists what a recipe installs and asks before
+fetching it; for the length of one release commit it also records the version each manifest
+declares, whose tag that release cuts next. A published version never changes: new files need a
+new version, and a release refuses to publish different content under a version already tagged. A
+lost index is rebuilt from the tags.
 
 ## Releasing
 

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

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

package/src/base-command.ts

@@ -88,6 +88,20 @@ export abstract class BaseCommand extends Command {
    */
   static requiresConfig = true;
 
+  /**
+   * Whether a config that cannot be located or loaded stops this command. It
+   * is false on every command but the one whose job may be to repair that
+   * config: `sous update` installs a sous that may understand a config this
+   * copy rejects (one written for a newer version, say). When true, a failure
+   * to locate or load the config becomes one warning, naming the config and
+   * quoting the error, and the run carries on with no config adopted:
+   * `hasConfig` is false, the env files are not applied, and `rejectedConfig`
+   * says where the config that failed to load was, when discovery found it.
+   * It only changes what a FAILURE does; finding no config at all is still
+   * decided by `requiresConfig`.
+   */
+  static toleratesConfigErrors = false;
+
   protected settings!: Settings;
 
   /** Where the active config was found. */
@@ -103,6 +117,13 @@ export abstract class BaseCommand extends Command {
   /** The full discovery result, including how the config was located. */
   protected discovered!: DiscoveredConfig;
 
+  /**
+   * The config discovery found but could not load, on a command that
+   * `toleratesConfigErrors`. Undefined when the config loaded, when there was
+   * none, or when the failure came before any config file was identified.
+   */
+  protected rejectedConfig?: { configPath: string; sousDir: string };
+
   /**
    * The real shell environment, snapshotted BEFORE the `.sous/` env files are
    * injected into `process.env`. The variables layer needs it to tell a value
@@ -177,7 +198,7 @@ export abstract class BaseCommand extends Command {
       [sousDirEnv, "SOUS_DIR"],
     ];
     const primary = primaryCandidates.find(([value]) => value !== undefined);
-    const requiresConfig = (this.constructor as typeof BaseCommand).requiresConfig;
+    const { requiresConfig, toleratesConfigErrors } = this.constructor as typeof BaseCommand;
 
     this.configLocator = {
       cwd,
@@ -195,6 +216,12 @@ export abstract class BaseCommand extends Command {
       try {
         discovered = resolveConfigFlag(primarySource, cwd, confDirOverride, sourceLabel);
       } catch (error) {
+        if (toleratesConfigErrors) {
+          return this.warnConfigNotLoaded(
+            error,
+            `the project config at ${this.configLocator.primary?.value} (named by ${sourceLabel})`
+          );
+        }
         // 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;
@@ -202,7 +229,12 @@ export abstract class BaseCommand extends Command {
         return this.exit(1);
       }
     } else {
-      discovered = discoverConfig(cwd, confDirOverride);
+      try {
+        discovered = discoverConfig(cwd, confDirOverride);
+      } catch (error) {
+        if (!toleratesConfigErrors) throw error;
+        return this.warnConfigNotLoaded(error, `the project config it found searching up from ${cwd}`);
+      }
     }
 
     if (!discovered) {
@@ -243,6 +275,7 @@ export abstract class BaseCommand extends Command {
     try {
       refreshed = refreshDiscoveredConfig(discovered);
     } catch (error) {
+      if (this.toleratesConfigErrors) return this.rejectConfig(discovered, error);
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
@@ -262,11 +295,51 @@ export abstract class BaseCommand extends Command {
     try {
       this.settings = await loadSettings(refreshed);
     } catch (error) {
+      if (this.toleratesConfigErrors) return this.rejectConfig(refreshed, error);
       displayErrorBlock(error instanceof Error ? error.message : String(error), this.errorSink);
       return this.exit(1);
     }
   }
 
+  /** The `toleratesConfigErrors` setting of the running command's class. */
+  private get toleratesConfigErrors(): boolean {
+    return (this.constructor as typeof BaseCommand).toleratesConfigErrors;
+  }
+
+  /**
+   * Undoes a config adoption that failed on a command that tolerates it: the
+   * env files it injected are taken back out of `process.env`, nothing is left
+   * adopted, and one warning says what happened.
+   */
+  private rejectConfig(discovered: DiscoveredConfig, error: unknown): void {
+    for (const name of Object.keys(process.env)) {
+      if (!(name in this.shellEnv)) delete process.env[name];
+    }
+    this.shellEnv = {};
+    this.discovered = undefined as unknown as DiscoveredConfig;
+    this.configContext = undefined as unknown as ConfigContext;
+    this.rejectedConfig = { configPath: discovered.configPath, sousDir: discovered.sousDir };
+    this.warnConfigNotLoaded(error, `the project config at ${discovered.configPath}`);
+  }
+
+  /**
+   * The one warning a command that tolerates config errors prints in place of
+   * failing.
+   *
+   * @param error - What locating or loading the config threw.
+   * @param config - Which config: its file, or where it was looked for.
+   */
+  private warnConfigNotLoaded(error: unknown, config: string): void {
+    const message = error instanceof Error ? error.message : String(error);
+    warning(
+      `Sous could not load ${config}, so this command carries on without it.\n` +
+        "\n" +
+        "The error was:\n" +
+        message,
+      this.errorSink
+    );
+  }
+
   /**
    * Renders any failure as a plain, readable message instead of an oclif stack
    * trace: a config mistake, a mistyped command line, or a question sous could

package/src/commands/lock/rebuild.ts

@@ -150,7 +150,8 @@ export default class LockRebuild extends BaseCommand {
       repos,
       // A recipe's own manifest is what names its dependencies, and it is read
       // from the files this machine already holds. Nothing is fetched here, so a
-      // recipe that is not in the store yet comes back under `missingManifests`.
+      // recipe that is not in the store yet is walked from what its index entry
+      // records, and comes back under `missingManifests` when that is nothing.
       loadManifest: (recipe) => {
         const directory = recipeFilesDirectory({
           service,
@@ -208,9 +209,9 @@ export default class LockRebuild extends BaseCommand {
     if (result.missingManifests.length > 0) {
       blankLine();
       paragraph(
-        `The files of these recipes are not on this machine, so their own ` +
-          `dependencies could not be read and are not in the rebuilt lockfile: ` +
-          `${result.missingManifests.join(", ")}.`
+        `The files of these recipes are not on this machine, and their repository's ` +
+          `index does not record what they depend on, so their own dependencies are ` +
+          `not in the rebuilt lockfile: ${result.missingManifests.join(", ")}.`
       );
     }