@sous-io/sous 0.2.1 → 0.2.3

package/docs/markdown/repositories-providers.md

@@ -0,0 +1,322 @@
+# Providers
+
+A **provider** is everything sous knows about one kind of repository host. It is the only place
+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.
+
+## What a provider answers
+
+Every provider answers the **read path**, which is deliberately small:
+
+- recognize a repository URL as its own;
+- take that URL apart into a host, an owner and a name;
+- hand back the repository's `sous.index.json`;
+- fetch **one** recipe's subtree at one tag.
+
+Nothing there clones a whole repository. A provider that can also carry a contribution answers
+the **write path**: report whether its command line tool is installed and signed in, say whether
+you may push to the repository itself, fork it onto your account, and open the proposal.
+
+Each provider declares which of the two features, `fetch` and `submit`, it genuinely answers, and
+sous consults that declaration rather than a provider's name. Asking for something outside a
+provider's features is refused with a sentence naming it and what it cannot do, never a crash.
+
+## How a URL is matched
+
+When you name a repository, sous tries each provider in turn (`github`, then `gitlab`, then
+`local`) and the first one that recognizes the URL handles it.
+
+| Provider | Recognizes |
+|---|---|
+| `github` | any URL whose host is `github.com` |
+| `gitlab` | any URL whose host is `gitlab.com`, or whose host begins with `gitlab.` |
+| `local` | an absolute filesystem path, or the same path in `file:///...` form |
+
+Three spellings of a hosted URL are all understood, because all three are what people paste:
+
+```text
+https://github.com/sous-io/sous-recipes
+git@github.com:sous-io/sous-recipes.git
+ssh://git@github.com/sous-io/sous-recipes
+```
+
+A trailing slash and a trailing `.git` are dropped before anything else happens, and the scheme
+and the host are lowercased. Everything between the host and the last segment is the owner, so
+a GitLab group path of any depth (`group/subgroup/project`) is carried whole.
+
+`local` is tried last and matches only a path, so it can never intercept a hosted URL. A path
+you type relative (`../my-recipes`, `~/recipes`, `.`) is expanded and resolved against your
+working directory before any provider sees it, and the absolute form is what gets stored; a
+repository on this machine is machine-specific either way. In a config file that same relative path
+is refused outright, because an entry is read from a file that several working directories may run
+against; see
+[A local repository named by a relative path](repositories-troubleshooting.md#a-local-repository-named-by-a-relative-path).
+
+### Naming a provider explicitly
+
+`sous repo add --provider <id>` (and the `provider:` key on a repository entry) names the
+provider outright. That is what a self-hosted instance behind an unfamiliar host name needs:
+
+```bash
+sous repo add https://git.example.com/team/recipes --provider gitlab
+```
+
+A named provider is honored for any host nobody recognizes. It is refused only when a
+**different** provider plainly owns the URL, because that is a contradiction rather than a hint:
+
+```text
+Error: The gitlab provider does not handle https://github.com/sous-io/sous-recipes; that is a
+  github URL, which the github provider handles.
+  Drop '--provider' and let sous work it out, or name 'github'.
+```
+
+With no provider named and nothing recognizing the host, sous says so and points at the flag:
+
+```text
+Error: Sous does not recognize the host in the repository URL
+  https://git.example.com/team/recipes.
+  Sous ships these providers: github, gitlab, local. For a self-hosted instance, name the
+    provider that host runs on the repository entry, as in 'sous repo add
+    https://git.example.com/team/recipes --provider <provider>'.
+```
+
+`sous repo list` shows which provider each trusted repository resolved to:
+
+```text
+Repository    Provider  Origin    Linked      Recipes  URL
+------------  --------  --------  ------  -----------  ---------------------------------------
+qa-recipes    local     user      no                0  /home/me/Projects/qa-recipes
+sous-recipes  github    built in  no      not fetched  https://github.com/sous-io/sous-recipes
+```
+
+## Repository identity
+
+Canonicalizing a URL produces the repository's **identity**, `<host>/<owner path>/<name>`,
+lowercased and with any `.git` suffix gone:
+
+```text
+github.com/sous-io/sous-recipes
+gitlab.example.com/group/subgroup/project
+localhost/home/me/projects/my-recipes
+```
+
+A local repository's identity uses the host `localhost` and the directory's parent path as its
+owner, so a path on disk keys exactly the way a hosted repository does. Identity is then what
+every machine-wide thing keys by:
+
+| Keyed by identity | Looks like |
+|---|---|
+| the store entry | `~/.sous/cache/github.com/sous-io/sous-recipes/<namespace>/<recipe>/<version>/` |
+| the cached index | `~/.sous/cache/_indexes/github.com/sous-io/sous-recipes.json` |
+| the index sidecar | `~/.sous/cache/_indexes/github.com/sous-io/sous-recipes.meta.json` |
+| the lockfile's `identity` field | `github.com/sous-io/sous-recipes` |
+
+A repository's **short name** (`sous-recipes`) is something your project chose, and it keys
+nothing shared: two projects may call one repository different things, and two may use one name
+for different repositories. Keying by identity is what lets them share one cached copy without
+colliding. See [The store on disk](repositories-file-formats.md#the-store-on-disk).
+
+Canonicalizing also produces the two clone URLs sous hands to git, `https://<host>/<owner>/<name>.git`
+and `git@<host>:<owner>/<name>.git`. For the `local` provider the HTTPS slot carries the
+absolute directory, because that is what git is given when a recipe is fetched.
+
+?> A published manifest names a dependency in another repository by a locator URL 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. `local://`
+is refused, because a path on your disk is not a published location. The grammar is in
+[Dependencies named by location](repositories-file-formats.md#dependencies-named-by-location).
+
+## Private repositories
+
+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:
+
+```text
+https://raw.githubusercontent.com/<owner>/<name>/HEAD/sous.index.json
+https://<gitlab host>/<owner>/<name>/-/raw/HEAD/sous.index.json
+```
+
+A token is looked for in two places, in this order:
+
+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.
+
+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:
+
+```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:
+
+```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.
+```
+
+**A recipe's files** come from git itself: a shallow, blobless, sparse clone at the version's
+tag, fetching only the blobs inside that one recipe folder. That means git's own credentials
+apply, exactly as they would for a manual clone: credential helpers, the SSH agent, proxies and
+`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.
+
+## Proposing a change
+
+[`sous repo submit`](repositories-authoring.md#contribute-to-someone-elses-repository) validates
+your repository, then hands the host-specific mechanics to the provider that owns its `origin`
+remote. Providers differ, and sous says so rather than pretending otherwise:
+
+| Provider | Tool | Push permission | Forking | Proposal |
+|---|---|---|---|---|
+| `github` | `gh` | read from GitHub, so a contributor without it is forked automatically | `gh repo fork`, with a `fork` remote added for you | pull request |
+| `gitlab` | `glab` | sous cannot tell, so it pushes to `origin` and says so | not done for you | merge request |
+| `local` | none | not applicable | not applicable | not applicable |
+
+**GitLab reports "cannot tell" rather than guessing.** Sous has no cheap, reliable way to ask
+whether you may push, and a wrong guess would send you down a fork path this provider cannot
+finish. So the submission announces that it could not tell and pushes to `origin` as it stands. If
+that push is refused, the command stops at the push step and reports git's own error alongside
+everything it had already done; forking the project and pushing there is then a manual route.
+
+**A local repository never submits.** It declares `fetch` only, so `sous repo submit` stops before
+anything is written and prints the repository's own contribution route instead:
+
+```text
+Error: The 'local' provider cannot propose a change on your behalf.
+  This repository asks that changes be sent this way:
+    https://github.com/sous-io/sous-recipes/blob/main/CONTRIBUTING.md
+```
+
+That second line is the `contribute` field from the repository's `sous.repo.yaml`; sous prints it
+whenever a provider cannot carry the proposal, so a contributor is never left without a route. A
+manifest that sets none gets "This repository's manifest does not say where to send a change, so
+send it the way its maintainers prefer." Set the field in your own repository for the same reason;
+see [the repository manifest](repositories-file-formats.md#sousrepoyaml-the-repository-manifest).
+
+## Self-hosted GitLab
+
+A self-hosted instance needs no special configuration beyond being recognized. A host that
+begins with `gitlab.` is matched automatically; any other host name is matched by naming the
+provider once, on the repository entry:
+
+```jsonc
+{
+  "repos": {
+    "team-recipes": {
+      "url": "https://git.example.com/platform/recipes",
+      "provider": "gitlab"
+    }
+  }
+}
+```
+
+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
+[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
+`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.
+
+`sous repo submit` is the exception: it runs inside the repository checkout and never reads a
+project's config, so it picks the provider from the `origin` remote URL alone. A host that does not
+begin with `gitlab.` goes unrecognized there, and sous prints the repository's `contribute` pointer.
+
+## The local provider
+
+A repository on this machine is an ordinary directory holding a `sous.repo.yaml`, read through
+the `local` provider:
+
+```term
+$ sous repo add ../my-recipes --name my-recipes --trust
+// sous resolves the path, reads the index and records the absolute form
+▶ Adding a repository:
+    Repository: my-recipes
+    Location  : /home/me/Projects/my-recipes
+    Provider  : local
+// the namespace and recipe rows are left out here
+```
+
+It exists 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. Two details make it behave
+like a host rather than like a shortcut.
+
+- The index is read from the **working tree** when `sous.index.json` is there, so an index you are
+  still writing is picked up without a commit, and from `git show HEAD:sous.index.json` otherwise.
+- A recipe's files come from a clone of the local repository at the version's **tag**, exactly as
+  a hosted repository would be fetched, so a version really is the version its tag points at. A
+  directory that is not a git repository, or one missing that tag, has no versions to honor, so
+  its working tree is copied instead.
+
+!> A local path is added, and therefore trusted, through the same ceremony as a hosted
+repository, because its recipes still run on this machine. See [Trust](repositories.md#trust).
+
+A path that is not a repository is explained as a path mistake rather than as a provider
+failure, naming what you typed, what sous resolved it to, and what it expected to find:
+
+```text
+Error: There is no directory at './nope'.
+  Sous read that as the path /home/me/Projects/my-project/nope, and nothing is there.
+  A repository on this machine is a directory holding a 'sous.repo.yaml' file at its root.
+  Check the path, or create one with 'sous repo init'.
+```
+
+For editing a repository you already subscribe to, reach for
+[`sous repo link`](repositories-authoring.md#edit-a-repository-in-place) instead; it redirects
+one repository's resolution at a working copy without changing what your project subscribes to.
+
+## 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`, and `submit` only if all four write calls
+  are real);
+- `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.
+
+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.
+
+## Where to go next
+
+- [Repositories](repositories.md): the model, trust, and the lockfile
+- [Consuming recipes](repositories-consuming.md): adding, subscribing and building
+- [Authoring a repository](repositories-authoring.md): releasing and contributing
+- [Repository file formats](repositories-file-formats.md): every manifest, index and lockfile
+  schema
+- [Troubleshooting](repositories-troubleshooting.md): what the errors mean and how to clear them
+- [Command reference](commands.md): every command and flag

package/docs/markdown/repositories-quickstart.md

@@ -0,0 +1,340 @@
+# Repositories Quickstart
+
+Twelve steps take you from an empty directory to a project whose agent skills come from the
+official repository and from a repository you wrote yourself, with a lockfile a colleague can
+restore from. Budget about ten minutes.
+
+This page is the guided tour; [Repositories](repositories.md) explains the model behind it, and
+[Consuming recipes](repositories-consuming.md) and
+[Authoring a repository](repositories-authoring.md) are the reference guides for each half. You
+need sous on your path (`npm install -g @sous-io/sous`), git, and a network connection for the two
+steps that reach GitHub. Output below is trimmed: sous prints absolute paths and a banner that are
+left out here, and a line reading `...` marks rows removed for length.
+
+## 1. Create a project
+
+A sous project is a directory with a `.sous/` directory in it holding one config file. One line is
+a valid config:
+
+```bash
+export SOUS_HOME=~/tmp/sous-quickstart
+mkdir -p ~/projects/my-project/.sous
+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/`. `SOUS_HOME` puts
+the machine-wide store somewhere throwaway, so this walkthrough leaves your real one alone. See
+[The config file](configuration.md) for the keys you will want later.
+
+## 2. Build once
+
+```term
+$ sous build
+▶ Locking subscribed recipes:
+    pinned: core/sous-skills at version 0.2.0.
+  The lockfile has been updated. Commit it, so everyone building this project
+    gets exactly these versions.
+▶ Building:
+  ✓ .claude/skills/about-sous/SKILL.md (~782 tokens)
+  ✓ .claude/skills/about-sous-configuration/SKILL.md (~1,204 tokens)
+  ✓ .claude/skills/about-agent-skills/SKILL.md (~1,937 tokens)
+  ✓ .claude/skills/about-liquid-templates/SKILL.md (~1,486 tokens)
+  ✓ .claude/skills/create-skill/SKILL.md (~655 tokens)
+✓ Done.
+```
+
+You subscribed to nothing and five skills appeared. That is the `core` namespace, which every
+project is auto-subscribed to at the version matching the CLI you are running. It carries the
+skills that teach an agent what sous manages and why it must not hand-edit a generated file.
+
+?> `core` ships inside the sous package and seeds the machine-wide store on first run, so this
+step works with no network at all. It is an ordinary subscription and
+[one line switches it off](repositories-consuming.md#opt-out-of-core).
+
+## 3. See what is on offer
+
+```bash
+sous recipe list
+```
+
+```text
+  Recipe                      Repository    Latest  Pinned  Subscribed  What it is
+  --------------------------  ------------  ------  ------  ----------  ------------------------------
+  communication/control-flow  sous-recipes  1.0.0           no          Generic interaction skills
+  core/sous-skills            sous-recipes  0.2.0   0.2.0   yes         What sous is, and how it works
+  workflow/task-files         sous-recipes  1.0.2           no          Per-branch task files
+  ...
+```
+
+This reads the cached index of every repository the project trusts, so it works offline and
+downloads nothing. The official repository, `sous-recipes`, is trusted out of the box.
+
+Before subscribing to something, read it:
+
+```bash
+sous recipe show workflow/task-files
+```
+
+```text
+    Repository     : sous-recipes
+    Latest version : 1.0.2
+    Subscribed     : no
+  ...
+  The recipe's own files are not on this machine, so the questions it asks and
+    the files it publishes are not known here. Subscribing to it fetches them.
+```
+
+On a machine that has never fetched the recipe, sous shows what the index knows: every published
+version, and every dependency with each declared range beside the exact version the index resolved
+it to. The questions it asks are not known until it is fetched; run the same command after
+subscribing and it adds a table of the variables the recipe publishes.
+
+## 4. Subscribe to a recipe
+
+```bash
+sous subscription add workflow/task-files
+```
+
+Sous states what subscribing does, asks once, resolves the whole dependency closure, downloads it,
+then asks the questions the recipe publishes. Answering the confirmation and the two questions:
+
+```text
+➔ What was installed:
+  Recipe                         Version  Repository    Why
+  -----------------------------  -------  ------------  --------------------------
+  workflow/sub-agent-delegation  1.0.0    sous-recipes  needed by workflow/task-files
+  workflow/task-files            1.0.2    sous-recipes  you subscribed to it
+
+➔ Variables:
+  Answers stored:
+      taskFileRoot       : .sous/tasks TASK_FILE_ROOT in .env
+      ticketIdExample    : PROJ-1234 TICKET_ID_EXAMPLE in .env
+
+  Left unanswered:
+      ticketPrefix       : no answer yet, and this variable is optional
+```
+
+A script, a pipeline or a coding agent has no terminal to answer on, so it passes the answers in:
+
+```bash
+sous subscription add workflow/task-files --yes \
+  --answer taskFileRoot=.sous/tasks \
+  --answer ticketIdExample=PROJ-1234
+```
+
+The answers land in `.sous/.env`, which is committed; a definition marked secret goes to the
+gitignored `.sous/.env.local`. [Recipe variables](repositories-variables.md) covers the rest.
+
+## 5. Look at what landed
+
+`sous subscription add` finishes by building, so the files are already on disk. `ls .claude/skills`
+now lists the five `core` skills plus the seven this recipe ships, among them `about-task-files`,
+`start-task` and `resume-task`. The build dependency contributes nothing: a recipe held through
+`depends` is fetched and pinned, and its files stay out of your output.
+
+Recipe files compile the way your own targets do, under the
+[`.tpl.` convention](configuration.md#templates-and-the-tpl-convention): a file with `.tpl.` in
+its name is rendered through LiquidJS and loses that segment (`SKILL.tpl.md` becomes `SKILL.md`),
+and any other file is copied verbatim. They are tracked like every file sous writes, so
+`sous prune` removes them when you unsubscribe. Where each kind lands is your project's decision,
+under
+[`recipeOutputs`](repositories-file-formats.md#recipeoutputs-where-the-files-land).
+
+## 6. Start a repository of your own
+
+A recipe repository is not a sous project; it has no `.sous/` directory, and the three commands
+that work inside one do not look for a config. Run this outside your project:
+
+```bash
+sous repo init ~/projects/my-recipes --name my-recipes --namespace workflow
+```
+
+```text
+▶ Creating a recipe repository:
+  wrote sous.repo.yaml
+  wrote sous.index.json
+  wrote recipes/workflow/example/sous.recipe.yaml
+  wrote recipes/workflow/example/skills/example-skill/SKILL.md
+  wrote README.md
+  wrote .github/workflows/sous-release.yml
+  wrote .gitignore
+```
+
+The scaffold validates as written, and every file it leaves is heavily commented. `sous.repo.yaml`
+declares the namespaces and lists every recipe folder; each folder's `sous.recipe.yaml` is one
+recipe, with its own version.
+
+## 7. Put something in the recipe
+
+Edit `recipes/workflow/example/skills/example-skill/SKILL.md` into a real skill, then name the
+recipe in its manifest:
+
+```yaml
+formatVersion: 1
+namespace: workflow
+name: example
+version: 0.1.0
+description: One paragraph saying what a project gets by subscribing to it.
+
+contents:
+  - kind: skills
+    include:
+      - skills/**/*.md
+```
+
+`contents` is what a subscriber receives, one group per kind (`skills`, `memories`, `prompts` or
+`config`), each with globs relative to the recipe folder. Copying the folder is how you start a
+second recipe; its path goes in the `recipes` list at the root.
+
+## 8. Release it
+
+Releasing reads versions from the recipe manifests, regenerates the index, commits and tags, so
+the repository has to be a git repository with your work committed:
+
+```bash
+cd ~/projects/my-recipes
+git init -b main . && git add -A && git commit -m "First recipe"
+sous repo release
+```
+
+Releasing commits and tags on your behalf, so `git config user.name` and `git config user.email`
+have to be set in this repository first. Sous then prints the versions it would publish and what
+the run would do, and asks once.
+
+```text
+  ...
+▶ Publishing:
+  workflow/example: publishing version 0.1.0.
+  Wrote sous.index.json.
+  Committed: Release workflow/example@0.1.0
+  Created the tag workflow/example@0.1.0.
+```
+
+Add `--push` to push the commit and the tags in the same run, and `--yes` to accept the plan
+without being asked, which is what the scaffolded workflow does. Never edit `sous.index.json` by
+hand; the recipe manifests are the source of truth for versions, and this command regenerates the
+catalog from them. `sous repo release --check` validates without publishing, and runs on a pull
+request.
+
+## 9. Add your repository to the project
+
+Adding a repository is how you trust it, so sous asks before recording it. A path works as well as
+a URL; sous reads a path through the built-in `local` provider:
+
+```term
+$ cd ~/projects/my-project
+$ sous repo add ../my-recipes --name my-recipes
+One repository has to be trusted before this can continue.
+  my-recipes
+    Location: /home/you/projects/my-recipes
+    Required: my-recipes (required by this project)
+// then what trusting means, and the question
+? Do you trust this repository? (y/N) y
+▶ Adding a repository:
+    Repository: my-recipes
+    Location  : /home/you/projects/my-recipes
+    Provider  : local
+    Namespaces: workflow
+    Recipes   : 1
+  This project now trusts 'my-recipes'. Nothing from it has been installed.
+```
+
+One file is fetched, the repository's `sous.index.json`, and nothing is installed. The entry lands
+in `.sous/conf.d/500-repos.jsonc`, which is committed, so a colleague inherits the repository and
+the trust decision together.
+
+!> A repository on your own disk goes through the same question as a hosted one; its recipes still
+run on this machine, and [Trust](repositories.md#trust) says what the decision covers. A local path is machine-specific, so a colleague cloning your project needs
+that path to exist, or needs the repository pushed somewhere they can reach. To edit a repository
+your project already subscribes to, use
+[`sous repo link`](repositories-authoring.md#edit-a-repository-in-place) instead.
+
+## 10. Subscribe to your own recipe
+
+```bash
+sous subscription add workflow/example
+```
+
+```text
+➔ What was installed:
+  Recipe            Version  Repository  Why
+  ----------------  -------  ----------  --------------------
+  workflow/example  0.1.0    my-recipes  you subscribed to it
+```
+
+Your skill is now in `.claude/skills/` beside the ones from the official repository. Nothing about
+a recipe's files is special once they are on disk, and nothing distinguishes yours from anyone
+else's.
+
+## 11. Commit the lockfile
+
+```bash
+sous subscription list
+```
+
+```text
+  Subscription         Range        Pinned version             Origin    Enabled
+  -------------------  -----------  -------------------------  --------  -------
+  core                 0.2.0        core/sous-skills 0.2.0     built in  yes
+  workflow/example     any version  workflow/example 0.1.0     user      yes
+  workflow/task-files  any version  workflow/task-files 1.0.2  user      yes
+```
+
+Everything sous needs to rebuild this project is under `.sous/`, and it is all committed:
+
+| File | Holds |
+|------|-------|
+| `.sous/sous.config.yaml` | your project's own config |
+| `.sous/sous.lock.json` | the exact version and content hash of every recipe in use |
+| `.sous/conf.d/500-repos.jsonc` | the repositories the project trusts |
+| `.sous/conf.d/510-subscriptions.jsonc` | what the project subscribes to |
+| `.sous/.env` | the answers to the recipes' questions, minus the secret ones |
+| the rest of `.sous/conf.d/` | the README sous writes there, and the agent pointers beside it |
+
+Gitignore compiled output (`.claude/`), the state file `.sous/sous.state.json`, and the secrets
+file `.sous/.env.local`. The store on your machine is not in the project at all.
+
+```bash
+git add .sous && git commit -m "Subscribe to task-files and my own example recipe"
+```
+
+## 12. Restore on a second machine
+
+A clone has the lockfile and the subscriptions and no store at all. `sous build` restores exactly
+what the lockfile pins, asking nothing:
+
+```term
+$ git clone git@github.com:my-team/my-project.git
+>> 100%
+$ cd my-project
+$ sous build
+▶ Restoring recipes:
+  This project's lockfile pins recipes that are not in the store on this machine,
+    so they are being fetched at exactly the versions it records.
+    restored: workflow/example
+    restored: workflow/sub-agent-delegation
+    restored: workflow/task-files
+▶ Building:
+  ✓ .claude/skills/about-task-files/SKILL.md (~942 tokens)
+✓ Done.
+```
+
+Nothing was resolved and nothing was asked, because the lockfile already said what to fetch; see
+[The lockfile](repositories.md#the-lockfile) for why restore decides nothing.
+
+?> The store those recipes were restored into, `$SOUS_HOME/cache`, is machine-wide and disposable;
+everything in it is re-fetchable from a lockfile pin. `SOUS_HOME` moves it, and is what step 1 set
+so this walkthrough keeps its own; unset, the store is `~/.sous/cache`. To undo everything above,
+`rm -rf ~/projects/my-project ~/projects/my-recipes ~/tmp/sous-quickstart`; on a store you mean to
+keep, `sous repo gc` reclaims what no lockfile pins instead.
+
+## Where to go next
+
+- [Consuming recipes](repositories-consuming.md): dry runs, one-word refs, removal, `repo gc`
+- [Authoring a repository](repositories-authoring.md): variables, editing in place, contributing
+- [Recipe variables](repositories-variables.md): the resolution ladder and the `sous vars` commands
+- [Repositories](repositories.md): trust, providers, freshness, and what lives where
+- [Command reference](commands.md): every command and flag
+- [Troubleshooting](repositories-troubleshooting.md): what the errors mean and how to clear them