@sous-io/sous 0.2.17 → 0.2.19

package/docs/markdown/_sidebar.md

@@ -12,6 +12,7 @@
   - [Overview](repositories.md)
   - [Quickstart](repositories-quickstart.md)
   - [Consuming recipes](repositories-consuming.md)
+  - [Contributing a change](repositories-contributing.md)
   - [Authoring a repository](repositories-authoring.md)
   - [Recipe variables](repositories-variables.md)
   - [Providers](repositories-providers.md)

package/docs/markdown/commands.md

@@ -231,9 +231,50 @@ Example: `sous repo link sous-recipes ~/Projects/sous-recipes`, or `sous repo li
 --generate-branch --latest --yes`
 
 ### `sous repo unlink REPO`
-Stops reading a repository from a working copy and goes back to published versions; `REPO` is the short name as
-it appears in `sous.links.json` (see [File formats](repositories-file-formats.md)). `--global` removes the
-machine-wide link, not this project's; `--dry-run` prints what changes. Example: `sous repo unlink sous-recipes`
+Stops reading a repository from a working copy, goes back to the versions the lockfile pins, and rebuilds the
+project; `REPO` is the short name as it appears in `sous.links.json` (see
+[File formats](repositories-file-formats.md)). On its own it also fetches the repository's index, with a short
+timeout, and reports any newer published version the ranges allow, without moving anything; when the index
+cannot be fetched in time it says it could not check. The checkout stays where it is unless `--remove` is passed.
+Takes `--dry-run`, `--no-build`, `--answer` and `--answers-file`.
+
+- `--global`: remove the machine-wide link, not this project's.
+- `--update`: move this repository's pins to the newest versions their ranges allow before rebuilding. It runs
+  the same code as `sous subscription update REPO`.
+- `--remove`: delete the checkout as well, but only one sous cloned itself; a checkout linked by path is refused
+  with an error. Uncommitted changes, commits no remote has and stashes are listed first and asked about.
+- `-y, --yes`: answer every question this command asks: deleting a checkout that holds work, the update plan,
+  and the trust question for a repository a newer version needs (also `--force`, `--trust`).
+
+Example: `sous repo unlink sous-recipes --update`
+
+### `sous repo contribute REF`
+Starts a contribution to a recipe repository, or finishes one with `--finish`, by running `sous repo link`,
+`sous repo submit` and `sous repo unlink` in order; see [Contributing a change](repositories-contributing.md).
+`REF` names a repository, or a namespace or recipe, in which case the repository that publishes it is used.
+Each step runs the real command with the flags below passed through, prints as it runs, and a failure names the
+step that failed and the steps that completed. `--dry-run` prints each step and runs none. Also spelled
+`sous repo contrib`.
+
+Starting runs `sous repo link REPO --latest --generate-branch`:
+
+- `--create-branch <name>`: start on a new branch with this name instead of a generated one.
+- `--branch <name>`: work on an existing branch instead of a new one (when finishing, the branch to submit).
+- `--from <branch>`: the base of the new branch; defaults to the repository's default branch.
+- `--global`: the machine-wide link, sharing one checkout (when finishing, too).
+
+Finishing looks for work no proposal carries yet (uncommitted changes, commits never pushed, or pushed commits
+with no open proposal), asks whether to submit it with `sous repo submit REPO`, then runs
+`sous repo unlink REPO --update`. With nothing to submit, the submit step is skipped without asking.
+
+- `--submit`, `--no-submit`: submit without asking, or finish without submitting.
+- `--title <text>`, `--body <text>`, `--draft`, `--commit`: passed through to `sous repo submit`.
+- `--remove`: passed through to `sous repo unlink`, deleting the checkout sous cloned.
+- `-y, --yes`: passed through to every step, and submits without asking (also `-f`, `--force`).
+- `--accept-first`: when `REF` matches several things, take the first one listed.
+
+Example: `sous repo contribute workflow/task-files`, then `sous repo contribute workflow/task-files --finish
+--title "Clarify the resume steps" --body "The resume steps skipped the task file."`
 
 ### `sous repo init [DIRECTORY]`
 Creates a new recipe repository in a directory, defaulting to the current one; `--dry-run` prints the files it
