@sous-io/sous 0.2.36 → 1.0.1

package/docs/markdown/configuration.md

@@ -7,7 +7,7 @@ user-level config (nothing is read from `~/.sous`) and no multi-project map.
 ## The config file
 
 Exactly one primary config lives inside `.sous/`: `sous.config.js`, `sous.config.mjs`,
-`sous.config.json`, `sous.config.jsonc`, or `sous.config.yaml`. Two or more candidates is an
+`sous.config.ts`, `sous.config.json`, `sous.config.jsonc`, or `sous.config.yaml`. Two or more candidates is an
 error, never a silent first-match. A typical config:
 
 ```js
@@ -16,8 +16,7 @@ export const config = {
   name: "My Project",                  // optional display name
   _env: { userHome: "HOME" },          // map config vars from env vars (top-level only)
   _vars: {
-    projectRoot: "${sousDir}/..",      // ${sousDir} is the discovered .sous/ dir
-    docsDir: "${projectRoot}/docs",    // declaration order never matters
+    docsDir: "${projectRoot}/docs",    // projectRoot is set by sous; order never matters
   },
   _aliases: { myDocs: "${docsDir}" },  // extra @include bases (optional)
   compilation: {
@@ -38,9 +37,16 @@ export const config = {
 };
 ```
 
