@sous-io/sous 0.2.1 → 0.2.3

package/docs/markdown/repositories-variables.md

@@ -1,387 +1,339 @@
 # Recipe Variables
 
-A recipe that needs a value from your project publishes a **variable definition**: a
-specification with a name, a type, a question and a set of constraints. You supply an **answer**.
-A "question" is only the interactive moment; sous asks one only when a subscribed recipe needs a
-variable and nothing in scope answers it, or when the answer in scope no longer fits.
+A recipe that needs a value from your project publishes a **variable definition**: a name, a type, a question
+and a set of constraints. You supply an **answer**. A "question" is only the interactive moment: sous asks one
+when a recipe needs a variable and nothing in scope answers it, or when what is there no longer fits.
 
-?> This page is about variables that recipes publish. Your project's own `${var}` configuration
-variables are a different, older, deliberately ceremony-free system; see
-[Variables](config-variables.md) for those. The two never mix.
+?> This page is about variables that recipes publish. Your project's own `${var}` configuration variables are
+a separate, ceremony-free system; see [Variables](config-variables.md). The two meet in one place only, under
+[How a template reads an answer](#how-a-template-reads-an-answer).
 
-## Where answers live
+## What a definition is, and where it lives
 
-Answers are stored in your project's env files, and nowhere else:
+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).
 
-| File | Committed | Holds |
-|------|-----------|-------|
-| `.sous/.env` | yes | Shared answers (`scope: shared`), the team's defaults |
-| `.sous/.env.local` | no, gitignored | Machine-specific answers (`scope: local`) and every secret |
+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
+failing, so a fresh clone lists what it can until `sous build` restores the rest.
 
-Sous edits these files the way a careful person would. Exactly one value line is rewritten or
-appended; comments, blank lines, ordering and quoting all survive untouched. A newly added entry
-gets a short generated header comment above it saying where the value came from:
+A project can also ask questions no recipe publishes: write the same `variables:` array into a YAML or JSON
+file of your own and point `--file` at it. Every `sous vars` command takes that flag, and the definitions in
+it are attributed to a pseudo-recipe in the `local` namespace named after the file, so an `apiUrl` declared in
+`questions.yaml` generates `SOUS_VAR_LOCAL_QUESTIONS_API_URL`, `SOUS_VAR_LOCAL_API_URL` and `SOUS_VAR_API_URL`.
 
