@sous-io/sous 1.0.14 → 1.0.16

package/docs/markdown/commands.md

@@ -40,8 +40,10 @@ already exists.
 - `--timings` prints how long each step of the run took.
 - `--json`, on the commands that print a listing or a report, prints it as JSON instead.
 
-Sous warns on standard error when a step takes longer than its time budget, so the warning never mixes with
-`--json` output. The `budgets` config key changes a budget, and `false` turns its warning off.
+Sous reports, at the `debug` level, when a step takes longer than its time budget, so the report shows only
+with `--debug` or `--log-level debug`. It goes to standard error, so it never mixes with `--json` output. Time
+spent waiting for you to answer a question does not count. The `budgets` config key changes a budget, and
+`false` turns its report off.
 
 `sous --version` prints the version (`v1.2.3`); add `--verbose` for where it is installed, the platform and
 the Node build.

package/docs/markdown/configuration.md

@@ -163,8 +163,9 @@ Two more keys settle what plugins do:
   the same one stops sous with an error until you choose one:
   `"services": { "replace": { "git.runner": "sous-plugin-fast-git" } }`. Sous then warns on every
   run that the other plugin may not work as expected.
-- `budgets` changes how long a step may take before sous warns that it is slow; a budget set to
-  `false` turns that warning off. `--timings` on any command prints how long every step took.
+- `budgets` changes how long a step may take before sous reports that it is slow (at the `debug`
+  level, so only with `--debug`); a budget set to `false` turns that report off. `--timings` on any
+  command prints how long every step took.
 
 `sous plugins show` lists every plugin and what it adds. Recipes may ship plugins too; see
 [where plugins come from](architecture/specifications/S1-engine.md#where-plugins-come-from).

package/docs/markdown/repositories-authoring.md

@@ -276,6 +276,11 @@ says which one to keep. `--ci` implies `--no-bump` and `--yes`, accepting the pl
 but it deliberately does not imply `--push`, so what a workflow pushes stays visible in the workflow file. Under
 either, a recipe whose files changed without a bump is an error naming its manifest and the colliding tag.
 
+`--push` pushes the branch to `origin`, plus every release tag that `sous.index.json` publishes, that this checkout
+holds and that `origin` lacks. That includes tags an earlier run cut without `--push`, so the pushed index never
+names a tag subscribers cannot fetch. The tags go first, then the branch. A `--push` run with nothing new to
+release still pushes them, which is how to send a release you made without `--push`.
+
 ### The branch rule
 
 The default branch is whatever `origin/HEAD` points at. On any other branch a release bumps and commits but cuts

package/docs/markdown/repositories-consuming.md

@@ -376,20 +376,27 @@ there is no entry to delete: the one sous provides comes back on the next run, s
 opt-out outlives it. `sous subscription add core` clears it again. If you remove `core`, make sure
 something else tells your agents not to edit generated files.
 
-## Switch a subscription off on one machine
+## Switch a subscription off
 
 A subscription stays in the config with `enabled: false`, so the opt-out is visible. A switched-off
 subscription is not built: the recipes reached only through it are skipped, the outputs they wrote are
 pruned, and their variables are neither asked nor required. Their pins stay in the committed lockfile,
-so switching a recipe off on your machine never removes it for anyone else.
+so a machine that switches a recipe off never removes it from the lockfile for anyone else.
 
 ```bash
 sous subscription disable tool-usage/automated-browser-tasks
 sous subscription enable tool-usage/automated-browser-tasks
 ```
 
-Both edit `.sous/conf.d/510-subscriptions.jsonc` by key. To switch one off only on some machines, write
-`enabled` in a `conf.d` file of your own that sorts after 510; a later file wins over the managed one:
+Both edit `.sous/conf.d/510-subscriptions.jsonc` by key. That file is committed, so once the change is
+committed the subscription is switched off, or back on, for **everyone** using the project. `disable`
+writes `"enabled": false`; `enable` removes it again, so the file goes back to what it held before.
+
+### On one machine only
+
+To switch one off only on some machines, write `enabled` in a `conf.d` file of your own that sorts
+after 510, and keep that file out of git if it is for your machine alone; a later file wins over the
+managed one:
 
 ```jsonc
 // .sous/conf.d/610-mac.jsonc
@@ -442,7 +449,9 @@ rather than stopping the build, and the build prints a warning naming it before
 A build holds the versions the lockfile pins and does not talk to the network on every run. Sous
 asks a repository for a newer index only when it has never asked, when the freshness window has
 lapsed (`store.freshnessSeconds`, five minutes by default), or when a command forces it; a failed
-check never breaks a build, because the cached index is used instead. Always-pull changes what
+check never breaks a build, because the cached index is used instead. When a recipe or a version
+is missing from the cached index, sous asks upstream once more before reporting it, so a recipe
+released moments ago is found straight away. Always-pull changes what
 happens after that check, not how often it happens: a repository or subscription marked
 `alwaysPull` takes a newer in-range version rather than the locked one; set it with
 `--always-pull`, or on either entry in the config. Without it, `sous subscription update` is how a

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

@@ -478,7 +478,7 @@ old `.json` name is read as a fallback and migrates on the next write: the `.jso
 
 No file is special to sous when it reads the config: a `conf.d` file of your own that sorts after 510 can
 override a subscription the managed file lists, such as switching it off on one machine (see
-[Switch a subscription off on one machine](repositories-consuming.md#switch-a-subscription-off-on-one-machine)).
+[On one machine only](repositories-consuming.md#on-one-machine-only)).
 
 ## Where to go next
 

package/docs/markdown/repositories-providers.md

@@ -161,6 +161,13 @@ https://raw.githubusercontent.com/<owner>/<name>/HEAD/sous.index.json
 https://<gitlab host>/api/v4/projects/<owner>%2F<name>/repository/files/sous.index.json/raw?ref=HEAD
 ```
 
+GitHub's raw host can answer with a copy it cached for up to five minutes. When sous must see the
+current index (a `--latest` read, or a recipe missing from its cached copy, which is how a recipe
+released moments ago looks), it reads GitHub's contents API without a token instead
+(`https://api.github.com/repos/<owner>/<name>/contents/sous.index.json`), and tries the raw host only
+if nothing else answers. GitHub allows 60 such requests an hour from one address, so ordinary reads
+never use it. GitLab's API always answers with the current file.
+
 A token is looked for in these places, in this order, and a missing one is skipped:
 
 1. the environment: `GITHUB_TOKEN` for GitHub, `GITLAB_TOKEN` for GitLab;
@@ -183,6 +190,7 @@ Error: could not read gitlab.com/acme/private-recipes.
 Fix one of these:
   export GITLAB_TOKEN=<a token with read_repository>
   set up git access to gitlab.com (an SSH key, or a credential helper)
+A token reads only the index. Recipe files are downloaded with git, so building also needs git access.
 ```
 
 **A recipe's files** come from git itself: a shallow, blobless, sparse clone at the version's

package/docs/markdown/repositories-troubleshooting.md

@@ -9,11 +9,17 @@ lines under the first sentence of a failure, because that is where the remedy is
 ## A repository this project does not trust
 
 ```text
-Error: No added repository publishes the recipe 'workflow/nope'.
-  Repositories searched: qa-recipes, sous-recipes.
-  Add the repository that publishes it with 'sous repo add <url>', then try again.
+Error: None of this project's repositories publishes the recipe 'workflow/nope'.
+  Checked just now: qa-recipes, sous-recipes.
+  Check the spelling, or run 'sous repo search nope' to look for it. If a repository this project
+    has not added publishes it, add that one with 'sous repo add <url>'.
 ```
 
+Before sous reports this, it reads every added repository's index upstream once, so a recipe
+released moments ago is found rather than reported missing. A repository it could not reach just
+then is listed under `Could not be checked just now`, and only the copy of its index that sous
+already had was searched.
+
 A browsing command given a qualified ref whose qualifier is unknown says `This project trusts no
 repository called 'acme'`; a subscribe says `Sous does not know where the repository 'acme' lives,
 so it cannot add it for you`, and prints the `sous repo add <url> --name acme` line to run. Either
@@ -341,10 +347,13 @@ Error: could not read gitlab.com/acme/private-recipes.
 Fix one of these:
   export GITLAB_TOKEN=<a token with read_repository>
   set up git access to gitlab.com (an SSH key, or a credential helper)
+A token reads only the index. Recipe files are downloaded with git, so building also needs git access.
 ```
 
-Sous tried every way it has to read the repository, and each line says why that one failed. Any one fix
-is enough: a token in the environment, or git access to the host. `gh` and `glab` are not needed to read.
+Sous tried every way it has to read the repository's index, and each line says why that one failed. Any
+one fix lets sous read the index. Recipe files are a different matter: sous downloads them with git alone,
+so a build needs git access to the host (an SSH key, or a credential helper) even when a token is set. A
+token in the environment only makes reading the index faster. `gh` and `glab` are not needed to read.
 The order sous tries, and where it finds a token, are under
 [Private repositories](repositories-providers.md#private-repositories).
 

package/docs/markdown/repositories.md

@@ -205,7 +205,8 @@ plugin included, until the repository is trusted.
 A subscription can be switched off on one machine and left on for everyone else, for example from
 a `conf.d` file of your own. A switched-off subscription is not built: its outputs are pruned, its
 variables are not asked, and its pins stay in the committed lockfile. `sous subscription disable <ref>`
-and `sous subscription enable <ref>` switch one off and on.
+and `sous subscription enable <ref>` switch one off and on for everyone, because they edit the
+committed `conf.d/510-subscriptions.jsonc`.
 
 ## The official repository, and the built-in core
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -39,44 +39,44 @@
     "sous.config.schema.json"
   ],
   "dependencies": {
-    "@sous-io/plugin-api": "1.0.14"
+    "@sous-io/plugin-api": "1.0.16"
   },
   "devDependencies": {
     "esbuild": "^0.27.4",
     "jsonc-parser": "^3.3.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "@sous-io/core": "1.0.14",
-    "@sous-io/documents": "1.0.14",
-    "@sous-io/plugin-build": "1.0.14",
-    "@sous-io/plugin-claude-code": "1.0.14",
-    "@sous-io/plugin-authoring": "1.0.14",
-    "@sous-io/plugin-cli": "1.0.14",
-    "@sous-io/plugin-compiler": "1.0.14",
-    "@sous-io/plugin-config-files": "1.0.14",
-    "@sous-io/plugin-formats": "1.0.14",
-    "@sous-io/plugin-expressions": "1.0.14",
-    "@sous-io/plugin-confd": "1.0.14",
-    "@sous-io/plugin-git": "1.0.14",
-    "@sous-io/plugin-github": "1.0.14",
-    "@sous-io/plugin-harnesses": "1.0.14",
-    "@sous-io/plugin-init": "1.0.14",
-    "@sous-io/plugin-host": "1.0.14",
-    "@sous-io/plugin-inspect": "1.0.14",
-    "@sous-io/plugin-gitlab": "1.0.14",
-    "@sous-io/plugin-local": "1.0.14",
-    "@sous-io/plugin-liquid": "1.0.14",
-    "@sous-io/plugin-mcp": "1.0.14",
-    "@sous-io/plugin-memories": "1.0.14",
-    "@sous-io/plugin-pnpm": "1.0.14",
-    "@sous-io/plugin-recipe-answers": "1.0.14",
-    "@sous-io/plugin-npm": "1.0.14",
-    "@sous-io/plugin-recipes": "1.0.14",
-    "@sous-io/plugin-skills": "1.0.14",
-    "@sous-io/plugin-update": "1.0.14",
-    "@sous-io/plugin-variables": "1.0.14",
-    "@sous-io/plugin-refs": "1.0.14",
-    "@sous-io/plugin-yarn": "1.0.14"
+    "@sous-io/core": "1.0.16",
+    "@sous-io/plugin-authoring": "1.0.16",
+    "@sous-io/plugin-build": "1.0.16",
+    "@sous-io/documents": "1.0.16",
+    "@sous-io/plugin-claude-code": "1.0.16",
+    "@sous-io/plugin-cli": "1.0.16",
+    "@sous-io/plugin-compiler": "1.0.16",
+    "@sous-io/plugin-confd": "1.0.16",
+    "@sous-io/plugin-formats": "1.0.16",
+    "@sous-io/plugin-expressions": "1.0.16",
+    "@sous-io/plugin-config-files": "1.0.16",
+    "@sous-io/plugin-git": "1.0.16",
+    "@sous-io/plugin-gitlab": "1.0.16",
+    "@sous-io/plugin-harnesses": "1.0.16",
+    "@sous-io/plugin-github": "1.0.16",
+    "@sous-io/plugin-host": "1.0.16",
+    "@sous-io/plugin-inspect": "1.0.16",
+    "@sous-io/plugin-liquid": "1.0.16",
+    "@sous-io/plugin-init": "1.0.16",
+    "@sous-io/plugin-local": "1.0.16",
+    "@sous-io/plugin-mcp": "1.0.16",
+    "@sous-io/plugin-memories": "1.0.16",
+    "@sous-io/plugin-npm": "1.0.16",
+    "@sous-io/plugin-recipe-answers": "1.0.16",
+    "@sous-io/plugin-pnpm": "1.0.16",
+    "@sous-io/plugin-recipes": "1.0.16",
+    "@sous-io/plugin-refs": "1.0.16",
+    "@sous-io/plugin-skills": "1.0.16",
+    "@sous-io/plugin-update": "1.0.16",
+    "@sous-io/plugin-variables": "1.0.16",
+    "@sous-io/plugin-yarn": "1.0.16"
   },
   "engines": {
     "node": ">=22"

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

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