+`${projectRoot}` is the directory that holds `.sous/`. Sous sets it, and setting `projectRoot` in any
+`_vars` block is an error; see [Variables](config-variables.md#auto-vars).
+
+The `.claude/skills` target above compiles the project's own skills. Skills from subscribed recipes
+need no target of their own: the built-in Claude Code plugin sends them to `.claude/skills`, and
+`recipes.skills.outputs` adds destinations of your own (see
+[Consuming recipes](repositories-consuming.md)).
+
 A JSON config may set `"$schema"` to bind the `sous.config.schema.json` artifact shipped with
-sous for editor autocompletion; sous accepts and ignores the key. `sous init --format json`
-writes one already bound to the copy of that artifact published for the running version.
+sous for editor autocompletion; sous accepts and ignores the key.
 
 ?> Configs use `${var}` syntax. Template files use LiquidJS double-brace syntax instead; the two
 are resolved at different stages and never mix.
@@ -72,32 +78,113 @@ A path may use glob syntax (`*`, `**`, `?`, `[..]`, `{a,b}`) and then includes e
 path order. The same file may be included in more than one place; a circular include is an error, as is a line
 that looks like an include (`@docs/notes.txt`, `@~workflow/missing`) but cannot be resolved, which fails the
 build naming the file and the line. A line inside a fenced code block is left as written. An alias name may not
-start with `~` or `#`. Reads of recipe files go through the
-[ref resolver](adrs/0013-one-ref-resolver.md); [Including recipe files in your own templates](repositories.md#including-recipe-files-in-your-own-templates)
+start with `~` or `#`. [Including recipe files in your own templates](repositories.md#including-recipe-files-in-your-own-templates)
 has the namespace rules.
 
 ## Composition
 
-The primary config is optionally extended by drop-in layers: every `*.js|mjs|json|jsonc|yaml` file
-directly inside `.sous/conf.d/` is loaded after the primary config and deep-merged over it. A
-`.js`/`.mjs` config or layer can also compose programmatically through a `configure()` function.
-[Layers and merging](config-layers.md) covers the full semantics.
+The primary config is optionally extended by drop-in files: every `*.js|mjs|ts|json|jsonc|yaml`
+file directly inside `.sous/conf.d/` is applied after the primary config, in the order of the
+number its name starts with (`500-repos.jsonc` before `610-mac.jsonc`), and merged into it. Recipes and plugins can change the config too, and your own files are always
+applied again after them, so a value you set wins. A
+`.js`, `.mjs` or `.ts` file can also change the config through a `configure()` function, and a
+`.patch.json` or `.patch.jsonl` file holds raw edits. [Layers and merging](config-layers.md) covers
+the full semantics.
+
+## Config expressions
+
+A value in a JSON, JSONC or YAML config file may be an expression object, decided when sous builds
+the config instead of when the file is written. The reserved keys are `$expr`, `$if`, `$elseif` and
+`$else` (each `$if` and `$elseif` may carry a `:<name>` qualifier, and `$expr` a `:<language>` one).
+Liquid is the expression language. An expression can read `host.platform`, `env.<NAME>`, variables
+by their bare name, and recipe answers (except under `subscriptions` and `repos`).
+
+A subscription switched off on a Mac only:
+
+```jsonc
+// conf.d/610-mac.jsonc
+{
+    "subscriptions": {
+        "tool-usage/automated-browser-tasks": {
+            "enabled": {
+                "$if": {
+                    "expr": "host.platform == 'darwin'",
+                    "then": false
+                }
+            }
+        }
+    }
+}
+```
+
+On a Mac, `enabled` is `false`. Elsewhere the condition is false and there is no `$else`, so the key
+is dropped and the subscription stays on. An expression may appear at any depth, including inside
+arrays. An object mixing a reserved key with any other key is an error, so a typo such as `"$iff"`
+never passes through as config. The full rules are in
+[the design of config expressions](architecture/specifications/S5-config-expressions.md).
+
+## Plugins
+
+Sous is a small engine plus plugins; the CLI, recipes, the compiler, skills, memories, Claude Code
+support and the package-manager and repository-host integrations are all built-in plugins. Which
+plugins load is an ordinary config key, so it may be set in any config file, a recipe's included.
+There is no separate bootstrap config and no `"sous"` key in `package.json`.
+
+- `plugins.discover` (`"dependencies" | "scan" = "dependencies"`): `"dependencies"` loads the
+  built-ins, the plugins in the project's `package.json` dependencies (and the workspace root's) and
+  those under `load`; `"scan"` also looks for installed plugins through the package managers.
+- `plugins.load` (`string[]`): plugins to load though `package.json` does not list them.
+- `plugins.disabled` (`string[]`): plugins never to load, built-ins included.
+- `plugins.options` (`Record<string, object>`): each plugin's own options, keyed by plugin name.
+
+```jsonc
+// .sous/sous.config.jsonc
+{
+    "plugins": {
+        "load": [
+            "sous-plugin-bun"
+        ],
+        "disabled": [
+            "sous-plugin-old-thing"
+        ],
+        "options": {
+            "sous-plugin-claude-code": {
+                "model": "opus"
+            }
+        }
+    }
+}
+```
+
+Two more keys settle what plugins do:
+
+- `services.replace` picks the winner when two plugins both take over the same piece of sous's
+  work. Each piece has a name, such as `git.runner` (how sous runs git), and two plugins replacing
+  the same one stops sous with an error until you choose one:
+  `"services": { "replace": { "git.runner": "sous-plugin-fast-git" } }`. Sous then warns on every
+  run that the other plugin may not work as expected.
+- `budgets` changes how long a step may take before sous warns that it is slow; a budget set to
+  `false` turns that warning off. `--timings` on any command prints how long every step took.
+
+`sous plugins show` lists every plugin and what it adds. Recipes may ship plugins too; see
+[where plugins come from](architecture/specifications/S1-engine.md#where-plugins-come-from).
 
 ## Where to go next
 
 - [Discovery and overrides](config-discovery.md): how sous finds the config, and the flags and
   environment variables that override it
-- [Layers and merging](config-layers.md): `conf.d/` ordering, merge semantics, the JS
-  `configure()` contract
-- [Variables](config-variables.md): the `${var}` scope chain, auto-vars, fixpoint resolution
+- [Layers and merging](config-layers.md): the order files apply in, how values merge, the
+  `configure()` function, patch files
+- [Variables](config-variables.md): where `${var}` values come from, the variables sous sets
+  (`projectRoot` among them), and variables that refer to other variables
 - [Inspecting and validating](config-inspection.md): the `sous config` commands and the
   validation pipeline
 
 ## Rules of the road
 
-- Hand-written config belongs in the primary file or your own `conf.d/` layers. The
-  `conf.d/500-*` through `conf.d/599-*` band is reserved for layers the sous CLI itself writes.
+- Hand-written config belongs in the primary file or your own `conf.d/` files. The
+  `conf.d/500-*` through `conf.d/599-*` band is reserved for files the sous CLI itself writes.
   Sous edits those by key, so you may edit them too and your comments, key order and formatting
-  survive; put a layer of your own outside the band.
+  survive; put a file of your own outside the band.
 - Any config problem halts sous with a `ConfigError` naming the offending file; there is no
   warn-and-continue.

package/docs/markdown/design-principles.md

@@ -52,7 +52,10 @@ sous at runtime.*
 Everything gets an escape hatch, within practicality. The happy path stays maximally simple;
 the escape hatches are advanced usage and may require the docs, but they must exist and they
 still get thoughtful ergonomics. Projects control everything granularly, and an individual
-user can override every project decision through their own configuration layers.
+user can override every project decision through their own config files. Plugins get the same
+reach: nearly everything sous does, the CLI included, is a plugin, and a plugin can change the
+config, wrap or replace another plugin's work, and add commands. Where a choice is risky, sous
+reports the problem and lets it happen rather than forbidding it.
 
 *Example: subscribing to a recipe is one line and pulls in everything the recipe provides;
 excluding one skill from that subscription may take a documented setting, but the setting is

package/docs/markdown/repositories-authoring.md

@@ -99,6 +99,36 @@ template may include a file from a recipe this one depends on through the reserv
 this recipe's own `depends` and `subscribes` at their pinned versions; see
 [Including recipe files in your own templates](repositories.md#including-recipe-files-in-your-own-templates).
 
+### Recipes that ship sous plugins
+
+A recipe may ship a sous plugin: code that extends sous itself, with the same plugin interface an npm
+plugin uses. It is one self-contained bundled file, because sous never runs `npm install` for a recipe.
+The same rule holds for anything else in a recipe that runs, such as a helper script or a hook. The
+manifest names the bundle, and optionally its type declarations:
+
+```yaml
+# sous.recipe.yaml
+plugin:
+    bundle: plugin/index.js
+    types: plugin/index.d.ts      # optional
+```
+
+Nothing in a repository runs until the subscriber trusts the repository, so the trust question is the
+gate for a recipe's plugin as for its other content. Sous copies a recipe plugin's `.d.ts` file into the
+subscriber's `.sous/types/`, so other plugins in that project see its types; a plugin with no `.d.ts`
+still works. A recipe may also require plugins from npm, each with a version range:
+
+```yaml
+# sous.recipe.yaml
+requires:
+    plugins:
+        sous-plugin-claude-code: "^1.0.0"
+```
+
+A subscriber is offered the missing plugin when they subscribe; see
+[Subscribe to a recipe](repositories-consuming.md#subscribe-to-a-recipe). How a plugin is written is in
+[the engine specification](architecture/specifications/S1-engine.md), under "Plugins".
+
 ## Declare the variables a recipe needs
 
 A recipe that needs a value from the project asks through a **definition**: a published specification, never a

package/docs/markdown/repositories-consuming.md

@@ -112,16 +112,16 @@ recorded in its canonical form, `namespace/recipe`.
 The whole dependency closure resolves before anything is downloaded, and only then is anything
 written; an install is whole or not at all.
 
-| Flag | What it does |
-|------|--------------|
-| `-y, --yes` | Answer yes to both questions this command can ask: the subscribe confirmation, and the trust question for a repository it has to add |
-| `--accept-first` | When a ref matches several things, take the first one listed |
-| `--answer <name>=<value>` | Answer one question ahead of time. Repeat it per answer, or read a whole file of them with `--answers-file <path>` |
-| `--always-pull` | Install a newer in-range version whenever one exists, rather than holding the locked one |
-| `--dry-run` | Print what would be installed, writing and downloading nothing |
-| `--no-build` | Record the subscription without rebuilding the project |
-| `--prerelease` | Let prerelease versions take part in version range matching |
-| `--non-interactive` | Never ask; fail instead, naming the flag that would have answered |
+A few flags change how it runs: `--yes` answers yes to the subscribe confirmation and the trust
+question, `--answer <name>=<value>` answers a recipe's question ahead of time, `--dry-run` prints what
+would be installed without writing or downloading anything, and `--non-interactive` fails instead of
+asking, naming the flag that would have answered. `sous subscription add --help` lists every flag.
+
+A recipe may require sous plugins from npm, each with a version range. When a required plugin is
+missing or outside its range, `sous subscription add` refuses the recipe; run interactively, it offers
+to install the plugin, and `--install-plugins` does that without asking. A build fails when a
+subscribed recipe's requirement breaks later, for example after the plugin was removed, and the
+message names the plugin and the command that installs it.
 
 ?> `sous subscribe` and `sous unsubscribe` are accepted spellings of these two commands, and every
 topic answers to both spellings of its name (`sous subscriptions add`, `sous repos list`).
@@ -175,10 +175,21 @@ like `workflow/qa-helper` above, is fetched and pinned but stays out of your out
 
 Recipe files compile under the [`.tpl.` convention](configuration.md#templates-and-the-tpl-convention): a file
 with `.tpl.` in its name is rendered through LiquidJS and loses `.tpl.` on the way out, and anything else is copied
-verbatim. Skills are written to the directories named by the
-[`recipes`](repositories-file-formats.md#recipes-what-each-content-kind-does) config key; for example
-`recipes: { skills: { outputs: ["${projectRoot}/.claude/skills", "${projectRoot}/.codex/skills"] } }`. The
-default is `<project root>/.claude/skills`, because that is where every agent looks. Written skills are tracked
+verbatim. Skills are written to every skills directory a plugin for an agent tool names, and to the directories you name
+under the [`recipes`](repositories-file-formats.md#recipes-what-each-content-kind-does) config key. The
+Claude Code plugin built into sous adds `<project root>/.claude/skills`, so that is where skills land unless
+you disable that plugin (see [Plugins](configuration.md#plugins)). To add a destination of your own:
+
+```js
+recipes: {
+  skills: {
+    outputs: ["${projectRoot}/.codex/skills"],
+  },
+}
+```
+
+`projectRoot` is set by sous (the directory holding `.sous/`), so you never define it. When no plugin names a skills directory
+and you name none, skills go nowhere, and the build says so and how to fix it. Written skills 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 reaches into a linked checkout.
 
@@ -214,6 +225,11 @@ When a build finds a memory an active recipe publishes that no include of any ou
 or the view) and `exclude` does not name, it warns, naming the memory and the line to add. Subscribing alone
 includes nothing, and the warning is how that is never silent.
 
+?> In sous 1.0 an agent's plugin can also name the instruction file that agent reads in every session
+(`CLAUDE.md` for the Claude Code plugin built into sous). Sous then writes that file with one `@` include
+line for each memory `recipes.memories` selects, so the memories reach the agent without a line of your own.
+How that file and an instruction file your own templates write fit together is still being decided.
+
 ## Answer the questions
 
 A recipe publishes variable definitions; you supply answers. Subscribing asks whatever is
@@ -354,6 +370,48 @@ there is no entry to delete: the one sous provides comes back on the next run, s
 opt-out outlives it. `sous subscription add core` clears it again. If you remove `core`, make sure
 something else tells your agents not to edit generated files.
 
+## Switch a subscription off on one machine
+
+A subscription stays in the config with `enabled: false`, so the opt-out is visible. A switched-off
+subscription is not built: the recipes reached only through it are skipped, the outputs they wrote are
+pruned, and their variables are neither asked nor required. Their pins stay in the committed lockfile,
+so switching a recipe off on your machine never removes it for anyone else.
+
+```bash
+sous subscription disable tool-usage/automated-browser-tasks
+sous subscription enable tool-usage/automated-browser-tasks
+```
+
+Both edit `.sous/conf.d/510-subscriptions.jsonc` by key. To switch one off only on some machines, write
+`enabled` in a `conf.d` file of your own that sorts after 510; a later file wins over the managed one:
+
+```jsonc
+// .sous/conf.d/610-mac.jsonc
+{
+    "subscriptions": {
+        "tool-usage/automated-browser-tasks": {
+            "enabled": {
+                "$if": {
+                    "expr": "host.platform == 'darwin'",
+                    "then": false
+                }
+            }
+        }
+    }
+}
+```
+
+The build prints one line per skipped recipe, saying why:
+
+```text
+$ sous build
+Skipped tool-usage/automated-browser-tasks: its subscription is switched off (conf.d/610-mac.jsonc).
+Pruned 4 outputs it had written.
+```
+
+The `$if` object is a config expression, decided each time sous builds the config; see
+[Config expressions](configuration.md#config-expressions).
+
 ## Restore a fresh clone
 
 A clone has the lockfile and the subscriptions, and no store. `sous build` restores what the

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

@@ -79,11 +79,23 @@ contents:                           # what a subscriber actually receives
 | `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 |
 | `submissions` | no | Whether this recipe takes proposed changes, winning over the repository's block; see [The submissions block](#the-submissions-block) |
+| `plugin` | no | A sous plugin the recipe ships: `bundle`, the path of one self-contained bundled file, and optionally `types`, its `.d.ts` file; see [Recipes that ship sous plugins](repositories-authoring.md#recipes-that-ship-sous-plugins) |
+| `requires` | no | `requires.plugins` maps npm sous plugin names to version ranges the recipe needs |
 
-`contents[].kind` is `skills`, `memories`, `prompts` or `config`; there is no kind for a sous plugin. `skills` are
+```yaml
+plugin:
+    bundle: plugin/index.js
+    types: plugin/index.d.ts
+requires:
+    plugins:
+        sous-plugin-claude-code: "^1.0.0"
+```
+
+`contents[].kind` is `skills`, `memories`, `prompts` or `config`; a sous plugin is not a content kind but the
+`plugin` field above. `skills` are
 written to the destinations named by [`recipes`](#recipes-what-each-content-kind-does); `memories` are included
 into your instruction files by one line (see [Recipe memories](repositories-consuming.md#recipe-memories));
-`config` entries become config layers; nothing takes `prompts` yet, and the build warns about a recipe that
+each `config` file joins the subscriber's config, under the project's own files so the project wins; nothing takes `prompts` yet, and the build warns about a recipe that
 publishes them. `include` needs at least one glob, and both lists are recipe-relative.
 
 ### The submissions block
@@ -126,9 +138,8 @@ two readings that both publish what is named fail it too, naming the spellings t
 
 ### Ref forms
 
-Every place a ref is written reads it with one ref resolver (`src/services/ref-resolver/`): a parser that
-returns every reading of the text, a pruner for the place that drops the readings the place refuses, and a
-lookup that keeps the readings that exist. These forms are recognized everywhere; the table after them says
+Every place a ref is written reads it the same way: sous lists every way the text can be read, drops the
+readings that place does not accept, and keeps the ones that name something that exists. These forms are recognized everywhere; the table after them says
 which each place allows. A refused form is an error saying what to write there instead.
 
 | Form | Example | Names |
@@ -359,7 +370,7 @@ These live at the top level of the merged config; [The config file](configuratio
 repos:
   sous-recipes:
     url: https://github.com/sous-io/sous-recipes
-    provider: github       # inferred from the URL when omitted; github, gitlab or local
+    provider: github       # inferred from the URL when omitted; github, gitlab, local, or a host a plugin adds
     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
@@ -373,7 +384,7 @@ store:                     # every value is a default you can change
   freshnessSeconds: 300    # how long a fetched index stays fresh
   watchPollSeconds: 300    # how often watch mode polls upstream
 recipes:                   # what each content kind a subscribed recipe publishes does
-  skills: { outputs: ["${projectRoot}/.claude/skills", "${projectRoot}/.codex/skills"] }
+  skills: { outputs: ["${projectRoot}/.codex/skills"] }   # added to the skills directories agent plugins name
   memories: { first: ["communication/*"], exclude: ["tool-usage/automated-browser-tasks"] }
 varMappings:
   QA_SERVICE_TOKEN: workflow/qa-variables/qaServiceToken
@@ -395,15 +406,18 @@ the default stands.
 
 ### recipes: what each content kind does
 
-One block per content kind a subscribed recipe publishes. A recipe's `config` contents become layers, not files,
-and a recipe's own config layer may set `recipes.skills` only; `recipes.memories` chooses what the project
+One block per content kind a subscribed recipe publishes. A recipe's `config` contents join the config, not the
+output files, and a recipe's own config file may set `recipes.skills` only; `recipes.memories` chooses what the project
 includes, so it is dropped from a recipe's layer with a warning.
 
-- `recipes.skills.outputs` (`string[]`, default `["<project root>/.claude/skills"]`): the directories recipe skill
-  bundles are written into, `${var}` substituted as in any config path. Name several to feed more than one agent.
+- `recipes.skills.outputs` (`string[]`, default none): your own directories recipe skill bundles are written
+  into, besides every skills directory a plugin for an agent tool names. `${var}` is substituted as in any config path. The
+  built-in Claude Code plugin adds `<project root>/.claude/skills`, so skills land there with no setting. When no
+  plugin names a skills directory and this list is empty, skills go nowhere, and the build says why. `${projectRoot}` is set by sous;
+  setting `projectRoot` in any `_vars` is an error.
 - `recipes.memories.first` (`string[]`, default none): recipes whose memories lead the `#memories` view. An entry
   is a glob over `namespace/recipe` keys (`communication/*`), or a regular expression written between two slashes
-  (`/^tool-usage\//`); a string, because a config layer is JSON and cannot hold a `RegExp`.
+  (`/^tool-usage\//`); a string, because the config is plain JSON data and cannot hold a `RegExp`.
 - `recipes.memories.exclude` (`string[]`, default none): recipes whose memories the view leaves out, and the
   build's unincluded-memory warning never lists. The same entry forms as `first`.
 
@@ -418,7 +432,7 @@ are `.jsonc` so they can carry real comments, and each opens with a header sayin
 | Layer | Holds | Written by |
 |-------|-------|-----------|
 | `500-repos.jsonc` | `repos` | `sous repo add`, `sous repo remove` |
-| `510-subscriptions.jsonc` | `subscriptions` | `sous subscription add`, `sous subscription remove` |
+| `510-subscriptions.jsonc` | `subscriptions` | `sous subscription add`, `remove`, `enable` and `disable` |
 | `520-var-mappings.jsonc` | `varMappings` | `sous vars ask` |
 
 ```jsonc
@@ -438,6 +452,10 @@ so an interrupted write leaves the previous layer rather than a truncated one. A
 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.
 
+No file is special to sous when it reads the config: a `conf.d` file of your own that sorts after 510 can
+override a subscription the managed file lists, such as switching it off on one machine (see
+[Switch a subscription off on one machine](repositories-consuming.md#switch-a-subscription-off-on-one-machine)).
+
 ## Where to go next
 
 - [Repositories](repositories.md): the model, trust, and the lockfile

package/docs/markdown/repositories-providers.md

@@ -4,9 +4,9 @@ A **provider** is everything sous knows about one kind of repository host. It is
 a host-specific fact is allowed to live, so every command above it (add, subscribe, build,
 release, submit) talks about repositories in the same terms whatever host they live on.
 
-Sous ships three: `github`, `gitlab` and `local`. This page covers how one is chosen for a URL,
-what a URL becomes once a provider has taken it apart, how private repositories authenticate,
-what each provider can do when you propose a change, and what writing a fourth one involves.
+Sous ships three providers, `github`, `gitlab` and `local`, and a sous plugin can add another. This
+page covers how a provider is chosen for a URL, what a URL becomes once a provider has taken it apart, how private repositories authenticate,
+what each provider can do when you propose a change, and what adding another one involves.
 
 ## What a provider answers
 
@@ -132,8 +132,8 @@ absolute directory, because that is what git is given when a recipe is fetched.
 whose scheme is the provider's identifier: `github://sous-io/sous-recipes/workflow/sat@^1.1`. A
 first segment containing a dot is read as the host, so `gitlab://gitlab.example.com/group/project/-/ns/recipe`
 addresses a self-hosted instance; without one, the provider's public host is assumed. Where a
-repository path ends, and what a browser URL's path looks like, is each provider's own rule (its
-`readLocation`), so a URL copied from either host's file view works too. `local://` is refused,
+repository path ends, and what a browser URL's path looks like, is each provider's own rule, so a URL
+copied from either host's file view works too. `local://` is refused,
 because a path on your disk is not a published location. Every form is in
 [Ref forms](repositories-file-formats.md#ref-forms).
 
@@ -141,37 +141,48 @@ because a path on your disk is not a published location. Every form is in
 
 Sous reads a repository in two very different ways, and they authenticate differently.
 
-**The index** is one plain HTTPS GET of a raw file, carrying a bearer token when sous has one:
+**The index** is read by trying three ways in order, so reading works with whatever access you have.
+Neither `gh` nor `glab` is ever required to read a repository; they are needed only for
+`sous repo contribute` and `sous repo submit`.
+
+```text
+Reading sous.index.json from a repository
+  1. HTTP with a token     if a token is found (see below)
+  2. HTTP with no token    public repositories
+  3. git                   a shallow, sparse fetch of the one file, using your own git
+                           credentials (SSH keys, credential helpers)
+```
+
+For GitLab, the HTTP requests use the API address, with the whole project path encoded, so a nested
+group's `/` becomes `%2F`:
 
 ```text
 https://raw.githubusercontent.com/<owner>/<name>/HEAD/sous.index.json
-https://<gitlab host>/<owner>/<name>/-/raw/HEAD/sous.index.json
+https://<gitlab host>/api/v4/projects/<owner>%2F<name>/repository/files/sous.index.json/raw?ref=HEAD
 ```
 
-A token is looked for in two places, in this order:
+A token is looked for in these places, in this order, and a missing one is skipped:
 
 1. the environment: `GITHUB_TOKEN` for GitHub, `GITLAB_TOKEN` for GitLab;
-2. the host's own command line tool, `gh auth token` or `glab auth token`, when it is installed
-   and signed in.
+2. `git credential fill`, the credential git already stores for `https://<host>`;
+3. the host's own command line tool, only when it is installed: `gh` for GitHub, and
+   `glab config get token --host <host>` for GitLab.
 
-Neither is required. A public repository needs no token at all, and a missing `gh` or `glab` is
-never an error on the read path; sous simply fetches without one. When the host refuses, the
-error says which of the two situations you are in:
+A command's output counts as a token only when the command exits `0` and prints exactly one non-empty
+line holding no whitespace.
 
-```text
-Sous could not fetch the repo index from https://raw.githubusercontent.com/acme/recipes/HEAD/sous.index.json.
-  The server answered 404 Not Found.
-  Either the repository publishes no sous index yet, or the URL names a repository that does
-  not exist.
-```
-
-A 401 or 403 says the repository is private or was not authorized, and points at the two sources:
+Sous remembers, per repository, which way worked, in `$SOUS_HOME/cache/read-strategies.json`, and tries it
+first next time; after a failure it forgets it and walks the whole list again. When every way fails, one
+error lists each attempt and why it failed, then names the fixes:
 
 ```text
-Sous could not fetch the repo index from https://raw.githubusercontent.com/acme/recipes/HEAD/sous.index.json.
-  The server answered 403 Forbidden.
-  The repository is private or the request was not authorized. Sous uses a token from the
-  environment, or from the provider's command line tool when one is installed and signed in.
+Error: could not read gitlab.com/acme/private-recipes.
+  HTTP with token      no token found (GITLAB_TOKEN unset; git has no stored credential for gitlab.com)
+  HTTP without token   302 to sign-in page: the repository is private
+  git                  Permission denied (publickey)
+Fix one of these:
+  export GITLAB_TOKEN=<a token with read_repository>
+  set up git access to gitlab.com (an SSH key, or a credential helper)
 ```
 
 **A recipe's files** come from git itself: a shallow, blobless, sparse clone at the version's
@@ -180,9 +191,8 @@ apply, exactly as they would for a manual clone: credential helpers, the SSH age
 `insteadOf` rewrites are all inherited from your git configuration, and sous adds nothing of its
 own. Cloning a working copy with `sous repo link` works the same way.
 
-?> For a private repository, make sure both halves work. `gh auth login` (or `GITHUB_TOKEN`)
-covers the index, and a git credential helper or an SSH key covers the recipe files. A build that
-finds the index but cannot clone has only the second half missing.
+?> For a private repository, git access (a credential helper or an SSH key) covers both the index
+and the recipe files. A token in the environment makes reading the index faster.
 
 ## Proposing a change
 
@@ -238,12 +248,12 @@ provider once, on the repository entry:
 }
 ```
 
-That block goes at the top level of your primary config or of a `conf.d/` layer of your own; sous
-writes its own entries to the `conf.d/500-repos.jsonc` layer it manages. Every key is listed under
+That block goes at the top level of your primary config or of a `conf.d/` file of your own; sous
+writes its own entries to the `conf.d/500-repos.jsonc` file it manages. Every key is listed under
 [configuration keys](repositories-file-formats.md#configuration-keys).
 
 Everything downstream then works normally: the index is read from that host's own raw endpoint,
-`GITLAB_TOKEN` or `glab` supplies the token, and the identity is
+a token comes from the sources above, and the identity is
 `git.example.com/platform/recipes`. Group paths of any depth are preserved, so
 `group/subgroup/project` stays one repository rather than being mistaken for a namespace.
 
@@ -296,32 +306,13 @@ one repository's resolution at a working copy without changing what your project
 
 ## Adding a provider
 
-Adding a provider is one file plus one line. The interface is internal for now, not a published
-plugin API, so it can still change shape; what follows is what a new provider writes today. A
-provider class extends `ProviderBase`, which carries the plumbing no provider should repeat:
-running a subprocess through the injectable runner, checking whether a tool exited cleanly,
-capturing its output, finding a host token, and refusing every write-path call by name until a
-subclass overrides it. Each member is documented where it lives, in
-`src/lib/repos/providers/base.ts`.
-
-The subclass supplies the rest:
-
-- `id`, the identifier a repository entry and a locator scheme use;
-- `features`, the ones it genuinely answers (`fetch`; `submit` only if all four write calls are
-  real; `proposals` only if `findProposal`, `proposalStatus` and `updateProposal` are);
-- `matches(url)` and `canonicalize(url)`, the URL half;
-- `fetchIndex(repo, options)` and `fetchRecipeTree(repo, recipePath, tag, destDir, options)`, the
-  read half;
-- `cli` and `proposalNoun` when it submits, so messages can name the tool and call a proposal
-  what the host calls it;
-- overrides of the four write-path calls when it submits, and of the three proposals calls when
-  it can follow a proposal up. Each answers with plain data (a proposal's id, address, state,
-  title, review and check counts), never with a host's own vocabulary.
-
-Every call takes an options object carrying the testing seams (`cwd`, `env`, `fetchImpl`, `run`),
-which is why no provider reaches for `spawn` or the global `fetch` directly and no test in this
-layer touches the network. The last change is adding the class to the built-in provider list in
-`providers/index.ts`; nothing above the provider layer learns its name.
+A provider is a sous plugin. It holds everything specific to its host: recognizing and taking apart the
+host's URLs, the ways it reads an index and where it finds a token, and, when it supports them, proposing
+changes and the CI workflow `sous repo init` writes. Nothing else in sous knows a host's name. A plugin can
+also add a way of reading to an existing provider, for example for a host with its own sign-in.
+
+?> The exact interface a provider plugin implements is not published yet; it is settled as sous 1.0
+lands. The plugin design is in [the engine specification](architecture/specifications/S1-engine.md).
 
 ## Where to go next
 

package/docs/markdown/repositories-quickstart.md

@@ -23,8 +23,9 @@ cd ~/projects/my-project
 echo 'name: my-project' > .sous/sous.config.yaml
 ```
 
-Everything else has a default: skills compile into `<project root>/.claude/skills`, and the
-lockfile, the state file and the config layers sous writes land under `.sous/`. Outside a
+Everything else has a default: skills compile into `<project root>/.claude/skills` (where the
+Claude Code plugin built into sous puts them), and the lockfile, the state file and the `conf.d`
+files sous writes land under `.sous/`. Outside a
 walkthrough, `sous init` writes a fuller starting point (a commented config, a starter prompt,
 the env files and the ignore block) and runs the first build for you; the one-line config is
 used here so that each step shows one thing. `SOUS_HOME` puts