@@ -306,6 +347,20 @@ Example: `sous subscription add workflow/task-files@^1.2.0 --answer apiUrl=https
 Removes a subscription and everything only it brought in, then rebuilds so those files are gone. Also spelled
 `sous unsubscribe`. Takes `--dry-run` and `--no-build`. Example: `sous subscription remove workflow/task-files`
 
+### `sous subscription update [REF]`
+Moves the lockfile's pins to the newest published versions their ranges allow, then rebuilds the project. With
+no `REF` it covers every subscription; a `REF` naming a repository, a namespace or a recipe narrows it, and
+everything outside it stays where it is pinned. It fetches every trusted repository's index first, never widens
+a range, moves dependencies with the closure, and changes only the lockfile, never the subscriptions. It prints
+the plan and asks once; with nothing to update it says so and asks nothing. See
+[Moving to newer versions](repositories-consuming.md#moving-to-newer-versions). Takes `--no-build`, `--answer`
+and `--answers-file`, and `--dry-run`, which fetches the indexes but downloads no recipe and writes nothing.
+
+- `-y, --yes`: accept the plan, and trust any repository a newer version needs (also `--force`, `--trust`).
+- `--accept-first`: when `REF` matches several things, take the first one listed.
+
+Example: `sous subscription update workflow/task-files`
+
 ### `sous subscription list`
 Lists the subscriptions this project declares, switched-off ones included, with the range each resolves within,
 the versions the lockfile pins, the latest version each of those recipes has published, where it came from and
@@ -317,7 +372,8 @@ only the subscriptions that have pinned something. Example: `sous subscription l
 
 `namespace` reads the cached indexes and the lockfile, so it works offline. A trusted repository whose index has
 never been fetched is named at the end of a listing, not left out. Both commands take the
