@sous-io/sous 0.2.1 → 0.2.3

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

@@ -1,1084 +1,320 @@
 # Repository File Formats
 
-Repositories publish versioned **recipes**, grouped into **namespaces**, and projects subscribe
-to them. Six files carry the whole system on disk. Three of them you write by hand; three sous
-writes for you.
+The reference for every file and config key in the Repositories system; the pages explaining how to use them
+are listed at the end. You write the repository manifest and one recipe manifest per recipe; sous writes the
+rest: the published index, a project's lockfile, the marker on a store entry, and the links map.
 
-| File | Where | Written by | Purpose |
-|------|-------|-----------|---------|
-| `sous.repo.yaml` | repository root | you | Declares the repository: its namespaces and where its recipes live |
-| `sous.recipe.yaml` | each recipe folder | you | Declares one recipe: version, dependencies, contents, variables |
-| `sous.index.json` | repository root | `sous repo release` | Every namespace, recipe and published version, with content hashes |
-| `sous.lock.json` | a project's `.sous/` | sous | What the project actually resolved to |
-| `.sous.entry.json` | each store entry | sous | Makes a cached recipe version self-describing |
-| `sous.links.json` | `.sous/` or `$SOUS_HOME` | `sous repo link` | Redirects a repository at a local working copy |
+Every one carries `formatVersion: 1`; a future incompatible change raises that number, so an older sous
+refuses a file it would otherwise misread.
 