-```bash
-# Set by sous for workflow/task-files: Where should task files live?
-# One file per git branch is written here.
-# Edit freely; sous only rewrites the value line.
-SOUS_VAR_TASK_FILE_ROOT=.sous/tasks
-```
+!> A definition's `validate.pattern` is a regular expression published by someone else, so sous runs each
+match on a worker under a fixed budget of 100 milliseconds, and a pattern that exceeds it fails validation
+naming the pattern and the recipe rather than blaming your answer. See
+[A variable pattern that runs out of time](repositories-troubleshooting.md#a-variable-pattern-that-runs-out-of-time).
 
-Those comments are output only. Sous never reads one back, so editing or deleting a comment
-changes nothing, and editing the value line is a perfectly normal way to change an answer.
+## Answer the questions
 
-## The ladder
+Subscribing asks whatever is unanswered, so in normal use you rarely run `sous vars ask` yourself; reach for
+it after editing an env file by hand, after an upgrade tightened a constraint, or to re-answer with `--all`.
 
-For each variable, sous generates a list of environment variable names and tries them in order,
-most specific first. The first name that holds a value wins.
+Every trust decision is settled first: a subscribe resolves the dependency closure and runs the trust
+ceremony for each new repository before the first question prints. Questions then run one recipe at a time,
+the one you asked for and then each recipe it depends on, with a lead-in and per-recipe counts:
 
-| Rung | Name | Example | When it applies |
-|------|------|---------|-----------------|
-| 1. mapping record | whatever the record names | `TEAM_API_URL` | Only when a record exists for this variable |
-| 2. recipe scope | `SOUS_VAR_<NAMESPACE>_<RECIPE>_<VARIABLE>` | `SOUS_VAR_WORKFLOW_TASK_FILES_API_URL` | Answers this one recipe's variable and nothing else |
-| 3. namespace scope | `SOUS_VAR_<NAMESPACE>_<VARIABLE>` | `SOUS_VAR_WORKFLOW_API_URL` | Answers every recipe in the namespace at once |
-| 4. shared scope | `SOUS_VAR_<VARIABLE>` | `SOUS_VAR_API_URL` | Answers every recipe that declares that variable name |
-| 5. declared name | the definition's own `env` field | `GITHUB_TOKEN` | How a recipe binds a value the environment already carries |
-
-Read from the bottom up, the ladder is a story about sharing. One `SOUS_VAR_API_URL` answers
-every recipe that wants an `apiUrl`, which is what you want most of the time. When two recipes
-want the same name and mean different things, move one answer up a rung to the namespace or the
-recipe form, and the more specific name wins for that recipe alone. When even that is not enough,
-a mapping record settles it.
-
-!> Candidate names are only ever GENERATED and looked up, never parsed back into scopes. The
-underscore is both the delimiter and a legal identifier character, so no parse of a name would be
-trustworthy: `SOUS_VAR_TASK_FILES_ROOT` could be three different things. Sous therefore builds the
-five candidates it knows are correct and asks the environment about each one.
-
-## The three sources, within a rung
-
-Each rung is looked up in three places, in this order:
-
-1. **The real shell environment.** `SOUS_VAR_API_URL=... sous build` beats both files.
-2. **`.sous/.env.local`.** Gitignored; your machine, your secrets.
-3. **`.sous/.env`.** Committed; the team's shared defaults.
-
-No load ever overwrites a value that is already set, so the first writer wins. This is the same
-precedence the rest of sous uses for env files; see
-[Discovery and overrides](config-discovery.md).
-
-## Mapping records
-
-A mapping record binds one environment variable, of any name at all, to one fully qualified
-variable. It is the top rung and the universal conflict resolver: two recipes wanting the same
-name, or a name that already means something else in your environment.
-
-```json
-{
-  "varMappings": {
-    "TEAM_API_URL": "sous-recipes:misc/stuff/apiUrl"
-  }
-}
-```
+```text
+workflow/task-files needs 4 answers, and workflow/sub-agent-delegation, which it depends on, needs 2.
 
-A target is written `namespace/recipe/variableName`, optionally qualified as
-`repo:namespace/recipe/variableName`. Records live under the top-level `varMappings` config key.
-Sous writes the ones it creates into `.sous/conf.d/520-var-mappings.jsonc`, editing one record at
-a time so each name has exactly one, and you may hand-write `varMappings` in your primary config
-too; the two merge like any other config layer.
+workflow/task-files needs 4 answers before it can be used.
+```
 
-You rarely write one yourself, because sous offers one at the moment the conflict appears. When
-the name an answer would use already holds a value that does not fit the definition, you are
-asked where the answer should go:
+Each question prints its header, the publisher's description wrapped to your terminal, and four labeled facts:
 
 ```text
-SERVICE_TOKEN already holds a value that does not fit serviceToken. Where should this answer go?
-  SOUS_VAR_TOOLING_DEPLOY_SERVICE_TOKEN, with a mapping record (recommended)
-  SERVICE_TOKEN, replacing what is there
-```
-
-Choosing the record writes both the answer under the scoped name and the record binding it, and
-the run reports the pair. Where there is no terminal, the record is written, because overwriting
-a value something else is already using would be the worse of the two guesses.
+Question 1 of 4: taskFileRoot
 
-## `sous vars list`
+This recipe mandates the creation of task files that are stored locally and, in
+general, should not be committed. The default stores them in the project's .sous
+directory; any local path works, relative to the project root or absolute.
 
-Lists every variable in play: its name, the recipe that published it, the environment variable
-that answered it, the value, and where the value came from. A secret's value is hidden.
+    default     : .sous/tasks
+    example     : ~/my-task-files
+    stored-as   : SOUS_VAR_TASK_FILE_ROOT
+    storage-path: /home/you/project/.sous/.env
 
-```term
-$ sous vars list
-Variable      Recipe               Answered by          Value                     Source
-apiUrl        workflow/task-files  SOUS_VAR_API_URL     https://api.example.com   shared scope, the .env file
-taskFileRoot  workflow/task-files  SOUS_VAR_TASK_...    .sous/tasks               shared scope, the .env file
-serviceToken  tooling/deploy                                                      nothing yet
+? Where should task files be stored? (.sous/tasks):
+⏎ accept default • ⇥ advanced
 ```
 
-`--file <path>` reads definitions from a standalone definitions file instead of the project's
-recipes. The file holds the same `variables:` array a recipe manifest carries, which is how a
-project asks questions no recipe publishes yet.
+The legend under the input line names the keys that do anything: Enter accepts what is typed, or the default
+when there is one; a list question names the arrow keys instead, and a yes-or-no question the two letters.
 
-## `sous vars show <name>`
+### Tab opens the advanced view
 
-Shows one variable in full: its question, the publisher's description and example, the recipe and
-version that published it, the value in scope and whether it fits, then the same labeled facts the
-advanced view of a question prints, and finally every name on the ladder with the rung that
-actually answered.
+Tab works at every kind of question. The advanced view repeats the header and description, prints every fact
+about the variable through the renderer `sous vars show` uses, and offers a menu:
 
-```term
-$ sous vars show apiUrl
-    Question   : Which API should sous talk to?
-    About      : Every request this recipe generates is sent to one deployment of
-                 the API, and this setting says which one. The default points at
-                 the public production host, but any deployment you can reach works.
-    For example: https://api.example.com
-    Recipe     : workflow/task-files version 1.2.0 from sous-recipes
-    Stored in  : .env
-    Value      : https://api.example.com
-
-    example     : https://api.example.com
+```text
+[Advanced Variable Settings]
+
+Question 1 of 4: taskFileRoot
+
+    default     : .sous/tasks
+    example     : ~/my-task-files
     required-by : workflow/task-files https://example.com/owner/recipes/workflow/task-files
     defined-by  : workflow/task-files https://example.com/owner/recipes/workflow/task-files
     storage-path: /home/you/project/.sous/.env
-    stored-as   : SOUS_VAR_API_URL
-    constraints : • must be a value of the type url (type: url)
+    stored-as   : SOUS_VAR_TASK_FILE_ROOT
+    constraints : • must be a value of the type path (type: path)
 
-Environment variable                     Rung             Status
-SOUS_VAR_WORKFLOW_TASK_FILES_API_URL     recipe scope     not set
-SOUS_VAR_WORKFLOW_API_URL                namespace scope  not set
-SOUS_VAR_API_URL                         shared scope     answered it, from the .env file
+? What would you like to do?
+  Return to value entry
+  Change the storage file
+  Change the stored variable name
 ```
 
-`required-by` and `defined-by` are the same links the advanced view of a question shows, so the
-two views say the same thing in the same words.
+`required-by` names the recipe whose closure pulled this variable in, and spells out the chain when it
+arrived through a dependency; `defined-by` names the recipe that declares it. Both carry the location beside
+the recipe key, in muted grey: a repository URL, or a filesystem path for a repository on this machine.
 
-The name may be the bare variable name or its full `namespace/recipe.name` key, which is what you
-use when two recipes publish the same name.
+**Changing the stored variable name** offers every rung the ladder looks up, sous's choice preselected, plus
+a name you type; one the ladder never looks at is bound with a [mapping record](#when-names-collide-mapping-records).
 
-?> Three names cannot be reached by the `sous vars <name>` shorthand: `list`, `show` and `ask`,
-because each of those is a subcommand. A variable with one of those names is reached the long
-way, as `sous vars show ask`.
+**Changing the storage file** offers the committed `.sous/.env` and the gitignored `.sous/.env.local`.
+Pointing a secret, or a variable the publisher declared machine-specific, at the committed file is allowed;
+sous says what that means and asks you to confirm, which is informed consent rather than a locked door:
 
-## `sous vars ask`
+```text
+workflow/task-files declared this variable a secret, and .env is committed to git. An answer stored
+there enters your project's git history, is pushed with every clone, and is visible to everyone who
+can read the repository.
 
-Asks the questions the project's definitions imply and stores the answers.
+? Store this answer in .env anyway? (y/N)
+```
 
-| Invocation | What it does |
-|------------|--------------|
-| `sous vars ask` | Asks only what is unanswered, or what no longer fits its definition |
-| `sous vars ask <name>` | Asks everything the name covers; see the forms below |
-| `sous vars ask --repo <name>` | Asks every variable one repository publishes |
-| `sous vars ask --namespace <name>` | Asks every variable one namespace publishes |
-| `sous vars ask --var <name>` | Asks one variable; repeat it for each variable |
-| `sous vars ask --accept-first` | When the name matches several things, takes the first one listed |
-| `sous vars ask --all` | Asks every variable again, including the ones already answered |
-| `sous vars ask --file <path>` | Reads definitions from a standalone definitions file |
-| `sous vars ask --answer <name>=<value>` | Answers one question ahead of time; repeat it for each answer |
-| `sous vars ask --answers-file <path>` | Reads answers from a YAML or JSON file of `name: value` pairs |
-| `sous vars ask --dry-run` | Reports what would be asked and written, without writing anything |
+Once anything has changed, the first menu item becomes "Save changes and return to value entry" and a
+"Discard changes and return to value entry" item joins it; returning prints the question again with the
+updated facts. When an answer is entered, two lines say what was stored and where; a secret is never printed:
+
+```text
+    Answer  : SOUS_VAR_TASK_FILE_ROOT=.sous/tasks
+    Saved to: /home/you/project/.sous/.env
+```
 
-### What the name may be
+Every run ends with a three-part report: `Answers already in scope:`, `Answers stored:`, `Left unanswered:`.
 
-The name is a reference, resolved the way every sous command resolves one. It may name a
-variable, an environment variable that answers one, a recipe, a namespace or a repository, and
-anything larger than a variable asks every question it publishes:
+## Where answers are stored
 
-```term
-$ sous vars ask taskFileRoot
-// one variable, by the name its recipe gave it
-$ sous vars ask SOUS_VAR_TASK_FILE_ROOT
-// the same variable, by an environment variable in use that answers it
-$ sous vars ask workflow/task-files.taskFileRoot
-// the same variable again, spelled out
-$ sous vars ask task-files
-// every question that one recipe asks
-$ sous vars ask workflow
-// every question every recipe in that namespace asks
-$ sous vars ask sous-recipes
-// every question that repository's recipes ask
+Answers live in your project's env files, and nowhere else:
+
+| File | Committed | Holds |
+|------|-----------|-------|
+| `.sous/.env` | yes | Shared answers (`scope: shared`), the team's defaults |
+| `.sous/.env.local` | no, gitignored | Machine-specific answers (`scope: local`) and every secret |
+
+Sous edits them the way a careful person would: exactly one value line is rewritten or appended, and
+comments, blank lines, ordering and quoting survive untouched. A new entry gets a generated header comment:
+
+```bash
+# Set by sous for workflow/qa-variables: Where should a review keep its working files?
+# A run writes partial output, logs and diffs somewhere before it assembles the note.
+# Edit freely; sous only rewrites the value line.
+SOUS_VAR_QA_SCRATCH_DIR=/var/tmp/qa-review
 ```
 
-Every reference may be written at any level of qualification, up to the fully qualified
-`repository:namespace/recipe.variable`, and matching is case-sensitive. An environment variable
-name resolves when the definition declares it (a recipe may bind an existing variable such as
-`GITHUB_TOKEN`) or when it is one of the generated ladder names that `.sous/.env` or
-`.sous/.env.local` actually sets.
+Comments are output only; sous never reads one back, and editing the value line changes the answer.
 
-`--repo`, `--namespace` and `--var` say outright which kind of thing is meant, and narrow the
-same way. Each one resolves against what the one before it left, so
-`sous vars ask --namespace workflow apiUrl` asks about that namespace's `apiUrl` even when
-another namespace publishes one too.
+## How sous finds an answer: the ladder
 
-When a name matches more than one thing, sous lists what it could have meant and asks which one
-you meant. `--accept-first` takes the first one listed, and a run with no terminal fails naming
-that flag rather than guessing.
+For each variable, sous tries these names in order; the first one holding a value wins.
 
-### How the questions run
+| Rung | Name | Example | When it applies |
+|------|------|---------|-----------------|
+| 1. mapping record | whatever the record names | `TEAM_TOKEN` | Only when a record exists for this variable |
+| 2. recipe scope | `SOUS_VAR_<NAMESPACE>_<RECIPE>_<VARIABLE>` | `SOUS_VAR_WORKFLOW_QA_VARIABLES_QA_SERVICE_TOKEN` | Answers this one recipe's variable and nothing else |
+| 3. namespace scope | `SOUS_VAR_<NAMESPACE>_<VARIABLE>` | `SOUS_VAR_WORKFLOW_QA_SERVICE_TOKEN` | Answers every recipe in the namespace at once |
+| 4. shared scope | `SOUS_VAR_<VARIABLE>` | `SOUS_VAR_QA_SERVICE_TOKEN` | Answers every recipe that declares that variable name |
+| 5. declared name | the definition's own `env` field | `QA_SERVICE_TOKEN` | How a recipe binds a value the environment already carries |
 
-Every trust decision is settled first. A subscribe resolves the whole dependency closure and runs
-the trust ceremony for each new repository before the first question is printed, so a question is
-never interleaved with a decision about who you are trusting.
+Read from the bottom up, the ladder is a story about sharing. One `SOUS_VAR_API_URL` answers every recipe
+that wants an `apiUrl`, which is what you want most of the time; when two recipes want the same name and
+mean different things, move one answer up a rung and the more specific name wins for that recipe alone.
 
-Questions then run one recipe at a time: the recipe you subscribed to first, then each recipe it
-depends on, each opening with how many answers it needs. When the closure covers more than one
-recipe, a single lead-in says so before anything is asked:
+Each rung is looked up in three places, in this order: the real shell environment, then `.sous/.env.local`,
+then `.sous/.env`. So `SOUS_VAR_API_URL=... sous build` beats both files, and a machine-specific answer beats
+the team's committed default; see [Discovery and overrides](config-discovery.md).
 
-```term
-workflow/task-files needs 4 answers, and workflow/sub-agent-delegation, which it depends on, needs 2.
-```
+!> Candidate names are only ever GENERATED and looked up, never parsed back into scopes. The underscore is
+both the delimiter and a legal identifier character, so no parse would be trustworthy.
 
-Each question then prints its own view: the header, the publisher's description wrapped to your
-terminal, and four labeled facts (the default, the example, and exactly where the answer will be
-stored and under what name). The keys that do anything are named by the legend the question draws
-under its own input line, in the style the stock prompts use. Those facts are drawn by the renderer
-the advanced view uses, so the same label means the same thing and lines up the same way on both.
+`sous vars show` prints the whole ladder, which is the fastest way to see why an answer did or did not take
+effect. Here `qaServiceToken` declared `env: QA_SERVICE_TOKEN`, so the bottom rung is that name:
 
 ```term
-workflow/task-files needs 4 answers before it can be used.
+$ sous vars show qaServiceToken
+➔ Environment variables sous looks at, most specific first:
+
+  Environment variable                             Rung             Status
+  -----------------------------------------------  ---------------  -------------
+  SOUS_VAR_WORKFLOW_QA_VARIABLES_QA_SERVICE_TOKEN  recipe scope     not set
+  SOUS_VAR_WORKFLOW_QA_SERVICE_TOKEN               namespace scope  not set
+  SOUS_VAR_QA_SERVICE_TOKEN                        shared scope     not set
+  QA_SERVICE_TOKEN                                 declared name    not set
+```
 
-Question 1 of 4: taskFileRoot
+## When names collide: mapping records
 
-This recipe mandates the creation of task files that are stored locally and, in
-general, should not be committed. This setting dictates the path in which agents
-will store and search for your task files. The default value stores task files in
-the project's .sous directory, but you can specify any local path, either relative
-to the project root or absolute.
+A mapping record binds one environment variable, of any name at all, to one fully qualified variable. It is
+the top rung and the universal conflict resolver: two recipes wanting the same name, or a name already in use.
 
-    default     : .sous/tasks
-    example     : ~/my-task-files
-    stored-as   : SOUS_VAR_TASK_FILE_ROOT
-    storage-path: /home/you/project/.sous/.env
+You rarely write one by hand, because sous offers one when the conflict appears: when the name an answer
+would use already holds a value that does not fit the definition, you are asked where the answer should go:
 
-? Where should task files be stored? (.sous/tasks):
-⏎ accept default • ⇥ advanced
+```text
+? SERVICE_TOKEN already holds a value that does not fit serviceToken. Where should this answer go?
+> SOUS_VAR_TOOLING_DEPLOY_SERVICE_TOKEN, with a mapping record (recommended)
+  SERVICE_TOKEN, replacing what is there
 ```
 
-Enter accepts what is typed, or the default when nothing is. A question with no default drops
-the Enter half of the legend, since there is nothing for Enter alone to accept, and shows
-`⇥ advanced` alone. A question answered from a list rather than typed names the arrow keys
-instead:
+Choosing the record writes both the answer under the scoped name and the record binding it, and the run
+reports the pair. Where there is no terminal the record is written, since overwriting a value in use is worse.
 
-```term
-? Which ticket system do you use?
-> github
-  jira
-  linear
-↑↓ navigate • ⏎ select • ⇥ advanced
-```
+Sous writes the records it creates into `.sous/conf.d/520-var-mappings.jsonc`, one at a time, so each name
+has exactly one. The record's shape and the rest of the managed layers are under
+[Configuration keys](repositories-file-formats.md#configuration-keys) and
+[Managed config layers](repositories-file-formats.md#managed-config-layers); hand-write one if you prefer.
 
-Tab opens the advanced view from every kind of question: a typed one, a pick-one list, and a
-yes-or-no confirmation alike. The word is always "Advanced". Once an answer is stored, two lines
-say what was stored and where:
+## See and answer variables from the command line
+
+`sous vars list` prints every variable in play, what answered it, and where the value came from.
 
 ```term
-    Answer  : SOUS_VAR_TASK_FILE_ROOT=.sous/tasks
-    Saved to: /home/you/project/.sous/.env
+$ sous vars list
+  Variable        Recipe                 Answered by              Value           Source
+  --------------  ---------------------  -----------------------  --------------  --------------------------------
+  qaScratchDir    workflow/qa-variables  SOUS_VAR_QA_SCRATCH_DIR  /var/tmp/qa     shared scope, the .env.local file
+  qaServiceToken  workflow/qa-variables                           (unanswered)    nothing yet
+  qaTaskRoot      workflow/qa-variables  SOUS_VAR_QA_TASK_ROOT    .sous/qa-notes  shared scope, the .env file
 ```
 
-An answer that was already in scope is never asked about again; it is reported with its scope and
-its source instead.
+`sous vars show <name>` prints one variable in full: the question, the publisher's description and example,
+the recipe and version that published it, the value in scope and whether it fits, the labeled facts the
+advanced view draws, and the ladder table above. The name may be bare or the full `namespace/recipe.name`.
 
-### The advanced view
+`sous vars ask [name]` asks the questions the definitions imply and stores the answers.
 
-Tab opens the advanced view of the same question: every fact about the variable, laid out by the
-same renderer `sous vars show` uses, and a menu for changing where the answer goes.
+| Invocation | What it does |
+|------------|--------------|
+| `sous vars ask` | Asks only what is unanswered, or what no longer fits its definition |
+| `sous vars ask <name>` | Asks everything the name covers; see the forms below |
+| `sous vars ask --repo <name>` | Asks every variable one repository publishes |
+| `sous vars ask --namespace <name>` | Asks every variable one namespace publishes |
+| `sous vars ask --var <name>` | Asks one variable; repeat the flag for each one |
+| `sous vars ask --all` | Asks every variable again, including the ones already answered |
+| `sous vars ask --accept-first` | When the name matches several things, takes the first one listed |
+| `sous vars ask --file <path>` | Reads definitions from a standalone definitions file |
+| `sous vars ask --answer <name>=<value>` | Answers one question ahead of time; repeat it for each answer |
+| `sous vars ask --answers-file <path>` | Reads answers from a YAML or JSON file of `name: value` pairs |
+| `sous vars ask --dry-run` | Reports what would be asked and written, without writing anything |
+| `sous vars ask --non-interactive` | Never asks; fails instead, naming the environment variable or flag that would answer each question |
 
-```term
-[Advanced Variable Settings]
+`<name>` is a reference, resolved like any sous ref; anything larger than a variable asks all its questions:
 
-Question 1 of 4: taskFileRoot
+```bash
+sous vars ask taskFileRoot                      # one variable, by the name its recipe gave it
+sous vars ask SOUS_VAR_TASK_FILE_ROOT           # the same one, by a name in use that answers it
+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
+```
 
-This recipe mandates the creation of task files that are stored locally and, in
-general, should not be committed. This setting dictates the path in which agents
-will store and search for your task files. The default value stores task files in
-the project's .sous directory, but you can specify any local path, either relative
-to the project root or absolute.
+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
+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.
 
-    default     : .sous/tasks
-    example     : ~/my-task-files
-    required-by : workflow/task-files https://example.com/owner/recipes/workflow/task-files
-    defined-by  : workflow/task-files https://example.com/owner/recipes/workflow/task-files
-    storage-path: /home/you/project/.sous/.env
-    stored-as   : SOUS_VAR_TASK_FILE_ROOT
-    constraints : • must be a value of the type path (type: path)
-                  • must be at least 1 character long (minLength: 1)
+?> Bare `sous vars` is shorthand for `vars list`, and `sous vars <name>` for `vars show <name>`, which prints
+the same report (`vars show` spells the storage path out in full); `sous var list`, `sous var show` and
+`sous var ask` work too. A variable named `list`, `show` or `ask` collides with the subcommand, so reach it
+the long way: `sous vars show ask`.
 
-? What would you like to do?
-  Return to value entry
-  Change the storage file
-  Change the stored variable name
-```
+### Answering ahead of the questions
 
-`required-by` names the recipe you subscribed to whose closure pulled this variable in, and spells
-out the chain when it arrived through a dependency; `defined-by` names the recipe that declares
-the definition. Both carry the location beside the recipe key, in muted grey: a repository URL with
-the recipe's folder for a hosted repository, and a filesystem path for one read from this machine.
+`--answer <name>=<value>` answers a question before it is asked and repeats as often as needed, and
+`--answers-file <path>` reads the same pairs from YAML or JSON; an `--answer` wins over the same name in the
+file. Pair either with `--dry-run` first, as in
+`sous vars ask --var qaScratchDir --answer qaScratchDir=/var/tmp/qa-review --dry-run`. Both work the same way
+on `sous subscription add`; see [Answer the questions](repositories-consuming.md#answer-the-questions).
 
-Changing the stored name offers every rung the ladder looks up, with the one sous would use
-already selected, plus a name of your own; a name the ladder would never look at is bound with a
-mapping record, so resolution still finds it. Changing the storage file offers the committed
-`.sous/.env` and the gitignored `.sous/.env.local`. Once anything has changed, the first menu item
-becomes "Save changes and return to value entry" and a "Discard changes" item joins it.
+Every supplied answer is checked before anything is written, so a value that does not fit fails the run
+naming the constraint, and an unknown name fails naming every variable in play. An answer replacing a stored
+one is written where that answer lives, and a value the shell supplies is never rewritten:
 
-A secret, or a variable the publisher declared machine-specific, may still be pointed at the
-committed file. Sous does not prevent it; it says plainly that the value would enter your git
-history and asks you to confirm, which is informed consent rather than a locked door. Returning to
-the value question prints its view again, with the updated `stored-as` and `storage-path`
-facts.
+```text
+  Answers stored:
+      qaParallelAgents: 4 SOUS_VAR_QA_PARALLEL_AGENTS in .env
+                        replaced the answer already there: 99
+                        SOUS_VAR_QA_PARALLEL_AGENTS is set in your shell environment and answers
+                          this variable first; unset it for the stored answer to take effect
+```
 
-Every run ends with the same three-part report: what was inherited from an answer already in
-scope, what was stored and under which name in which file, and what was left unanswered and why.
+## Answer without a terminal
 
-Subscribing runs the same machinery, so in normal use you rarely invoke `vars ask` by hand;
-reach for it after editing an env file, after a recipe upgrade tightened a constraint, or when
-you want to re-answer something deliberately with `--all`.
+Sous never hangs waiting on a prompt it cannot show; what counts as "no terminal" is listed under
+[Run sous in CI, or from an agent](repositories-consuming.md#run-sous-in-ci-or-from-an-agent). Such a run
+fails on the unanswered required variables, naming every environment variable that would satisfy each one:
 
-### Answering ahead of the questions
+```text
+  Error: 1 variable still needs an answer, and there is no terminal to ask on.
 
-`--answer <name>=<value>` answers a question before it is asked, and repeats for as many answers
-as there are questions; `--answers-file <path>` reads the same pairs from a YAML or JSON file
-(comments allowed), and an `--answer` wins over the same name in the file. Both flags work the
-same way on `sous subscription add`, which is where a run with no terminal usually meets them;
-[Consuming recipes](repositories-consuming.md#answering-questions-ahead-of-time) walks through
-that flow, dry run first.
+  Set one of the environment variables listed under each variable, or run
+  'sous vars ask' from a terminal.
 
-```bash
-sous vars ask --answer taskFileRoot=.sous/tasks --answer apiUrl=https://api.example.com
-sous vars ask --answers-file ./answers.yaml
+    qaTaskRoot (workflow/qa-variables): Where should the review notes be stored?
+      SOUS_VAR_WORKFLOW_QA_VARIABLES_QA_TASK_ROOT (recipe scope)
+      SOUS_VAR_WORKFLOW_QA_TASK_ROOT (namespace scope)
+      SOUS_VAR_QA_TASK_ROOT (shared scope)
 ```
 
-The name is spelled exactly as the recipe declares it, in camelCase, or as its full
-`namespace/recipe.name` key; everything after the first `=` is the answer. Every supplied answer
-is checked against its definition before anything is written, so a value that does not fit fails
-the run naming the constraint and the publisher's example, and a name no recipe declares fails
-naming every variable that is in play. An answer for a variable that already has one replaces it,
-where that answer lives, and the report says what it replaced. Whatever is left over is asked for
-as usual.
+Set one of those names in your pipeline and the build proceeds. For an answer the whole team shares, and
+nothing about it sensitive, committing it to `.sous/.env` is simpler: a fresh clone needs no pipeline setup.
 
-## Without a terminal
+## How a template reads an answer
 
-Sous never hangs waiting on a prompt it cannot show. A run with no terminal and an unanswered
-required variable fails, and the failure names every environment variable that would satisfy it,
-most specific first, which is the message a continuous integration log needs to be useful:
+A build lays the answers into the template scope itself. For every variable a subscribed recipe publishes,
+the build walks the ladder above, takes the first value it finds, and adds it to the scope under the
+variable's own name. So once `taskFileRoot` is answered, `{{ taskFileRoot }}` renders in the recipe's own
+skills and in any template this project compiles, and `${taskFileRoot}` works in `_vars` and every other
+config value. Nothing has to be mapped by hand.
 
-```text
-One variable still needs an answer, and there is no terminal to ask on.
+The answers sit under your config, not over it. The scope a template renders with is assembled in this
+order, each layer overriding the one before:
 
-Set one of the environment variables listed under each variable, or run
-'sous vars ask' from a terminal.
+1. The auto-injected `sous*` variables.
+2. The recipe answers, found through the ladder.
+3. Your `_env` block.
+4. Your `_vars` block.
 
-  apiUrl (workflow/task-files): Where does the API live?
-    SOUS_VAR_WORKFLOW_TASK_FILES_API_URL  (recipe scope)
-    SOUS_VAR_WORKFLOW_API_URL  (namespace scope)
-    SOUS_VAR_API_URL  (shared scope)
-```
+So a project that already carries an answer in `_vars`, or maps one through `_env`, keeps rendering exactly
+what it did; the answer in the env files is simply shadowed, and `sous vars list` still reports it.
+
+When no rung answers, the definition's own `default` is what renders, because the description a publisher
+writes promises what the default does. A required variable with no answer and no default renders as an
+empty string, and the build says so before it compiles, naming each such variable, the recipe that asks for
+it, and `sous vars ask` as the way to answer. The build still succeeds; an unanswered question is
+something to tell you about, not a reason to refuse the rest of the project.
+
+?> Two recipes may ask the same question. Their shared answer renders in both, and in your own templates.
+When the recipe-scoped name gives one of them a different answer, that recipe's own files render its own
+answer while everything else, your templates included, renders the first definition's; `sous vars show`
+tells you which names are in play.
+
+An answer is laid in exactly as it is stored: a path stays the string you typed, relative or absolute, and a
+number stays text. A template that needs an absolute path from a relative answer composes one under another
+name in `_vars`, for instance `taskFileDir: "${sousDir}/../${taskFileRoot}"`.
 
-Set one of those names as a secret or a variable in your pipeline and the build proceeds. For an
-answer the whole team shares and nothing about it is sensitive, committing it to `.sous/.env` is
-simpler still: a fresh clone then needs no pipeline configuration at all.
+The `_env` block is still the way to reach any environment variable no recipe asks about.
 
 ## Where to go next
 
 - [Consuming recipes](repositories-consuming.md): subscribing, building, and what lands where
-- [Authoring a repository](repositories-authoring.md): declaring the definitions this page
-  resolves
-- [Variable definitions](repositories-file-formats.md#variable-definitions): the full field table
+- [Authoring a repository](repositories-authoring.md): declaring the definitions this page resolves
+- [Troubleshooting](repositories-troubleshooting.md): a question sous cannot ask, a pattern that runs out of time
 - [Command reference](commands.md): every command and flag