@sous-io/sous 0.2.37 → 1.0.1

package/docs/markdown/repositories-troubleshooting.md

@@ -25,7 +25,8 @@ before fetching anything and asks about all of them in one question, listing eac
 that requires it; declining any of them stops the whole install.
 
 !> Trusting a repository trusts every namespace and recipe in it, including ones published later.
-Trusting alone runs nothing; subscribing to something inside it can run scripts on this machine.
+Trusting alone runs nothing; subscribing to something inside it can run scripts on this machine,
+and a sous plugin a recipe ships runs inside sous itself.
 See [Trust](repositories.md#trust).
 
 ## A ref that names more than one thing
@@ -330,6 +331,31 @@ active, so a project needing its own store can say `SOUS_HOME=~/caches/sous-home
 compare [Discovery and overrides](config-discovery.md), where `SOUS_CONFIG`, `SOUS_DIR` and
 `SOUS_CONFD` are read from the real environment only.
 
+## A private repository sous cannot read
+
+```text
+Error: could not read gitlab.com/acme/private-recipes.
+  HTTP with token      no token found (GITLAB_TOKEN unset; git has no stored credential for gitlab.com)
+  HTTP without token   302 to sign-in page: the repository is private
+  git                  Permission denied (publickey)
+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)
+```
+
+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.
+The order sous tries, and where it finds a token, are under
+[Private repositories](repositories-providers.md#private-repositories).
+
+## A recipe that requires a plugin
+
+A recipe may require a sous plugin from npm, with a version range. `sous subscription add` refuses such a
+recipe while the plugin is missing or outside the range, and a build fails when a subscribed recipe's
+requirement breaks later, for example after the plugin was removed from `package.json`. Both messages name
+the plugin and the command that installs it. Run that command, or rerun the subscribe with
+`--install-plugins`, which installs it through the project's package manager without asking.
+
 ## Where to go next
 
 - [Quickstart](repositories-quickstart.md): the shortest path from an empty project to a skill

package/docs/markdown/repositories-variables.md

@@ -231,6 +231,7 @@ advanced view draws, and the ladder table above. The name may be bare or the ful
 | `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 --env-file <file>` | Stores every answer of the run in `.sous/.env` (committed) or `.sous/.env.local` (this machine only); any spelling that names one is accepted, and a secret or machine-specific variable sent to the committed file needs a yes (`--yes`) |
 | `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 |
@@ -330,6 +331,9 @@ empty string, and the build says so before it compiles, naming each such variabl
 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.
 
+A variable declared only by recipes that are not built on this machine, because their subscription is
+switched off, is neither asked by `sous vars ask` nor required by the build.
+
 ?> 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`
@@ -337,7 +341,8 @@ 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}"`.
+name in `_vars`, for instance `taskFileDir: "${projectRoot}/${taskFileRoot}"`. `projectRoot` is set by sous
+(the directory holding `.sous/`); setting it in any `_vars` is an error.
 
 The `_env` block is still the way to reach any environment variable no recipe asks about.
 

package/docs/markdown/repositories.md