-Every one of them carries `formatVersion: 1`. A future incompatible change bumps that number, so
-an older sous refuses a file it would otherwise misread.
-
-?> Hand-written manifests are YAML or JSON, never JavaScript. Repository trust rests on being
-able to read a repository's whole surface without running any of its code, and a manifest that
-could execute would break that guarantee.
+?> Both hand-written manifests are YAML or JSON, never JavaScript: `.yaml`, `.yml`, `.json` or `.jsonc`
+(both JSON forms allow comments and trailing commas). Two in one directory is an error, not a first-match
+win. Unknown keys are rejected except extension keys starting with `x-`, carried through untouched; [the one
+sous reads](repositories-authoring.md#declare-the-variables-a-recipe-needs) is `x-intentional`. Every path
+in a manifest is checked: absolute paths, backslashes, `.` or `..` segments, empty segments and trailing
+slashes are refused.
 
 ## Refs: how anything is named
 
-A **ref** names a namespace or a recipe. The same grammar works on the command line and in a
-project's subscriptions. A recipe manifest names its dependencies by LOCATION instead, which is
-a small variation on the same grammar; see [dependencies](#dependencies-named-by-location).
-
-```
+```text
 ref := [ repo ":" ] namespace [ "/" recipe [ "@" range ] ]
 ```
 
-| Ref | Means |
-|-----|-------|
-| `workflow` | The whole `workflow` namespace, including recipes published later |
-| `workflow/task-files` | One recipe, any published version |
-| `workflow/task-files@^1.2.0` | One recipe, constrained to a semantic version range |
-| `sous-recipes:workflow/task-files@^1.2.0` | The same recipe, in a named repository |
+So `workflow` is a whole namespace, `workflow/task-files@^1.2.0` one recipe constrained to a range (npm's
+rules; namespaces are not versioned), and `sous-recipes:workflow/task-files` that recipe in a named
+repository. Only a consuming project writes the `repo:` qualifier; it is that project's own label.
 
-The rules behind the grammar:
-
-- **No prefix.** A ref is written bare. `@` introduces a version range and nothing else; `~` is
-  the template include sigil and never appears in a ref.
-- **The repo qualifier is optional, and is yours.** Refs resolve across the cached indexes of
-  every added repository. You only need `repo:` when the same ref genuinely resolves in more than
-  one, and in that case sous reports the conflict and asks for the qualified form rather than
-  picking a winner. The short name is your project's own label for a repository, so it means
-  nothing in a published manifest and is refused there.
-- **A version range applies to a recipe.** Namespaces are not versioned, so `workflow@^1.0.0` is
-  an error.
-- **Ranges follow npm's rules.** `^1.2.0`, `~2.1`, `>=1.0.0 <2.0.0`, `1.x` and `*` all behave
-  exactly as they do in npm, because sous resolves them with npm's own `semver` package.
-  Prerelease versions sit out of range matching unless a subscription opts in.
-
-Namespace names, recipe names and repository short names are lowercase kebab-case: a letter,
-then letters, digits or hyphens.
+| Thing | Shape |
+|-------|-------|
+| Repository short name, namespace, recipe name | lowercase kebab-case |
+| Recipe key | always both segments, `namespace/recipe` |
+| Repository identity | the host, then the path it lives at, lowercased |
+| Variable name, environment variable name | camelCase, and upper snake case |
+| Content hash | `sha256-` and 64 lowercase hex characters |
+| Timestamp | ISO 8601 |
 
 ## `sous.repo.yaml`: the repository manifest
 
-The entry point sous reads to learn what a repository publishes. It lives at the repository root
-and may be written as `sous.repo.yaml`, `sous.repo.yml` or `sous.repo.json`. Exactly one of
-those, never two.
-
 ```yaml
-formatVersion: 1
-
-# A suggested short name. A project records the name it actually uses when the
-# repository is added, so two repositories suggesting the same name never collide.
-name: sous-recipes
-
-description: The official sous recipe repository.
-
-# Surfaced when a provider cannot support `sous repo submit`, so a contributor is
-# never left without a route. A URL or plain prose.
-contribute: https://github.com/sous-io/sous-recipes/blob/main/CONTRIBUTING.md
-
+formatVersion: 1                    # every format on this page carries it
+name: qa-recipes                    # suggested short name; a project records its own
 namespaces:
-  core:
-    description: Skills that teach agents about sous itself.
   workflow:
-    description: Task tracking and branch workflow.
-
-# Each path holds a sous.recipe.yaml. Paths are relative to the repository root.
-recipes:
-  - recipes/core/sous-skills
-  - recipes/workflow/task-files
+    description: Recipes about how work moves through a project.
+  quality:
+    description: Recipes that exercise the edges.
+recipes:                            # every recipe folder, relative to the repository root
+  - recipes/workflow/qa-variables
+  - recipes/quality/qa-remote-dep
 ```
 
-| Field | Required | Type | Notes |
-|-------|----------|------|-------|
-| `formatVersion` | yes | `1` | The on-disk format version |
-| `name` | yes | kebab-case string | Suggested short name for the repository |
-| `description` | no | string | Shown by `sous repo list` and `sous repo search` |
-| `contribute` | no | string | URL or prose describing how to contribute |
-| `namespaces` | yes | map of name to `{ description? }` | Every namespace the repository publishes |
-| `recipes` | yes | list of relative paths | Every recipe folder, each holding a recipe manifest |
-
-Recipe paths stay inside the repository: an absolute path, a backslash, a `..` segment or a
-trailing slash is rejected.
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | yes | A suggestion only; `sous repo add --name` decides what a project calls it |
+| `description`, `contribute` | no | A summary for anyone reading the repository, and where to send a contribution when a provider cannot support `sous repo submit` |
+| `namespaces` | yes | Keyed by namespace name; each entry takes an optional `description` |
+| `recipes` | yes | Relative paths, each holding a recipe manifest; a path listed twice is an error |
 
 ## `sous.recipe.yaml`: the recipe manifest
 
-One recipe, complete. It lives in the recipe's own folder, as `sous.recipe.yaml`,
-`sous.recipe.yml` or `sous.recipe.json`.
-
 ```yaml
 formatVersion: 1
-namespace: workflow
-name: task-files
-version: 1.2.0
-description: Per-branch task files, with skills for starting and resuming work.
-
-# Build dependencies. Fetched, pinned and trust-gated, and addressable from this
-# recipe's own files, but their files do NOT enter a subscriber's output.
-# A bare ref names a recipe in this same repository.
-depends:
-  - workflow/sat
-
-# Co-subscriptions. Subscribing to this recipe subscribes the project to these too,
-# with full semantics: their questions run and their files DO enter the output.
-# A curated bundle is simply a recipe made mostly of these. A locator URL names a
-# recipe in another repository.
-subscribes:
-  - github://sous-io/sous-recipes/communication/control-flow@^2.0.0
-
-# The files this recipe contributes. Patterns are relative to the recipe folder.
-contents:
+namespace: quality
+name: qa-remote-dep
+version: 0.1.0
+depends:                            # 'subscribes' takes the same two spellings
+  - workflow/qa-helper
+  - github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0
+contents:                           # what a subscriber actually receives
   - kind: skills
-    include:
-      - skills/**/*.md
-    exclude:
-      - skills/**/draft-*.md
-  - kind: memories
-    include:
-      - memories/*.md
-  - kind: config
-    include:
-      - config/510-task-files.json
-
-# Published specifications, not values. A question is asked only when a subscribed
-# recipe needs the variable and no valid answer is already in scope.
-variables:
-  - name: taskFileRoot
-    env: SOUS_VAR_TASK_FILE_ROOT
-    type: path
-    prompt: Where should task files live?
-    description: >-
-      One markdown file per git branch is written here. Most projects keep these
-      as local working notes and gitignore the directory.
-    example: .sous/tasks
-    default: .sous/tasks
-    required: true
-    scope: shared
-
-  - name: ticketSystem
-    type: enum
-    prompt: Which ticket system do you use?
-    description: >-
-      Decides which ticket identifiers the skills expect and which links they
-      write into a task file.
-    example: github
-    default: github
-    validate:
-      enum: [github, jira, linear]
+    include: [skills/**/*.md]       # 'exclude' is the optional counterpart
 ```
 
-### Top-level fields
+| Field | Required | Notes |
+|-------|----------|-------|
+| `namespace`, `name` | yes | The namespace must be declared by the repository manifest; the name is unique within it |
+| `version` | yes | An exact semantic version; the manifest is the source of truth and the git tag follows it |
+| `description` | no | Copied into the index at release time; shown by `sous recipe list` and `sous repo search` |
+| `depends`, `subscribes` | no | Build dependencies and co-subscriptions; within either list, no entry may repeat |
+| `contents`, `variables` | no | Contents default to an empty list, which is what a curated bundle publishes; a duplicated variable name, or two definitions claiming one `env`, is an error |
 
-| Field | Required | Type | Notes |
-|-------|----------|------|-------|
-| `formatVersion` | yes | `1` | The on-disk format version |
-| `namespace` | yes | kebab-case string | Must be declared by the repository manifest |
-| `name` | yes | kebab-case string | Unique within its namespace |
-| `version` | yes | exact semantic version | Never a range; `1.2.0`, or `2.0.0-beta.1` for a prerelease |
-| `description` | no | string | Shown by `sous repo search` and `sous repo list` |
-| `depends` | no | list of dependencies | Build dependencies, named by location |
-| `subscribes` | no | list of dependencies | Co-subscriptions, named by location |
-| `contents` | no | list of content groups | Defaults to an empty list, which is what a curated bundle wants |
-| `variables` | no | list of variable definitions | Published specifications |
-
-Recipe metadata is the source of truth for versions. A git tag shaped
-`namespace/recipe@1.2.3` is a convenience ref that `sous repo release` keeps consistent with the
-`version` field; a missing or wrong tag is reported rather than silently hiding a version.
+`contents[].kind` is `skills`, `memories`, `prompts` or `config`. The first three are written to the
+destinations named by [`recipeOutputs`](#recipeoutputs-where-the-files-land); `config` entries become config
+layers instead. `include` needs at least one glob, and both lists are recipe-relative.
 
 ### Dependencies named by location
 
-`depends` and `subscribes` hold plain strings, and a manifest names its targets by WHERE THEY
-LIVE. There are two spellings.
-
-**A sibling**, in this same repository, is a bare ref:
-
-```yaml
-depends:
-  - workflow/sat            # the sibling as released alongside me
-  - workflow/sat@^1.1       # supported, and uncommon
-```
+`depends` and `subscribes` share one grammar in two spellings: `workflow/qa-helper` is a sibling in this
+same repository, and `github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0` is a recipe in
+another one. A locator URL's scheme is the provider's identifier (`github` and `gitlab` ship today), and its
+path is read from the RIGHT: the last two segments are the namespace and the recipe, and everything before
+them names the repository, whose first segment is the host when it carries a dot and otherwise the
+provider's public host, so `gitlab://gitlab.example.com/group/subgroup/project/workflow/task-files`
+resolves. A trailing `.git` is dropped and at most one `@` range may follow. A manifest may write no `repo:`
+qualifier, no `local://` locator (a local repository is a convenience, not a published location) and no
+filesystem path such as `../qa-helper`.
 
-With no range, a sibling means "the version released alongside me": `sous repo release` cuts both
-tags in one run and records the exact version in the index, so the pairing is fixed forever.
+### Variable definitions
 
-**Another repository** is a locator URL whose scheme is the provider's identifier:
+A definition is a specification, not a value; [Recipe variables](repositories-variables.md) covers how an
+answer is found and stored, and a worked pair of definitions, including a secret, is in [Declare the
+variables a recipe needs](repositories-authoring.md#declare-the-variables-a-recipe-needs).
 
 ```yaml
-subscribes:
-  - github://sous-io/sous-recipes/workflow/sat@^1.1
-  - gitlab://gitlab.example.com/group/subgroup/project/workflow/sat
+variables:
+  - name: qaTaskRoot
+    type: path
+    prompt: Where should the review notes be stored?
+    description: One review note per branch is read from and written to this directory.
+    example: ~/qa-notes
+    default: .sous/qa-notes
 ```
 
-The parsing rule is worth stating exactly, because it never guesses:
-
-- The **last two path segments are always the namespace and the recipe**. That is the recipe's
-  published identity, never a path on disk: a recipe stored at `recipes/shared/sat/` and
-  published as `workflow/sat` is written `github://owner/repo/workflow/sat`. The repository's own
-  index maps that identity to the directory.
-- **Everything before them is the repository.** A first segment carrying a dot is the host
-  (`gitlab.example.com`); otherwise the provider's own public host is used (`github.com`,
-  `gitlab.com`). Everything after the host is the repository's path, so GitLab subgroups work
-  without any extra syntax.
-- The **range after `@` is optional**, and follows npm's rules like every other range.
-
-Two things a manifest may not write:
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name`, `type` | yes | camelCase, as templates refer to it; one of `string`, `number`, `boolean`, `enum`, `path` or `url` |
+| `prompt`, `description` | yes | The one-line question, and the paragraph explaining the variable; both are shown when sous asks and by `sous vars show <name>` |
+| `example` | yes | A realistic sample answer; documentation only, never stored and never a fallback. Use `default` for the value offered when nothing else is in scope |
+| `env` | no | The environment variable an answer binds to; omitted, it is `SOUS_VAR_` plus the upper snake case form of the variable's own name, so `qaScratchDir` binds to `SOUS_VAR_QA_SCRATCH_DIR` |
+| `required`, `secret` | no | Default to `true` and `false`; a secret is always written to the gitignored `.sous/.env.local` |
+| `scope` | no | `shared` (the committed `.sous/.env`) or `local` (the gitignored `.sous/.env.local`); defaults to `shared` |
+| `validate` | no | `pattern`, `minLength`, `maxLength`, `min`, `max`, `enum` |
 
-- **`local://` is refused.** A local repository is a consumer's convenience for working on
-  recipes, not a published location; publish the recipe and depend on it where it lives.
-- **`repo:` short names are refused.** A short name is the label one project chose when it added
-  a repository, and no other project has to agree with it.
-
-A consumer matches a locator against the repositories it has added by their canonical identity
-(`github.com/sous-io/sous-recipes`), so a project that added the same repository under a
-different short name resolves against the copy it already has. One it has not added goes through
-the ordinary trust round, which can show the URL the dependency named.
-
-### Content groups
-
-| Field | Required | Type | Notes |
-|-------|----------|------|-------|
-| `kind` | yes | `skills`, `memories`, `prompts` or `config` | Decides where the files land in a subscribing project |
-| `include` | yes | list of glob patterns | At least one; relative to the recipe folder |
-| `exclude` | no | list of glob patterns | Removed from the include set |
-
-`config` entries name config layer files that are merged into the subscriber's config. Like
-recipe paths, include and exclude patterns may not escape the recipe folder.
-
-### Variable definitions
+At publish time: a `type: enum` variable must list its options under `validate.enum`; `minLength` cannot
+exceed `maxLength`, nor `min` exceed `max`; `default` and `example` must match the type and, for an enum, be
+one of its options; `secret: true` with `scope: shared` is refused; the committed env file would leak it.
 
-| Field | Required | Type | Notes |
-|-------|----------|------|-------|
-| `name` | yes | camelCase string | How templates refer to the variable |
-| `env` | no | upper snake case string | The environment variable an answer binds to. `sous repo release` derives a default when it is omitted; the runtime never derives one |
-| `type` | yes | `string`, `number`, `boolean`, `enum`, `path` or `url` | How the answer is validated and prompted for |
-| `prompt` | yes | string | The one-line question text |
-| `description` | yes | non-empty string | The paragraph explaining what the variable is for. Shown above the question when sous asks, and by `sous vars show <name>` |
-| `example` | yes | string, number or boolean | A realistic sample answer, shown with the question. Checked against the declared type and the enum options exactly as `default` is, but never stored and never offered as the answer |
-| `default` | no | string, number or boolean | Must match the declared type, and for an enum must be one of the options |
-| `required` | no | boolean, default `true` | Whether a build needs an answer |
-| `secret` | no | boolean, default `false` | A secret is always stored in the gitignored `.sous/.env.local` |
-| `scope` | no | `shared` or `local`, default `shared` | Which env file the answer is written to |
-| `validate` | no | object | Constraints, below |
+## `sous.index.json`
 
-A publisher has to explain every variable: `description` and `example` are both required, and a
-manifest missing either is refused. The two are not interchangeable. An `example` is documentation
-only, so it shows what a real answer looks like without sous ever storing it; a `default` is a real
-value, offered as the answer when nothing else is in scope. A variable whose sample answer is
-genuinely the right starting value carries the same text in both.
-
-`scope: shared` writes to `.sous/.env`, which is committed and shared with the team.
-`scope: local` writes to `.sous/.env.local`, which is gitignored and machine-specific. A secret
-declared as shared is rejected, because that combination would commit the secret.
-
-Constraints under `validate`:
-
-| Field | Type | Applies to |
-|-------|------|-----------|
-| `pattern` | string holding a regular expression | String-like answers |
-| `minLength`, `maxLength` | whole numbers | String-like answers |
-| `min`, `max` | numbers | Numeric answers |
-| `enum` | list of strings | Required when `type` is `enum` |
-
-A `pattern` runs under a time budget, on a worker rather than on the thread waiting for the
-answer; a pattern that exceeds the budget fails validation, and the failure names the pattern
-rather than blaming the answer.
-
-!> A schema may only LOOSEN within a major version. Tightening a constraint is a major bump,
-and an upgrade re-validates stored answers, re-prompting only where an old answer no longer
-fits.
-
-### Unknown keys
-
-Both hand-written manifests reject an unknown key and report it as a likely typo, naming the
-file and the field's path. The one exception is the reserved `x-` namespace: a key such as
-`x-team` is accepted and ignored, so a repository can carry metadata sous knows nothing about.
-
-### JSON manifests
-
-A `.json` manifest is read with a permissive parser: line comments, block comments and trailing
-commas are all allowed, so a manifest can explain itself.
+Machine-written by `sous repo release` and committed beside the recipes it describes. Adding a repository
+fetches only this file; nothing more is downloaded until a project subscribes.
 
 ```json
 {
-  // the only format version sous understands
-  "formatVersion": 1,
-  "namespace": "workflow",
-  "name": "task-files",
-  "version": "1.2.0",
-  "contents": [
-    { "kind": "skills", "include": ["skills/**/*.md"] },
-  ]
+  "formatVersion": 1, "name": "qa-recipes", "generator": "0.2.0",
+  "generatedAt": "2026-09-12T07:06:33.236Z",
+  "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" } },
+      "hash": "sha256-46e75442aeb368116c8830ad382707759f1ecd03974c4b5d42a5fabffce0324f",
+      "prerelease": false, "releasedAt": "2026-09-12T07:06:33.236Z",
+      "tag": "quality/qa-remote-dep@0.1.0"
+    } } } }
 }
 ```
 
-## `sous.index.json`: the repository index
+| Field | Where | Notes |
+|-------|-------|-------|
+| `generatedAt`, `generator`, `name`, `namespaces` | top level | When the index was generated and by which sous version, then the name and namespaces copied from the repository manifest. `$comment` is free text, since JSON has no comments, and is ignored on a published index |
+| `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 |
 
-Machine-written by `sous repo release` and committed alongside the recipes it describes. The
-index is the portable contract across providers: whatever a provider's API looks like, it can
-hand back this one file, and it is all sous needs to resolve a ref, enumerate published versions
-and check whether a cached copy is current.
+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.
 
-Adding a repository fetches only this file. Nothing else is downloaded until a project
-subscribes to something inside it.
+**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
+any other, marked `seeded: true`; if the repository already publishes it, the published copy wins. Sous
+never writes `seeded` onto a fetched index, and when it writes the placeholder into the index cache it
+stamps a fixed `$comment`, so a later run can tell its own placeholder from a real index and replace it.
 
-```json
-{
-  "formatVersion": 1,
-  "name": "sous-recipes",
-  "generatedAt": "2026-09-09T14:03:11.482Z",
-  "generator": "0.2.0",
-  "namespaces": {
-    "core": { "description": "Skills that teach agents about sous itself." },
-    "workflow": { "description": "Task tracking and branch workflow." }
-  },
-  "recipes": {
-    "workflow/task-files": {
-      "path": "recipes/workflow/task-files",
-      "description": "Per-branch task files.",
-      "versions": {
-        "1.0.0": {
-          "hash": "sha256-3b1f...c9",
-          "tag": "workflow/task-files@1.0.0",
-          "prerelease": false,
-          "releasedAt": "2026-08-01T09:00:00.000Z",
-          "dependencies": {
-            "workflow/sat": { "version": "1.4.0" },
-            "communication/control-flow": {
-              "repo": "github.com/sous-io/sous-recipes",
-              "range": "^2.0.0"
-            }
-          }
-        },
-        "1.1.0-beta.1": {
-          "hash": "sha256-77ad...20",
-          "tag": "workflow/task-files@1.1.0-beta.1",
-          "prerelease": true
-        }
-      }
-    }
-  }
-}
-```
-
-| Field | Required | Type | Notes |
-|-------|----------|------|-------|
-| `formatVersion` | yes | `1` | The on-disk format version |
-| `name` | yes | kebab-case string | The repository's suggested short name |
-| `generatedAt` | yes | ISO 8601 timestamp | When the index was generated |
-| `generator` | yes | exact semantic version | The version of sous that generated it |
-| `namespaces` | yes | map of name to `{ description? }` | Copied from the repository manifest |
-| `recipes` | yes | map of `namespace/recipe` to a recipe entry | Every recipe published |
-| `$comment` | no | string | A note about where this copy came from. JSON has no comment syntax, and an index is machine-written, so this is the one place a writer can say something to whoever opens the file. Sous ignores it, with one exception: the seed index below |
-
-A recipe entry holds `path`, an optional `description`, and `versions`: a map from an exact
-version to `{ hash, tag, prerelease, releasedAt?, dependencies?, seeded? }`. Every recipe needs
-at least one version, and its namespace must be one the index declares. `seeded` is never
-written by `sous repo release`; it marks the packaged core version sous folds in itself, and is
-described under the seed index below.
-
-### Resolved dependencies
-
-`dependencies` records what one exact version was released against, keyed `namespace/recipe`. It
-is why a published version means one thing forever: a consumer installing `1.0.0` installs the
-versions `1.0.0` was published with, rather than re-resolving its ranges months later.
-
-| Field | When | Notes |
-|-------|------|-------|
-| `version` | a sibling | The exact version, settled when both tags were cut |
-| `repo` | another repository | That repository's canonical identity, `<host>/<owner path>/<name>` |
-| `range` | another repository | The range the manifest declared; its exact version lives in that repository's own index |
-
-The field is additive: an index written before it existed still parses, and a consumer that
-finds no entry falls back to the ranges the recipe's manifest declares. `formatVersion` stays
-`1`.
-
-A version's `tag` must be exactly `<namespace>/<recipe>@<version>` for the entry it sits under,
-and an index that says otherwise is refused when it is read. The tag is what the provider
-fetches, so an index publishing `1.0.0` with `tag: "main"` would point a pinned version at a
-branch: the content behind it changes on every push and the pinned hash then simply starts
-failing, with nothing on the consumer's side able to say why.
-
-Content hashes are written as `sha256-` followed by 64 lowercase hexadecimal characters. The
-hash of a version is checked after every fetch, and against the lockfile before a cached copy is
-used.
+## `.sous/sous.lock.json`
 
-### The seed index
-
-One index is not published by any repository: sous writes a stand-in index for its own
-`sous-recipes` entry, into the index cache, when nothing real has ever been fetched from it. It
-lists exactly one recipe, `core/sous-skills`, at the version of the running sous, with the hash
-of the copy that was just seeded out of the installed package. That is what lets a project
-resolve the core namespace on a machine that has never had a network connection.
-
-The stand-in says so in its `$comment`, which is how a later run recognizes its own placeholder
-and is willing to replace it; an index a repository actually published is never overwritten. No
-freshness sidecar is written beside it, so the very first command that does have a network
-fetches the real index rather than waiting out a window the stand-in never earned. When there is
-still no network, sous reports that it could not check and uses the stand-in, which is the same
-last-good behavior every repository gets.
-
-### The packaged core version
-
-The stand-in covers a machine that has never fetched anything. A machine that has been using
-sous for a while holds the repository's real index instead, and that index publishes whatever
-core versions the release pipeline has cut so far. Upgrade sous and the version the built-in
-`core` subscription asks for is, for a while, not among them.
-
-So sous folds the packaged version into that index IN MEMORY whenever the index does not carry
-it: one more entry under `core/sous-skills`, at the running sous version, with the hash of the
-copy just seeded out of the package, `prerelease` set from the version itself, and `seeded` set
-to `true`. Nothing is written to disk; the cached file stays exactly what the repository served,
-so the next real fetch is compared against the truth. The moment the repository does publish
-that version, its own entry is what gets used, and if the two disagree about the content hash
-sous says so once and prefers the published one.
-
-## `sous.lock.json`: the project lockfile
-
-Machine-written into the project's `.sous/` directory, and committed. The lockfile records the
-exact version and content hash of everything the project currently uses, so a fresh clone
-restores deterministically with no prompts and no version drift. Together with repository trust
-it is the supply-chain defense: nothing new enters a project except through an explicit, visible
-change to these files.
+Machine-written, committed, and the reason a fresh clone restores with no prompts and no drift.
 
 ```json
 {
   "formatVersion": 1,
-  "repos": {
-    "sous-recipes": {
-      "url": "https://github.com/sous-io/sous-recipes",
-      "identity": "github.com/sous-io/sous-recipes",
-      "indexHash": "sha256-91cc...4e"
-    }
-  },
   "recipes": {
-    "core/sous-skills": {
-      "repo": "sous-recipes",
-      "version": "0.2.0",
-      "hash": "sha256-4d20...af",
-      "requestedBy": ["workflow/task-files"],
-      "kind": "depends"
-    },
-    "workflow/task-files": {
-      "repo": "sous-recipes",
-      "version": "1.2.0",
-      "hash": "sha256-3b1f...c9",
-      "requestedBy": ["project"],
-      "kind": "subscribes"
-    }
-  }
-}
-```
-
-| Field | Required | Type | Notes |
-|-------|----------|------|-------|
-| `formatVersion` | yes | `1` | The on-disk format version |
-| `repos` | yes | map of short name to `{ url, identity, indexHash? }` | Every repository the locked recipes came from |
-| `recipes` | yes | map of `namespace/recipe` to a locked entry | Everything currently in use |
-
-A locked entry holds `repo` (which must appear under `repos`), the exact `version` resolved, its
-`hash`, a `requestedBy` list and a `kind` of `subscribes` or `depends`.
-
-A repository appears twice over, and the two are for different readers. The KEY is your
-project's short name, which is what every message and every recipe entry names. The `identity`
-is the canonical location it was derived from, and it is what the machine-wide store and the
-index cache file that repository under, so two projects that call the same repository different
-things still share one cached copy.
-
-`requestedBy` is what makes removal safe. Every entry lists who holds it: the literal string
-`project` for something the project subscribed to directly, or a recipe key for something pulled
-in as a dependency. Unsubscribing removes one holder, and the entry itself goes only when the
-last holder does.
-
-Every key is written sorted, so a regenerated lockfile changes only when its content genuinely
-does.
-
-## `.sous.entry.json`: the store entry marker
-
-The machine-wide store lives under the user-level sous directory, one folder per recipe version:
-`$SOUS_HOME/cache/<repository identity>/<namespace>/<recipe>/<version>/`. A marker beside each
-one makes the entry self-describing, so the store can be verified and swept without consulting
-any project.
-
-```json
-{
-  "formatVersion": 1,
-  "repo": "github.com/sous-io/sous-recipes",
-  "namespace": "workflow",
-  "name": "task-files",
-  "version": "1.2.0",
-  "hash": "sha256-3b1f...c9",
-  "fetchedAt": "2026-09-01T10:00:00.000Z",
-  "lastAccessAt": "2026-09-09T14:03:11.482Z",
-  "sizeBytes": 20480
+    "quality/qa-remote-dep": { "kind": "subscribes", "repo": "qa-recipes", "version": "0.1.0",
+      "requestedBy": ["project"], "hash": "sha256-46e75442aeb368116c8830ad38...ffce0324f" },
+    "workflow/qa-helper": { "kind": "depends", "repo": "qa-recipes", "version": "0.1.0",
+      "requestedBy": ["quality/qa-remote-dep"], "hash": "sha256-78660ab9889e707a38be...b2c69698d" }
+  },
+  "repos": { "qa-recipes": { "identity": "localhost/home/me/projects/qa", "url": "/home/me/Projects/qa" } }
 }
 ```
 
-Every field is required. `repo` is the repository's canonical identity, because the store is
-shared by every project on the machine and a short name is one project's private label. `hash`
-is checked against the lockfile before the entry is used; `sizeBytes` and `lastAccessAt` drive
-the size-capped, least-recently-used collection that `sous repo gc` performs.
+| Field | Notes |
+|-------|-------|
+| `repos.<name>.url`, `.identity`, `.indexHash` | Where the repository lives, as recorded when it was added; the canonical identity the store and index cache file it under; and the hash of the index this lock was resolved against, when known |
+| `recipes.<key>.repo`, `.version`, `.hash` | The project's short name for the repository, which must appear under `repos`; the version resolved; and the hash verified against the store after every fetch |
+| `recipes.<key>.requestedBy`, `.kind` | Who holds the entry, the literal `project` or the key of a recipe that requires it, and whether that holder is a `subscribes` or a `depends` |
 
-The store is disposable by design: everything in it is re-fetchable from the pins in a project's
-lockfile. Builds read inputs from the store and render or copy outputs into the project; sous
-does not symlink store content into a project, and store content is never edited in place.
+A repository appears under two names on purpose: the key is the project's own short name, which every
+message uses, while `identity` is what the store is keyed by, so two projects with different labels share
+one cached copy. `identity` is optional on read only, for older lockfiles, and is derived from the URL on
+the next write. `requestedBy` makes removal safe; an entry goes when its last holder does.
 
 ## The store on disk
 
-The store is a plain directory tree under the user-level sous directory, which is `~/.sous`
-unless `SOUS_HOME` says otherwise. Unlike `SOUS_CONFIG` and `SOUS_DIR`, `SOUS_HOME` does not
-decide which project is active, so it may be set in an env file (`.sous/.env.local` or
-`.sous/.env`) as well as in the shell. The same directory holds globally linked checkouts
-(`repos/`) and the machine-wide links map.
+The store is machine-wide, immutable per version, and disposable (everything is re-fetchable from a
+lockfile's pins); every entry carries a `.sous.entry.json` marker. It sits under `$SOUS_HOME`, default
+`~/.sous`.
 
 ```text
 $SOUS_HOME/
