@sous-io/sous 0.1.1 → 0.2.0

package/README.md

@@ -1,9 +1,20 @@
+<p align="center">
+  <a href="https://sous.io">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sous-io/sous/main/docs/img/logo-on-dark-sm.png">
+      <img src="https://raw.githubusercontent.com/sous-io/sous/main/docs/img/logo-on-white-sm.png" alt="Sous" height="180">
+    </picture>
+  </a>
+</p>
+
 # sous
 
 sous compiles AI coding agent configuration from templates. You write skills, memories, and
 instructions once as LiquidJS templates in layered sources, then sous renders them into the
 formats agents actually read: `.claude/` plus `CLAUDE.md` for Claude Code, `.codex/` plus
-`AGENTS.md` for Codex. The CLI binary is named `xcv`.
+`AGENTS.md` for Codex. The CLI binary is named `sous`.
+
+**New to sous? Watch the animated introduction at [sous.io](https://sous.io).**
 
 ## Why
 
@@ -31,7 +42,7 @@ npm link
 ```
 
 Then set up a project. A project needs a `.sous/` directory holding a config file, named
-`sous.config.js`, `sous.config.mjs`, or `sous.config.json`:
+`sous.config.js`, `sous.config.mjs`, `sous.config.json`, or `sous.config.yaml`:
 
 ```bash
 cd /path/to/your/project
@@ -43,32 +54,28 @@ A config that compiles one file:
 
 ```js
 export const config = {
-  projects: {
-    myproject: {
-      name: "My Project",
-      _vars: { projectRoot: "${sousDir}/.." },
-      compilation: {
-        targets: [
-          {
-            entryPoint: "${sousDir}/AGENTS.md",
-            outputs: [{ destinationFile: "${projectRoot}/CLAUDE.md" }],
-          },
-        ],
+  name: "My Project",
+  _vars: { projectRoot: "${sousDir}/.." },
+  compilation: {
+    targets: [
+      {
+        entryPoint: "${sousDir}/AGENTS.md",
+        outputs: [{ destinationFile: "${projectRoot}/CLAUDE.md" }],
       },
-    },
+    ],
   },
 };
 ```
 
 `${sousDir}` is the `.sous/` directory sous found, so a config can name paths relative to
-itself without hardcoding anything machine-specific. With a single project defined you do
-not need `defaultProject`; sous uses the only one. Then build:
+itself without hardcoding anything machine-specific. One config describes one project. Then
+build:
 
 ```bash
-xcv build
+sous build
 ```
 
-`xcv build` compiles every configured target and prunes outputs that are no longer in the
+`sous build` compiles every configured target and prunes outputs that are no longer in the
 config. Config discovery walks up from the current directory until it finds a `.sous/`
 directory holding a config, so you can run it from anywhere inside the project. Pass
 `--config <path>` to point at one explicitly instead.
@@ -81,19 +88,22 @@ anything resolves. There are two layers:
 - `.sous/.env.local` is gitignored. Put machine-specific values and secrets here.
 
 Precedence, highest first: your shell environment, then `.env.local`, then `.env`. So
-`FOO=bar xcv build` beats both files, and `.env.local` beats `.env` per key. This repo
+`FOO=bar sous build` beats both files, and `.env.local` beats `.env` per key. This repo
 ships `.sous/.env.local.example` documenting the layer.
 
 Useful commands:
 
 | Command | What it does |
 |---|---|
-| `xcv build` | Compile, then prune stale outputs |
-| `xcv build --watch` | Rebuild on source changes |
-| `xcv compile` | Compile only |
-| `xcv prune` | Remove outputs no longer in the config |
-| `xcv clear` | Delete every file sous wrote for the project |
-| `xcv launch claude` | Build, then start the agent |
+| `sous build` | Compile, then prune stale outputs |
+| `sous build --watch` | Rebuild on source changes |
+| `sous compile` | Compile only |
+| `sous prune` | Remove outputs no longer in the config |
+| `sous clear` | Delete every file sous wrote for the project |
+| `sous launch claude` | Build, then start the agent |
+| `sous config show` | Print the merged config (all layers) as JSON |
+| `sous config get <path>` | Read one value by dot-path; `--layers` shows which file set it |
+| `sous config validate` | Validate the merged config: schema, then variable resolution |
 
 ## How it works
 
@@ -119,28 +129,98 @@ each level can define variables:
 }
 ```
 
-Variables resolve later-wins across scopes: auto-injected, env, root, project, compilation,
+Variables resolve later-wins across scopes: auto-injected, env, config, compilation,
 target, output. Templates read them as `{{ varName }}`; config files reference them as `${varName}`.
 The auto-injected ones include `${sousDir}` and `${sousConfigPath}` for the discovered
 config, and `${sousTemplatePath}` for the template being rendered.
 
 Sources come in three tiers, each able to build on the one above it:
 
-1. **Built-in** shared prompts that ship with sous, covering skill authoring, templating, and
-   the sous conventions themselves.
-2. **Team-shared**, a repo your team owns, holding the configs everyone should get.
+1. **Published recipes**, fetched from a recipe repository and pinned in your project's
+   lockfile. The official repository publishes the `core` namespace, which teaches an agent
+   about sous itself and which every project gets without asking, plus recipes for skill
+   authoring, task tracking and more.
+2. **Team-shared**, a recipe repository your team owns, holding the recipes everyone should
+   get.
 3. **Per-project**, the project's own `.sous/` directory, for anything specific to it.
 
-The built-in tier is reachable without knowing where sous is installed. `@include` paths
-accept aliases, and two are always defined: `~sous-shared` for the shared prompts that ship
-with sous, and `~project` for the project root. So `@~sous-shared/_partials/sub-agent-delegation.md`
-composes a built-in block into your own instruction file, and an `entryGlob` can point at a
-built-in skill bundle to compile it into your project. Define your own aliases with an
-`_aliases` block to do the same for a team-shared repo.
+A recipe's files are reachable without knowing where anything is installed. An `@include`
+path may name a recipe by its namespace, so
+`@~workflow/task-files/_partials/resume-task.md` composes a block published by the recipe
+`workflow/task-files`, at the version your project has pinned, into your own instruction
+file. `@~project/...` names your project's root, and you can define your own aliases with
+an `_aliases` block.
 
 Sous records every file and directory it writes in a state file, `.sous/sous.state.json` by
 default, which is what lets `prune` and `clear` clean up precisely instead of guessing.
 
+## Composing config from layers
+
+One config can grow large, so sous lets you split it. Alongside the primary
+`sous.config.*`, any file matching `.sous/conf.d/*.{js,mjs,json,yaml}` is a layer. Sous loads
+the primary first, then the `conf.d/` files sorted bytewise-lexicographically (identical order
+on every machine), and merges them into one config: objects deep-merge key by key, scalars are
+later-wins, and arrays concatenate in load order. Every layer is forced back to plain JSON
+before merging, so functions, `RegExp`, `Date`, and `undefined` do not survive a layer.
+
+```
+.sous/
+  sous.config.js          # base config
+  conf.d/
+    100-tools.json        # adds or overrides tools
+    200-skills.yaml       # adds compilation targets
+```
+
+For anything JSON cannot express, a `.js`/`.mjs` layer may export a `configure` function
+instead of (or alongside) a `config` object. Sous calls it with the cumulative config so far
+and a small builder, and merges the result:
+
+```js
+export function configure(currentConfig, builder) {
+  // currentConfig is the live merged config; mutate it by reference, or return
+  // an object to merge. builder.env(name, fallback), builder.loadConfig(path),
+  // builder.loadConfigs(glob), and builder.merge(obj) are available.
+  currentConfig._vars.apiBase = builder.env("API_BASE", "https://example.com");
+}
+```
+
+`configure` may be async. Builder paths (`loadConfig`/`loadConfigs`) run before variable
+resolution, so they accept only the auto-vars `${sousDir}`, `${sousConfDir}`, `${sousRootPath}`,
+and `${sousVersion}`; any other `${var}` in a builder path is an error.
+
+## Locating the config
+
+By default sous walks up from the current directory to find the `.sous/` holding a config.
+You can point it elsewhere with an environment variable or a flag; every command accepts these:
+
+| Flag | Env var | What it overrides |
+|---|---|---|
+| `--config` / `-c` / `--sous-config` | `SOUS_CONFIG` | The exact primary config file |
+| `--sous-dir` | `SOUS_DIR` | The `.sous/` directory to use |
+| `--sous-confd` | `SOUS_CONFD` | The `conf.d/` directory (defaults to `<sousDir>/conf.d`) |
+
+Precedence, highest first: flag, then env var, then walk-up discovery. These location inputs
+are read from the real environment only, never from `.env` or `.env.local` (those files are
+found by discovery, so they cannot decide where discovery looks).
+
+## Validating and inspecting config
+
+`sous config validate` runs the full pipeline: it merges every layer, checks it against the
+schema, then resolves variables, reporting the first failure with a readable message.
+`sous config show` prints the merged config as JSON, and `sous config get <dot.path>` reads a
+single value; add `--layers` to see which layer file set it and to what.
+
+Config is validated against a JSON Schema on every load. A config may declare a `version`
+field; omit it or set it to `1`. JSON layers can point an editor at the shipped schema with a
+`"$schema"` key for autocompletion and inline validation:
+
+```json
+{
+  "$schema": "./sous.config.schema.json",
+  "version": 1
+}
+```
+
 ## Platform support
 
 - **Ubuntu** is where sous is developed and tested.

package/bin/run.js

@@ -14,4 +14,13 @@ const { execute, settings } = await import("@oclif/core");
 // the (unshipped) typescript devDependency is missing.
 settings.enableAutoTranspile = false;
 
-await execute({ development: true, dir: import.meta.url });
+// oclif's development mode turns on its debug setting, which makes every error
+// it prints a raw stack trace. Sous reports its own errors as sentences (see
+// src/utils/command-errors.ts), so development mode is switched on only when
+// SOUS_DEBUG asks for the traces; anything that gets past a command's own
+// reporting then prints its stack too.
+const debugRequested = !["", "0", "false", "no", "off"].includes(
+  (process.env.SOUS_DEBUG ?? "").trim().toLowerCase()
+);
+
+await execute({ development: debugRequested, dir: import.meta.url });

package/docs/markdown/README.md

@@ -0,0 +1,27 @@
+# Sous Documentation
+
+Sous is an agent configuration manager for LLM coding tools: it compiles markdown templates,
+aggregates configuration from many sources, and keeps the files your coding agents rely on
+current. The CLI is called `sous` and ships on npm as
+[`@sous-io/sous`](https://www.npmjs.com/package/@sous-io/sous). Earlier releases installed the
+same CLI under the name `xcv`; every command below is unchanged apart from that name.
+
+```term
+$ npm install -g @sous-io/sous
+>> 100%
+$ sous build
+building "My Project"...
+compiled 4 targets, pruned 1 stale file
+```
+
+?> These docs are young. **Configuration** and **Repositories** are the reference material so
+far; more will follow.
+
+## Where to look
+
+- Watch the [animated introduction](../) for the full pitch
+- Learn [how sous is configured](configuration.md)
+- Share configuration between projects with [repositories](repositories.md)
+- Look up a command in the [command reference](commands.md)
+- Read the [design principles](design-principles.md) that constrain every feature
+- Read the [source on GitHub](https://github.com/sous-io/sous)

package/docs/markdown/_sidebar.md

@@ -0,0 +1,18 @@
+- [Overview](/)
+- [Design principles](design-principles.md)
+- [Skill categories](skill-categories.md)
+- [Command reference](commands.md)
+- **Configuration**
+  - [The config file](configuration.md)
+  - [Discovery and overrides](config-discovery.md)
+  - [Layers and merging](config-layers.md)
+  - [Variables](config-variables.md)
+  - [Inspecting and validating](config-inspection.md)
+- **Repositories**
+  - [Overview](repositories.md)
+  - [Consuming recipes](repositories-consuming.md)
+  - [Recipe variables](repositories-variables.md)
+  - [Authoring a repository](repositories-authoring.md)
+  - [File formats](repositories-file-formats.md)
+- **ADRs**
+  - [0001: Repositories](adrs/0001-repositories.md)

package/docs/markdown/commands.md

@@ -0,0 +1,308 @@
+# Command Reference
+
+Every command the `sous` CLI ships, with its arguments and its own flags. Run any of them with
+`--help` for the same information in your terminal.
+
+## The flags every project command shares
+
+These four locate the configuration and are accepted by every command that works on a project.
+They are listed once here rather than repeated in every table below.
+
+| Flag | What it does |
+|------|--------------|
+| `-c, --config <path>` | Path to a sous config file, or to a directory holding one. Overrides `.sous/` discovery |
+| `--sous-config <path>` | Alias of `--config` |
+| `--sous-dir <path>` | Path to the `.sous` directory to use, overriding walk-up discovery |
+| `--sous-confd <path>` | Path to the `conf.d/` drop-in layer directory, overriding `<sousDir>/conf.d` |
+
+The environment variables `SOUS_CONFIG`, `SOUS_DIR` and `SOUS_CONFD` do the same jobs; a flag
+beats the matching variable, and both beat walk-up discovery.
+[Discovery and overrides](config-discovery.md) covers the precedence in full. One more variable,
+`SOUS_DEBUG`, is read by every command: it turns stack traces back on when something fails
+(see [Exit behavior](#exit-behavior)).
+
+?> Three commands take none of these, because they run inside a recipe repository rather than
+inside a project: `sous repo init`, `sous repo release` and `sous repo submit`. A recipe
+repository has no `.sous/` directory to discover. All three do take `--non-interactive`:
+`repo init` and `repo submit` accept it without ever having a question to suppress, and
+`repo release` reads the flag, the terminal and the `CI` environment variable to decide whether
+it may ask, with `--ci` or `--yes` settling it outright.
+
+## Flags common to many commands
+
+A few flags mean the same thing wherever they appear, so the tables below name them without
+explaining them again.
+
+| Flag | What it does |
+|------|--------------|
+| `-y, --yes` | Answers yes to every confirmation the command would ask. `--force` and `-f` are the same flag; so is `--trust` on the commands that trust a repository |
+| `--non-interactive` | The opposite instruction: never ask anything. A run that would have prompted fails instead, naming the question and the flag that would have answered it |
+| `--dry-run` | Prints what the command would do and writes, downloads and asks nothing |
+| `-h, --help` | Prints the command's own help and exits |
+
+`sous clear` is the one command whose primary spelling is `--force` rather than `--yes`, because
+that is the spelling it has always had; `-y` and `--yes` are aliases of it there and behave
+identically. `sous repo init --force` is a different flag with a different meaning (overwrite an
+existing repository), and it is not a confirmation.
+
+Help is available in four forms, all of which draw the same screen:
+
+```bash
+sous --help
+sous repo add --help
+sous repo add -h
+sous help repo add
+```
+
+`sous help` on its own lists the topics and commands, and `sous help <topic>` lists one topic's
+commands.
+
+## Singular and plural
+
+Every topic answers to both spellings of its name, so nothing hinges on remembering which one
+sous prefers: `repo` and `repos`, `subscription` and `subscriptions`, `namespace` and
+`namespaces`, `recipe` and `recipes`, `lock` and `locks`, `var` and `vars`, `config`
+and `configs`. The tables below print the spelling `sous --help` shows; the other one runs
+exactly the same command.
+
+## Building
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous build` | none | `--no-prune`, `--no-compile`, `--rebuild`, `--dry-run`, `--strict`, `-w, --watch` |
+| `sous compile` | none | `--strict`, `--rebuild`, `--dry-run`, `-w, --watch` |
+| `sous prune` | none | `--dry-run` |
+| `sous clear` | none | `-f, --force` (also `-y, --yes`) |
+| `sous launch` | `TOOL...` | `--no-build`, `--continuous` |
+
+`build` is compile plus prune, and is the command you want almost always. `--rebuild` ignores
+cached hashes and reprocesses every output; `--strict` fails on the first compilation error
+rather than reporting and continuing; `--watch` rebuilds on every change to a source file, a
+config layer, or a linked recipe checkout.
+
+`clear` deletes every file and directory sous has written for the project, and asks first unless
+you pass `--force` (or `-y`, or `--yes`). Neither `prune` nor `clear` ever reaches into a linked checkout or the
+machine-wide recipe store.
+
+`launch` builds and then spawns a coding agent configured under `tools` in your config. Any
+argument it does not recognize is forwarded to the tool. A flag that collides with one of sous's
+own goes after a bare `--`, which forwards everything following it verbatim:
+
+```bash
+sous launch claude --resume
+sous launch claude -- -c
+```
+
+## Inspecting the configuration
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous config show` | none | none |
+| `sous config get` | `PATH` | `--layers` |
+| `sous config validate` | none | none |
+
+`show` and `get` write machine-readable output to standard output, with the decorative header and
+any error block routed to standard error, so `sous config show | jq` works even when the config is
+broken. `PATH` is a dot-path with `[n]` for array indices, such as
+`compilation.targets[0].entryPoint`, and `--layers` prints one `old -> new` line per config layer
+that changed the value. `validate` runs the resolvers that schema validation alone cannot,
+surfacing reference cycles and undefined `${var}` references.
+
+See [Inspecting and validating](config-inspection.md).
+
+## Repositories
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous repo add` | `URL` | `--name <name>`, `--provider github\|gitlab\|local`, `-y, --yes` (also `--trust`), `--dry-run` |
+| `sous repo remove` | `REPO` | `-y, --yes` (also `-f, --force`), `--dry-run`, `--no-build` |
+| `sous repo list` | none | `--verbose` |
+| `sous repo search` | `TEXT` | `--limit <n>` (default 25) |
+| `sous repo gc` | none | `--max-bytes <n>`, `--dry-run` |
+| `sous repo link` | `REPO` (a short name, a URL or a path) `[PATH]` | `--global`, `-y, --yes` (also `--trust`), `--dry-run` |
+| `sous repo unlink` | `REPO` | `--global`, `--dry-run` |
+
+`repo add` is the trust ceremony; it asks inline, and the confirmation flag is how a run with no
+terminal acknowledges instead. `--trust` is the spelling the ceremony reads best with, and it is
+the same flag as `-y`, `--yes`, `-f` and `--force`. `URL` may be an address or an absolute path to a repository on this
+machine. `list` and `search` read only what is already cached, so both work offline and neither
+downloads anything.
+
+`repo remove` is the reverse of `repo add`: it stops trusting a repository. Before it writes
+anything it prints what goes with it, so the decision is made on facts: the entry itself, every
+subscription that resolves into the repository, every locked recipe those subscriptions alone held,
+the output files the next build prunes, and the linked checkout, if one points at it. Then it asks
+once, and the confirmation flag answers ahead of time. The link entry is removed with the
+repository; the checkout itself stays on disk. The command finishes by building the project, the
+same way the subscription commands do, so the files those recipes wrote are gone when it returns;
+`--no-build` leaves the outputs alone. Removing the built-in `sous-recipes` repository records
+`sous-recipes: { enabled: false }` in the managed repositories layer rather than deleting an entry,
+because the entry sous provides comes back on every run.
+
+`repo search` is also a top-level `sous search`, because searching is how you find something to
+subscribe to before you know what any of it is called.
+
+## Browsing what a project trusts
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous namespace list` | none | none |
+| `sous namespace show` | `REF` (a namespace, optionally `repo:namespace`) | none |
+| `sous recipe list` | none | none |
+| `sous recipe show` | `REF` (a recipe, a recipe name on its own, or either with a `repo:` qualifier) | none |
+
+All four read the cached repository indexes and the lockfile, so they work offline and download
+nothing. A trusted repository whose index has never been fetched is named at the end of a listing
+rather than left out of it.
+
+`namespace list` shows every namespace, how many recipes it holds, and how much of it this project
+subscribes to: the whole namespace, some recipes, or none. `namespace show` adds every recipe in
+one namespace, with the latest published version, the version this project pins, and whether it is
+subscribed.
+
+`recipe list` shows the same per-recipe columns across every namespace. `recipe show` describes one
+recipe completely: the repository and its location, every published version labeled as the latest
+one, the pinned one or an earlier one, what the version depends on (both as the recipe's manifest
+declares it and as its repository's index resolved it at release time), the questions it asks with
+the environment variable each answer is stored under, and the directories its files are written
+into. The questions and the file list come from the recipe's own manifest, so a recipe this machine
+does not hold yet is described from its index alone and says so.
+
+## The lockfile
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous lock show` | none | none |
+| `sous lock rebuild` | none | `--dry-run` |
+
+`lock show` prints what `.sous/sous.lock.json` pins: the recipe, the version, the repository it came
+from, and who holds it (this project, or the recipes that require it).
+
+`lock rebuild` recomputes the whole file from the subscriptions the config declares and the cached
+indexes, then writes it. It starts from an empty lockfile, so an entry nothing holds any more is
+dropped rather than carried through; that makes it the repair for a file that has drifted from the
+config through a hand edit or a bad merge. It asks nothing and grants no trust: a subscription whose
+closure reaches a repository this project has not added fails, naming the repository. It downloads
+nothing, so a recipe whose files are not on this machine has its own dependencies left out, and is
+named when that happens. `--dry-run` prints the same summary and writes nothing.
+
+## Subscriptions
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous subscription list` | none | none |
+| `sous subscription add` | `REF` | `--prerelease`, `--always-pull`, `-y, --yes` (also `--trust`), `--accept-first`, `--answer <name>=<value>`, `--answers-file <path>`, `--dry-run`, `--no-build` |
+| `sous subscription remove` | `REF` | `--dry-run`, `--no-build` |
+
+`sous subscribe` and `sous unsubscribe` are the original spellings of `subscription add` and
+`subscription remove`, and both still work.
+
+Adding or removing a subscription changes what the project compiles, so both commands finish by
+building it: the same compile and prune `sous build` runs, so a newly subscribed recipe's files
+are on disk when the command returns and a removed one's files are gone. `--no-build` changes the
+subscription and leaves the outputs alone. A build that fails leaves the subscription change in
+place, since it is already written and locked, and says so.
+
+`REF` is a ref: `namespace`, `namespace/recipe`, either with an `@<range>`, and optionally
+qualified with `repo:`. See
+[Refs: how anything is named](repositories-file-formats.md#refs-how-anything-is-named).
+
+`subscription add --dry-run` installs nothing and, after the plan, prints every question the
+recipes would ask: what each variable is for, where its answer would be stored, and whether
+anything answers it already. `--answer <name>=<value>`, repeated, answers those questions ahead of
+time, and `--answers-file <path>` reads the same pairs from a YAML or JSON file; together they are
+how a run with no terminal subscribes to a recipe that asks questions. See
+[Answering questions ahead of time](repositories-consuming.md#answering-questions-ahead-of-time).
+
+`subscription list` reads the config and the lockfile only, so it works offline. It reports every
+subscription the project declares, switched-off ones included, with the range it resolves within,
+the versions the lockfile pins for it, where it came from, and whether it is on.
+
+Removing the `core` subscription sous provides itself records `core: { enabled: false }` in the
+managed subscriptions layer rather than deleting an entry, because the default would otherwise
+come back on the next run. Adding it back clears the opt-out. Either way the `sous-recipes`
+repository stays trusted and keeps appearing in `repo list` as built in.
+
+`repo link` is written three ways. `REPO` on its own, as the short name of a repository this
+project has already added, clones it into `.sous/repos/<owner>/<name>`, or into
+`$SOUS_HOME/repos/<owner>/<name>` with `--global`. `REPO` followed by a `PATH` links the checkout
+at that path to that repository and clones nothing. A path in the `REPO` slot, on its own, links
+the checkout already at that path where it is, under the short name its repo manifest suggests.
+Naming a repository this project has not added, by URL or by path, runs the same trust ceremony
+`repo add` runs, since a linked repository's recipes are read with no version, lockfile or hash
+check; it asks inline, and `--trust` (or any other spelling of the confirmation flag)
+acknowledges instead for a run with no terminal.
+
+## Authoring a repository
+
+These three run inside a recipe repository and take none of the config-locating flags.
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous repo init` | `[DIRECTORY]` | `--name <name>`, `--namespace <name>`, `--force`, `--dry-run` |
+| `sous repo release` | none | `--namespace <ns>`, `--recipe <ns/name>`, `--bump patch\|minor\|major\|prerelease`, `--no-bump`, `--include-unchanged`, `--tag`, `--push`, `--yes`, `--check`, `--ci`, `--dry-run` |
+| `sous repo submit` | none | `--title <text>`, `--body <text>`, `--draft`, `--dry-run` |
+
+`sous repo release` plans first, asks once, and then bumps, regenerates the index, commits and
+tags in one run. `--namespace` and `--recipe` are repeatable and narrow the run; `--check` reads
+only and cannot be combined with `--bump`, `--tag` or `--push`; `--ci` is the merge preset and
+implies `--no-bump`. See [Authoring a repository](repositories-authoring.md).
+
+## Variables
+
+| Command | Arguments | Own flags |
+|---------|-----------|-----------|
+| `sous vars list` | none | `--file <path>` |
+| `sous vars show` | `NAME` | `--file <path>` |
+| `sous vars ask` | `[NAME]` | `--repo <name>`, `--namespace <name>`, `--var <name>`, `--accept-first`, `--all`, `--file <path>`, `--answer <name>=<value>`, `--answers-file <path>`, `--dry-run` |
+
+`vars list` prints every variable in play, with the environment variable that answered each one
+and where the value came from. `vars show` prints one variable in full, including every
+environment variable on the resolution ladder and which rung answered. `NAME` is a bare variable
+name or a full `namespace/recipe.name` key.
+
+On `vars ask`, `NAME` is a reference like any other: a variable, an environment variable that
+answers one, a recipe, a namespace or a repository, at any level of qualification, and anything
+larger than a variable asks every question it publishes. `--repo`, `--namespace` and `--var`
+(repeatable) narrow the same way, and `--accept-first` takes the first candidate when the name
+means more than one thing. `--file` reads definitions from a standalone
+definitions file instead of the project's subscribed recipes. `--answer` and `--answers-file`
+answer questions ahead of time, exactly as they do on `subscription add`.
+
+Bare `sous vars` is shorthand for `vars list`, and `sous vars <name>` for `vars show <name>`. A
+variable whose name is also a subcommand name (`list`, `show` or `ask`) has to be reached the
+long way, as `sous vars show list`.
+
+See [Recipe variables](repositories-variables.md).
+
+## Tables and terminal width
+
+Every listing sous prints fits itself to the terminal it is running in. Columns shrink toward
+their minimums, a long description wraps onto more lines, and a path or a URL is cut in the
+middle so the host and the last segment both survive. On a terminal too narrow to hold
+everything, the columns that matter least step aside, and one line under the table names them:
+`Hidden at this width: URL. Widen the terminal to see it.` Nothing is hidden when the output is
+not a terminal (a pipe, a file, a CI log), which is laid out at a fixed width instead, so a
+recorded run always shows every column.
+
+`sous repo list --verbose` adds the namespaces each repository publishes, on a dim line under
+that repository's row.
+
+## Exit behavior
+
+Every command exits non-zero on a configuration problem and prints a plain-language error block
+naming the file at fault. There is no warn-and-continue: a broken config halts sous rather than
+producing output built on a guess.
+
+What a failure prints is the message and nothing else. Forget an argument, misspell a flag, or
+pass a value a flag does not accept, and sous prints the sentence describing the mistake and
+then that command's own help, so the flag you wanted is on the screen already. No expected
+failure prints a stack trace.
+
+Set the `SOUS_DEBUG` environment variable to anything but `0`, `false`, `no` or `off` and every
+failure prints its stack trace to standard error underneath the message. It is there for
+debugging sous itself; nothing else changes when it is set.
+
+```bash
+SOUS_DEBUG=1 sous build
+```

package/docs/markdown/config-discovery.md

@@ -0,0 +1,74 @@
+# Discovery and Overrides
+
+How sous locates a project's configuration, and every way to override it. Discovery runs on
+every command; there is no opt-out.
+
+## Locating the primary config
+
+Precedence, highest first. Flags beat env vars; both beat walk-up discovery:
+
+1. `--config <path>` (`-c`), or its verbose alias `--sous-config <path>`
+2. `SOUS_CONFIG` environment variable
+3. `--sous-dir <path>` flag
+4. `SOUS_DIR` environment variable
+5. Walk UP from the working directory to the filesystem root, taking the first `.sous/`
+   directory that holds a primary config. A `.sous/` without one does not stop the walk.
+
+A primary config is named `sous.config.js`, `sous.config.mjs`, `sous.config.json`,
+`sous.config.jsonc` or `sous.config.yaml`. The `.jsonc` form is JSON with comments: line comments,
+block comments and trailing commas are all allowed in it.
+
+Every flag or env value resolves with the same rules. It may point at:
+
+- a config file directly,
+- a directory holding one of the primary config names, or
+- a directory whose `.sous/` child holds one (so `--config .` works from a project root).
+
+A leading `~` expands to your home directory. An empty or whitespace-only value (for example a
+bare `export SOUS_CONFIG=`) is treated as unset and falls through to the next tier; it never
+hijacks resolution. Error messages name the source that was actually set (`--sous-dir`,
+`SOUS_CONFIG`, and so on), not a generic flag.
+
+## Locating the conf.d layer directory
+
+Precedence: `--sous-confd <path>` flag, then `SOUS_CONFD` env var, then the default
+`<sousDir>/conf.d`. An override flows everywhere the default would: layer enumeration, the
+duplicate-baseName check, and watch-mode reload.
+
+## Env file layering
+
+After discovery, sous loads two optional files from the discovered `.sous/` into the process
+environment:
+
+- `.env.local`: gitignored; machine-specific values and secrets
+- `.env`: committed; team-shared defaults
+
+Load order is `.env.local` first, then `.env`, and no load ever overwrites a value that is
+already set. Effective precedence is therefore: real shell environment, then `.env.local`, then
+`.env`. The syntax is deliberately small (not a shell): `KEY=value` lines, `#` comments, an
+optional `export ` prefix, single or double quoted values (`\n` and `\t` expand inside double
+quotes), and inline `# comment` stripped from unquoted values. Lines without `=` are ignored.
+
+!> The location vars (`SOUS_CONFIG`, `SOUS_DIR`, `SOUS_CONFD`) are read from the real shell
+environment only, never from the env files. Finding `.env.local` requires knowing `sousDir`
+first, so setting a location var inside `.env.local` has no effect on discovery.
+
+## Discovery errors
+
+All are hard `ConfigError`s; sous never guesses:
+
+- **No config found**: the error lists every directory checked during the walk and shows a
+  minimal starter config.
+- **Multiple primary configs**: two or more of `sous.config.js|mjs|json|jsonc|yaml` in the same
+  `.sous/` is an error naming every candidate.
+- **Duplicate layer baseNames**: any two loaded files (primary or conf.d) whose names differ
+  only by extension is an error naming both files, because their merge order would otherwise
+  depend on extension. `500-repos.json` and `500-repos.jsonc` collide for the same reason, which
+  is what keeps a layer sous is migrating to `.jsonc` from being loaded twice.
+
+## Interaction with `sous launch` pass-through
+
+`sous launch` forwards unrecognized arguments to the launched tool. The `--sous-config`,
+`--sous-dir` and `--sous-confd` flags are declared on every command, so launch consumes them
+rather than forwarding. To pass a literally-named flag through to the tool, put it after a bare
+`--`, which forwards everything following it verbatim.