-[browsing flags](#flags-that-browse); with `--installed` the recipe count is the number installed.
+[browsing flags](#flags-that-browse); with `--installed` the recipe count is the number installed. The core version this installation of sous
+ships is listed even while the cached index does not publish it yet.
 
 ### `sous namespace list`
 Lists every namespace the trusted repositories publish, how many recipes each holds, and how much of it this
@@ -354,8 +410,10 @@ Prints what `.sous/sous.lock.json` pins: the recipe, the version, the repository
 ### `sous lock rebuild`
 Recomputes the whole lockfile from the subscriptions the config declares and the cached indexes, starting from
 empty, so an entry nothing holds any more is dropped rather than carried through: the repair for a file that
-drifted through a hand edit or a bad merge. It asks nothing, grants no trust and downloads nothing. Takes
-`--dry-run`. Example: `sous lock rebuild --dry-run`
+drifted through a hand edit or a bad merge. It asks nothing, grants no trust and downloads nothing. The core
+version this installation of sous ships resolves even when the cached index has not published it yet, exactly
+as it does in a build. To move pins to versions published since the last fetch, use `sous subscription update`.
+Takes `--dry-run`. Example: `sous lock rebuild --dry-run`
 
 ## vars
 

package/docs/markdown/repositories-authoring.md

@@ -289,8 +289,29 @@ and freshness checks no longer apply to it. Builds say so every time.
 Run 'sous repo unlink my-recipes' to go back to published versions.
 ```
 
-`sous repo unlink` removes the map entry and nothing else: the checkout stays where it is, and its path is
-printed so you can delete it. Unlinking a name linked in the other scope says which scope holds it.
+### Unlink, and pick up your release
+
+Linking never touches the lockfile, so `sous repo unlink my-recipes` goes back to exactly the versions pinned
+before the link, and rebuilds the project so its outputs match them. It also fetches the repository's index,
+with a short timeout, and says whether a newer version the ranges allow has been published since; it moves
+nothing, and when the index cannot be fetched in time it says it could not check. Unlinking a name linked in
+the other scope says which scope holds it.
+
+Once your change is released, one of these moves the project onto it:
+
+```bash
+sous repo unlink my-recipes --update       # unlink, move this repository's pins, then rebuild
+sous subscription update my-recipes        # the same move, when nothing is linked any more
+```
+
+`--update` runs exactly the code `sous subscription update my-recipes` runs: every pin the repository supplies
+moves to the newest version its range allows, after one plan and one question. See
+[Moving to newer versions](repositories-consuming.md#moving-to-newer-versions).
+
+The checkout stays where it is unless you pass `--remove`, because `sous repo submit` uses a leftover checkout to
+revise a proposal that is still open. `--remove` deletes it only when sous cloned it; a checkout you linked by
+path is yours, and sous refuses with an error. Before deleting, sous lists anything in the checkout that exists
+nowhere else (uncommitted changes, commits no remote has, and stashes) and asks; `--yes` answers ahead.
 
 ### How a checkout compares with upstream
 
@@ -347,6 +368,10 @@ changing its branch says it affects all of them.
 
 ## Contribute to someone else's repository
 
+?> The whole path a recipe user takes, from starting a change in their own project to picking up the released
+version, is one page: [Contributing a change](repositories-contributing.md). `sous repo contribute` chains the
+commands this section and [Edit a repository in place](#edit-a-repository-in-place) describe.
+
 `sous repo submit` proposes a change to a repository's maintainers and follows it through; it never publishes
 and never writes to a repository directly. Run it inside the recipe repository you changed, or from a project
 that links it: `sous repo submit sous-recipes` runs in the linked checkout, and with no argument the project's
@@ -380,7 +405,8 @@ your change carries with the default branch:
 
 - recipes added, and recipes retired (a renamed recipe shows as one of each);
 - version changes;
-- recipes whose files changed without a version raise, which merging will release as the next patch;
+- recipes whose files changed without a version raise, with a warning that a release run with `--ci` (as the
+  scaffolded workflow runs it after a merge) refuses a changed recipe whose version was not raised;
 - namespaces added or removed;
 - variables added, removed or changed, with a warning that removing a variable or tightening its validation is
   usually a major change.
@@ -413,6 +439,7 @@ that field in your own repository so a contributor is never left without a route
 
 - [Repository file formats](repositories-file-formats.md): every manifest and index schema
 - [Consuming recipes](repositories-consuming.md): the other side, from `repo add` to `build`
+- [Contributing a change](repositories-contributing.md): proposing a change to a recipe you use, start to finish
 - [Command reference](commands.md): every command and flag
 - [Providers](repositories-providers.md): what `gh` and `glab` can each do for a release and a submission
 - [Recipe variables](repositories-variables.md): how the definitions declared here are answered at build time

package/docs/markdown/repositories-consuming.md

@@ -220,7 +220,48 @@ build` instead. The `Latest version` column beside it is read from the cache, or
 `sous repo list` shows each trusted repository with its provider, origin, whether it is linked, its
 recipe count and its URL; `--verbose` adds a `Namespaces:` line under each row. `sous lock show`
 prints the other half: every version your lockfile pins, where it came from and who holds it. When
-that file has drifted, `sous lock rebuild` recomputes it from your subscriptions.
+that file has drifted, `sous lock rebuild` recomputes it from your subscriptions and the cached
+indexes, fetching nothing.
+
+## Moving to newer versions
+
+A build holds the versions the lockfile pins, so a newer release reaches the project only when
+something moves the pin. `sous subscription update` is that step:
+
+```term
+$ sous subscription update workflow/qa-variables
+  Updating the recipe 'qa-recipes:workflow/qa-variables' changes the lockfile:
+
+    • Adding workflow/qa-helper version 1.0.0
+    • Updating workflow/qa-variables from version 0.1.0 to version 0.2.0
+
+  Update the lockfile? (y/N)
+```
+
+It fetches every trusted repository's index first, so a version published a minute ago counts.
+With no reference it covers every subscription; a reference names a repository, a namespace or a
+recipe, at any level of qualification, and everything outside it stays exactly where it is pinned.
+What it will and will not do:
+
+- A pin moves only within the range its subscription declares, or the range the recipe depending
+  on it declares; a range is never widened. Prereleases count only for a subscription that opted
+  into them.
+- Dependencies move with the closure: a dependency a newer version adds is pinned, and one it
+  dropped leaves the lockfile unless something else still holds it.
+- Only the lockfile changes. Your subscriptions stay exactly as they are written.
+- It prints the plan and asks once; `--yes` accepts it, and a run with no terminal and no `--yes`
+  fails naming the flag. With nothing to update it says so and asks nothing.
+- A repository a newer version needs that the project does not trust goes through the usual trust
+  question, and new questions the newer versions ask are asked the way subscribing asks them.
+- A repository whose index cannot be fetched is skipped and named, and its pins stay put.
+- A linked repository's pins move too, and the plan notes that builds keep reading the checkout
+  until it is unlinked.
+- The built-in `core` subscription never moves: its range is exactly the running sous version, so
+  upgrading sous is what moves it.
+
+It rebuilds the project afterwards. `--dry-run` fetches the indexes and prints the plan, and
+downloads no recipe and writes nothing, so the dependencies and questions of a version this machine
+does not hold yet are named rather than listed. `--no-build` skips the rebuild.
 
 ## Remove a subscription
 
@@ -290,7 +331,8 @@ lapsed (`store.freshnessSeconds`, five minutes by default), or when a command fo
 check never breaks a build, because the cached index is used instead. Always-pull changes what
 happens after that check, not how often it happens: a repository or subscription marked
 `alwaysPull` takes a newer in-range version rather than the locked one; set it with
-`--always-pull`, or on either entry in the config.
+`--always-pull`, or on either entry in the config. Without it, `sous subscription update` is how a
+pin moves; see [Moving to newer versions](#moving-to-newer-versions).
 
 Every other repository the lockfile pins from is checked on the same window, only to tell you what
 is newer. A build lists each recipe with a newer version inside the range declared for it, beside

package/docs/markdown/repositories-contributing.md

@@ -0,0 +1,145 @@
+# Contributing a Recipe Change
+
+This page takes you from "a recipe I use could be better" to "my project runs the released fix", for a recipe
+published by someone else's repository. It is written for the person using the recipe, not the person who
+maintains it; everything happens from inside your own project.
+
+One command covers the lifecycle: `sous repo contribute` starts a contribution, and `sous repo contribute --finish`
+ends it. Each step it takes is an ordinary sous command, named on this page, so you can also run the parts by
+hand.
+
+## Start
+
+Name the repository, or any namespace or recipe it publishes:
+
+```bash
+sous repo contribute sous-recipes            # the repository itself
+sous repo contribute workflow/task-files     # the repository that publishes this recipe
+```
+
+A namespace or recipe is resolved to the repository that publishes it, the same way every other command resolves
+a reference; a name that matches in more than one trusted repository is a question, which `--accept-first`
+answers by taking the first match.
+
+Starting runs one step, `sous repo link <repo> --latest --generate-branch`:
+
+- the repository is cloned into `.sous/repos/<owner>/<name>`, or the clone already there is reused;
+- its default branch is brought up to upstream's (anything that would discard local work is listed and asked
+  about first; `--yes` answers);
+- a new branch named `sous/edit-<YYYYMMDD>-<HHMM>` is created from it, so the change never stacks on an old,
+  already-merged branch;
+- the project is pointed at the checkout, so builds read the repository from it instead of from a published
+  version.
+
+Name the branch yourself with `--create-branch <name>`, work on a branch that already exists with
+`--branch <name>`, or start the new branch from another base with `--from <branch>`. `--global` links the
+machine-wide checkout that every project on this machine shares. The link and its flags are described in full
+under [Edit a repository in place](repositories-authoring.md#edit-a-repository-in-place).
+
+`--dry-run` prints the step without running it.
+
+## Edit, and see the change in your own build
+
+Edit the recipe's files in the checkout the start step printed. While the repository is linked, every build in
+your project reads its recipes from that checkout, so the next `sous build` shows your edit in your own agent's
+files; there is nothing to publish first. Builds say the repository is linked every time, because a link
+bypasses versions, the lockfile and freshness checks.
+
+Commit your work on the branch as you go. What a proposal carries is commits.
+
+## Propose the change
+
+Finishing proposes whatever is not proposed yet, so you can go straight to [Finish](#finish). To open the proposal
+now and keep working, run the submit step on its own:
+
+```bash
+sous repo submit sous-recipes --title "Clarify the resume steps" --body "The resume steps skipped the task file."
+```
+
+`sous repo submit` validates the repository, pushes the branch (through a fork on your own account when you
+cannot push to the repository itself) and opens a pull request or merge request through the host's own command
+line tool. Its body is your description followed by a changelog sous generates. Every step it takes is described
+under [Contribute to someone else's repository](repositories-authoring.md#contribute-to-someone-elses-repository).
+
+## Revise it
+
+Review comments are answered with more commits on the same branch. Commit them, then run
+`sous repo submit sous-recipes` again: it finds the open proposal for the branch and pushes the new commits into
+it. A new `--title` or `--body` replaces the proposal's own. With nothing new to send, it reports where the
+proposal stands (review, checks, and whether it can merge). `sous repo submit sous-recipes --status` only
+reports.
+
+## Finish
+
+```bash
+sous repo contribute sous-recipes --finish
+```
+
+Finishing first looks at the branch for work no proposal carries yet: uncommitted changes, commits that were never
+pushed, or pushed commits with no open proposal behind them (that last one is looked up with the host's command
+line tool). When it finds some, it asks whether to submit it; `--submit` or `--yes` submits without asking,
+`--no-submit` finishes without submitting, and a run with no terminal fails naming those flags. When there is
+nothing to submit, that part is skipped. The submit step passes `--title`, `--body`, `--draft`, `--commit` and
+`--branch` through to `sous repo submit`.
+
+Then it runs `sous repo unlink <repo> --update`:
+
+- the project goes back to reading published versions, exactly the ones the lockfile pinned before the link;
+- each pin the repository supplies moves to the newest published version its range allows;
+- the project is rebuilt.
+
+The checkout stays on disk, so an open proposal can still be revised from it later with `sous repo submit`. Pass
+`--remove` to delete it as well; sous deletes only a checkout it cloned, and lists anything in it that exists
+nowhere else before asking.
+
+Every step prints as it runs, preceded by the command line that runs it. When a step fails, its own error comes
+first, followed by the name of the step that failed and the steps that had already completed; nothing after the
+failed step runs. `--dry-run` shows what finishing would do and runs none of it.
+
+## Pick up the release
+
+A contribution ships when the repository's maintainers merge it and the repository releases a new version. If
+that happened before you finished, `--finish` already moved your pins to it. If it happens later, move them with
+
+```bash
+sous subscription update sous-recipes
+```
+
+which runs the same update `unlink --update` runs; with `--dry-run` it only shows what it would move. See
+[Moving to newer versions](repositories-consuming.md#moving-to-newer-versions).
+
+## What a contributor leaves alone
+
+**Releases are the maintainers' business.** A contributor never runs `sous repo release`, and never edits
+`sous.index.json`. The index is written by the repository's own release after a merge, from the manifests and the
+tags; `sous repo submit` refuses a change that edits it, and says how to put it back.
+
+**Versions depend on how the repository releases.** The release workflow `sous repo init` scaffolds, which
+`sous-recipes` also runs, publishes on every merge to the default branch with `sous repo release --ci`, and that
+raises no versions: the version a merge publishes is the one the merged change declares. A recipe whose files
+changed while its `version` still equals its last release tag stops that release. So, unless the repository's
+contribution guide says its maintainers raise versions themselves, raise the recipe's `version` in its
+`sous.recipe.yaml` by hand as part of your change: a patch step for wording and fixes, a minor step for new files
+or a new optional variable, and a major step for anything that breaks an existing subscriber (removing a file,
+renaming a variable, or tightening a variable's validation). The changelog `sous repo submit` generates lists any
+recipe your change touches without a version raise, with a warning that a `--ci` release refuses it, so a missed
+one is visible in the proposal. The repository's
+own guide is named by the `contribute` field of its `sous.repo.yaml`; for `sous-recipes` it is its
+`CONTRIBUTING.md`.
+
+**Core is edited in sous itself.** The `core` recipes in `sous-io/sous-recipes` are machine-written copies. Their
+source is `recipes/core/sous-skills/` in `sous-io/sous`, and each sous release overwrites the copy, so an edit
+merged into the copy would be lost. Their manifest says so with a
+[`submissions`](repositories-file-formats.md#the-submissions-block) block: `sous repo submit` warns before
+proposing a change that touches one and names where to send it instead, and the repository's own pull request
+check refuses such a change. Propose core edits as a pull request to `sous-io/sous`.
+
+## The commands this chains
+
+| Part of the lifecycle | What `sous repo contribute` runs |
+|-----------------------|----------------------------------|
+| Start | `sous repo link <repo> --latest --generate-branch` (or the branch you named) |
+| Propose, when finishing | `sous repo submit <repo>`, with the proposal flags passed through |
+| Finish | `sous repo unlink <repo> --update`, plus `--remove` when given |
+
+Every flag is listed in the [command reference](commands.md#sous-repo-contribute-ref).

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

@@ -252,7 +252,8 @@ freshness checks; entries are keyed by the repository's configured short name.
 ```
 
 `path` is absolute; `origin` is `clone` when sous cloned the working copy itself and `path` when it was
-pointed at an existing checkout, and unlinking removes the entry while leaving either in place. Both the
+pointed at an existing checkout. Unlinking removes the entry and leaves the checkout in place, unless
+`sous repo unlink --remove` is asked to delete one sous cloned; it never deletes a `path` checkout. Both the
 project's `.sous/sous.links.json` and `$SOUS_HOME/sous.links.json` are read, and the project's entries win.
 
 ## Configuration keys

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",

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

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