-  cache/                                   the store root
-    _indexes/<identity>.json               one cached index per repository
-    <identity>/<namespace>/<recipe>/<version>/
-      .sous.entry.json                     the marker for this entry
-      ...                                  the recipe's files, exactly as fetched
-  repos/<owner>/<repo>/                    checkouts linked with --global
-  sous.links.json                          the machine-wide links map
+  cache/<repository identity>/<namespace>/<name>/<version>/   .sous.entry.json, then the files
+  cache/_indexes/<repository identity>.json                   the cached index
+  cache/_indexes/<repository identity>.meta.json              etag, fetchedAt, lastCheckedAt, ref
+  repos/            checkouts cloned by 'sous repo link --global'
+  sous.links.json   the machine-wide links map
 ```
 
-`<identity>` is the repository's canonical location, `<host>/<owner path>/<name>`, so it is
-several directories deep on its own: `github.com/sous-io/sous-recipes/`, with the namespace, the
-recipe and the version following it. Keying by location rather than by
-a short name is what lets two projects that call a repository different things share one cached
-copy, and stops two projects that use the same short name for different repositories from
-colliding. Nothing migrates a store keyed another way: entries sous cannot find are simply
-fetched again, which costs a download and nothing else.
-
-An entry is written atomically: sous copies the fetched files into a temporary directory
-beside the entry's final home, hashes them, checks the hash against the pin it was given,
-writes the marker, and only then renames the directory into place. A published version is
-immutable, so re-storing one is allowed only when the content hashes the same; different
-content under a version already in the store is an error rather than a silent overwrite.
-
-The content hash is SHA-256 over a canonical serialization of the folder: files in bytewise
-order of their relative paths, each contributing its path, its byte length and its bytes.
-File modes, owners and timestamps are excluded, so the same recipe hashes the same after a
-copy, a clone or an archive round-trip. `.git` and the entry's own `.sous.entry.json` are
-skipped, which is what lets sous touch the marker without invalidating the entry. Every read
-re-verifies the hash; an entry that no longer matches is removed and re-fetched, and the
-build says so.
-
-Symbolic links are skipped entirely, by the hash and by the copy into the store alike, and so
-is anything under a linked directory. A link points at bytes the repository does not own, so
-following one would make the same published version hash differently on the publisher's
-machine and the consumer's, and every install would then fail against its own pin.
-`sous repo release` refuses to publish a recipe folder containing a link, naming it, so this
-is caught where it can be fixed rather than at install time. A recipe that needs a file ships
-the file.
-
-Collection is size-capped and least-recently-used. `store.maxBytes` sets the cap (one
-gigabyte by default) and `lastAccessAt` in each marker sets the order; entries a lockfile
-still pins are never evicted, even when honoring the cap would require it. Everything in
-the store is re-fetchable from those pins, so deleting the whole directory costs a download
-and nothing else.
-
-## `sous.links.json`: the links map
-
-A link redirects a repository's resolution away from the store and at a real working copy, which
-is how a maintainer edits recipes: edits happen in a checkout, never in the store.
+The marker makes an entry self-describing, so the store is sweepable without consulting a project:
 
 ```json