@@ -48,7 +48,9 @@ $ sous namespace list
 A recipe is the unit you subscribe to and the only thing that carries a version. It may hold
 skills, memories, prompts, config layers and variable definitions in any mixture, and
 subscribing to it gets all of them. A recipe may ship a plugin for a coding tool (a Claude Code
-plugin, say), but never a plugin for sous itself; those come only with sous or as npm packages.
+plugin, say), and it may ship a plugin for sous itself, as one bundled file (see
+[Recipes that ship sous plugins](repositories-authoring.md#recipes-that-ship-sous-plugins)). A recipe may
+also require sous plugins from npm.
 
 ```yaml
 # recipes/workflow/task-files/sous.recipe.yaml
@@ -194,10 +196,16 @@ this machine.
 Subscribing decides what is switched on, and it is not a second security gate. A recipe is
 **active** when the project subscribes to it directly or through its namespace, or when an active
 recipe lists it under `subscribes`; only an active recipe registers entry points of its own, such as
-output files, skills, tool hooks and tool plugins. A recipe held only through `depends` is a library:
+output files, skills, tool hooks, tool plugins and sous plugins. A recipe held only through `depends` is a library:
 an active recipe may include, call or import its files, but it registers nothing itself. Activation
 keeps a project from running what it has no use for and keeps unrelated recipes from colliding;
-everything in a trusted repository is already trusted.
+everything in a trusted repository is already trusted. Nothing inside a repository runs, a sous
+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.
 
 ## The official repository, and the built-in core
 
@@ -280,9 +288,9 @@ $ sous build
   ✓ /home/me/my-project/.claude/skills/start-task/SKILL.md (~1,996 tokens)
 ```
 
-Skills default to `<project root>/.claude/skills`, and the
-[`recipes`](repositories-file-formats.md#recipes-what-each-content-kind-does) block changes that. Memories are
-not copied anywhere; one include line in your instruction source pulls them in (see
+Skills go to `<project root>/.claude/skills`, the skills directory the built-in Claude Code plugin names, and the
+[`recipes`](repositories-file-formats.md#recipes-what-each-content-kind-does) block adds destinations of
+your own. Memories are not copied as files; one include line in your instruction source pulls them in (see
 [Recipe memories](repositories-consuming.md#recipe-memories)).
 
 By default a build uses what the lockfile pins and does not talk to the network. Two things
@@ -321,8 +329,10 @@ and `varMappings:` in your primary config instead, which sous never touches. See
 
 Every directory sous creates for its own bookkeeping explains itself: the first time it creates
 one it writes a short `README.md` saying what the directory is, who writes to it, whether you may
-edit it and whether it is committed, plus an `AGENTS.md` and a `CLAUDE.md` pointing at that
-README. None is ever overwritten, and directories holding rendered output are left alone.
+edit it and whether it is committed. Agent plugins add one-line pointer files beside it that tell
+their agent to read the README: the built-in Claude Code plugin adds a `CLAUDE.md`, and a plugin for an
+agent that reads `AGENTS.md` adds that. Each file is written once, none is ever overwritten, and
+directories holding rendered output are left alone.
 
 ## Including recipe files in your own templates
 

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.37",
+  "version": "1.0.1",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
   "author": "Luke Chavers",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/sous-io/sous.git"
+    "url": "git+https://github.com/sous-io/sous.git",
+    "directory": "packages/sous"
   },
   "homepage": "https://sous.io",
   "bugs": "https://github.com/sous-io/sous/issues",
@@ -27,121 +28,61 @@
     "access": "public"
   },
   "bin": {
-    "sous": "./bin/run.js"
+    "sous": "./dist/bin.js"
   },
   "files": [
-    "bin/run.js",
-    "src",
-    "!src/**/*.spec.ts",
-    "!src/test",
+    "dist/bin.js",
+    "dist/sous.js",
     "recipes",
     "docs/markdown/*.md",
     "sous.config.schema.json"
   ],
-  "scripts": {
-    "build": "tsc",
-    "sous:build": "./bin/sous build --rebuild",
-    "claude": "./bin/sous launch claude",
-    "clean": "rm -rf dist",
-    "schema:build": "tsx scripts/build-schema.mts",
-    "version:sync": "tsx scripts/sync-core-version.mts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts"
-  },
   "dependencies": {
-    "@inquirer/core": "^11.1.7",
-    "@inquirer/prompts": "^8.3.2",
-    "@oclif/color": "^1.0.13",
-    "@oclif/core": "^4",
-    "chokidar": "^5.0.0",
-    "glob": "^13.0.6",
-    "inversify": "^8.2.3",
-    "jsonc-parser": "^3.3.1",
-    "liquidjs": "^10.25.0",
-    "minimatch": "^10.2.4",
-    "package-manager-detector": "^1.8.0",
-    "semver": "^7.8.5",
-    "tiktoken": "^1.0.22",
-    "tsx": "^4",
-    "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "@sous-io/plugin-api": "1.0.1"
   },
   "devDependencies": {
-    "@types/glob": "^8.1.0",
-    "@types/node": "^22",
-    "@types/semver": "^7.8.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "memfs": "^4.56.11",
-    "typescript": "^5",
-    "vitest": "^4.1.0"
-  },
-  "oclif": {
-    "bin": "sous",
-    "dirname": "sous",
-    "flexibleTaxonomy": true,
-    "topicSeparator": " ",
-    "additionalHelpFlags": [
-      "-h"
-    ],
-    "commands": {
-      "strategy": "pattern",
-      "target": "./src/commands"
-    },
-    "topics": {
-      "config": {
-        "description": "Inspect the merged configuration"
-      },
-      "configs": {
-        "description": "Inspect the merged configuration",
-        "hidden": true
-      },
-      "repo": {
-        "description": "Manage the recipe repositories this project trusts"
-      },
-      "repos": {
-        "description": "Manage the recipe repositories this project trusts",
-        "hidden": true
-      },
-      "lock": {
-        "description": "Inspect and repair this project's lockfile"
-      },
-      "locks": {
-        "description": "Inspect and repair this project's lockfile",
-        "hidden": true
-      },
-      "namespace": {
-        "description": "Browse the namespaces the trusted repositories publish"
-      },
-      "namespaces": {
-        "description": "Browse the namespaces the trusted repositories publish",
-        "hidden": true
-      },
-      "recipe": {
-        "description": "Browse the recipes the trusted repositories publish"
-      },
-      "recipes": {
-        "description": "Browse the recipes the trusted repositories publish",
-        "hidden": true
-      },
-      "subscription": {
-        "description": "Manage which recipes this project subscribes to"
-      },
-      "subscriptions": {
-        "description": "Manage which recipes this project subscribes to",
-        "hidden": true
-      },
-      "vars": {
-        "description": "Recipe variables and their answers"
-      },
-      "var": {
-        "description": "Recipe variables and their answers",
-        "hidden": true
-      }
-    }
+    "esbuild": "^0.27.4",
+    "jsonc-parser": "^3.3.1",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3",
+    "@sous-io/core": "1.0.1",
+    "@sous-io/plugin-authoring": "1.0.1",
+    "@sous-io/plugin-build": "1.0.1",
+    "@sous-io/plugin-claude-code": "1.0.1",
+    "@sous-io/documents": "1.0.1",
+    "@sous-io/plugin-cli": "1.0.1",
+    "@sous-io/plugin-compiler": "1.0.1",
+    "@sous-io/plugin-confd": "1.0.1",
+    "@sous-io/plugin-config-files": "1.0.1",
+    "@sous-io/plugin-formats": "1.0.1",
+    "@sous-io/plugin-expressions": "1.0.1",
+    "@sous-io/plugin-git": "1.0.1",
+    "@sous-io/plugin-github": "1.0.1",
+    "@sous-io/plugin-gitlab": "1.0.1",
+    "@sous-io/plugin-host": "1.0.1",
+    "@sous-io/plugin-harnesses": "1.0.1",
+    "@sous-io/plugin-inspect": "1.0.1",
+    "@sous-io/plugin-init": "1.0.1",
+    "@sous-io/plugin-liquid": "1.0.1",
+    "@sous-io/plugin-local": "1.0.1",
+    "@sous-io/plugin-mcp": "1.0.1",
+    "@sous-io/plugin-memories": "1.0.1",
+    "@sous-io/plugin-npm": "1.0.1",
+    "@sous-io/plugin-recipe-answers": "1.0.1",
+    "@sous-io/plugin-pnpm": "1.0.1",
+    "@sous-io/plugin-recipes": "1.0.1",
+    "@sous-io/plugin-refs": "1.0.1",
+    "@sous-io/plugin-skills": "1.0.1",
+    "@sous-io/plugin-update": "1.0.1",
+    "@sous-io/plugin-yarn": "1.0.1",
+    "@sous-io/plugin-variables": "1.0.1"
   },
   "engines": {
     "node": ">=22"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p .",
+    "build": "node scripts/bundle.mjs"
   }
-}
+}

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

@@ -196,12 +196,10 @@ wins**; if none exist, the build errors listing every path tried:
 
 ## Custom Tags
 
-The tags below are built into sous. A recipe cannot add a tag or a filter, since that would be a
-Sous plugin; a Sous plugin comes only from sous's built-ins or an npm-style module.
-
-> "recipes will not be allowed to install _Sous_ plugins. All Sous plugins, besides any built-ins that ship with Sous, itself, will come from a NPM repo (or similar) as modules. Recipes _will_ be allowed to install tool plugins (e.g. Claude Code Plugins)."
->
->   -- **Luke Chavers** in an agent session (2026-09-29)
+The tags below are built into sous. A Sous plugin (a package that extends sous itself, which a
+subscribed recipe may also ship) can add more tags and filters, and config expressions (`$if`,
+`$expr`) can use the filters too. Run `sous plugins show` to list the tags and filters each loaded
+plugin added before using one that is not documented here.
 
 **`showVars`**: dumps all variables currently in scope as a fenced JSON block.
 Useful during development to see exactly what variables are available at a given point

package/recipes/core/sous-skills/skills/about-liquid-templates/references/liquid-filters.tpl.md

@@ -80,3 +80,5 @@ Standard filters available in all `.tpl.` files. Chained with `|`.
 | Filter | Description |
 |:-------|:------------|
 | `bulletList` | Convert array to markdown bullet list (`- item` per line) |
+
+Sous plugins may add more filters; run `sous plugins show` to list them.

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

@@ -64,15 +64,16 @@ trust question reads only its index.
 
 Subscribing decides what is switched on, not what is safe. A recipe is active when the
 project subscribes to it, directly or through its namespace, or when an active recipe
-lists it under `subscribes`, and only an active recipe registers entry points of its own
-(output files, skills, tool hooks and tool plugins). A recipe held only through `depends` is a
-library: an active recipe may include, call or import its files, but it registers nothing
-itself. No recipe installs a Sous plugin; Sous plugins come only from sous's built-ins and from
-npm-style modules.
-
-> "recipes will not be allowed to install _Sous_ plugins. All Sous plugins, besides any built-ins that ship with Sous, itself, will come from a NPM repo (or similar) as modules. Recipes _will_ be allowed to install tool plugins (e.g. Claude Code Plugins)."
->
->   -- **Luke Chavers** in an agent session (2026-09-29)
+lists it under `subscribes`. Only an active recipe adds anything to the project: output files,
+skills, tool hooks, tool plugins (such as a Claude Code plugin) and Sous plugins (code that
+extends sous itself). A recipe held only through `depends` is a library: an active recipe may
+include, call or import its files, but it adds nothing to the project itself.
+
+A recipe's Sous plugin runs inside sous while sous builds the project's config, with the user's
+own permissions, so it is code from that recipe's repository like any other. A recipe may also
+require plugins from npm; `sous subscription add` refuses it while one is missing or outside
+its version range, and offers to install it. Run `sous plugins show` to list every loaded plugin
+and what it added.
 
 ## Sous's Own Documentation
 

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

@@ -17,12 +17,20 @@ metadata:
 
 # About Sous Configuration
 
-Sous reads one configuration per project from the project's `.sous/` directory: exactly ONE
-primary config (`sous.config.js|mjs|json|yaml`), optionally extended by `conf.d/` drop-in
-layers that deep-merge over it. One config describes one project; every setting lives at the
-top level of a single flat object. There is no user-level config and no multi-project map.
-Configs use `${var}` syntax, resolved by a fixpoint loop (declaration order never matters);
-`sous*`-prefixed variable names are reserved auto-vars.
+Sous builds one configuration per project, from the project's `.sous/` directory: exactly ONE
+primary config (`sous.config.js|mjs|json|yaml`), optionally extended by `conf.d/` drop-in files.
+One config describes one project; every setting lives at the top level of a single flat object.
+There is no user-level config, no multi-project map and no separate bootstrap config.
+
+Plugins and subscribed recipes may change the config too. The primary config and the `conf.d/`
+files are always applied after them, in file order, so the project's own files win over any plugin
+or recipe. Sous may apply a file more than once while it builds the config, so a JS config's
+`configure()` MUST give the same result every time it runs for the same input (no counters, no
+writes to disk).
+
+Configs use `${var}` syntax, resolved until every value settles (declaration order never
+matters); `sous*`-prefixed names and `projectRoot` are auto-variables sous sets itself.
+`projectRoot` is the directory holding `.sous/`; setting it in any `_vars` is an error.
 
 ## This Project's Configuration
 
@@ -40,10 +48,10 @@ Read these files for anything beyond this page; do not guess and do not search t
 - `{{ sousRootPath }}/docs/markdown/configuration.md`: the config file, its shape, composition
 - `{{ sousRootPath }}/docs/markdown/config-discovery.md`: how sous finds the config; flag/env
   precedence; env-file layering; discovery errors
-- `{{ sousRootPath }}/docs/markdown/config-layers.md`: merge semantics; the JS `configure()`
-  contract; the builder API; the managed 5xx layer band
-- `{{ sousRootPath }}/docs/markdown/config-variables.md`: the scope chain; auto-vars; fixpoint
-  resolution; error anatomy; `stateFilePath`/`pidFilePath`
+- `{{ sousRootPath }}/docs/markdown/config-layers.md`: how the files combine; the JS
+  `configure()` contract; the builder API; patch files; the 5xx band the sous CLI writes
+- `{{ sousRootPath }}/docs/markdown/config-variables.md`: the scope chain; auto-vars; how values
+  settle; error anatomy; `stateFilePath`/`pidFilePath`
 - `{{ sousRootPath }}/docs/markdown/config-inspection.md`: the validation pipeline; the JSON
   Schema artifact; the `sous config` commands
 
@@ -55,14 +63,27 @@ prefer the on-disk copies.
 
 - After editing any config file, run `sous config validate`: it runs schema validation plus
   full variable resolution, surfacing cycles and undefined `${refs}`. Use
-  `sous config get <path> --layers` to see which file set a value.
+  `sous config get <path> --layers` to see which file or plugin changed a value, in order.
 - Hand-written config belongs in the primary file or your own `conf.d/` layers. Never
   hand-edit `conf.d/500-*` through `conf.d/599-*`; that band is reserved for layers the sous
   CLI writes.
-- The top-level `recipes` key says what the project does with each content kind its subscribed
-  recipes publish: `recipes.skills.outputs` lists the directories skills are written to, and
+- The top-level `recipes` key says what the project does with each kind of content its
+  subscribed recipes publish. Skills go to every skills directory an agent plugin adds (the
+  built-in Claude Code plugin adds `.claude/skills`) and to every directory listed in
+  `recipes.skills.outputs`; with neither, the build skips the skills and says why.
   `recipes.memories.first` and `recipes.memories.exclude` (globs over `namespace/recipe`, or
-  `/regex/` strings) order and filter the memories the `@#memories/**/*.md` include pulls in.
+  `/regex/` strings) order and filter the recipe memories.
+- The `plugins` key decides which Sous plugins (packages that extend sous itself) load, beyond
+  the built-ins and those listed in the project's `package.json`, and holds each plugin's own
+  options. `configuration.md` above documents its fields. Run `sous plugins show` to see which
+  plugins loaded and what each added.
+- A value in a JSON, JSONC or YAML config may be a config expression (`$if`, `$elseif`, `$else`,
+  `$expr`), worked out when sous builds the config, for example to switch a subscription off on
+  one platform. See `configuration.md` above for the syntax.
+- A `conf.d/*.patch.json` or `*.patch.jsonl` file holds raw edit operations (for example, remove
+  an array item) instead of config data. Read the "Patch files" section of `config-layers.md`
+  above before writing one: an array index in a patch file is NEVER recomputed, so it can hit the
+  wrong item if anything else changes that array.
 - Any config problem halts sous with a ConfigError naming the offending file; fix the named
   file rather than working around it.
 - Configs use `${var}`; template files use LiquidJS double-brace syntax. The two resolve at

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

@@ -2,8 +2,8 @@
 name: about-sous-recipes
 description: >
   YOU MUST load this skill when creating or changing a sous recipe: its sous.recipe.yaml, its
-  version, the variables it asks for, the files it publishes, its depends or subscribes lists,
-  or a partial or @~ include inside it.
+  version, the variables it asks for, the files it publishes, a Sous plugin it ships or requires,
+  its depends or subscribes lists, or a partial or @~ include inside it.
 user-invocable: false
 license: Apache-2.0
 compatibility:
@@ -49,21 +49,16 @@ The fields in that example:
   `sous repo search`.
 - `contents` is what a subscriber receives: one group per kind (`skills`, `memories`, `prompts` or
   `config`), each with `include` globs and optional `exclude` globs, relative to the recipe folder.
-  The subscribing project decides where skills land; memories are included into its instruction
-  files by one line, `@#memories/**/*.md` (see "Shipping Memories" below), and nothing takes
-  prompts yet. A `config` file becomes
-  a config layer in the project, loaded under the project's own config so the project always wins;
-  it MUST be `.json`, `.jsonc`, `.yaml` or `.yml`, and every key outside `_aliases`, `_vars`,
-  `compilation`, `recipes`, `runtimeContext`, `store` and `varMappings` is dropped with a
-  warning. A recipe that only bundles others may leave `contents` out.
-- A recipe MAY install tool plugins (a plugin for a coding agent tool, such as a Claude Code
-  plugin) and MUST NOT install a Sous plugin (one that extends sous itself). Sous plugins come only
-  from the built-ins that ship with sous and from npm-style modules. A `config` file is
-  configuration, not a Sous plugin.
-
-  > "recipes will not be allowed to install _Sous_ plugins. All Sous plugins, besides any built-ins that ship with Sous, itself, will come from a NPM repo (or similar) as modules. Recipes _will_ be allowed to install tool plugins (e.g. Claude Code Plugins)."
-  >
-  >   -- **Luke Chavers** in an agent session (2026-09-29)
+  The subscribing project decides where skills land (its config, and the Sous plugin for each
+  coding agent it uses, such as the built-in Claude Code plugin); memories reach its instruction
+  files as described in "Shipping Memories" below, and nothing takes prompts yet. A `config` file
+  is added to the project's config, and the project's own config files are applied after it, so
+  the project always wins. It MUST be `.json`, `.jsonc`, `.yaml` or
+  `.yml`, and every key outside `_aliases`, `_vars`, `compilation`, `plugins`, `recipes`,
+  `runtimeContext`, `store` and `varMappings` is dropped with a warning. Its `_vars` MUST NOT set
+  `projectRoot`, which sous sets itself (to the directory holding `.sous/`); setting it is an error. A recipe that only bundles others
+  may leave `contents` out.
+- `plugin` and `requires` are described in "Shipping Sous Plugins" below.
 - `depends`, `subscribes` and `variables` are described below; `submissions` is in
   `about-sous-repos`.
 
@@ -163,14 +158,50 @@ Each entry names its target by where it lives:
 `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.
 
+## Shipping Sous Plugins
+
+A recipe MAY ship a Sous plugin (code that extends sous itself, for example to add a Liquid
+filter), and MAY install tool plugins (a plugin for a coding agent tool, such as a Claude Code
+plugin).
+
+A recipe's plugin is ONE self-contained bundled file, since sous never runs `npm install` for a
+recipe; the same holds for every helper script a recipe ships. A `.d.ts` file beside it is
+optional; sous copies it into the subscriber's `.sous/types/`, so other plugins in that project
+get its types.
+
+```yaml
+plugin:
+  bundle: plugin/index.js
+  types: plugin/index.d.ts
+```
+
+Sous loads the plugin while it builds the subscriber's config, and only from a trusted
+repository: nothing inside a repository runs before it is trusted. A recipe held only through
+`depends` is a library and adds nothing to the subscriber, so its plugin NEVER loads.
+
+A recipe can also require plugins from npm, each with a version range:
+
+```yaml
+requires:
+  plugins:
+    sous-plugin-claude-code: "^1.0.0"
+```
+
+`sous subscription add` refuses such a recipe while a required plugin is missing or outside its
+version range. Run in a terminal, it offers to install the plugin; `--install-plugins` installs it
+without asking. If a required plugin later goes missing, the build fails and names the plugin and
+the command that installs it.
+
 ## Shipping Memories
 
 A memory is a fragment of an agent's always-loaded instructions. Publish one with a `contents`
 group of `kind: memories`, for example `include: [memories/**/*.md]`. A plain `.md` file is copied
 as it is; name a file `*.tpl.md` when it needs the subscriber's answers. The recipe never says where
-a memory lands: a subscribing project includes the memories of every recipe it holds directly with
-one line, `@#memories/**/*.md`, at the virtual path `#memories/<namespace>/<recipe>/<path>` (the path
-being relative to the pattern's static base). A recipe held only through `depends` is a library and
+a memory lands. A subscribing project can include the memories of every recipe it holds directly
+with one line, `@#memories/**/*.md`, at the virtual path `#memories/<namespace>/<recipe>/<path>`
+(the path being relative to the pattern's static base). The Sous plugin for a coding agent may
+also name the instruction file that agent reads (`CLAUDE.md` for Claude Code, for example), and
+sous then adds the active recipes' memories to that file itself. A recipe held only through `depends` is a library and
 contributes none, and the subscriber's build warns about a published memory no output includes.
 
 ## Includes and Partials

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

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