@sous-io/sous 0.2.15 → 0.2.17

package/docs/markdown/commands.md

@@ -17,7 +17,8 @@ Every command that works on a project takes these four. `SOUS_CONFIG`, `SOUS_DIR
 a flag beats its variable, and both beat walk-up discovery. See [Discovery and overrides](config-discovery.md).
 
 ?> `repo init`, `repo release` and `repo submit` take none of these. They run inside a recipe repository, which
-has no `.sous/` directory to discover. All three still take `--non-interactive`.
+has no `.sous/` directory to discover. All three still take `--non-interactive`. `repo submit` may also be run
+from a project, which it finds by walking up from the working directory.
 
 ## Flags that answer questions
 
@@ -41,6 +42,22 @@ Help has four spellings. `sous --help` prints the root screen; `sous repo add --
 `sous --version` prints the version alone, as `v1.2.3`; `sous --version --verbose` adds the package name, where
 it is installed, the platform and the Node build under it.
 
+## Flags that browse
+
+Every command that shows published versions takes the same two flags: `sous recipe list`, `sous recipe show`,
+`sous namespace list`, `sous namespace show`, `sous repo list`, `sous repo search` (and `sous search`) and
+`sous subscription list`. The flags combine.
+
+| Flag | What it does |
+|------|--------------|
+| `--latest` | Read each repository's index from upstream instead of the cache. `--remote` is the same flag. What it fetches is never written to the cache; a repository that cannot be reached is shown from the cache and named as not checked |
+| `--installed` | Show only what this project has installed, at the version its lockfile pins. A recipe whose repository is linked is marked `linked`, because builds read it from the checkout rather than the pinned version |
+
+Without either flag a browsing command reads only the cached indexes, so it works offline and fast.
+`sous recipe list --installed --latest` is the out-of-date view: each installed recipe with upstream's newest
+version beside the installed one. With `--installed`, `recipe show` and `namespace show` look the reference up
+among installed recipes only, and a reference to something published but not installed is an error saying so.
+
 Every topic answers to both spellings of its name: `repo` and `repos`, `subscription` and `subscriptions`,
 `namespace` and `namespaces`, `recipe` and `recipes`, `lock` and `locks`, `vars` and `var`, `config` and
 `configs`. Three commands also answer to one word: `sous search`, `sous subscribe` and `sous unsubscribe`.
@@ -79,6 +96,12 @@ and the command you want almost always. Takes `--dry-run`.
 - `--strict`: fail on any compilation error rather than reporting it and continuing.
 - `-w, --watch`: rebuild on every change to a source file, a config layer or a linked checkout.
 
+Before it compiles, a build lists each recipe this project uses that has a newer version within the range
+declared for it, beside the version pinned. It moves no pin; only always-pull moves one. The build reads upstream
+for this at most once per freshness window (`store.freshnessSeconds`, five minutes by default), gives a
+repository three seconds to answer, and otherwise answers from the cached index without a word about the
+failed check.
+
 Example: `sous build --rebuild`
 
 ### `sous compile`
@@ -103,8 +126,10 @@ Example: `sous launch claude --continuous`
 
 ### `sous search TEXT`
 Searches the recipes every trusted repository publishes, by name or description; reads the cached indexes only,