-{
-  "formatVersion": 1,
-  "links": {
-    "sous-recipes": {
-      "path": "/home/me/Projects/sous-recipes",
-      "linkedAt": "2026-09-09T14:03:11.482Z",
-      "origin": "clone"
-    }
-  }
-}
+{ "formatVersion": 1, "repo": "github.com/sous-io/sous-recipes", "namespace": "workflow",
+  "name": "sub-agent-delegation", "version": "1.0.0", "sizeBytes": 3032,
+  "hash": "sha256-6841b6f61a9a62d84152bc0fcfe246af35b7f75001527d6addf55e51068f8387",
+  "fetchedAt": "2026-09-12T07:06:57.123Z", "lastAccessAt": "2026-09-12T07:06:57.292Z" }
 ```
 
-| Field | Required | Type | Notes |
-|-------|----------|------|-------|
-| `formatVersion` | yes | `1` | The on-disk format version |
-| `links` | yes | map of repository short name to a link entry | Everything currently linked |
-
-A link entry holds an absolute `path`, a `linkedAt` timestamp, and an `origin` of `clone` (sous
-cloned the working copy itself) or `path` (sous was pointed at an existing checkout). Unlinking
-removes the entry and leaves the checkout on disk.
-
-Two maps are read: the project's `.sous/sous.links.json` and the machine-wide
-`$SOUS_HOME/sous.links.json`, with the project map winning on conflict. The file is never
-committed. A link bypasses versions, the lockfile and freshness checks, and those bypasses
-belong to one person's machine rather than to the team, so builds announce a linked repository
-loudly.
-
-### Where a linked checkout lives
-
-`sous repo link <repo>` with no path clones the repository for you. The working copy lands in
-`.sous/repos/<owner>/<name>`, or in `$SOUS_HOME/repos/<owner>/<name>` with `--global`, where
-every project on the machine shares one checkout. A directory that is already a checkout of the
-same remote is reused rather than cloned again, so running the command twice is harmless; one
-holding a different remote is an error, because reading the wrong recipes silently would be
-worse than stopping.
-
-`sous repo link <repo> <path>` links a checkout that already exists and clones nothing. The path
-must hold a repo manifest at its root, since a directory without one is not a repository.
+`hash` is checked against the lockfile before the entry is used, and `sizeBytes` and `lastAccessAt` drive
+the size-capped, least-recently-used collection `sous repo gc` performs. The hash is SHA-256 over each
+file's path and bytes in a canonical order, with `.git`, the marker and anything behind a symlink excluded,
+so a version hashes the same on every machine.
 
-`<repo>` is normally the short name of a repository this project has already added. A URL is
-accepted, but it is not a way around adding one: a linked repository's recipes are read with no
-version, no lockfile and no hash check, so a URL the project has not added runs the same trust
-ceremony `sous repo add` runs before anything is cloned or linked. It asks inline, `--trust`
-acknowledges instead for a run with no terminal, and a URL whose short name already belongs to a
-different repository is refused outright.
+## `sous.links.json`
 
-`sous repo unlink <repo>` removes the map entry and nothing else. The checkout stays where it
-is, and its path is printed so you can delete it yourself if you want to.
+A link redirects a repository away from the store and at a real working copy, which is how a maintainer
+edits recipes. It is machine-local and never committed, because a link bypasses versions, the lockfile and
+freshness checks; entries are keyed by the repository's configured short name.
 
-### Ignore hygiene
-
-Everything sous keeps under `.sous/` for one machine is kept out of the project's repository,
-and linking maintains both files that do it:
-
-- `.sous/repos/.gitignore` holds a single `*`. That covers the ignore file itself, so a cloned
-  checkout underneath it contributes nothing at all to the project's repository.
-- `.sous/.gitignore` carries a delimited managed block:
-
-```
-# >>> sous managed (do not edit between these markers)
-sous.links.json
-sous.state.json
-sous.pid
-repos/
-# <<< sous managed
+```json
+{ "formatVersion": 1, "links": {
+  "qa-recipes": { "path": "/home/me/Projects/qa", "origin": "path", "linkedAt": "2026-09-12T07:07:42.800Z" } } }
 ```
 
