@sous-io/sous 0.2.31 → 0.2.33

package/README.md

@@ -70,8 +70,8 @@ sous init
 
 `sous init` writes the project's `.sous/` directory and runs the first build. It creates a
 commented `sous.config.js` (pass `--format json` for a JSON config bound to the shipped
-schema), a starter prompt at `.sous/memories/AGENTS.md` that the config compiles to `AGENTS.md`
-at the project root, the two env files described below, and a `.sous/.gitignore` covering the
+schema), a starter prompt at `.sous/memories/AGENTS.tpl.md` that the config compiles to `AGENTS.md`
+at the project root (it includes every memory your subscribed recipes publish, with one line, `@#memories/**/*.md`), the two env files described below, and a `.sous/.gitignore` covering the
 files sous keeps local to one machine. A project with a `package.json` also gains `@sous-io/sous`
 as a devDependency at the running version, so the project pins the sous it builds with; run
 your package manager's install afterwards. The first build compiles the starter prompt and the
@@ -87,12 +87,12 @@ export const config = {
   compilation: {
     targets: [
       {
-        entryPoint: "${sousDir}/memories/AGENTS.md",
+        entryPoint: "${sousDir}/memories/AGENTS.tpl.md",
         outputs: [{ destinationFile: "${projectRoot}/AGENTS.md" }],
       },
     ],
   },
-  recipeOutputs: { skills: ["${projectRoot}/.claude/skills"] },
+  recipes: { skills: { outputs: ["${projectRoot}/.claude/skills"] } },
 };
 ```
 
@@ -179,8 +179,9 @@ A recipe's files are reachable without knowing where anything is installed. An `
 path may name a recipe by its namespace, so
 `@~workflow/task-files/_partials/resume-task.md` composes a block published by the recipe
 `workflow/task-files`, at the version your project has pinned, into your own instruction
-file. `@~project/...` names your project's root, `@~/...` names your home directory, and you
-can define your own aliases with an `_aliases` block. Either spelling of a file finds it:
+file. `@#project/...` names your project's root, `@~/...` names your home directory, and you
+can define your own aliases with an `_aliases` block. A path may be a glob, and
+`@#memories/**/*.md` includes the memories of every recipe your project subscribes to. Either spelling of a file finds it:
 `@shared.md` also finds `shared.tpl.md`, and the other way round.
 
 Sous records every file and directory it writes in a state file, `.sous/sous.state.json` by

package/docs/markdown/_sidebar.md

@@ -30,3 +30,5 @@
   - [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)
   - [0011: `sous update` updates sous through the package managers](adrs/0011-self-update.md)
+  - [0012: Recipes do not install Sous plugins](adrs/0012-recipes-and-plugins.md)
+  - [0013: One ref resolver, and recipe memories through a `#memories` view](adrs/0013-one-ref-resolver.md)

package/docs/markdown/commands.md

@@ -67,8 +67,8 @@ Every topic answers to both spellings of its name: `repo` and `repos`, `subscrip
 ### `sous init [DIRECTORY]`
 Sets a project up for sous: writes its `.sous/` directory, then runs the first build. It is the one command that
 runs before a config exists, and the starting point for a project that has never used sous. It writes a commented
-primary config, a starter prompt at `.sous/memories/AGENTS.md` that the config compiles to `AGENTS.md` at the
-project root, `.sous/.env` and `.sous/.env.local.example`, and the sous-managed block in `.sous/.gitignore`. A
+primary config, a starter prompt at `.sous/memories/AGENTS.tpl.md` that the config compiles to `AGENTS.md` at the
+project root (it holds the one line, `@#memories/**/*.md`, that includes every memory your subscribed recipes publish), `.sous/.env` and `.sous/.env.local.example`, and the sous-managed block in `.sous/.gitignore`. A
 project that has a `package.json` also gains `@sous-io/sous` in its `devDependencies`, at exactly the running
 version, unless it already depends on it; nothing is installed, so run your package manager's install afterwards.
 The first build compiles the starter prompt and the `core` skills, and pins them in `.sous/sous.lock.json`.