-so it works offline. `--limit <n>` sets how many matches to show, defaulting to 25. Also spelled
-`sous repo search`. Example: `sous search task --limit 50`
+so it works offline. `--limit <n>` sets how many matches to show, defaulting to 25. Takes the
+[browsing flags](#flags-that-browse): `--latest` searches the indexes upstream serves, and `--installed` searches
+only installed recipes and adds an Installed column. Also spelled `sous repo search`.
+Example: `sous search task --limit 50`
 
 ### `sous help [COMMAND]`
 Prints the help for sous, or for one command or topic. Works from any directory, including one with no config
@@ -155,7 +180,9 @@ held, the files the next build prunes, and the linked checkout if one points at
 ### `sous repo list`
 Lists the repositories this project trusts, with the provider, where the entry came from, whether it is linked,
 how many recipes it publishes (`not fetched` until its index has been downloaded) and its URL. `--verbose` adds
-the namespaces each one publishes, on a line under its row.
+the namespaces each one publishes, on a line under its row. Takes the [browsing flags](#flags-that-browse):
+`--installed` keeps only the repositories something is installed from and names each installed recipe and
+version on a line under its row.
 
 ```term
 $ sous repo list
@@ -165,7 +192,8 @@ $ sous repo list
 ```
 
 ### `sous repo search TEXT`
-Same command as `sous search`, under its own topic; takes `--limit <n>`. Example: `sous repo search browser`
+Same command as `sous search`, under its own topic; takes `--limit <n>` and the
+[browsing flags](#flags-that-browse). Example: `sous repo search browser --installed`
 
 ### `sous repo gc`
 Collects the machine-wide recipe store down to its size cap. `--max-bytes <n>` collects to that cap instead of
@@ -227,17 +255,32 @@ and `git config user.email`), because it commits and cuts annotated tags. Takes
 - `--no-bump`: raise nothing; a changed recipe that was never raised is then an error.
 - `--include-unchanged`: release every recipe in scope, changed or not.
 - `--tag`, `--push`: tag even on a non-default branch, and push the commit and this run's tags.
-- `--check`: only validate. It fails on a problem the release would refuse, and reports, without failing, how
-  merging would rewrite the committed index.
+- `--check`: only validate. It fails on a problem the release would refuse, and on a change to a recipe that
+  takes no proposals (see [`submissions`](repositories-file-formats.md#the-submissions-block)), and reports,
+  without failing, how merging would rewrite the committed index.
 - `--ci`: the merge preset. Never bump, never ask, and fail on anything unbumped. It still needs `--yes` to
   accept the plan it prints, so a merge job runs `sous repo release --ci --yes --push`.
 
 Example: `sous repo release --recipe workflow/task-files --bump minor --push`
 
-### `sous repo submit`
-Proposes this repository's committed changes to its maintainers. `--title <text>` defaults to the last commit's
-subject and `--body <text>` to a summary sous writes; `--draft` opens the proposal as a draft, and `--dry-run`
-prints the plan without sending anything. Example: `sous repo submit --title "Add a linting recipe" --draft`
+### `sous repo submit [REPO]`
+Proposes a recipe repository's changes to its maintainers, and follows the proposal through: it opens one,
+updates it when there is more to send, reports where it stands, and starts the next one once it was merged. Run
+inside a recipe repository it works there; run inside a project, `REPO` names a linked repository and the
+submission runs in its checkout (with no `REPO`, the only linked repository is used, and several are a
+question). Takes `-y, --yes` and `--dry-run`.
+
+- `--title <text>`, `--body <text>`: the proposal's title and description. Both are required for a new
+  proposal, and asked for at a terminal when missing; on an open proposal they are optional and replace its own.
+  The body is followed by a changelog sous generates.
+- `--branch <name>`: work with this branch instead of the one checked out. A branch that does not exist is
+  created from the current commit.
+- `--status`: only report where the branch's proposal stands; nothing is checked, written or sent.
+- `--commit`: commit uncommitted changes for you, after listing them and asking once, with the title, the
+  description and the changelog as the message.
+- `--draft`: open a new proposal as a draft.
+
+Example: `sous repo submit --title "Add a linting recipe" --body "Adds lint rules for shell scripts." --draft`
 
 ## subscription
 
@@ -265,13 +308,16 @@ Removes a subscription and everything only it brought in, then rebuilds so those
 
 ### `sous subscription list`
 Lists the subscriptions this project declares, switched-off ones included, with the range each resolves within,
-the versions the lockfile pins, where it came from and whether it is on. Reads the config and the lockfile only.
-Example: `sous subscription list`
+the versions the lockfile pins, the latest version each of those recipes has published, where it came from and
+whether it is on. Reads the config, the lockfile and the cached indexes only. Takes the
+[browsing flags](#flags-that-browse): `--latest` reads the latest versions from upstream, and `--installed` keeps
+only the subscriptions that have pinned something. Example: `sous subscription list --latest`
 
 ## namespace
 
 `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.
+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.
 
 ### `sous namespace list`
 Lists every namespace the trusted repositories publish, how many recipes each holds, and how much of it this
@@ -284,11 +330,12 @@ Example: `sous namespace show sous-recipes:core`
 
 ## recipe
 
-Browses the recipes the trusted repositories publish; like `namespace`, it works offline.
+Browses the recipes the trusted repositories publish; like `namespace`, it works offline, and both commands take
+the [browsing flags](#flags-that-browse).
 
 ### `sous recipe list`
 Lists the recipes the trusted repositories publish, across every namespace, with the same per-recipe columns
-`namespace show` prints. Example: `sous recipe list`
+`namespace show` prints. Example: `sous recipe list --installed --latest`
 
 ### `sous recipe show REF`
 Describes one recipe completely: its repository and location, every published version, its dependencies as

package/docs/markdown/repositories-authoring.md

@@ -4,8 +4,9 @@ The guide to publishing recipes of your own: creating a repository, writing a re
 needs, cutting a release, editing a published repository in place, and proposing a change to somebody else's.
 [Repository file formats](repositories-file-formats.md) holds the schemas; this page is the workflow.
 
-?> A recipe repository is not a sous project. It has no `.sous/` directory, and `sous repo init`, `sous repo
-release` and `sous repo submit` do not look for one. Run them from inside the repository itself.
+?> A recipe repository is not a sous project. It has no `.sous/` directory, and `sous repo init` and `sous repo
+release` do not look for one. Run them from inside the repository itself. `sous repo submit` runs there too, and
+may also be run from a project that links the repository.
 
 ## Create a repository
 
@@ -196,8 +197,9 @@ third case is what a merge looks like to continuous integration: the bump is don
 `--namespace <ns>` and `--recipe <ns/name>` narrow the run and both repeat; `--bump <level>` is `patch` (the
 default), `minor`, `major` or `prerelease`; `--no-bump` raises nothing; `--include-unchanged` releases every
 recipe in scope, changed or not; `--check` only reads, validating, failing on any problem the release would
-refuse, and reporting how merging would rewrite the committed index without failing on it, since that index is
-the release's output; and `--ci` is the merge preset: never bump, accept the plan, never ask, fail on anything unbumped. Every flag
+refuse and on a change to a recipe whose [`submissions`](repositories-file-formats.md#the-submissions-block)
+block says it takes no proposals, and reporting how merging would rewrite the committed index without failing
+on it, since that index is the release's output; and `--ci` is the merge preset: never bump, accept the plan, never ask, fail on anything unbumped. Every flag
 this command takes, `--tag`, `--push` and `--non-interactive` among them, is in the
 [command reference](commands.md#sous-repo-release).
 
@@ -235,7 +237,8 @@ missing from the index is rebuilt from it whenever the index is regenerated, whi
 publishes something. A bump edits the manifest in place, so comments, field order and layout survive; a folded
 block of YAML prose may be re-wrapped and the space before a trailing comment collapsed to one.
 
-!> A release commits the version bumps and the index, and nothing else. It refuses to run while anything else is
+!> A release commits the version bumps and the index, and nothing else; the only other commit sous ever makes
+for you is `sous repo submit --commit`. It refuses to run while anything else is
 uncommitted, because a tag names one commit and the index records what each recipe folder holds right now. It also
 refuses when git does not know who is committing: set `git config user.name` and `git config user.email` first, or
 give that identity to the account a continuous integration job runs as (the scaffolded workflow already does).
@@ -344,22 +347,60 @@ changing its branch says it affects all of them.
 
 ## Contribute to someone else's repository
 
-`sous repo submit` proposes your committed changes to a repository's maintainers; it never publishes and never
-writes to a repository directly. It takes `--title`, `--body`, `--draft` and `--dry-run`, and runs three stages,
-printing each step:
+`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
+only linked repository is used (several are a question). A repository you have since unlinked is still
+submitted from the checkout sous cloned for it, with a note saying so; with no checkout at all there is no
+working copy to propose from, and `submit` says so.
+
+It prints each step as it runs them:
 
 1. **Preflight.** An `origin` remote exists, sous recognizes its provider, that provider's command line tool
-   (`gh` or `glab`) is installed and signed in, and everything is committed.
+   (`gh` or `glab`) is installed and signed in, and everything is committed. `--commit` lifts that last rule:
+   sous lists what is uncommitted, asks once (`--yes` answers), checks git knows who is committing before
+   writing anything, and commits it all with the proposal's title, description and changelog as the message.
 2. **Validation.** The repository validates, and your change leaves `sous.index.json` as it found it, so a
    proposal never fails the maintainer's own checks and wastes their review. The index is written by the
    repository's own release after a merge; whether it agrees with the release tags is checked there, by
    `sous repo release --check` on a full clone, not by `submit`. That is what lets `submit` run from the shallow
    checkout `sous repo link` makes, which holds almost none of the tags. The comparison is made against the
    copy of the default branch your checkout holds (`origin/main`, for example); when it holds none, `submit`
-   says the check was skipped.
+   says the check was skipped. A change that touches a recipe whose
+   [`submissions`](repositories-file-formats.md#the-submissions-block) block says it takes no proposals is
+   warned about, with where to send it instead, and proposed only if you carry on.
 3. **Delegation.** Sous asks the provider whether you can push to the repository itself, forks it onto your
    account when you cannot, pushes the branch, and asks the provider to open the proposal. A change sitting on
-   the default branch is moved to `sous/submit-<YYYYMMDD>-<HHMM>`.
+   the default branch is moved to `sous/submit-<YYYYMMDD>-<HHMM>`, or to the branch `--branch` names.
+
+**A title and a description are yours to write.** A new proposal needs both: pass `--title` and `--body`, or
+answer the two questions at a terminal (Tab opens your editor for a longer description). Sous never borrows a
+commit message. The body is your description followed by a changelog sous generates by comparing the manifests
+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;
+- 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.
+
+The changelog explains; it never refuses. Only what the repository's own checks would reject stops a submission.
+
+**One command for the proposal's whole life.** Every run looks up the proposal for the current branch (or the
+one `--branch` names), by the fork's owner as well as the branch when you work through a fork, and then:
+
+| The branch's proposal | What `submit` does |
+|-----------------------|--------------------|
+| none | Opens one |
+| open, with new commits | Pushes them, which updates it; a given `--title` or `--body` replaces its own |
+| open, with nothing new | Reports where it stands: review, checks, whether it can merge |
+| merged | Says so, then continues on a new branch: you name one, sous generates one, or you cancel. `--yes` generates one |
+| closed without merging | Says so, and opens a fresh one for the branch |
+
+When the branch on the remote holds commits yours lacks (a maintainer pushed to it), git refuses the push and
+`submit` passes git's own explanation through and stops. It never forces a push. `--status` only reports, and
+`--dry-run` works everything out and writes and sends nothing.
 
 Each step is the provider's own business, and what each one can do depends on the host; see
 [Providers](repositories-providers.md#proposing-a-change). Sous sequences the steps and reports what came back. A

package/docs/markdown/repositories-consuming.md

@@ -52,6 +52,19 @@ sous namespace show workflow   # one namespace and the recipes in it
 sous recipe list               # every recipe, latest version, pinned version, subscribed
 ```
 
+The cache can be behind what a repository has published since. Every one of these commands, plus
+`sous recipe show`, `sous repo list` and `sous subscription list`, takes two flags that combine:
+
+- `--latest` (also `--remote`) reads each index from upstream instead. Nothing it fetches is
+  written to the cache; only a command that resolves versions changes what the cache holds. A
+  repository that cannot be reached is shown from the cache and named as not checked.
+- `--installed` narrows the listing to what this project has installed, at the version the
+  lockfile pins. A recipe from a linked repository is marked `linked`, because builds read it from
+  the checkout instead of that version.
+
+`sous recipe list --installed --latest` is the out-of-date view: every installed recipe, with
+upstream's newest version beside the installed one.
+
 Read `sous recipe show` before subscribing: every published version, what it depends on (as
 declared, beside the version the index resolved it to), and its questions and files once it has
 them here.
@@ -201,7 +214,8 @@ $ sous subscription list
 
 A namespace subscription names every recipe it holds, each with the version the lockfile pins. A
 subscription that has never been built has nothing pinned yet, and its cell reads `pinned on first
-build` instead.
+build` instead. The `Latest version` column beside it is read from the cache, or from upstream with
+`--latest`.
 
 `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`
@@ -278,6 +292,23 @@ happens after that check, not how often it happens: a repository or subscription
 `alwaysPull` takes a newer in-range version rather than the locked one; set it with
 `--always-pull`, or on either entry in the config.
 
+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
+the version it pins, and moves nothing:
+
+```term
+$ sous build
+▶ Newer versions published:
+
+    workflow/qa-variables: 0.2.0 this project pins 0.1.0
+
+  This version is within the range declared for the recipe. No pin was changed, so this build
+  uses the pinned version.
+```
+
+That check waits at most three seconds for a repository, and a check that fails or runs out of
+time is not mentioned: the cached index answers instead, and the build carries on.
+
 The store is machine-wide and disposable, because everything in it is re-fetchable from a
 lockfile's pins. `sous repo gc` collects it back to its size cap, evicting least recently used
 entries first, and protects everything this project's lockfile pins whatever that does to the

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

@@ -54,6 +54,7 @@ recipes:                            # every recipe folder, relative to the repos
 | `description`, `contribute` | no | A summary for anyone reading the repository, and where to send a contribution when a provider cannot support `sous repo submit` |
 | `namespaces` | yes | Keyed by namespace name; each entry takes an optional `description` |
 | `recipes` | yes | Relative paths, each holding a recipe manifest; a path listed twice is an error |
+| `submissions` | no | Whether the repository's recipes take proposed changes; see [The submissions block](#the-submissions-block) |
 
 ## `sous.recipe.yaml`: the recipe manifest
 
@@ -77,11 +78,30 @@ contents:                           # what a subscriber actually receives
 | `description` | no | Copied into the index at release time; shown by `sous recipe list` and `sous repo search` |
 | `depends`, `subscribes` | no | Build dependencies and co-subscriptions; within either list, no entry may repeat |
 | `contents`, `variables` | no | Contents default to an empty list, which is what a curated bundle publishes; a duplicated variable name, or two definitions claiming one `env`, is an error |
+| `submissions` | no | Whether this recipe takes proposed changes, winning over the repository's block; see [The submissions block](#the-submissions-block) |
 
 `contents[].kind` is `skills`, `memories`, `prompts` or `config`. The first three are written to the
 destinations named by [`recipeOutputs`](#recipeoutputs-where-the-files-land); `config` entries become config
 layers instead. `include` needs at least one glob, and both lists are recipe-relative.
 
+### The submissions block
+
+Both manifests accept a `submissions` block. On `sous.repo.yaml` it covers every recipe in the repository; on
+`sous.recipe.yaml` it covers that recipe, and wins over the repository's.
+
+```yaml
+submissions:
+  allowed: false                    # defaults to true
+  instead: Propose changes in sous-io/sous, under recipes/core/sous-skills/.
+```
+
+It exists for a recipe whose files are copied in from somewhere else: an edit merged into the copy is
+overwritten by the next copy, and a version it tagged can collide with the one the real source publishes.
+`sous repo submit` warns before proposing a change that touches such a recipe, prints the `instead` text, and
+proposes it if the contributor carries on. `sous repo release --check` fails a pull request that changes one,
+because a pull request can be opened without `submit`, and the check is the one gate every change passes. A
+release itself is never restricted, so whatever publishes the recipe still releases it.
+
 ### Dependencies named by location
 
 `depends` and `subscribes` share one grammar in two spellings: `workflow/qa-helper` is a sibling in this

package/docs/markdown/repositories-providers.md

@@ -21,8 +21,12 @@ Nothing there clones a whole repository. A provider that can also carry a contri
 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
+A provider may also answer the **proposals** path, which is what lets a submission follow a proposal
+after it is opened: find the proposal a branch was pushed for, report where it stands, and replace its
+title or body.
+
+Each provider declares which of the three features, `fetch`, `submit` and `proposals`, 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
@@ -184,11 +188,15 @@ finds the index but cannot clone has only the second half missing.
 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 |
+| Provider | Tool | Push permission | Forking | Proposal | Following it up |
+|---|---|---|---|---|---|
+| `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 | `gh pr list`, `gh pr view` and `gh pr edit`, matching a fork's pull request by its owner |
+| `gitlab` | `glab` | sous cannot tell, so it pushes to `origin` and says so | not done for you | merge request | not done: every run opens a merge request, and `--status` is refused |
+| `local` | none | not applicable | not applicable | not applicable | not applicable |
+
+**GitLab cannot follow a proposal up yet.** It does not declare `proposals`, so a submission cannot
+look for a merge request that is already open; it says so, pushes, and opens one. When the branch
+already has one, the push updates it and GitLab may refuse the second.
 
 **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
@@ -297,14 +305,16 @@ subclass overrides it. Each member is documented where it lives, in
 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);
+- `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.
+- 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "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.15
+version: 0.2.17
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous
@@ -19,6 +19,13 @@ description: >-
   debugged, the .tpl. template convention and LiquidJS syntax, what an agent
   skill is, and how to create one.
 
+# The copy in sous-io/sous-recipes is overwritten by every sous release, so a
+# change proposed there would be lost, and a version it tagged would collide
+# with the one the release publishes.
+submissions:
+  allowed: false
+  instead: Propose changes in sous-io/sous, under recipes/core/sous-skills/.
+
 contents:
   - kind: skills
     include:

package/src/commands/namespace/list.ts

@@ -3,17 +3,25 @@
  *
  * Shows every namespace published by the repositories this project trusts, how
  * many recipes each one holds, and how much of it the project subscribes to. It
- * reads only the indexes sous already has on disk, so it works offline; a
- * repository whose index has never been fetched is named at the end rather than
- * being silently left out.
+ * reads only the indexes sous already has on disk by default, so it works
+ * offline; a repository whose index has never been fetched is named at the end
+ * rather than being silently left out. `--latest` reads the indexes from
+ * upstream instead, without saving them, and `--installed` narrows the listing
+ * to the namespaces the lockfile pins a recipe from.
  */
 
 import { BaseCommand } from "../../base-command.js";
 import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
-import { catalogContextFor } from "../../lib/repos/catalog-inputs.js";
-import { listNamespaces } from "../../lib/repos/catalog.js";
-import { INDENT, describeCoverage } from "../../lib/repos/catalog-display.js";
+import { loadCatalogContext } from "../../lib/repos/catalog-inputs.js";
+import { listNamespaces, narrowToInstalled } from "../../lib/repos/catalog.js";
+import {
+  INDENT,
+  describeCoverage,
+  describeIndexSource,
+  printBrowsingNotes,
+} from "../../lib/repos/catalog-display.js";
 import { renderTable, type TableColumn } from "../../utils/table.js";
+import { browsingFlags } from "../../utils/flags.js";
 import {
   blankLine,
   footer,
@@ -53,19 +61,28 @@ export default class NamespaceList extends BaseCommand {
    */
   static aliases = ["namespaces:list"];
 
-  static examples = ["<%= config.bin %> namespace list"];
+  static examples = [
+    "<%= config.bin %> namespace list",
+    "<%= config.bin %> namespace list --installed",
+  ];
 
-  static flags = { ...BaseCommand.baseFlags };
+  static flags = { ...BaseCommand.baseFlags, ...browsingFlags() };
 
   async run(): Promise<void> {
-    await this.parse(NamespaceList);
+    const { flags } = await this.parse(NamespaceList);
 
     showCommandVars({
       Project: this.projectLabel,
       Config: this.configContext.configPath,
+      Reading: describeIndexSource(flags.latest),
+      ...(flags.installed ? { Showing: "only what this project has installed" } : {}),
     });
 
-    heading("Namespaces in the repositories this project trusts");
+    heading(
+      flags.installed
+        ? "Namespaces this project has installed recipes from"
+        : "Namespaces in the repositories this project trusts"
+    );
 
     const service = subscriptionServiceFor({
       configContext: this.configContext,
@@ -73,13 +90,21 @@ export default class NamespaceList extends BaseCommand {
       shellEnv: this.shellEnv,
     });
 
-    const { inputs, notFetched } = catalogContextFor({
+    const { inputs, notFetched, notChecked } = await loadCatalogContext({
       service,
       sousDir: this.configContext.sousDir,
       settings: this.settings,
+      latest: flags.latest,
     });
 
-    const listings = listNamespaces(inputs);
+    // Narrowed to what is installed, a namespace's recipe count is the number
+    // of its recipes the project has installed, and the column says so.
+    const listings = listNamespaces(flags.installed ? narrowToInstalled(inputs) : inputs);
+    const columns = flags.installed
+      ? COLUMNS.map((column) =>
+          column.key === "recipes" ? { ...column, header: "Installed" } : column
+        )
+      : COLUMNS;
 
     blankLine();
 
@@ -88,7 +113,9 @@ export default class NamespaceList extends BaseCommand {
         inputs.repos.length === 0
           ? "Sous has read no repository index for this project, so there are no " +
             "namespaces to show."
-          : "The repositories this project trusts publish no namespaces."
+          : flags.installed
+            ? "This project has installed no recipe from the repositories it trusts."
+            : "The repositories this project trusts publish no namespaces."
       );
     } else {
       const rows = listings.map((entry) => ({
@@ -99,18 +126,12 @@ export default class NamespaceList extends BaseCommand {
         description: entry.description ?? "no description published",
       }));
 
-      for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+      for (const line of renderTable(columns, rows, { indent: INDENT })) {
         log(indent(line, INDENT));
       }
     }
 
-    if (notFetched.length > 0) {
-      blankLine();
-      paragraph(
-        `These repositories are trusted and their index has not been fetched yet, so ` +
-          `nothing in them is listed: ${notFetched.join(", ")}.`
-      );
-    }
+    printBrowsingNotes({ notFetched, notChecked });
 
     footer();
   }