-Only the lines between the markers are ever rewritten. Anything you put above or below them is
-left exactly as it was, and both files are written only when their contents would change, so
-linking repeatedly never produces a diff. An opening marker with no closing partner stops the
-command with an error rather than a guess about where the block ends.
-
-`sous prune` and `sous clear` only ever touch paths recorded in the state file, so nothing in
-`.sous/repos/` is at risk from either of them.
+`path` is absolute; `origin` is `clone` when sous cloned the working copy itself and `path` when it was
+pointed at an existing checkout, and unlinking removes the entry while leaving either in place. Both the
+project's `.sous/sous.links.json` and `$SOUS_HOME/sous.links.json` are read, and the project's entries win.
 
-## Project configuration
+## Configuration keys
 
-Four optional top-level keys in a project's sous config carry the consumer side. `sous repo add`
-and `sous subscription add` write the first two into machine-managed `conf.d/` layers, and you may also
-hand-write them in the primary config; the layers merge like anything else. The fourth,
-`recipeOutputs`, is always yours to write and is covered under
-[Consuming recipes](#consuming-recipes).
+These live at the top level of the merged config; [The config file](configuration.md) covers the rest.
 
 ```yaml
-# Trusted repositories, keyed by the short name refs use. Adding a repository IS
-# trusting it, and removing the entry withdraws that trust.
 repos:
-  team-recipes:
-    url: https://github.com/example-org/team-recipes
-    provider: github        # inferred from the URL when omitted
-    enabled: true           # defaults to true; false takes it out of play entirely
-    alwaysPull: false
-    addedAt: 2026-09-09T14:03:11.482Z
-    addedBy: user           # "user", "sous", or the ref of the recipe that required it
-
-# What the project subscribes to, keyed by ref key.
+  sous-recipes:
+    url: https://github.com/sous-io/sous-recipes
+    provider: github       # inferred from the URL when omitted; github, gitlab or local
+    enabled: true          # false opts out of a repository sous provides itself
+    alwaysPull: false      # install a newer in-range version rather than holding the lock
+    addedBy: sous          # provenance; "user", "sous" for an entry sous provides itself, or the
+                           # ref of the recipe that pulled it in; one you add records 'addedAt' too
 subscriptions:
   workflow/task-files:
-    range: ^1.2.0
-    enabled: true           # defaults to true
-    prerelease: false
-    alwaysPull: false
-
-# Knobs for the machine-wide store. Every number here is configurable; the values
-# sous ships are defaults, not assumptions.
-store:
-  maxBytes: 1073741824      # one gigabyte
-  freshnessSeconds: 300     # five minutes
-  watchPollSeconds: 300     # five minutes
+    range: "^1.2.0"        # defaults to "*"; prerelease, enabled, alwaysPull, addedAt
+    prerelease: false      # and addedBy work as they do above
+store:                     # every value is a default you can change
+  maxBytes: 1073741824     # one gigabyte; past it, 'sous repo gc' evicts unpinned entries
+  freshnessSeconds: 300    # how long a fetched index stays fresh
+  watchPollSeconds: 300    # how often watch mode polls upstream
+recipeOutputs:             # 'memories' and 'prompts' take the same list-of-paths shape
+  skills: ["${projectRoot}/.claude/skills", "${projectRoot}/.codex/skills"]
+varMappings:
+  QA_SERVICE_TOKEN: workflow/qa-variables/qaServiceToken
 ```
 
-A subscription key is a ref key: a namespace, or a namespace and a recipe. It never carries a
-repository qualifier or a version range, because the range belongs in the entry.
-
-### The entries sous provides itself
-
-Two entries are there without you writing them. Sous lays them UNDER whatever your config
-layers produced, so `sous config show` prints them and `sous repo list` marks the repository
-"built in":
-
-- the repository `sous-recipes`, pointing at `https://github.com/sous-io/sous-recipes`, and
-- a `core` subscription, whose range is exactly the version of sous you are running.
-
-The `core` namespace holds the skills that teach an agent what sous is and how it works, and a
-copy of it ships inside the sous package, so a brand new project builds with those skills even
-with no network. Trust is not a question here: sous itself ships the recipe and pins the
-version to its own.
+| Key | Keyed by | Notes |
+|-----|----------|-------|
+| `repos` | the short name refs use | Adding a repository IS trusting it, and removing the entry withdraws that trust |
+| `subscriptions` | a ref key | A bare namespace (every recipe in it, including ones published later) or `namespace/recipe`. No repo qualifier and no range in the key |
+| `enabled: false` | either of the two above | The opt-out for the entries sous provides itself, the `sous-recipes` repository and the `core` subscription |
+| `store` | fixed fields | Plain numbers, all optional; the values sous ships are defaults, not assumptions |
+| `recipeOutputs` | content kind | Destination directories per kind; see [recipeOutputs: where the files land](#recipeoutputs-where-the-files-land) |
+| `varMappings` | environment variable name | Binds one name to one recipe variable, written `namespace/recipe/variableName` with an optional `repo:` qualifier |
 
-The range being the exact running version is deliberate. Core is published in lockstep with the
-CLI, so upgrading sous upgrades core with it, and a build re-pins core the first time it notices
-that the locked version no longer satisfies the range.
+A repository's `url` may be a URL or an absolute path to one on this machine, read by the `local` provider
+with identical trust. A hand-written entry is laid over sous's default field by field, so an entry holding
+`{ enabled: false }` is a complete opt-out, and a written `url` repoints the repository while the rest of
+the default stands.
 
-### Switching either one off
+### recipeOutputs: where the files land
 
-`enabled` is an ordinary field on any `repos` or `subscriptions` entry. It defaults to true, and
-setting it to false takes that entry out of play entirely: nothing resolves through it, nothing
-is fetched for it, and nothing it publishes is compiled. The entry stays in your config, so the
-opt-out is legible to whoever reads it next.
-
-The two entries above are what it is mostly for:
-
-```yaml
-# Keep the repository, but do not install the core skills.
-subscriptions:
-  core:
-    enabled: false
-
-# Or drop the repository entirely, which withdraws the core subscription with it.
-repos:
-  sous-recipes:
-    enabled: false
-```
-
-Those two lines are complete entries on their own. Sous merges your fields over its own field by
-field, so `{ enabled: false }` inherits the URL and provider underneath it; writing a `url`
-repoints the repository and changes nothing else.
-
-`alwaysPull` installs a newer in-range version whenever one exists rather than holding the
-locked one. It never widens the range a subscription or a dependency declared, and the lockfile
-is still regenerated continuously so it records what the last build actually used. A freshness
-check that fails never breaks a build; the last good answer stands.
+Where each content kind lands, `${var}` substituted as in any config path. Only `skills` has a default,
+`<project root>/.claude/skills`; sous cannot guess where memories or prompts go, so a kind with no
+destination is skipped and one warning names this key. A recipe's `config` contents become layers, not files.
 
 ## Managed config layers
 
-Sous writes three of those keys itself, into the `conf.d/` band reserved for machine-written
-layers:
-
-| File | Holds | Written by |
-|------|-------|------------|
-| `conf.d/500-repos.jsonc` | the `repos:` map | `sous repo add` |
-| `conf.d/510-subscriptions.jsonc` | the `subscriptions:` map | `sous subscription add`, `sous subscription remove` |
-| `conf.d/520-var-mappings.jsonc` | the `varMappings:` map | `sous vars ask` |
-
-All three are ordinary config layers: they load in filename order after your primary config and
-merge into it, so a repository you hand-write in your own config and one sous added are the same
-thing by the time anything reads them. Sous never edits your primary config, and never edits a
-layer outside the `500` through `599` band.
+Three files in a project's `conf.d/` are written by sous rather than by a person, in the machine-written
+`500` to `599` band described under [Layers and merging](config-layers.md#the-managed-5xx-layer-band). They
+are `.jsonc` so they can carry real comments, and each opens with a header saying what it is:
 
-**Sous edits these files by key; you may edit them too.** An edit rewrites only the bytes of the
-entry that changes, through a JSON-with-comments editor, so your comments, your key order and your
-formatting all survive it. New entries are inserted in sorted order, so a change to one repository
-shows up as a change to one repository in your version control history.
-
-They are `.jsonc`, not `.json`, which is why each one can open with a header comment saying what it
-holds:
+| Layer | Holds | Written by |
+|-------|-------|-----------|
+| `500-repos.jsonc` | `repos` | `sous repo add`, `sous repo remove` |
+| `510-subscriptions.jsonc` | `subscriptions` | `sous subscription add`, `sous subscription remove` |
+| `520-var-mappings.jsonc` | `varMappings` | `sous vars ask` |
 
 ```jsonc
 // This file is managed by sous. Sous edits these files by key; you may edit
 // them too, and your comments, key order and formatting are kept.
 //
-// It records the repositories this project trusts. The 'sous repo add'
-// command writes the entries under 'repos'.
+// It records the repositories this project trusts. The 'sous repo add' and
+// 'sous repo remove' commands write the entries under 'repos'.
 //
 // It is JSON with comments (.jsonc): line comments, block comments and trailing
 // commas are all allowed here.
-{
-  "repos": {
-    "sous-recipes": {
-      "url": "https://github.com/sous-io/sous-recipes",
-      "addedAt": "2026-09-09T14:03:11.482Z",
-      // ours; the whole team reads from it
-      "addedBy": "user"
-    }
-  }
-}
-```
-
-Sous reads `.jsonc` anywhere it reads `.json`: a primary `sous.config.jsonc`, any `conf.d/` layer, a
-repo or recipe manifest, and a config layer a recipe contributes. A layer still named
-`500-repos.json` from an older sous is read as a fallback, and the next write moves it to `.jsonc`
-and removes the old file. Only one of the two names may exist at a time; two layers whose names
-differ only by extension are a hard error.
-
-Where a comment is impossible because the format really is strict JSON, the convention is a `//`
-key, which sous ignores wherever it appears. Nothing sous writes uses one today.
-
-The machine-written files that are NOT config layers stay strict JSON, because they carry no prose
-and other tooling parses them: the lockfile, the repo index, the links map and the marker beside a
-store entry.
-
-## Consuming recipes
-
-Subscribing pins a recipe; building is what turns it into files in your project. A recipe's
-`contents` block says what it contributes and of what kind, and each kind lands somewhere your
-config decides.
-
-### `recipeOutputs`: where the files land
-
-```yaml
-# Where the files subscribed recipes contribute are written, per content kind.
-# Every path is ${var} substituted like any other config path, and a kind may
-# name several destinations so one recipe feeds more than one agent directory.
-recipeOutputs:
-  skills:
-    - ${projectRoot}/.claude/skills
-    - ${projectRoot}/.codex/skills
-  memories:
-    - ${projectRoot}/.claude/memories
-  prompts:
-    - ${projectRoot}/prompts/recipes
-```
-
-Only `skills` has a default: `<project root>/.claude/skills`, the project root being the parent
-of your `.sous/` directory. That is where every agent looks, so it is worth defaulting. Nothing
-else is: a kind with no destination is skipped, and sous says so once, naming this key. It will
-not guess where you want your memories or your prompts.
-
-Files are written the same way an `entryGlob` target of your own writes them. The static part of
-each include pattern is the base the output tree mirrors, so a recipe publishing
-`skills/task-files/SKILL.md` under `include: ["skills/**/*.md"]` writes
-`<destination>/task-files/SKILL.md`. The [`.tpl.` convention](configuration.md) applies
-unchanged: a `.tpl.md` file is rendered and loses the `.tpl.` from its name, and everything else
-is copied verbatim.
-
-?> Only recipes you are subscribed to contribute files. A recipe pulled in through `depends` is
-fetched, pinned and addressable from the recipe that declared it, and its files never enter your
-output. That is the whole difference between the two dependency kinds.
-
-Recipe outputs are tracked like every other file sous writes, so `sous prune` removes what an
-unsubscribed recipe used to write, and `sous clear` removes all of it. Neither ever reaches into
-a linked checkout or the machine-wide store; both hold work that is not a project's to delete.
-
-### `config` contents: recipes that configure
-
-A recipe's `config` contents are not written anywhere. They are config layers, and they load
-after your primary config and before your own `conf.d/` layers, so a recipe can supply defaults
-and your project always wins over them.
-
-A recipe's config layer is JSON or YAML only (`.json`, `.yaml` or `.yml`). Sous must be able to
-read everything a repository publishes without running any of it, so an executable layer from a
-recipe is refused with a warning rather than loaded, exactly as manifests are.
-
-A recipe's config layer may set only these top-level keys:
-
-| Key | What a recipe uses it for |
-|-----|---------------------------|
-| `_vars` | Default values for the variables its templates read |
-| `_aliases` | Include aliases pointing at the files it ships |
-| `compilation` | Targets that compile what it ships |
-| `runtimeContext` | Runtime context for the templates it ships |
-| `recipeOutputs` | Where the files it contributes are written |
-| `store` | Knobs for the machine-wide store |
-| `varMappings` | Bindings from an environment variable name to one of its variables |
-
-Every other key is removed before the layer is merged, and sous prints a warning naming the
-recipe and the key it removed. In particular a recipe may not set `repos`, `subscriptions`,
-`tools`, `_env`, `version`, `name` or `$schema`, and it may not set a key sous does not
-recognise. Subscribing to a recipe is not a decision to let it choose which repositories this
-project trusts, what else it subscribes to, or which programs `sous launch` runs; those stay
-yours. Sous reads the layer itself and applies this filter before the config kernel merges
-anything, so the kernel never opens a recipe's layer file at all.
-
-### The `local` provider: repositories on this machine
-
-A repository does not have to be hosted. Name one by a path, relative or absolute, or by the
-same path in `file:///...` form, and sous reads it through the built-in `local` provider:
-
-```bash
-sous repo add /home/me/Projects/my-recipes --name my-recipes
-sous repo add ../my-recipes --name my-recipes
+{ "repos": { "qa-recipes": { "url": "/home/me/Projects/qa", "addedBy": "user" } } }
 ```
 
-A relative path is resolved against the working directory and stored in its absolute form, since
-a repository on this machine is machine-specific anyway.
-
-It is meant for local development and for tests: authoring a repository, trying a recipe before
-publishing it, or running a whole workflow with no network at all. The index is read from the
-working tree when the file is there, so an index you are still writing is picked up without a
-commit, and from the committed copy otherwise. A recipe's files come from the version's tag in
-the local git repository; a directory that is not a git repository has no versions to honour, so
-its working tree is copied instead.
-
-!> Trust semantics are identical to a hosted repository. A local path is added, and therefore
-trusted, through the same ceremony, because the recipes in it still run on this machine. "It is
-already on my disk" is not a reason to skip the question.
-
-For editing a repository you are already subscribed to, reach for `sous repo link` instead: it
-redirects one repository's resolution at a working copy without changing what your project
-subscribes to.
-
-## Variables and answers
-
-A variable **definition** is a published specification; an **answer** is the stored value. A
-question is asked only when a subscribed recipe needs a variable and nothing in scope answers
-it, or when the answer in scope no longer fits the definition.
-
-### Where answers live
-
-Answers are stored in the project's own env files, and sous edits them the way a careful person
-would: exactly one value line is rewritten or appended, and comments, blank lines, ordering and
-quoting all survive. A newly added entry gets a short generated header comment above it saying
-where the value came from. Comments are output only; sous never reads one back.
-
-| File | Committed | Holds |
-|------|-----------|-------|
-| `.sous/.env` | yes | Shared answers (`scope: shared`), the team's defaults |
-| `.sous/.env.local` | no, gitignored | Machine-specific answers (`scope: local`) and every secret |
-
-### The resolution ladder
-
-For each variable sous generates a list of environment variable names and tries them in order,
-most specific first. Within a rung, the real shell environment wins, then `.sous/.env.local`,
-then `.sous/.env`.
-
-| Rung | Name | Example |
-|------|------|---------|
-| 1. mapping record | whatever the record names | `TEAM_API_URL` |
-| 2. recipe scope | `SOUS_VAR_<NAMESPACE>_<RECIPE>_<VARIABLE>` | `SOUS_VAR_MISC_STUFF_API_URL` |
-| 3. namespace scope | `SOUS_VAR_<NAMESPACE>_<VARIABLE>` | `SOUS_VAR_MISC_API_URL` |
-| 4. shared scope | `SOUS_VAR_<VARIABLE>` | `SOUS_VAR_API_URL` |
-| 5. declared name | the definition's own `env` field | `GITHUB_TOKEN` |
-
-!> Candidate names are only ever GENERATED and looked up, never parsed back into scopes. The
-underscore is both the delimiter and a legal identifier character, so no parse of a name would
-be trustworthy. When names collide, a mapping record settles it.
-
-### Mapping records
-
-A mapping record binds one environment variable, of any name, to one fully qualified variable.
-It is the top rung of the ladder and the universal conflict resolver: two recipes wanting the
-same name, or a name already meaning something else in your environment.
-
-```jsonc
-// This file is managed by sous. Sous edits these files by key; you may edit
-// them too, and your comments, key order and formatting are kept.
-{
-  "varMappings": {
-    "TEAM_API_URL": "sous-recipes:misc/stuff/apiUrl"
-  }
-}
-```
-
-A target is written `namespace/recipe/variableName`, optionally qualified as
-`repo:namespace/recipe/variableName`. Records live under the top-level `varMappings` config key;
-sous writes the ones it creates into the machine-managed `conf.d/520-var-mappings.jsonc` layer,
-editing one record at a time so each name has exactly one, and you may hand-write `varMappings` in
-the primary config too.
-
-### The commands
-
-| Command | What it does |
-|---------|--------------|
-| `sous vars list` | Lists every variable in play: its recipe, the environment variable that answered it, the value (hidden for a secret) and the source |
-| `sous vars show <name>` | Shows one variable in full, including every environment variable on the ladder and which rung answered |
-| `sous vars ask [name]` | Answers what is unanswered, or one named variable; `--all` asks everything again |
-| `sous vars ask --file <path>` | Asks the definitions in a standalone file holding the same `variables:` array a recipe manifest carries |
-
-`sous vars list`, `sous vars show` and `sous vars ask` all accept `--file`, and `sous vars ask`
-accepts `--dry-run`.
-
-Answers already in scope are listed visibly and never re-asked. Without a terminal, an
-unanswered required variable fails the run and names the exact environment variables that would
-satisfy it, most specific first, which is what a continuous integration log needs.
-
-## Releasing and contributing
-
-Two commands work inside a recipe repository rather than inside a project, so neither one looks
-for a `.sous/` directory: `sous repo release` publishes, and `sous repo submit` proposes a change
-to a repository someone else maintains. Both refuse to do anything until the repository describes
-itself consistently.
-
-### What is checked
-
-Every run of either command checks the same things, and reports all of them at once rather than
-stopping at the first:
-
-- Every folder listed under `recipes` in `sous.repo.yaml` exists and holds exactly one recipe
-  manifest.
-- Every recipe belongs to a namespace the repository manifest declares, and no two recipes share
-  a `namespace/name` key.
-- Every `depends` and `subscribes` ref parses.
-- No two variable definitions of DIFFERENT names claim the same environment variable. Two
-  definitions of the SAME name may share one, because that is exactly what the shared rung of the
-  resolution ladder is for.
-- A tag exists for the version its recipe manifest declares, or that version is pending; when the
-  tag does exist, the manifest carried by that tag declares the same version, and the folder's
-  content still matches what the tag published.
-
-Claiming a well-known name such as `PATH`, `HOME`, `GITHUB_TOKEN` or anything beginning `AWS_` or
-`SOUS_` is a warning rather than an error. Binding an existing token is legitimate; it just
-deserves saying out loud. Add `x-intentional: true` to the definition to say you meant it.
-
-### Versions, tags and the index
-
-Recipe metadata is the source of truth for versions. A tag shaped `namespace/recipe@1.2.3` is a
-convenience ref that records which commit a version was published from, and `sous.index.json` is
-the catalog subscribers read. The three are kept in step by three rules:
-
-- **A published version never changes.** Its hash is carried forward exactly as published, and a
-  disagreement is an error telling you to bump the version rather than republish it.
-- **A version is published when its tag exists.** The one moment an index records a version
-  without a tag is the release commit itself: the index is committed and the tag is cut on that
-  commit. Any older version missing its tag is an error.
-- **The tags are the backstop.** A tagged version missing from the index is rebuilt from its tag,
-  so deleting `sous.index.json` and regenerating it restores the same catalog.
-
-!> A release commits the version bumps and the index it writes, and nothing else. It refuses to
-run while anything else is uncommitted, because a tag names one commit and the index records
-what each recipe folder holds right now.
-
-### `sous repo release`
-
-One run plans, asks once, and then publishes. Within its scope it releases only recipes whose
-files changed since the tag that last published them, bumping any whose version still equals
-that tag.
-
-| Invocation | What it does |
-|------------|--------------|
-| `sous repo release` | Plan, ask once, then bump, regenerate the index, commit and tag. |
-| `sous repo release --dry-run` | Print the plan and stop. |
-| `sous repo release --yes` | Skip the question; everything else is the same. |
-| `sous repo release --namespace <ns>` | Release only that namespace. Repeatable. |
-| `sous repo release --recipe <ns/name>` | Release only that recipe. Repeatable. |
-| `sous repo release --bump <level>` | `patch` (the default), `minor`, `major` or `prerelease`. |
-| `sous repo release --no-bump` | Raise nothing; a changed recipe nobody raised is an error. |
-| `sous repo release --include-unchanged` | Release everything in scope, changed or not. |
-| `sous repo release --tag` | Cut the tags even on a branch other than the default one. |
-| `sous repo release --push` | Push the commit, and the tags this run created, to `origin`. |
-| `sous repo release --check` | Read only: validate, and fail when the committed index is out of date. This is what a pull request runs. |
-| `sous repo release --ci` | The merge preset: never bump, accept the plan, never ask, fail on anything unbumped. |
-
-Tags are cut dependency-first, and each version's resolved dependencies are written into the
-index. On a branch other than the default one a release bumps and commits but cuts no tags,
-because tags are cut on the default branch by the merge; `--tag` overrides that.
-
-A version bump edits the manifest in place, so its comments, its field order and its layout
-survive. Two small normalizations happen in a YAML manifest: a folded block of prose may be
-re-wrapped, and the spacing before a trailing comment is collapsed to one space.
-
-The workflow `sous repo init` scaffolds runs `--check` on every pull request and `--ci --push`
-on a merge.
-
-### `sous repo submit`
-
-`submit` means "propose a change for maintainers to review". It never publishes and never writes
-to a repository directly.
-
-Sous validates first, because a proposal that fails the maintainer's own checks wastes their
-review, and then hands the mechanics to the provider's own command line tool, which already holds
-your credentials:
-
-1. **Preflight.** An `origin` remote exists, sous recognizes its provider, that provider's CLI
-   (`gh` or `glab`) is installed and signed in, and everything is committed.
-2. **Validation.** The repository validates, and the committed index is current.
-3. **Delegation.** On GitHub, sous asks whether you can push to the repository itself; if you
-   cannot, it forks it onto your own account and proposes from there. The branch is pushed and a
-   pull request (a merge request on GitLab) is opened. A change sitting on the default branch is
-   moved to a branch named `sous/submit-<date>-<time>` first.
-
-| Flag | What it does |
-|------|--------------|
-| `--title <text>` | The proposal's title. Defaults to your last commit's subject. |
-| `--body <text>` | The proposal's body. Defaults to a summary sous writes, listing the recipes and the versions the change would publish. |
-| `--draft` | Opens the proposal as a draft. |
-| `--dry-run` | Runs the whole preflight and sends nothing. |
+A write rewrites only the bytes of the entry that changes, staging the result and renaming it over the file,
+so an interrupted write leaves the previous layer rather than a truncated one. A layer still carrying its
+old `.json` name is read as a fallback and migrates on the next write: the `.jsonc` file is written and the
+`.json` one removed, so a project never ends up with both, which would be a hard config error.
 
-Every step prints before it runs, and a failure says exactly which steps completed. A pushed
-branch with no proposal behind it is a normal outcome of a network failure, and you are told
-about it rather than left guessing.
+## Where to go next
 
-?> If a repository's provider cannot open a proposal for you, sous prints the `contribute` pointer
-from its `sous.repo.yaml` instead, so you are never left without a route.
+- [Repositories](repositories.md): the model, trust, and the lockfile
+- [Consuming recipes](repositories-consuming.md): adding, subscribing and building
+- [Authoring a repository](repositories-authoring.md): writing and releasing recipes
+- [Providers](repositories-providers.md): how a URL becomes a repository identity
+- [Troubleshooting repositories](repositories-troubleshooting.md): what each error means