@sous-io/sous 0.2.28 → 0.2.30

package/docs/markdown/_sidebar.md

@@ -26,4 +26,6 @@
   - [0005: Follow-ups from the first project on the hand-off](adrs/0005-first-project-follow-ups.md)
   - [0006: `sous repo init` follows `sous-recipes`](adrs/0006-repo-init-model-home.md)
   - [0007: Frozen index entries and tolerant readers](adrs/0007-frozen-index-dependencies.md)
+  - [0008: One ref parser, told where the ref came from](adrs/0008-one-ref-parser.md)
   - [0009: One whole build, everywhere](adrs/0009-whole-build-everywhere.md)
+  - [0010: The index describes each version's dependencies and questions](adrs/0010-index-describes-recipes.md)

package/docs/markdown/commands.md

@@ -347,8 +347,9 @@ optionally carrying an `@<range>` and a `repo:` qualifier; see
 ### `sous subscription add REF`
 Subscribes this project to a recipe, or to a whole namespace of them, then builds the project so the recipe's
 files are on disk when the command returns. Also spelled `sous subscribe`. Takes `-y, --yes`, `--no-build`, and
-`--dry-run`, which also prints the questions of every recipe this machine already holds; a recipe not held here
-yet is named instead, because a dry run downloads nothing.
+`--dry-run`, which also prints every question the recipes would ask. A dry run downloads nothing, so a recipe
+not on this machine is described from its repository's index; one whose index entry predates the release that
+began recording questions there is named instead.
 
 - `--prerelease`: let prerelease versions take part in range matching.
 - `--always-pull`: install a newer in-range version whenever one exists, rather than holding the lock.
@@ -409,10 +410,13 @@ Lists the recipes the trusted repositories publish, across every namespace, with
 `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
-declared and as resolved at release time, the questions it asks with the environment variable each answer is
-stored under, and the directories its files are written into. `REF` is `namespace/recipe`, a recipe name alone,
-or either with a `repository:` qualifier. Example: `sous recipe show sous-recipes:core/about-sous`
+Describes one recipe completely: its repository and location, every published version, its dependencies (the
+manifest entry bringing each one in, such as a whole namespace, whether it is a co-subscription or a build
+dependency, and the version it was released against), every recipe a subscription to it would install, every
+question that would ask, laid out as `sous subscription add --dry-run` lays them out, and the directories its
+files are written into. Everything but the files comes from the index, so a recipe nothing has installed yet
+is described in full, offline. `REF` is `namespace/recipe`, a recipe name alone, or either with a
+`repository:` qualifier. Example: `sous recipe show omakase/house`
 
 ## lock
 

package/docs/markdown/repositories-authoring.md

@@ -151,19 +151,23 @@ depends:
   - workflow/qa-helper                                       # a sibling, released alongside me
   - workflow/qa-helper@^1.1                                  # a sibling with a range; uncommon
   - github://sous-io/sous-recipes/workflow/sat@^1.0          # another repository
-  - gitlab://gitlab.example.com/group/subgroup/proj/qa/lint  # a self-hosted host, with subgroups
+  - gitlab://gitlab.example.com/group/subgroup/proj/-/qa/lint  # a self-hosted host, with subgroups
+  - https://github.com/acme/recipes/tree/main/recipes/lint     # a URL copied from the browser
 subscribes:
   - quality/code-review                                      # co-subscribed: its files land too
 ```
 
 A **bare ref** is a sibling in this repository; with no range it means "the version released alongside me", since
-one run cuts both tags and records the exact version in the index. A locator URL names another repository,
-and its last two segments are always the namespace and the recipe, which is the recipe's published **identity and
-never a path on disk**: a recipe stored at `recipes/shared/sat/` and published as `workflow/sat` is written
-`github://owner/repo/workflow/sat`. Everything before them is the repository, a dotted first segment naming the
-host. The optional range after `@` follows npm's rules. `local://` locators and `repo:` short names are refused:
-a local repository is a consumer's convenience, and a short name is one project's private label. See
-[Dependencies named by location](repositories-file-formats.md#dependencies-named-by-location).
+one run cuts both tags and records the exact version in the index. A location names another repository: a
+locator, an HTTPS or SSH URL, or a URL copied from the browser. A ref is stored and printed as its published
+**identity** (namespace and recipe), never as a folder path. Any spelling that settles to one identity is
+accepted, including a folder path or a pasted browser URL: a recipe stored at `recipes/shared/sat/` and
+published as `workflow/sat` may be written `github://owner/repo/workflow/sat` or
+`https://github.com/owner/repo/tree/main/recipes/shared/sat`, and the release settles the second through the
+other repository's index. The optional range after `@` follows npm's rules. `local://` locators and `repo:`
+short names are refused: a local repository is a consumer's convenience, and a short name is one project's
+private label. See [Dependencies named by location](repositories-file-formats.md#dependencies-named-by-location)
+and every accepted spelling in [Ref forms](repositories-file-formats.md#ref-forms).
 
 ## Cut a release
 
@@ -239,9 +243,13 @@ this release's scope** is fine: the release depends on the last published versio
 ```
 
 Each version's resolved dependencies are written into the index, so a consumer installing that version gets what
-it was published with rather than ranges re-resolved months later. A published version never changes: its content
-hash and its dependencies are carried forward exactly as published, and a disagreement is an error telling you
-to bump rather than republish ([what is checked](repositories-file-formats.md#sousindexjson)). A version counts
+it was published with rather than ranges re-resolved months later. Each dependency also records the manifest
+entry that brought it in and whether it is a co-subscription or a build dependency, and each version records the
+variable definitions its manifest publishes, so `sous recipe show` and `sous subscription add --dry-run` can say
+what a recipe installs and asks before anything is fetched. A published version never changes: its content
+hash, its dependencies and its variable definitions are carried forward exactly as published, and a
+disagreement is an error telling you to bump rather than republish
+([what is checked](repositories-file-formats.md#sousindexjson)). A version counts
 as published once its tag exists, and the tags are the backstop, so a tagged version missing from the index is
 rebuilt from it, dependencies included, whenever the index is regenerated, which only happens on a run that
 publishes something. A bump edits the manifest in place, so comments, field order and layout survive; a folded

package/docs/markdown/repositories-consuming.md

@@ -65,37 +65,57 @@ The cache can be behind what a repository has published since. Every one of thes
 `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.
+Read `sous recipe show` before subscribing. It works offline, from the index alone: every published
+version, what the version depends on (the manifest entry that brings each dependency in, whether it
+is a co-subscription whose files land here or a build dependency, and the version it was released
+against), every recipe a subscription would install, and every question that would ask. Only the
+files it publishes wait until it is installed. A preset set, a recipe that only bundles others,
+reads like this:
 
 ```term
-$ sous recipe show workflow/qa-variables
-    Latest version : 0.1.0
+$ sous recipe show omakase/house
+    Latest version : 1.0.0
     Pinned version : this project pins none
     Subscribed     : no
-  Dependency          Declared as                     Resolved to  Repository       Kind
-  ------------------  ------------------------------  -----------  ---------------  ----------------
-  workflow/qa-helper  not declared in the manifest    0.1.0        this repository  unknown
-  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.
+  Dependency       Declared as                     Resolved to  Repository       Kind
+  ---------------  ------------------------------  -----------  ---------------  ----------------
+  tools/lint       tools/lint                      1.0.0        this repository  build dependency
+  workflow/notes   the whole 'workflow' namespace  1.0.0        this repository  co-subscription
+  workflow/review  the whole 'workflow' namespace  1.0.0        this repository  co-subscription
+➔ What subscribing asks you:
+  These recipes ask 3 questions, 3 of which nothing answers yet.
+  workflow/notes asks 1 question:
+    notesDir
+      about       : Where the notes skill keeps its notes.
+      stored-as   : SOUS_VAR_NOTES_DIR
+      answered    : no, and this recipe requires an answer
 ```
 
+?> A recipe released before sous recorded questions in the index is described from its files
+instead, so its questions are listed once it is installed, and named as unknown until then.
+
 ## Subscribe to a recipe
 
 ```bash
 sous subscription add workflow/qa-variables
 sous subscription add workflow/qa-variables@^1.2.0
 sous subscription add workflow          # a whole namespace
+sous subscription add https://github.com/acme/recipes/tree/main/recipes/workflow/alpha
 ```
 
+A ref may be written in any form sous reads ([Ref forms](repositories-file-formats.md#ref-forms)),
+including a URL copied from the browser. A location is matched to the trusted repository at it,
+whatever this project calls that repository; one the project does not trust yet goes through the
+trust question first, and nothing is fetched from it before the answer. The subscription is
+recorded in its canonical form, `namespace/recipe`.
+
 The whole dependency closure resolves before anything is downloaded, and only then is anything
 written; an install is whole or not at all.
 
 | Flag | What it does |
 |------|--------------|
 | `-y, --yes` | Answer yes to both questions this command can ask: the subscribe confirmation, and the trust question for a repository it has to add |
-| `--accept-first` | When a one-word ref matches several things, take the first one listed |
+| `--accept-first` | When a ref matches several things, take the first one listed |
 | `--answer <name>=<value>` | Answer one question ahead of time. Repeat it per answer, or read a whole file of them with `--answers-file <path>` |
 | `--always-pull` | Install a newer in-range version whenever one exists, rather than holding the locked one |
 | `--dry-run` | Print what would be installed, writing and downloading nothing |
@@ -199,8 +219,9 @@ stored value nothing reads. Names are camelCase, as the recipe declares them; th
 `namespace/recipe.name` key works too when two recipes publish the same name, and everything after
 the first `=` is the answer. `--answers-file answers.yaml` reads a YAML or JSON file of them.
 
-?> A dry run downloads nothing, so a recipe your machine does not hold yet has no manifest to read
-and its questions cannot be listed; the run still succeeds and names them.
+?> A dry run downloads nothing. A recipe your machine does not hold yet is described from the
+questions its repository's index records; one released before sous recorded questions there cannot
+be, so the run still succeeds and names it.
 
 ## See what you have
 

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

@@ -104,15 +104,60 @@ release itself is never restricted, so whatever publishes the recipe still relea
 
 ### Dependencies named by location
 
-`depends` and `subscribes` share one grammar in two spellings: `workflow/qa-helper` is a sibling in this
+`depends` and `subscribes` name their targets by where they live: `workflow/qa-helper` is a sibling in this
 same repository, and `github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0` is a recipe in
-another one. A locator URL's scheme is the provider's identifier (`github` and `gitlab` ship today), and its
-path is read from the RIGHT: the last two segments are the namespace and the recipe, and everything before
-them names the repository, whose first segment is the host when it carries a dot and otherwise the
-provider's public host, so `gitlab://gitlab.example.com/group/subgroup/project/workflow/task-files`
-resolves. A trailing `.git` is dropped and at most one `@` range may follow. A manifest may write no `repo:`
-qualifier, no `local://` locator (a local repository is a convenience, not a published location) and no
-filesystem path such as `../qa-helper`.
+another one. Every spelling in [Ref forms](#ref-forms) that names a namespace or a recipe is accepted here,
+except a `repo:` qualifier (one project's private name for a repository), a local path or `local://`
+locator (a convenience, not a published location), and a location naming a whole repository with nothing
+inside it. Names are recorded lowercase.
+
+A ref is stored and printed as its published identity (namespace and recipe), never as a folder path. Any
+spelling that settles to one identity is accepted, including a folder path or a pasted browser URL. Two
+spellings need the other repository's index to settle: a GitLab URL with nested groups, which does not say
+where the project path ends (`gitlab.com/a/b/c/d` may be project `a/b` naming the recipe `c/d`, or project
+`a/b/c` naming the namespace `d`), and a browser URL, which names a folder. `sous repo release` settles each
+by fetching the index of every candidate repository and keeping the reading whose index publishes what was
+named, then records the repository it settled on in the index, beside each key the dependency reached. A
+consumer reads that record and never probes. A network failure fails the release rather than guessing, and
+two readings that both publish what is named fail it too, naming the spellings that read one way:
+`gitlab://a/b/c/-/d/*` for the namespace, `gitlab://a/b/-/c/d` for the recipe.
+
+### Ref forms
+
+Every place a ref is written reads it with one parser, told where the ref came from. These forms are
+recognized everywhere; the table after them says which each place allows. A refused form is an error saying
+what to write there instead.
+
+| Form | Example | Names |
+| --- | --- | --- |
+| A bare name | `workflow` | a namespace (on the command line, also a recipe or anything else by that name) |
+| Namespace and recipe | `workflow/alpha` | a recipe |
+| Namespace, spelled out | `workflow/*` | a namespace |
+| Repository-qualified | `sous-recipes:workflow/alpha` | a recipe in the repository this project calls `sous-recipes` |
+| With a range | `workflow/alpha@^1.2` | a recipe, within an npm-style range |
+| Provider-scheme locator | `github://owner/repo/workflow`, `.../workflow/*`, `.../workflow/alpha` | a namespace or a recipe in that repository |
+| A host other than the provider's own | `gitlab://gitlab.example.com/group/proj/-/workflow/alpha` | the same, on a self-hosted instance |
+| HTTPS URL | `https://github.com/owner/repo/workflow/alpha` | the same as the locator |
+| URL with no scheme | `github.com/owner/repo/workflow/alpha` | the same |
+| SSH remote | `git@github.com:owner/repo.git`, `ssh://git@github.com/owner/repo.git/workflow` | the repository, or something inside it |
+| Browser URL | `https://github.com/owner/repo/tree/main/recipes/workflow/alpha` | the recipe whose index `path` holds that folder (or a file in it); a folder holding one namespace's recipes names the namespace |
+| GitLab separator | `https://gitlab.com/group/sub/proj/-/tree/main/recipes/workflow/alpha` | the same, with `/-/` marking where the project path ends |
+| GitLab nested group | `gitlab://group/sub/proj/workflow/alpha` | every reading the path allows, settled as described above |
+
+A `.git` suffix on the repository is dropped in every URL form. GitLab's canonical locator always marks the
+end of the project path with `/-/`, so it reads one way.
+
+| Place | Allows |
+| --- | --- |
+| The command line | every form; names in any case |
+| A config file's subscription keys | `namespace` or `namespace/recipe`, lowercase; the repository is recorded in the lockfile and a range in the entry's `range` field |
+| A recipe manifest's `depends` and `subscribes` | every form naming a namespace or a recipe, except `repo:` and a local location |
+| A key sous stores (the lockfile, the index, the store) | `namespace` or `namespace/recipe`, lowercase |
+
+Matching tries the exact spelling first, then ignores case; a name that still matches several things is a
+question, answered by `--accept-first` or by choosing. What sous writes (config layers, the lockfile, the
+index) and prints is always the canonical form: `namespace/recipe`, qualified with the repository's short
+name where one is needed.
 
 ### Variable definitions
 
@@ -156,8 +201,16 @@ fetches only this file; nothing more is downloaded until a project subscribes.
   "namespaces": { "quality": { "description": "Recipes that exercise the edges." } },
   "recipes": { "quality/qa-remote-dep": { "path": "recipes/quality/qa-remote-dep",
     "versions": { "0.1.0": {
-      "dependencies": { "workflow/qa-helper": { "version": "0.1.0" },
-        "workflow/sub-agent-delegation": { "range": "^1.0", "repo": "github.com/sous-io/sous-recipes" } },
+      "dependencies": {
+        "workflow/qa-helper": { "version": "0.1.0", "declared": "workflow", "kind": "subscribes" },
+        "workflow/sub-agent-delegation": { "range": "^1.0", "repo": "github.com/sous-io/sous-recipes",
+          "declared": "github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0",
+          "kind": "depends" } },
+      "depends": [ "github://sous-io/sous-recipes/workflow/sub-agent-delegation@^1.0" ],
+      "subscribes": [ "workflow" ],
+      "variables": [ { "name": "qaNotesDir", "type": "path", "prompt": "Where should notes go?",
+        "description": "The directory QA notes are written to.", "example": "docs/qa",
+        "default": ".sous/qa-notes", "required": true, "secret": false, "scope": "shared" } ],
       "hash": "sha256-46e75442aeb368116c8830ad382707759f1ecd03974c4b5d42a5fabffce0324f",
       "prerelease": false, "releasedAt": "2026-09-12T07:06:33.236Z",
       "tag": "quality/qa-remote-dep@0.1.0"
@@ -171,12 +224,30 @@ fetches only this file; nothing more is downloaded until a project subscribes.
 | `recipes` | top level | Keyed `namespace/recipe`; a recipe whose namespace is not declared is an error. Each entry carries `path` (the recipe folder), `description`, and `versions`, keyed by exact version |
 | `hash`, `tag` | per version | The content hash verified after every fetch, and the tag, which must be exactly `namespace/recipe@version` so a version can never point at a branch |
 | `prerelease`, `releasedAt`, `seeded` | per version | Whether ranges skip it unless a subscription opts in, when it was released, and whether it is the copy sous folds in from its own package |
+| `dependencies` | per version | What the version was released against, keyed `namespace/recipe`; see below |
+| `variables` | per version | The version's variable definitions, exactly as its manifest publishes them (see [Variable definitions](#variable-definitions)), with `required`, `secret` and `scope` filled in; `[]` when it asks nothing |
+| `depends`, `subscribes` | per version | The version's manifest lists, exactly as written; `[]` when empty |
 
 Dependencies are resolved at release time and keyed `namespace/recipe`. An entry carries `version` (a
 sibling, resolved exactly) or `range` plus `repo` (the identity of the repository publishing it, whose own
 index resolves the range); at least one is required. Installing a version installs these rather than
 re-resolving the manifest's ranges.
 
+**Each version describes itself.** So that a recipe can be described before anything is fetched, every
+version a release records carries more than its dependencies. Each dependency records `declared`, the
+manifest entry that brings it in exactly as written (a recipe such as `workflow/qa-helper@^1.0`, a whole
+namespace such as `workflow`, or a locator), and `kind`: `subscribes` for a co-subscription, whose files
+land and whose questions are asked, or `depends` for a build dependency. When several entries cover one
+recipe, an entry naming it wins over a namespace, and it is a co-subscription when any entry covering it is
+one. The version records `variables`, its manifest's definitions, and `depends` and `subscribes`, its
+manifest's lists as written; the lists are what a consumer walks, because a namespace of another repository
+has no recipe key to record it under. All of them are written even when empty (`"dependencies": {}`,
+`"variables": []`), so "none" reads differently from "not recorded". From these, `sous recipe show` and
+`sous subscription add --dry-run` list everything a subscription installs and every question it asks, and
+the resolver walks a recipe whose files are not on the machine from its index entry just as it would walk
+its manifest. A version recorded before a release wrote these fields keeps its entry as it is; its questions
+are known only once its files are fetched, and the dry run names it as such.
+
 **A published version's entry is frozen.** Its dependencies are resolved once, when the version is first
 recorded, and every later release carries the entry forward exactly as published, like its hash; releasing
 other recipes, adding a recipe to a namespace it subscribes to, or raising a sibling it names changes nothing
@@ -189,9 +260,13 @@ against the repository as it stood at that tag, then frozen the same way. An ent
 recorded dependencies carries none, stays that way, and installs by resolving its manifest's ranges.
 
 **Fields this sous does not know are kept, not refused.** A later sous may add fields to the index, at any
-level. This one reads such an index, validates every field it defines as strictly as before, and ignores the
-rest; a release it runs carries a published version's entry forward with those fields intact. A sous older
-than the one that began tolerating unknown fields refuses the whole index once a repository publishes one.
+level, recorded variable definitions included. This one reads such an index, validates every field it
+defines as strictly as before, and ignores the rest; a release it runs carries a published version's entry
+forward with those fields intact.
+
+!> A sous older than 0.2.26, the first to tolerate unknown fields, refuses the whole index of any
+repository released with `declared`, `kind`, `variables`, `depends` or `subscribes` in it, the official
+one included. A project pinned to such a sous fails to read that index until it moves to 0.2.26 or later.
 
 **The `seeded` field.** Sous ships the `core` recipe in its own npm package, so a project can build before
 reaching the network. That copy is folded into the official repository's index in memory and resolved like

package/docs/markdown/repositories-providers.md

@@ -128,12 +128,14 @@ Canonicalizing also produces the two clone URLs sous hands to git, `https://<hos
 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).
+?> A published manifest names a dependency in another repository by location, such as a locator
+whose scheme is the provider's identifier: `github://sous-io/sous-recipes/workflow/sat@^1.1`. A
+first segment containing a dot is read as the host, so `gitlab://gitlab.example.com/group/project/-/ns/recipe`
+addresses a self-hosted instance; without one, the provider's public host is assumed. Where a
+repository path ends, and what a browser URL's path looks like, is each provider's own rule (its
+`readLocation`), so a URL copied from either host's file view works too. `local://` is refused,
+because a path on your disk is not a published location. Every form is in
+[Ref forms](repositories-file-formats.md#ref-forms).
 
 ## Private repositories
 

package/docs/markdown/repositories-troubleshooting.md

@@ -108,8 +108,14 @@ providers sous ships named (see [Providers](repositories-providers.md)). The leg
 depends:
   - workflow/sat                                       # a sibling in this repository
   - github://acme/recipes/workflow/sat@^1.1            # a recipe in another repository
+  - https://github.com/acme/recipes/tree/main/sat      # the same, copied from the browser
 ```
 
+Every accepted spelling is in [Ref forms](repositories-file-formats.md#ref-forms). A GitLab URL
+with nested groups, or a browser URL, is settled by `sous repo release` through the other
+repository's index; when that index cannot be read, the release stops and names it, and when two
+readings both publish what was named, it names the `/-/` and `/*` spellings that read one way.
+
 While developing both sides, use
 [`sous repo link`](repositories-authoring.md#edit-a-repository-in-place); it redirects resolution
 at a working copy without changing what you publish.

package/docs/markdown/repositories-variables.md

@@ -12,7 +12,10 @@ a separate, ceremony-free system; see [Variables](config-variables.md). The two
 
 A definition ships inside the recipe that needs it, in its manifest's `variables:` array, so it versions,
 resolves, pins and trusts like the rest of the recipe; every field it can carry is listed in
-[Variable definitions](repositories-file-formats.md#variable-definitions).
+[Variable definitions](repositories-file-formats.md#variable-definitions). `sous repo release` also copies
+each version's definitions into the repository's index, which is how `sous recipe show` and
+`sous subscription add --dry-run` list a recipe's questions before its files are on your machine. The index
+holds definitions only, never an answer; answers come from the ladder below and nowhere else.
 
 A definition is in play when your lockfile pins the recipe that declares it, whether you subscribed to that
 recipe or a dependency pulled it in. A recipe the store does not hold yet contributes nothing rather than
@@ -241,10 +244,17 @@ sous vars ask SOUS_VAR_TASK_FILE_ROOT           # the same one, by a name in use
 sous vars ask workflow/task-files.taskFileRoot  # the same one, spelled out in full
 sous vars ask task-files                        # every question one recipe asks
 sous vars ask sous-recipes                      # every question that repository's recipes ask
+sous vars ask https://github.com/sous-io/sous-recipes/tree/main/recipes/workflow/task-files
+                                                # the same recipe, as a URL copied from the browser
 ```
 
-Matching is case-sensitive, and an environment variable name resolves when a definition declares it or an
-env file sets it. `--repo`, `--namespace` and `--var` say which kind is meant, each narrowing what the one
+A repository, namespace or recipe may be written in any form in
+[Ref forms](repositories-file-formats.md#ref-forms), including a location: it is matched to the
+trusted repository at it and settled through that repository's cached index, then narrowed to the
+variables it covers. `--repo` and `--namespace` accept a location the same way.
+
+Matching tries the exact spelling first, then ignores case; a name that still matches several things is a
+question. An environment variable name resolves when a definition declares it or an env file sets it. `--repo`, `--namespace` and `--var` say which kind is meant, each narrowing what the one
 before left, so `sous vars ask --namespace workflow apiUrl` asks about that namespace's `apiUrl` alone. When
 a name matches several things, sous lists them and asks; `--accept-first` takes the first, and a run with no
 terminal fails naming it.

package/docs/markdown/repositories.md

@@ -101,9 +101,9 @@ subscribes:
   - quality/code-review
 ```
 
-Both name their targets by location, written as a **locator URL**
-([the grammar](repositories-file-formats.md#dependencies-named-by-location)) when the target lives
-in another repository, never by a short name a consuming project chose; a curated bundle is simply
+Both name their targets by location, written as a **locator URL** or any other URL form
+([the forms](repositories-file-formats.md#ref-forms)) when the target lives in another repository,
+never by a short name a consuming project chose; a curated bundle is simply
 a recipe made mostly of `subscribes` entries. Because both lists are
 declarative YAML rather than code, sous can read the whole dependency closure before fetching any
 of it, which is what makes the trust decision answerable up front.

package/package.json

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

package/recipes/core/sous-skills/skills/about-sous-recipes/SKILL.tpl.md

@@ -138,13 +138,17 @@ Both lists name other recipes, and they do different things:
 - `subscribes` is a **co-subscription**. The other recipe's files land and its questions are asked,
   as if the project had subscribed to it too.
 
-Each entry names its target by where it lives, in one of two forms:
-
-- a bare `namespace/recipe` for a sibling in the same repository. With no range it means the
-  version released alongside this one; an `@` range (npm's rules) is allowed but uncommon.
-- a locator URL for a recipe in another repository, such as
-  `github://example-org/team-recipes/review/wording@^1.0`. The scheme is the provider, and the last
-  two segments are always the recipe's namespace and name, never a path on disk.
+Each entry names its target by where it lives:
+
+- a bare `namespace/recipe` (or `namespace` for all of it) for a sibling in the same repository.
+  With no range it means the version released alongside this one; an `@` range (npm's rules) is
+  allowed but uncommon.
+- a location for a recipe in another repository, such as
+  `github://example-org/team-recipes/review/wording@^1.0`, an HTTPS or SSH URL, or a URL copied
+  from the browser. A ref is stored and printed as its published identity (namespace and recipe),
+  never as a folder path. Any spelling that settles to one identity is accepted, including a
+  folder path or a pasted browser URL; `sous repo release` settles one that needs the other
+  repository's index, and fails rather than guess.
 
 `local://` locators and `repo:` short names are refused: both are one project's private view of a
 repository, and a published manifest is read everywhere.

package/recipes/core/sous-skills/skills/about-sous-repos/SKILL.tpl.md

@@ -65,10 +65,13 @@ contribute: https://github.com/harbor-labs/team-recipes/blob/main/CONTRIBUTING.m
 A recipe's version lives in its manifest, which is the source of truth. A version is **published**
 once a git tag shaped `namespace/recipe@version` exists for it (for example
 `review/checklist@1.2.0`). The index records each published version with its content hash, its
-tag and the exact versions of its dependencies at release time; for the length of one release
-commit it also records the version each manifest declares, whose tag that release cuts next. A
-published version never changes: new files need a new version, and a release refuses to publish
-different content under a version already tagged. A lost index is rebuilt from the tags.
+tag, the exact versions of its dependencies at release time (each with the manifest entry that
+brought it in and whether it is a co-subscription or a build dependency) and the variable
+definitions it publishes, which is how a project lists what a recipe installs and asks before
+fetching it; for the length of one release commit it also records the version each manifest
+declares, whose tag that release cuts next. A published version never changes: new files need a
+new version, and a release refuses to publish different content under a version already tagged. A
+lost index is rebuilt from the tags.
 
 ## Releasing
 

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

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

package/src/commands/lock/rebuild.ts

@@ -24,7 +24,7 @@ import { recipeFilesDirectory } from "../../lib/repos/catalog-inputs.js";
 import { readRecipeManifestIn } from "../../lib/repos/locked-recipes.js";
 import { createEmptyLockfile } from "../../lib/repos/formats/lockfile.js";
 import type { LockRepoInput } from "../../lib/repos/lock-service.js";
-import { parseRef } from "../../lib/repos/ref.js";
+import { RefSource, parseShortRef } from "../../lib/refs/index.js";
 import {
   PROJECT_REQUESTER,
   resolveRefs,
@@ -133,7 +133,7 @@ export default class LockRebuild extends BaseCommand {
       .sort()
       .map((key) => {
         const entry = subscriptions[key]!;
-        const parsed = parseRef(key);
+        const parsed = parseShortRef(key, RefSource.Config);
         return {
           ref: {
             ...parsed,
@@ -150,7 +150,8 @@ export default class LockRebuild extends BaseCommand {
       repos,
       // A recipe's own manifest is what names its dependencies, and it is read
       // from the files this machine already holds. Nothing is fetched here, so a
-      // recipe that is not in the store yet comes back under `missingManifests`.
+      // recipe that is not in the store yet is walked from what its index entry
+      // records, and comes back under `missingManifests` when that is nothing.
       loadManifest: (recipe) => {
         const directory = recipeFilesDirectory({
           service,
@@ -208,9 +209,9 @@ export default class LockRebuild extends BaseCommand {
     if (result.missingManifests.length > 0) {
       blankLine();
       paragraph(
-        `The files of these recipes are not on this machine, so their own ` +
-          `dependencies could not be read and are not in the rebuilt lockfile: ` +
-          `${result.missingManifests.join(", ")}.`
+        `The files of these recipes are not on this machine, and their repository's ` +
+          `index does not record what they depend on, so their own dependencies are ` +
+          `not in the rebuilt lockfile: ${result.missingManifests.join(", ")}.`
       );
     }