@@ -103,10 +103,14 @@ repositories that ask for newer versions. Every command that builds (`init`, `bu
 `repo remove`, `repo unlink`, `subscription add`, `subscription remove`, `subscription update`) runs this same
 build, so each one prints the same things.
 
-A compile error (a missing or circular include, a template that fails to render, a file sous cannot read) fails
-the build. Every target is still compiled and every error is listed, then the build exits `1`. An output whose
+A compile error (a missing or circular include, a line that looks like an include but cannot be read as one, a
+template that fails to render, a file sous cannot read) fails the build. Every target is still compiled and every error is listed, then the build exits `1`. An output whose
 target had an error is not written, so the copy from the last good build stays in place.
 
+A build also warns about every memory an active recipe publishes that no output includes, naming the line to add
+(`@#memories/**/*.md`) and the `recipes.memories.exclude` opt-out; see
+[Recipe memories](repositories-consuming.md#recipe-memories).
+
 A build also lists each recipe this project uses that has a newer version within the range
 declared for it, beside the version pinned. It moves no pin; only always-pull moves one. The build reads upstream
 for this at most once per freshness window (`store.freshnessSeconds`, five minutes by default), gives a

package/docs/markdown/configuration.md

@@ -47,10 +47,34 @@ are resolved at different stages and never mix.
 
 ## Templates and the `.tpl.` convention
 
-A file's name decides whether sous renders it. A file with `.tpl.` in its name is rendered through
-LiquidJS and lands with that segment stripped, so `SKILL.tpl.md` compiles to `SKILL.md`; a file
-without it is copied verbatim, however much it looks like a template. The convention applies to
-`entryPoint` and `entryGlob` targets alike, and to the files a recipe brings into your project.
+A file's own name decides whether sous renders it, every time. A file with `.tpl.` in its name is rendered
+through LiquidJS and lands with that segment stripped, so `SKILL.tpl.md` compiles to `SKILL.md`; a file
+without it is never rendered, however much it looks like a template, even when a template includes it. A
+`.tpl.` file included from a plain file still renders, by its own name, before its text is placed. The
+convention applies to `entryPoint` and `entryGlob` targets alike, and to the files a recipe brings into your
+project.
+
+## Include syntax
+
+A line holding only `@path` includes that file's content. A path may be:
+
+- relative to the including file (`@sections/context.md`);
+- `${var}` substituted (`@${projectRoot}/prompts/x.md`);
+- home-relative (`@~/notes/private.md`);
+- an alias from `_aliases`, by its first segment (`@myAlias/doc.md`);
+- a name sous or a plugin registers, written with the `#` sigil: `#project` is the project root
+  (`@#project/prompts/intro.md`);
+- a recipe file, written with the `~` sigil and the recipe's namespace (`@~workflow/task-files/_partials/resume.md`);
+- a view: `@#memories/**/*.md` includes every active recipe's memories (see
+  [Recipe memories](repositories-consuming.md#recipe-memories)).
+
+A path may use glob syntax (`*`, `**`, `?`, `[..]`, `{a,b}`) and then includes every file it matches, in bytewise
+path order. The same file may be included in more than one place; a circular include is an error, as is a line
+that looks like an include (`@docs/notes.txt`, `@~workflow/missing`) but cannot be resolved, which fails the
+build naming the file and the line. A line inside a fenced code block is left as written. An alias name may not
+start with `~` or `#`. Reads of recipe files go through the
+[ref resolver](adrs/0013-one-ref-resolver.md); [Including recipe files in your own templates](repositories.md#including-recipe-files-in-your-own-templates)
+has the namespace rules.
 
 ## Composition
 

package/docs/markdown/repositories-authoring.md

@@ -68,11 +68,31 @@ contents:
 
 `contents` groups are what a subscribing project receives, one group per kind, each with `include` glob patterns
 relative to the recipe folder (and optional `exclude` patterns). The four kinds are `skills`, `memories`,
-`prompts` and `config`; the kind decides where files land, which the subscriber maps with
-[`recipeOutputs`](repositories-file-formats.md#recipeoutputs-where-the-files-land). Field tables are in the
+`prompts` and `config`; the kind decides what happens to them in the subscriber's project, which the subscriber shapes with
+[`recipes`](repositories-file-formats.md#recipes-what-each-content-kind-does). Field tables are in the
 [recipe manifest](repositories-file-formats.md#sousrecipeyaml-the-recipe-manifest) reference, and recipe
 metadata is the source of truth for the version: never edit `sous.index.json` by hand.
 
+### Shipping memories
+
+A memory is a fragment of an agent's always-loaded instructions. A recipe ships one with a `contents` group of
+`kind: memories`:
+
+```yaml
+contents:
+  - kind: memories
+    include:
+      - memories/**/*.md
+```
+
+Plain `.md` files are copied as they are; a file named `*.tpl.md` renders through LiquidJS with the subscriber's
+answers in scope. The recipe never says where a memory lands. A subscriber includes every memory of every recipe
+it holds directly with one line, `@#memories/**/*.md`, which lists a file at
+`#memories/<namespace>/<recipe>/<path under the pattern's static base>`. A recipe held only through `depends` is
+a library and contributes none. The build warns a subscriber whose output includes none of a memory it
+publishes, so a memory is never silently lost. See
+[Recipe memories](repositories-consuming.md#recipe-memories) for the subscriber's side.
+
 A recipe's files compile exactly the way a project's own `entryGlob` target does, so the
 [`.tpl.` convention](configuration.md#templates-and-the-tpl-convention) applies unchanged inside a recipe. A
 template may include a file from a recipe this one depends on through the reserved `~` sigil, resolved against

package/docs/markdown/repositories-consuming.md

@@ -173,17 +173,46 @@ like `workflow/qa-helper` above, is fetched and pinned but stays out of your out
 
 ## Choose where the files land
 
-Recipe files compile the way one of your own `entryGlob` targets does, under the
-[`.tpl.` convention](configuration.md#templates-and-the-tpl-convention): a file with `.tpl.` in its
-name is rendered through LiquidJS and loses `.tpl.` on the way out, and anything else is copied
-verbatim. Where each content kind lands is your project's decision, under the
-[`recipeOutputs`](repositories-file-formats.md#recipeoutputs-where-the-files-land) config key, which takes a list of
-directories for each of `skills`, `memories` and `prompts`; for example
-`recipeOutputs: { skills: ["${projectRoot}/.claude/skills", "${projectRoot}/.codex/skills"] }`.
-Only `skills` has a default, `<project root>/.claude/skills`, because that is where every agent
-looks; a kind with no destination is skipped and the build says so once, naming the key. Recipe
-outputs are tracked like every other file sous writes, so `sous prune` removes what an unsubscribed
-recipe used to write and `sous clear` removes all of it; neither reaches into a linked checkout.
+Recipe files compile under the [`.tpl.` convention](configuration.md#templates-and-the-tpl-convention): a file
+with `.tpl.` in its name is rendered through LiquidJS and loses `.tpl.` on the way out, and anything else is copied
+verbatim. Skills are written to the directories named by the
+[`recipes`](repositories-file-formats.md#recipes-what-each-content-kind-does) config key; for example
+`recipes: { skills: { outputs: ["${projectRoot}/.claude/skills", "${projectRoot}/.codex/skills"] } }`. The
+default is `<project root>/.claude/skills`, because that is where every agent looks. Written skills are tracked
+like every other file sous writes, so `sous prune` removes what an unsubscribed recipe used to write and
+`sous clear` removes all of it; neither reaches into a linked checkout.
+
+## Recipe memories
+
+A memory is a recipe's fragment of an agent's instructions. Sous does not copy memories anywhere; your
+instruction source includes them. Put one line in the file your `AGENTS.md` or `CLAUDE.md` is built from:
+
+```text
+@#memories/**/*.md
+```
+
+`#memories` is a view: it lists the memories of every recipe you hold directly (a subscription to it, to its
+namespace, or a co-subscription of a recipe you hold) at the virtual path
+`#memories/<namespace>/<recipe>/<path>`, and the line includes each one. A recipe held only through `depends`
+adds none. `sous init` writes this line into its starter, `.sous/memories/AGENTS.tpl.md`.
+
+Memories come in dependency order (a recipe after the recipes it depends on, ties by recipe key). Two config
+lists under `recipes.memories` shape the rest, each entry a glob over `namespace/recipe` keys or a regular
+expression written `/.../`:
+
+```js
+recipes: {
+  memories: { first: ["communication/*"], exclude: ["tool-usage/automated-browser-tasks"] },
+}
+```
+
+- `first`: those recipes' memories lead.
+- `exclude`: those recipes' memories are left out; this is how you opt a recipe out on purpose.
+
+A glob narrows the view as it does any path: `@#memories/communication/**/*.md` includes only that namespace.
+When a build finds a memory an active recipe publishes that no include of any output reached (by exact path, glob
+or the view) and `exclude` does not name, it warns, naming the memory and the line to add. Subscribing alone
+includes nothing, and the warning is how that is never silent.
 
 ## Answer the questions
 

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

@@ -80,9 +80,11 @@ contents:                           # what a subscriber actually receives
 | `contents`, `variables` | no | Contents default to an empty list, which is what a curated bundle publishes; a duplicated variable name, or two definitions claiming one `env`, is an error |
 | `submissions` | no | Whether this recipe takes proposed changes, winning over the repository's block; see [The submissions block](#the-submissions-block) |
 
-`contents[].kind` is `skills`, `memories`, `prompts` or `config`. The first three are written to the
-destinations named by [`recipeOutputs`](#recipeoutputs-where-the-files-land); `config` entries become config
-layers instead. `include` needs at least one glob, and both lists are recipe-relative.
+`contents[].kind` is `skills`, `memories`, `prompts` or `config`; there is no kind for a sous plugin. `skills` are
+written to the destinations named by [`recipes`](#recipes-what-each-content-kind-does); `memories` are included
+into your instruction files by one line (see [Recipe memories](repositories-consuming.md#recipe-memories));
+`config` entries become config layers; nothing takes `prompts` yet, and the build warns about a recipe that
+publishes them. `include` needs at least one glob, and both lists are recipe-relative.
 
 ### The submissions block
 
@@ -124,9 +126,10 @@ two readings that both publish what is named fail it too, naming the spellings t
 
 ### 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.
+Every place a ref is written reads it with one ref resolver (`src/services/ref-resolver/`): a parser that
+returns every reading of the text, a pruner for the place that drops the readings the place refuses, and a
+lookup that keeps the readings that exist. 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 |
 | --- | --- | --- |
@@ -153,6 +156,7 @@ end of the project path with `/-/`, so it reads one way.
 | 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 |
+| An include line, after its `~` | `namespace/recipe/path`, any part a glob, optionally starting with a `repo:` qualifier; see [Include syntax](configuration.md#include-syntax) |
 
 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
@@ -368,8 +372,9 @@ store:                     # every value is a default you can change
   maxBytes: 1073741824     # one gigabyte; past it, 'sous repo gc' evicts unpinned entries
   freshnessSeconds: 300    # how long a fetched index stays fresh
   watchPollSeconds: 300    # how often watch mode polls upstream
-recipeOutputs:             # 'memories' and 'prompts' take the same list-of-paths shape
-  skills: ["${projectRoot}/.claude/skills", "${projectRoot}/.codex/skills"]
+recipes:                   # what each content kind a subscribed recipe publishes does
+  skills: { outputs: ["${projectRoot}/.claude/skills", "${projectRoot}/.codex/skills"] }
+  memories: { first: ["communication/*"], exclude: ["tool-usage/automated-browser-tasks"] }
 varMappings:
   QA_SERVICE_TOKEN: workflow/qa-variables/qaServiceToken
 ```
@@ -380,7 +385,7 @@ varMappings:
 | `subscriptions` | a ref key | A bare namespace (every recipe in it, including ones published later) or `namespace/recipe`. No repo qualifier and no range in the key |
 | `enabled: false` | either of the two above | The opt-out for the entries sous provides itself, the `sous-recipes` repository and the `core` subscription |
 | `store` | fixed fields | Plain numbers, all optional; the values sous ships are defaults, not assumptions |
-| `recipeOutputs` | content kind | Destination directories per kind; see [recipeOutputs: where the files land](#recipeoutputs-where-the-files-land) |
+| `recipes` | content kind | What each kind does; see [recipes: what each content kind does](#recipes-what-each-content-kind-does) |
 | `varMappings` | environment variable name | Binds one name to one recipe variable, written `namespace/recipe/variableName` with an optional `repo:` qualifier |
 
 A repository's `url` may be a URL or an absolute path to one on this machine, read by the `local` provider
@@ -388,11 +393,21 @@ with identical trust. A hand-written entry is laid over sous's default field by
 `{ enabled: false }` is a complete opt-out, and a written `url` repoints the repository while the rest of
 the default stands.
 
-### recipeOutputs: where the files land
+### recipes: what each content kind does
 
-Where each content kind lands, `${var}` substituted as in any config path. Only `skills` has a default,
-`<project root>/.claude/skills`; sous cannot guess where memories or prompts go, so a kind with no
-destination is skipped and one warning names this key. A recipe's `config` contents become layers, not files.
+One block per content kind a subscribed recipe publishes. A recipe's `config` contents become layers, not files,
+and a recipe's own config layer may set `recipes.skills` only; `recipes.memories` chooses what the project
+includes, so it is dropped from a recipe's layer with a warning.
+
+- `recipes.skills.outputs` (`string[]`, default `["<project root>/.claude/skills"]`): the directories recipe skill
+  bundles are written into, `${var}` substituted as in any config path. Name several to feed more than one agent.
+- `recipes.memories.first` (`string[]`, default none): recipes whose memories lead the `#memories` view. An entry
+  is a glob over `namespace/recipe` keys (`communication/*`), or a regular expression written between two slashes
+  (`/^tool-usage\//`); a string, because a config layer is JSON and cannot hold a `RegExp`.
+- `recipes.memories.exclude` (`string[]`, default none): recipes whose memories the view leaves out, and the
+  build's unincluded-memory warning never lists. The same entry forms as `first`.
+
+There is no `prompts` block.
 
 ## Managed config layers
 

package/docs/markdown/repositories-quickstart.md

@@ -145,7 +145,7 @@ its name is rendered through LiquidJS and loses that segment (`SKILL.tpl.md` bec
 and any other file is copied verbatim. They are tracked like every file sous writes, so
 `sous prune` removes them when you unsubscribe. Where each kind lands is your project's decision,
 under
-[`recipeOutputs`](repositories-file-formats.md#recipeoutputs-where-the-files-land).
+[`recipes`](repositories-file-formats.md#recipes-what-each-content-kind-does).
 
 ## 6. Start a repository of your own
 

package/docs/markdown/repositories.md

@@ -47,7 +47,8 @@ $ 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.
+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.
 
 ```yaml
 # recipes/workflow/task-files/sous.recipe.yaml
@@ -193,10 +194,10 @@ 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 and hooks. 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.
+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. 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.
 
 ## The official repository, and the built-in core
 
@@ -279,8 +280,10 @@ $ sous build
   ✓ /home/me/my-project/.claude/skills/start-task/SKILL.md (~1,996 tokens)
 ```
 
-Skills default to `<project root>/.claude/skills`; every other content kind needs a destination in
-the [`recipeOutputs`](repositories-file-formats.md#recipeoutputs-where-the-files-land) block.
+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
+[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
 change that: **always-pull**, which installs a newer in-range version whenever one exists, and
@@ -324,13 +327,15 @@ README. None is ever overwritten, and directories holding rendered output are le
 ## Including recipe files in your own templates
 
 A template may pull in a file from a recipe through the reserved `~` sigil, naming the recipe's
-published identity and then the path inside it, on a line of its own:
+published identity and then the path inside it, on a line of its own. Any part may be a glob, and a
+`repo:` qualifier may start the path to say which repository when two publish the same namespace:
 
 ```text
 @~workflow/qa-helper/_partials/review-steps.md
+@~workflow/qa-helper/_partials/*.md
 ```
 
-The `~` is required. A bare `@path` is always a relative path or a declared alias, so an include
+A glob includes every file it matches, in bytewise path order. The `~` is required. A bare `@path` is always a relative path or a declared alias, so an include
 line can never quietly stop meaning a file on disk. In your own templates, `~<namespace>`
 resolves against every recipe the lockfile pins, whatever brought it in: a recipe you subscribe
 to, a member of a set you subscribe to, or a library another recipe depends on. Inside a recipe,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.31",
+  "version": "0.2.33",
   "description": "Compiles AI coding agent configuration (CLAUDE.md, skills, memories) from LiquidJS templates",
   "type": "module",
   "license": "Apache-2.0",
@@ -57,6 +57,7 @@
     "@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/recipes/core/sous-skills/skills/about-liquid-templates/SKILL.tpl.md

@@ -92,7 +92,7 @@ Include another file at render time (path **relative to the template file's dire
 {% endraw %}
 
 `render` resolves paths relative to the template file. For files outside that tree, use
-a recipe reference (`@~<namespace>/<recipe>/...`), a path **alias** (`@~project/...`, or a
+a recipe reference (`@~<namespace>/<recipe>/...`), a path **alias** (`@#project/...`, or a
 user-defined alias), a home-relative path (`@~/...`) or a `@`-prefixed `${var}` path; the
 same resolution as `@include` (see below) works in `render` too.
 
@@ -107,23 +107,24 @@ The `@path` syntax is processed by the build system before LiquidJS runs. It inc
 a file's content inline. Write `@` immediately followed by a `.md` path on its own line
 with nothing else on that line.
 
-`@include` works in both `.tpl.` and plain `.md` files. Included content is subject to
-LiquidJS rendering if the parent file is a `.tpl.` (so a Liquid tag inside the included
-file runs in the parent's render pass).
+`@include` works in both `.tpl.` and plain `.md` files. A file's own name decides whether it
+renders, every time: a `.tpl.` file always renders as Liquid and any other file never does, wherever
+it is included from. Each included file renders on its own, by its own name, with the including
+output's variables, and its text is then placed where the line was. A plain `.md` file that holds
+{% raw %}`{{ tags }}`{% endraw %} therefore keeps them verbatim; rename it `.tpl.md` when it needs rendering.
 
 The engine sets both `strictVariables: false` and `strictFilters: false`. An undefined
 variable renders as an empty string, and an **unknown filter silently no-ops**, passing
 its input through unchanged. Neither mistake raises an error, so a typo in a variable or
 filter name shows up only as missing or unfiltered output.
 
-### Gotcha: `@include` fires inside fenced code blocks
+### Fenced code blocks, repeats and malformed lines
 
-The `@include` processor runs on the raw file content *before* LiquidJS and has no
-markdown awareness whatsoever; it matches any line that is nothing but an `@`-prefixed
-`.md` path. A fenced code block does not protect it: an `@path.md` line inside triple
-backticks is still executed and replaced with the file's content. There is no escape
-syntax. To show an `@`-path as an example, put something else on the line (indent it,
-prefix it with a word, or wrap it in backticks inline).
+A line inside a fenced code block (``` or ~~~) is never an include, so an `@path.md` example
+inside a fence shows as written. The same file may be included in more than one place; a circular
+include is an error. A line that looks like an include (one word starting with `@`, holding a `/` or
+`.md`, or starting with `~`, `#`, `.` or `$`) but cannot be resolved fails the build, naming the file
+and the line; a line like `@alice thanks` is plain text.
 
 ### Path forms
 
@@ -133,12 +134,14 @@ A `@`-path may be any of:
 - **Variable-substituted**: `@${projectRoot}/prompts/x.md`; `${var}` is
   substituted before resolving; if the result is absolute it is used directly.
 - **Aliased**: `@<alias>/rest.md`, where the first segment names a registered alias.
+- **A glob**: `*`, `**`, `?`, `[..]` and `{a,b}` after substitution, as in `entryGlob`; it
+  includes every file it matches, in bytewise path order.
 
 ### Recipe references and path aliases
 
 The first path segment, up to the first `/` or `:` (both separators work, so `@a/b.md`
-is the same as `@a:b.md`), is matched first against the alias registry and then, when it begins with
-`~`, against the recipe namespaces this project or recipe can address.
+is the same as `@a:b.md`), is matched first against the alias registry (which holds the `#` names) and then, when it begins
+with `~`, against the recipe namespaces this project or recipe can address.
 
 The normal way to reach a file that another recipe publishes is a **recipe reference**,
 written `@~<namespace>/<recipe>/<path inside that recipe>`:
@@ -152,10 +155,15 @@ may address every recipe the project's lockfile pins, whatever brought it in. An
 is an error naming what was missing, so a reference can never quietly pick up a recipe
 nobody asked for.
 
-Built-in **aliases** are reserved, always begin with `~`, and are consulted before recipe
-namespaces. There is exactly one:
+Built-in names are reserved, begin with `#` (names sous or a plugin registers), and are consulted
+before recipe namespaces:
 
-- `@~project/...` → the consuming project's root.
+- `@#project/...` → the consuming project's root.
+- `@#memories/**/*.md` → a **view**: every memory published by a recipe this project holds
+  directly (a subscription, or a co-subscription of one), at the virtual path
+  `#memories/<namespace>/<recipe>/<path>`, in dependency order. A recipe held only through
+  `depends` contributes none. The `recipes.memories.first` and `recipes.memories.exclude` config
+  lists reorder and filter it.
 
 A bare `@~/...` is not an alias: the sigil followed only by a separator is the home
 directory, so `@~/notes/context.md` includes a file from your home directory.
@@ -168,7 +176,7 @@ Everything else sous once shipped inside its own package is published as a recip
 a recipe reference is what reaches it.
 
 Projects register their own aliases in settings via an `_aliases` block (root and/or
-project level); names may **not** start with `~` (reserved). An alias value is a string
+project level); names may **not** start with `~` or `#` (reserved). An alias value is a string
 or an array of strings (each may use `${var}`):
 
 ```
@@ -188,6 +196,13 @@ 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)
+
 **`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
 in a template. Remove before finalizing.

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

@@ -65,8 +65,14 @@ 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, hooks). A recipe held only through `depends` is a library: an active
-recipe may include, call or import its files, but it registers nothing itself.
+(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)
 
 ## Sous's Own Documentation
 

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

@@ -59,6 +59,10 @@ prefer the on-disk copies.
 - 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
+  `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.
 - 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

@@ -49,11 +49,21 @@ 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, memories and prompts land. A `config` file becomes
+  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`, `recipeOutputs`, `runtimeContext`, `store` and `varMappings` is dropped with a
+  `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)
 - `depends`, `subscribes` and `variables` are described below; `submissions` is in
   `about-sous-repos`.
 
@@ -153,13 +163,24 @@ 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 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
+contributes none, and the subscriber's build warns about a published memory no output includes.
+
 ## Includes and Partials
 
 A line holding only `@~<namespace>/<recipe>/<path>.md`, starting at the first column, includes that
 file from a recipe at its pinned version. Inside a recipe it resolves only against the recipe
 itself and the recipes it lists under `depends` or `subscribes`; the path may not be absolute or
-contain `.` or `..` segments, and it MUST end in `.md` (`notes.md` also finds `notes.tpl.md`). A
-line inside a fenced code block is never an include.
+contain `.` or `..` segments, and it MUST end in `.md` (`notes.md` also finds `notes.tpl.md`). Any
+part may be a glob, which includes every match. A line inside a fenced code block is never an
+include, and a line that looks like an include but cannot be read as one fails the build.
 
 A **partial** is a short piece of text several skills share, kept in the recipe's `_partials/`
 folder beside `skills/`. As long as no `contents` glob covers `_partials/`, it is never installed on
@@ -171,12 +192,11 @@ What to review: $ARGUMENTS
 @~review/checklist/_partials/review-rules.md
 ```
 
-The included text is pasted in before rendering, so any Liquid inside a partial renders only when
-the including file is a `.tpl.` file, and then with that file's variables. Every compiled source in
-the official sous repositories is named `*.tpl.md`, partials included, so a partial MAY use template
-variables: they render in every file that includes it. For example, a partial holding
+A file's own name decides whether it renders: a `.tpl.` file always renders as Liquid, and any other
+file never does, wherever it is included from. So a partial that uses template variables MUST be named
+`*.tpl.md`, and it renders with the including output's variables in every file that includes it. For
+example, a partial holding
 `{% raw %}Task files live in {{ taskFileRoot }}.{% endraw %}` renders with the project's answer wherever it is included.
-Name a new partial `*.tpl.md` too.
 
 ## Source for this Skill
 

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

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