@sous-io/sous 0.2.21 → 0.2.23

package/docs/markdown/_sidebar.md

@@ -24,3 +24,4 @@
   - [0003: Project setup with sous init](adrs/0003-project-init.md)
   - [0004: A global sous defers to the project's install](adrs/0004-project-install-handoff.md)
   - [0005: Follow-ups from the first project on the hand-off](adrs/0005-first-project-follow-ups.md)
+  - [0006: `sous repo init` follows `sous-recipes`](adrs/0006-repo-init-model-home.md)

package/docs/markdown/repositories-authoring.md

@@ -17,8 +17,11 @@ $ sous repo init ./my-recipes --name my-recipes --namespace workflow
   wrote sous.repo.yaml
   wrote sous.index.json
   wrote recipes/workflow/example/sous.recipe.yaml
-  wrote recipes/workflow/example/skills/example-skill/SKILL.md
+  wrote recipes/workflow/example/skills/example-skill/SKILL.tpl.md
   wrote README.md
+  wrote CONTRIBUTING.md
+  wrote CLAUDE.md
+  wrote AGENTS.md
   wrote .github/workflows/sous-release.yml
   wrote .gitignore
 ```
@@ -34,7 +37,11 @@ before releasing, since `sous repo release` reads and writes tags and fails in a
 commands spell `--yes`, `-y`, `--force` or `--trust`.
 
 `sous.repo.yaml` says what the repository publishes, `sous.index.json` is the catalog that `sous repo release`
-writes, and each recipe folder carries one `sous.recipe.yaml` beside the files it contributes. Nothing else is
+writes, and each recipe folder carries one `sous.recipe.yaml` beside the files it contributes. `CONTRIBUTING.md`,
+`CLAUDE.md` and `AGENTS.md` are for agents: they say that contribution instructions are written for agents, and
+point an agent at the sous core skills, which explain how a recipe repository works. The scaffold follows
+[`sous-io/sous-recipes`](https://github.com/sous-io/sous-recipes), a complete repository minus its recipes, and
+its placeholder skill is named `SKILL.tpl.md` because it ends with a footer that only a render fills in. Nothing else is
 fixed: recipe folders may live anywhere, and what makes a folder a recipe is that `sous.repo.yaml` lists its
 path under `recipes`. Both hand-written manifests are YAML or JSON and never JavaScript, because manifests are
 data: sous reads, validates and browses them without executing anything, before a repository is trusted, in a

package/docs/markdown/repositories-contributing.md

@@ -125,7 +125,7 @@ renaming a variable, or tightening a variable's validation). The changelog `sous
 recipe your change touches without a version raise, with a warning that a `--ci` release refuses it, so a missed
 one is visible in the proposal. The repository's
 own guide is named by the `contribute` field of its `sous.repo.yaml`; for `sous-recipes` it is its
-`CONTRIBUTING.md`.
+`CONTRIBUTING.md`, and a repository `sous repo init` created starts with a `CONTRIBUTING.md` of the same kind.
 
 **Core is edited in sous itself.** The `core` recipes in `sous-io/sous-recipes` are machine-written copies. Their
 source is `recipes/core/sous-skills/` in `sous-io/sous`, and each sous release overwrites the copy, so an edit

package/docs/markdown/repositories-quickstart.md

@@ -44,11 +44,13 @@ $ sous build
   ✓ .claude/skills/about-sous-configuration/SKILL.md (~1,204 tokens)
   ✓ .claude/skills/about-agent-skills/SKILL.md (~1,937 tokens)
   ✓ .claude/skills/about-liquid-templates/SKILL.md (~1,486 tokens)
+  ✓ .claude/skills/about-sous-repos/SKILL.md (~1,579 tokens)
+  ✓ .claude/skills/about-sous-recipes/SKILL.md (~1,639 tokens)
   ✓ .claude/skills/create-skill/SKILL.md (~655 tokens)
 ✓ Done.
 ```
 
-You subscribed to nothing and five skills appeared. That is the `core` namespace, which every
+You subscribed to nothing and seven skills appeared. That is the `core` namespace, which every
 project is auto-subscribed to at the version matching the CLI you are running. It carries the
 skills that teach an agent what sous manages and why it must not hand-edit a generated file.
 
@@ -133,7 +135,7 @@ gitignored `.sous/.env.local`. [Recipe variables](repositories-variables.md) cov
 ## 5. Look at what landed
 
 `sous subscription add` finishes by building, so the files are already on disk. `ls .claude/skills`
-now lists the five `core` skills plus the seven this recipe ships, among them `about-task-files`,
+now lists the seven `core` skills plus the seven this recipe ships, among them `about-task-files`,
 `start-task` and `resume-task`. The build dependency contributes nothing: a recipe held through
 `depends` is fetched and pinned, and its files stay out of your output.
 
@@ -159,8 +161,11 @@ sous repo init ~/projects/my-recipes --name my-recipes --namespace workflow
   wrote sous.repo.yaml
   wrote sous.index.json
   wrote recipes/workflow/example/sous.recipe.yaml
-  wrote recipes/workflow/example/skills/example-skill/SKILL.md
+  wrote recipes/workflow/example/skills/example-skill/SKILL.tpl.md
   wrote README.md
+  wrote CONTRIBUTING.md
+  wrote CLAUDE.md
+  wrote AGENTS.md
   wrote .github/workflows/sous-release.yml
   wrote .gitignore
 ```
@@ -171,7 +176,7 @@ recipe, with its own version.
 
 ## 7. Put something in the recipe
 
-Edit `recipes/workflow/example/skills/example-skill/SKILL.md` into a real skill, then name the
+Edit `recipes/workflow/example/skills/example-skill/SKILL.tpl.md` into a real skill, then name the
 recipe in its manifest:
 
 ```yaml

package/package.json

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

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

@@ -48,8 +48,10 @@ user-invocable: false
 
 **`name`**: becomes the `/slash-command`. Defaults to the directory name if omitted.
 
-**`description`**: tells the agent when to invoke this skill. Use strong trigger
-language: open with "YOU MUST load this skill when...". Under 500 chars.
+**`description`**: tells the agent when to invoke this skill. For a skill the agent
+may load on its own, use strong trigger language: open with "YOU MUST load this skill
+when...". A command the user alone can run gets a plain description instead (see
+"Writing a Skill's Text"). Under 500 characters.
 
 **`disable-model-invocation`**: set `true` to prevent the agent from invoking the
 skill automatically. Use this for command skills that represent intentional,
@@ -116,8 +118,9 @@ that inventory things which will evolve (e.g. available skills, current files in
 directory). Teach the agent where to look rather than providing a snapshot that will go
 stale. Only document things stable by nature.
 
-**Use strong trigger language.** Descriptions must open with `YOU MUST load this
-skill when...`. Cross-references to other skills must use `YOU MUST load`; weak
+**Use strong trigger language where the agent decides.** A skill the agent may load on
+its own MUST open its description with `YOU MUST load this skill when...`; a command the
+user alone can run gets a plain description. Cross-references to other skills must use `YOU MUST load`; weak
 language like "consult" or "see" is not sufficient. In a skill body, write the
 requirement so it binds whichever agent executes ("The agent performing this work MUST
 load `x`"), not just the main session: delegated sub-agents start with fresh context and
@@ -133,29 +136,94 @@ user must return it to the orchestrator, which relays it.
 **If no action skill exists for a task, ask the user.** Do not improvise an action
 that warrants its own skill.
 
+## Writing a Skill's Text
+
+These rules apply to every new skill, memory, partial and reference file. A skill is read by an
+agent that has read nothing else, so it has to be unambiguous on its own.
+
+MUST, MUST NOT, SHOULD, SHOULD NOT and MAY carry the meaning RFC 2119 gives them when, and only
+when, they appear in capitals (RFC 8174). Write them in capitals wherever a sentence states a rule;
+a lowercase "must" is ordinary English. NEVER means exactly MUST NOT, and ALWAYS exactly MUST, as
+more emphatic forms.
+
+- https://www.rfc-editor.org/rfc/rfc2119
+- https://www.rfc-editor.org/rfc/rfc8174
+
+The rules:
+
+- **The user and the agent.** Instruction text says "the user" and "the agent", never "me", "I" or
+  "you" for either. An imperative ("Load `x` first.") needs no subject. Example output, meaning what
+  the agent will say to the user, speaks naturally, "I" and "you" included.
+- **Brief.** A skill SHOULD be brief; move depth into `references/`.
+- **Explain before listing.** Say what a list is before it starts, and define every term it depends
+  on. Assume the reader has read nothing else.
+- **Show it applied.** Follow a list of rules with an example of them applied; several when each
+  adds real value. A skill that produces something for the user (a report, a list, a question) MUST
+  include an example of that output, in a `text` fence.
+- **Description tone follows invocation.** A skill the agent may load on its own opens its
+  description with "YOU MUST load this skill when...". A command only the user can run
+  (`disable-model-invocation: true`) gets a plain description of what it does; the agent never sees
+  it, and the user reads it in the `/` menu.
+- **Arguments are optional.** A command that takes arguments places `$ARGUMENTS` under a label
+  saying what they are, and treats them as refining the goal. With none, it takes the broadest
+  reasonable reading of roughly the last 10 turns, NEVER asks which of several targets was meant,
+  and names what it took in the first line of its reply.
+- **Tiers, never models.** Name a sub-agent's model by tier ("the next tier down from the main
+  session"), never by product or provider.
+- **Public by default.** A skill published in a recipe repository is public: its examples use
+  fictional people and projects, and it names no real colleague, private project or private URL.
+- **Plain text.** No em-dashes (use semicolons, commas or parentheses), no emojis, and complete
+  sentences with no compressed notation.
+
+Example of a command's opening under these rules:
+
+```markdown
+---
+name: walk
+description: Go through what still needs the user's input, or a named topic, one item at a time.
+argument-hint: "[what to walk through]"
+disable-model-invocation: true
+---
+
+# Walk Through It, One Item at a Time
+
+What to walk through: $ARGUMENTS
+
+If nothing is named above, walk through everything in roughly the last 10 turns that still needs
+the user's input, and name what was gathered in the first line of the reply. The agent MUST NOT
+present the next item until the user says "Next".
+```
+
 ## Template-Compiled Skills
 
-Every skill distributed from a shared library, whether this library (`sous`) or any other
-shared skill library, must use `SKILL.tpl.md`, not `SKILL.md`. This is required because
-every distributed skill must end with a `## Source for this Skill` section (see below), and
-that section uses a template variable for the source path, which requires LiquidJS rendering.
-No exceptions.
+Every skill MUST be named `SKILL.tpl.md`, not `SKILL.md`, because every skill ends with a
+`## Source for this Skill` footer, and the footer's source path is a template variable that only a
+LiquidJS render fills in. No exceptions, even for a skill with no other variables.
+
+A skill published in a recipe names its recipe:
+
+```
+## Source for this Skill
+
+This skill comes from the `<namespace>/<recipe>` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
+
+- Source Path: <resolved source path>
+```
 
-Every such skill's `SKILL.md` must end with a `## Source for this Skill` section:
+A project's own skill says it belongs to the project:
 
 ```
 ## Source for this Skill
 
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
+This skill belongs to this project and was compiled by sous from a template, so edit the source,
+never this output file.
 
 - Source Path: <resolved source path>
 ```
 
-This tells agents reading the compiled output where the skill originated and that the
-file must not be edited directly. Because this footer is required, all shared skills must
-use `SKILL.tpl.md` (not `SKILL.md`) so the source path variable can be rendered at
-compile time.
+The footer tells an agent reading the compiled copy where the skill came from and where to make a
+change.
 
 ## Examples
 
@@ -171,7 +239,7 @@ compile time.
 
 ## Source for this Skill
 
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
+This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
 
-- Source Path: {{ sousTemplatePath }}
+- Source Path: {{ sousTemplatePath }}

package/recipes/core/sous-skills/skills/about-agent-skills/examples/{do-something.md → do-something.tpl.md}

@@ -3,9 +3,7 @@
 ```markdown
 ---
 name: deploy
-description: >
-  YOU MUST use this skill when deploying the application. Do not use for rollbacks;
-  those follow a different process.
+description: Deploy the application to a target environment.
 disable-model-invocation: true
 ---
 

package/recipes/core/sous-skills/skills/about-agent-skills/references/{commands.md → commands.tpl.md}

@@ -23,6 +23,10 @@ Commands often accept arguments (e.g. `/deploy staging`). When they do:
    be substituted. See `substitutions.md` for full syntax.
 2. Add an `argument-hint` field to frontmatter; it appears in autocomplete next to the
    command name.
+3. A command that takes arguments also works without them. Put `$ARGUMENTS` under a label
+   saying what the arguments are. With none, the agent takes the broadest reasonable
+   reading of roughly the last 10 turns, never asks which target was meant, and names what
+   it took in the first line of its reply.
 
 ```yaml
 ---

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

@@ -284,7 +284,7 @@ The following variables are in scope at compile time in this project:
 
 ## Source for this Skill
 
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
+This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -0,0 +1,82 @@
+# LiquidJS Built-in Filters
+
+Standard filters available in all `.tpl.` files. Chained with `|`.
+
+## String
+
+| Filter | Description | Example |
+|:-------|:------------|:--------|
+| `upcase` | Uppercase | `{% raw %}{{ "hello" | upcase }}{% endraw %}` → `HELLO` |
+| `downcase` | Lowercase | `{% raw %}{{ "HELLO" | downcase }}{% endraw %}` → `hello` |
+| `capitalize` | First char uppercase | `{% raw %}{{ "hello world" | capitalize }}{% endraw %}` → `Hello world` |
+| `strip` | Remove leading/trailing whitespace | `{% raw %}{{ "  hi  " | strip }}{% endraw %}` → `hi` |
+| `lstrip` | Remove leading whitespace | |
+| `rstrip` | Remove trailing whitespace | |
+| `strip_newlines` | Remove all newlines | |
+| `strip_html` | Remove HTML tags | |
+| `escape` | HTML-escape `<`, `>`, `&`, `"` | |
+| `url_encode` | Percent-encode a URL string | |
+| `url_decode` | Decode a percent-encoded string | |
+| `append` | Append a string | `{% raw %}{{ "foo" | append: "bar" }}{% endraw %}` → `foobar` |
+| `prepend` | Prepend a string | `{% raw %}{{ "bar" | prepend: "foo" }}{% endraw %}` → `foobar` |
+| `replace` | Replace all occurrences | `{% raw %}{{ "aabbcc" | replace: "b", "x" }}{% endraw %}` → `aaxxcc` |
+| `replace_first` | Replace first occurrence | |
+| `remove` | Remove all occurrences | `{% raw %}{{ "aabbcc" | remove: "b" }}{% endraw %}` → `aacc` |
+| `remove_first` | Remove first occurrence | |
+| `truncate` | Truncate to N chars (adds `...`) | `{% raw %}{{ "hello world" | truncate: 7 }}{% endraw %}` → `hell...` |
+| `truncatewords` | Truncate to N words | `{% raw %}{{ "one two three" | truncatewords: 2 }}{% endraw %}` → `one two...` |
+| `split` | Split string into array | `{% raw %}{{ "a,b,c" | split: "," }}{% endraw %}` → `["a","b","c"]` |
+| `newline_to_br` | Replace `\n` with `<br>` | |
+
+## Array
+
+| Filter | Description | Example |
+|:-------|:------------|:--------|
+| `join` | Join array with separator | `{% raw %}{{ arr | join: ", " }}{% endraw %}` |
+| `first` | First element | `{% raw %}{{ arr | first }}{% endraw %}` |
+| `last` | Last element | `{% raw %}{{ arr | last }}{% endraw %}` |
+| `reverse` | Reverse order | |
+| `sort` | Sort ascending (case-sensitive) | |
+| `sort_natural` | Sort ascending (case-insensitive) | |
+| `uniq` | Remove duplicates | |
+| `compact` | Remove nil/falsy values | |
+| `map` | Extract a property from each object | `{% raw %}{{ items | map: "name" }}{% endraw %}` |
+| `where` | Filter objects by property value | `{% raw %}{{ items | where: "active", true }}{% endraw %}` |
+| `concat` | Concatenate two arrays | `{% raw %}{{ arr1 | concat: arr2 }}{% endraw %}` |
+| `slice` | Extract a sub-array | `{% raw %}{{ arr | slice: 1, 3 }}{% endraw %}` |
+| `size` | Length of string or array | `{% raw %}{{ arr | size }}{% endraw %}` |
+| `push` | Append element to array | |
+| `pop` | Remove last element | |
+| `shift` | Remove first element | |
+| `unshift` | Prepend element to array | |
+
+## Number
+
+| Filter | Description | Example |
+|:-------|:------------|:--------|
+| `plus` | Add | `{% raw %}{{ 4 | plus: 2 }}{% endraw %}` → `6` |
+| `minus` | Subtract | `{% raw %}{{ 4 | minus: 2 }}{% endraw %}` → `2` |
+| `times` | Multiply | `{% raw %}{{ 4 | times: 2 }}{% endraw %}` → `8` |
+| `divided_by` | Divide | `{% raw %}{{ 10 | divided_by: 2 }}{% endraw %}` → `5` |
+| `modulo` | Modulus | `{% raw %}{{ 10 | modulo: 3 }}{% endraw %}` → `1` |
+| `abs` | Absolute value | `{% raw %}{{ -4 | abs }}{% endraw %}` → `4` |
+| `ceil` | Round up | `{% raw %}{{ 4.1 | ceil }}{% endraw %}` → `5` |
+| `floor` | Round down | `{% raw %}{{ 4.9 | floor }}{% endraw %}` → `4` |
+| `round` | Round to nearest (or N decimal places) | `{% raw %}{{ 4.567 | round: 2 }}{% endraw %}` → `4.57` |
+| `at_least` | Clamp to minimum | `{% raw %}{{ 3 | at_least: 5 }}{% endraw %}` → `5` |
+| `at_most` | Clamp to maximum | `{% raw %}{{ 7 | at_most: 5 }}{% endraw %}` → `5` |
+
+## Other
+
+| Filter | Description | Example |
+|:-------|:------------|:--------|
+| `default` | Fallback if nil/empty/false | `{% raw %}{{ val | default: "n/a" }}{% endraw %}` |
+| `date` | Format a date | `{% raw %}{{ "now" | date: "%Y-%m-%d" }}{% endraw %}` |
+| `size` | Length of string or array | `{% raw %}{{ "hello" | size }}{% endraw %}` → `5` |
+| `json` | Serialize to JSON string | `{% raw %}{{ obj | json }}{% endraw %}` |
+
+## Sous Custom Filters
+
+| Filter | Description |
+|:-------|:------------|
+| `bulletList` | Convert array to markdown bullet list (`- item` per line) |

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

@@ -39,6 +39,9 @@ YOU MUST load `about-sous-configuration` when creating or editing the project's
 config (`sous.config.*`, `conf.d/` layers), defining or debugging config variables, or
 diagnosing a ConfigError.
 
+YOU MUST load `about-sous-repos` when working inside a recipe repository (one with a
+`sous.repo.yaml` at its root), and `about-sous-recipes` when creating or changing a recipe.
+
 ## Sous's Shared Recipes
 
 The `about-sous`, `about-sous-configuration`, `about-agent-skills` and
@@ -78,7 +81,7 @@ far.
 
 ## Source for this Skill
 
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
+This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -69,7 +69,7 @@ prefer the on-disk copies.
 
 ## Source for this Skill
 
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
+This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -0,0 +1,182 @@
+---
+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.
+user-invocable: false
+license: Apache-2.0
+compatibility:
+  - claude
+  - codex
+---
+
+# About Sous Recipes
+
+A **recipe** is a versioned bundle of agent instructions that sous installs into every project
+subscribed to it. It is one folder in a recipe repository, holding a `sous.recipe.yaml` manifest
+beside the files it publishes. For the repository around it (the repo manifest, the index,
+releasing and proposing), YOU MUST load `about-sous-repos`. For writing a skill inside it, YOU MUST
+load `about-agent-skills`.
+
+## The Manifest
+
+The manifest is YAML or JSON, never JavaScript, and unknown keys are refused except extension keys
+starting with `x-`. A typical one:
+
+```yaml
+formatVersion: 1
+namespace: review
+name: checklist
+version: 1.2.0
+description: >-
+  A pre-merge review checklist, with a command that walks a change through it.
+depends:
+  - review/wording
+contents:
+  - kind: skills
+    include:
+      - skills/**/*
+```
+
+The fields in that example:
+
+- `formatVersion` is always `1`.
+- `namespace` MUST be declared in the repo manifest, and `name` is unique inside it. Both are
+  lowercase kebab-case, and together (`review/checklist`) they are the recipe's identity.
+- `version` is an exact semantic version (see "Raising the Version").
+- `description` is optional; it is copied into the index, and shown by `sous recipe list` and
+  `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
+  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
+  warning. A recipe that only bundles others may leave `contents` out.
+- `depends`, `subscribes` and `variables` are described below; `submissions` is in
+  `about-sous-repos`.
+
+A file whose name contains `.tpl.` is rendered through LiquidJS and loses the `.tpl.`; every other
+file is copied as it is. YOU MUST load `about-liquid-templates` before deciding which a file needs.
+
+## Raising the Version
+
+Every change to a published recipe raises its version, in the same change. Versions are semantic:
+
+- **patch** for wording and fixes;
+- **minor** for new files or a new optional variable;
+- **major** for anything that breaks an existing subscriber: removing or renaming a file, renaming or
+  removing a variable, or tightening a variable's validation.
+
+The version rises once per release. When several changes to one recipe travel together, it rises
+once, by the largest step any of them needs. A version already raised past the recipe's last tag
+is left alone by every later release run.
+
+A contributor proposing a change edits `version` by hand. A maintainer releasing from the
+repository itself may instead commit the change and run
+`sous repo release --recipe <namespace>/<recipe> --bump <level>` (`patch` by default, `minor`,
+`major` or `prerelease`), which raises every changed recipe in scope whose version still equals its
+last tag and commits the raise together with the regenerated index. A proposal MUST NOT carry that
+index change, because `sous repo submit` refuses one that edits `sous.index.json`;
+`about-sous-repos` describes the rest of that run.
+
+Example: `review/checklist` is at `1.2.0`, its last tag. One pull request fixes a typo (a patch) and
+adds a command (a minor). The manifest goes to `1.3.0`, once.
+
+## Variables
+
+A recipe that needs a value from the project declares a **definition**; the project stores the
+answer in its env files, and a `.tpl.` file renders it by the definition's name.
+
+```yaml
+variables:
+  - name: reviewNotesDir
+    type: path
+    prompt: Where should review notes be kept?
+    description: >-
+      The checklist command writes one note per branch into this directory. The
+      default keeps them inside the project's .sous directory. Any path works,
+      relative to the project root or absolute.
+    example: docs/review-notes
+    default: .sous/review-notes
+    scope: shared
+```
+
+The fields in that example, and the ones it leaves out:
+
+- `name` is camelCase. `type` is `string`, `number`, `boolean`, `enum`, `path` or `url`; an `enum`
+  MUST list its options under `validate.enum`. `required` defaults to true.
+- `description` and `example` are REQUIRED; a manifest missing either is refused. The description
+  says, in full sentences, what the setting is for, what the default does, and what else is
+  acceptable; the `prompt` is one plain question. An example is only shown beside the question,
+  never stored or offered as an answer; a `default` is the answer of last resort. Both MUST fit the
+  declared type.
+- Every variable MUST provide a conservative default: the answer that does the least harm when the
+  project never chose one. For example, a setting for whether the agent may merge pull requests on
+  its own defaults to "only when asked", never to "always".
+- `scope: local` stores the answer in the gitignored `.sous/.env.local`; use it for anything that
+  belongs to one person or one machine. `scope: shared`, the default, stores it in the committed
+  `.sous/.env`.
+- `secret: true` hides the value wherever sous prints it. A secret MUST also set `scope: local`
+  explicitly; a secret left at the default scope is refused.
+- `env` names the environment variable the answer binds to, for example to reuse a `GITHUB_TOKEN`
+  the environment already carries. Left out, it is `SOUS_VAR_` plus the name in upper snake case
+  (`reviewNotesDir` becomes `SOUS_VAR_REVIEW_NOTES_DIR`). Two definitions of different names MUST
+  NOT claim the same environment variable.
+- `validate` takes `pattern`, `minLength`, `maxLength`, `min`, `max` and `enum`. Within a major
+  version a definition MAY only loosen; tightening is a major bump, because an upgrade re-checks the
+  answers already stored.
+
+## Depends and Subscribes
+
+Both lists name other recipes, and they do different things:
+
+- `depends` makes the other recipe a **library** for this one. It is fetched and pinned, and its
+  files can be included from this recipe's templates, but its files never reach the subscriber's
+  output.
+- `subscribes` is a **co-subscription**. The other recipe's files land and its questions are asked,
+  as if the project had subscribed to it too.
+
+Each entry names its target by where it lives, in one of two forms:
+
+- a bare `namespace/recipe` for a sibling in the same repository. With no range it means the
+  version released alongside this one; an `@` range (npm's rules) is allowed but uncommon.
+- a locator URL for a recipe in another repository, such as
+  `github://example-org/team-recipes/review/wording@^1.0`. The scheme is the provider, and the last
+  two segments are always the recipe's namespace and name, never a path on disk.
+
+`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.
+
+## 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.
+
+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
+its own; it reaches a project only inside the skills that include it:
+
+```markdown
+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
+`{% 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
+
+This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
+
+- Source Path: {{ sousTemplatePath }}

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

@@ -0,0 +1,177 @@
+---
+name: about-sous-repos
+description: >
+  YOU MUST load this skill when working inside a sous recipe repository (one with a
+  sous.repo.yaml at its root), adding a namespace or a recipe to one, running sous repo
+  release, sous repo submit, sous repo link, sous repo contribute or sous repo init, or
+  deciding what happens to a change when it is proposed, merged or released.
+user-invocable: false
+license: Apache-2.0
+compatibility:
+  - claude
+  - codex
+metadata:
+  version: 1.0.0
+  tags: [sous, recipes, repositories]
+---
+
+# About Sous Recipe Repositories
+
+A **recipe** is a versioned bundle of agent instructions (skills, memories, prompts and config
+layers) that sous installs into every project subscribed to it. A **recipe repository** is a git
+repository that publishes recipes. It is not a sous project and needs no `.sous/` directory; the
+commands that work on it (`sous repo release`, `sous repo submit`) run from anywhere inside it,
+and find its root by walking up to the first directory holding a repo manifest.
+
+Everything here holds for every recipe repository, the official `sous-io/sous-recipes` included.
+For one recipe (its manifest, version, variables, contents and dependencies), YOU MUST load
+`about-sous-recipes`.
+
+## The Files
+
+A recipe repository holds three kinds of file that sous reads:
+
+- `sous.repo.yaml`, the **repo manifest**, written by hand: the repository's suggested short name,
+  an optional description, its namespaces, and the list of recipe folders it publishes. A folder
+  is a recipe because this list names it; a new recipe folder MUST be added to the list, or it is
+  not published. Every recipe MUST belong to a namespace declared here.
+- `sous.recipe.yaml`, one **recipe manifest** in each recipe folder; see `about-sous-recipes`.
+- `sous.index.json`, the **index**: the catalog projects read, written only by `sous repo release`.
+  NEVER edit it by hand.
+
+Manifests are YAML (`.yaml`, `.yml`) or JSON (`.json`, `.jsonc`, both allowing comments and
+trailing commas), never JavaScript: sous reads them before anyone has trusted the repository, so
+nothing in them may run. Unknown keys are refused, except extension keys starting with `x-`. A
+recipe folder MUST NOT contain a symbolic link; the release refuses one.
+
+```yaml
+formatVersion: 1
+name: team-recipes
+description: >-
+  Review and release recipes for the Harbor Labs engineering team.
+namespaces:
+  review:
+    description: Recipes about reviewing code.
+recipes:
+  - recipes/review/checklist
+contribute: https://github.com/harbor-labs/team-recipes/blob/main/CONTRIBUTING.md
+```
+
+`contribute` is optional: a URL or a sentence saying how changes are sent, printed by
+`sous repo submit` when the repository's host cannot open a proposal for the contributor.
+
+## Versions, Tags and the Index
+
+A recipe's version lives in its manifest, which is the source of truth. A version is **published**
+once a git tag shaped `namespace/recipe@version` exists for it (for example
+`review/checklist@1.2.0`). The index records each published version with its content hash, its
+tag and the exact versions of its dependencies at release time; for the length of one release
+commit it also records the version each manifest declares, whose tag that release cuts next. A
+published version never changes: new files need a new version, and a release refuses to publish
+different content under a version already tagged. A lost index is rebuilt from the tags.
+
+## Releasing
+
+`sous repo release` publishes. It refuses to run while anything is uncommitted, or while git
+cannot say who is committing. In one run it:
+
+1. validates every manifest;
+2. finds the recipes whose files changed since the tag that last published them (a recipe never
+   tagged is released at the version its manifest declares);
+3. raises the version of each changed recipe whose version still equals that tag (a patch step by
+   default; `--bump minor` or `--bump major` for more);
+4. regenerates `sous.index.json`;
+5. commits the manifests and the index together;
+6. cuts one annotated tag per new version, dependencies first.
+
+It prints that plan and asks once. `--yes` answers ahead, `--dry-run` stops after the plan, and
+`--push` pushes the commit and the tags. `--namespace` and `--recipe` narrow the scope, and
+`--include-unchanged` releases unchanged recipes too. On a branch other than the default one it
+raises and commits but cuts no tags, because tags are cut after the merge; `--tag` overrides that.
+Two presets matter most:
+
+- `--check` only reads. It validates every manifest, reports how a merge would rewrite the index
+  (as information, never as a failure), lists the versions that publish on merge, and fails a
+  change to a recipe whose `submissions` block refuses proposals.
+- `--ci` is for automation after a merge. It raises no versions, accepts the plan without asking,
+  and fails on any changed recipe whose version still equals its last tag. It does NOT push; pass
+  `--push` for that.
+
+## What Happens to a Change
+
+A repository made by `sous repo init` carries `.github/workflows/sous-release.yml`, which runs:
+
+- on every pull request, `sous repo release --check`;
+- on every push to `main`, `sous repo release --ci --push --yes`, which tags every version that has
+  no tag yet, commits the regenerated index when it changed, and pushes both.
+
+So a change to a recipe MUST raise that recipe's version in the pull request itself, by editing
+`version` in its `sous.recipe.yaml`: after the merge, `--ci` refuses a recipe whose files changed
+while its version stayed the same. A contributor NEVER runs `sous repo release` on a proposal
+branch (`--check` and `--dry-run` excepted), because it commits a regenerated index and
+`sous repo submit` refuses a change that edits the index.
+
+Example: a contributor fixes a typo in `review/checklist`, which is at `1.2.0`, its last tag. The
+pull request changes the skill file and sets `version: 1.2.1`; `--check` passes and lists
+`review/checklist@1.2.1` as publishing on merge; after the merge, `--ci` regenerates the index,
+commits it and cuts the tag `review/checklist@1.2.1`.
+
+## Proposing a Change
+
+`sous repo submit` proposes a change to a repository's maintainers and follows the proposal through
+its life: it opens one, pushes new commits to an open one (replacing its title or description when
+new ones are given), reports on one (`--status` only reports), or moves to a new branch once one
+was merged. It runs in the repository's checkout, or from a project that links it (`sous repo
+submit <repo>`). Run on the default branch, it first creates a branch named
+`sous/submit-<date>-<time>`; `--branch` names another.
+
+Before sending anything it checks that everything is committed (`--commit` commits it, after
+listing the changes and asking once), validates the repository, and confirms the change leaves
+`sous.index.json` alone. It pushes through a fork on the contributor's own account when the
+contributor cannot push to the repository, and NEVER forces a push. The title and the description
+come from the user (`--title` and `--body`, or asked); sous never borrows a commit message, and
+adds a changelog it builds by comparing the manifests with the default branch.
+
+Either manifest can carry a `submissions` block, for recipes whose files are copied in from
+somewhere else; a recipe's own block wins over the repository's:
+
+```yaml
+submissions:
+  allowed: false
+  instead: Propose changes in harbor-labs/tooling, under recipes/review/.
+```
+
+`submit` warns, prints the `instead` text and asks before going on; `release --check` fails such
+a pull request. The release itself is never restricted.
+
+## Editing From a Project
+
+`sous repo link <repo>`, run in a project, points that project at a working copy of the
+repository, cloning it into `.sous/repos/<owner>/<name>` when needed (`--global` uses the
+machine-wide checkout under the user-level sous directory), so an edit shows in the project's next
+build with no release. A path in place of `<repo>` links that checkout where it is. A link never
+changes a checkout on its own: `--branch`, `--create-branch` and `--generate-branch` choose the
+branch, `--from` sets the base of a new one, and `--latest` brings it up to upstream after listing
+anything that would be discarded.
+
+`sous repo unlink <repo>` drops the link and goes back to the pinned versions; `--update` also
+moves the pins to the newest released versions their ranges allow, and `--remove` deletes a
+checkout sous cloned. `sous repo contribute <ref>` chains the three commands: it links on a new
+branch (`sous/edit-<date>-<time>`), and with `--finish` it submits whatever no proposal carries
+yet, then unlinks with `--update`.
+
+## Creating a Repository
+
+`sous repo init [dir]` writes a new recipe repository into the directory (the current one by
+default): the repo manifest, an empty index, one example recipe with its manifest and a
+placeholder skill, a README, `CONTRIBUTING.md`, `CLAUDE.md` and `AGENTS.md` for agents, the release
+workflow and a `.gitignore`. `sous-io/sous-recipes` is the model a scaffold follows: a new repository
+is as complete as it, minus its recipes. It does not run git: run `git init`, commit, and add a
+remote before the first release, because `sous repo release` reads and writes tags. Every new recipe folder is then listed under `recipes` in `sous.repo.yaml`.
+
+## Source for this Skill
+
+This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
+
+- Source Path: {{ sousTemplatePath }}

package/recipes/core/sous-skills/skills/create-skill/SKILL.tpl.md

@@ -74,14 +74,16 @@ variable straight into the output. The footer:
 ```markdown
 ## Source for this Skill
 
-This skill was compiled from a template and the output file should not be edited directly.
+This skill belongs to this project and was compiled by sous from a template, so edit the source,
+never this output file.
 
 - Source Path: {{ sousTemplatePath }}
 ```
 {% endraw %}
 
 The `{{ sousTemplatePath }}` variable renders to the absolute path of the source template
-at compile time, telling agents where the skill originated.
+at compile time, telling agents where the skill originated. A skill published in a recipe
+names its recipe instead; `about-agent-skills` has that form.
 
 For other files in the skill directory (references, scripts, supporting docs), use `.tpl.`
 naming only when the file genuinely needs LiquidJS processing. YOU MUST load
@@ -107,7 +109,7 @@ load `about-liquid-templates` if any file in your skill needs `.tpl.` processing
 
 ## Source for this Skill
 
-This skill was pulled from the `sous` project's "shared skills" library. It was compiled from a template and
-the output file should not be edited directly.
+This skill comes from the `core/sous-skills` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
 
 - Source Path: {{ sousTemplatePath }}

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

@@ -11,13 +11,13 @@ formatVersion: 1
 
 namespace: core
 name: sous-skills
-version: 0.2.21
+version: 0.2.23
 
 description: >-
   The skills that teach an agent what sous is and how it works: which files sous
   owns and must never be hand-edited, how a sous configuration is written and
   debugged, the .tpl. template convention and LiquidJS syntax, what an agent
-  skill is, and how to create one.
+  skill is and how to create one, and how a recipe repository and a recipe work.
 
 # The copy in sous-io/sous-recipes is overwritten by every sous release, so a
 # change proposed there would be lost, and a version it tagged would collide

package/src/lib/repos/scaffold/index.ts

@@ -22,6 +22,9 @@ import { parseRecipeManifest } from "../formats/recipe-manifest.js";
 import { parseRepoManifest } from "../formats/repo-manifest.js";
 import { findRepoManifest, loadJsonFile, loadManifestFile } from "../load-manifest.js";
 import {
+  buildAgentsMd,
+  buildClaudeMd,
+  buildContributing,
   buildExampleSkill,
   buildGitignore,
   buildIndexFile,
@@ -79,9 +82,10 @@ type PlannedFile = {
 };
 
 /**
- * Creates a new recipe repository: a repo manifest, one example recipe with a
- * placeholder skill, an empty but valid index, a README, release automation and
- * a `.gitignore`.
+ * Creates a new recipe repository modeled on `sous-io/sous-recipes`: a repo
+ * manifest, one example recipe with a placeholder skill, an empty but valid
+ * index, a README, a `CONTRIBUTING.md`, a `CLAUDE.md` and an `AGENTS.md` for
+ * agents, release automation and a `.gitignore`.
  *
  * @param options - What to scaffold, and where.
  */
@@ -138,10 +142,13 @@ function planFiles(context: ScaffoldContext): PlannedFile[] {
       contents: buildRecipeManifest(context),
     },
     {
-      relativePath: `${recipeDir}/skills/example-skill/SKILL.md`,
+      relativePath: `${recipeDir}/skills/example-skill/SKILL.tpl.md`,
       contents: buildExampleSkill(context),
     },
     { relativePath: "README.md", contents: buildReadme(context) },
+    { relativePath: "CONTRIBUTING.md", contents: buildContributing(context) },
+    { relativePath: "CLAUDE.md", contents: buildClaudeMd(context) },
+    { relativePath: "AGENTS.md", contents: buildAgentsMd() },
     {
       relativePath: ".github/workflows/sous-release.yml",
       contents: buildReleaseWorkflow(),

package/src/lib/repos/scaffold/templates.ts

@@ -59,8 +59,9 @@ description: >-
   One paragraph saying what this repository publishes and who it is for.
 
 # Where to send a change. Shown to anyone whose provider cannot open a proposal
-# for them, so a contributor is never left without a route.
-# contribute: https://example.com/contributing
+# for them, so a contributor is never left without a route. Point it at this
+# repository's CONTRIBUTING.md once the repository has a public URL.
+# contribute: https://github.com/<owner>/${context.name}/blob/main/CONTRIBUTING.md
 
 # Namespaces group recipes. They are not versioned, and a project may subscribe
 # to a whole namespace, which means every recipe in it, including ones published
@@ -164,7 +165,9 @@ contents:
 }
 
 /**
- * The placeholder skill the example recipe contributes.
+ * The placeholder skill the example recipe contributes. It is named
+ * `SKILL.tpl.md`, as every skill is, because it ends with the footer every
+ * skill carries, and the footer's source path is only filled in by a render.
  *
  * @param context - The repository being scaffolded.
  */
@@ -182,14 +185,23 @@ This file is a placeholder written by 'sous repo init'. Replace it with a real
 skill, or delete it once the ${context.recipe} recipe has content of its own.
 
 A skill is ordinary markdown. Everything under this recipe's 'contents' entry is
-copied into a subscribing project's agent skill directory, so what you write
-here is what an agent reads there.
+compiled into a subscribing project's agent skill directory, so what you write
+here is what an agent reads there. The '.tpl.' in this file's name means it is
+rendered as a LiquidJS template on the way, and the name it is written under
+drops the '.tpl.'.
 
 ## What to put here
 
 Describe the concept the skill covers, then the rules an agent should follow
 when it applies. Keep it short enough to be read in full, and point at reference
 files for anything long.
+
+## Source for this Skill
+
+This skill comes from the \`${context.namespace}/${context.recipe}\` recipe, installed by sous from a recipe
+repository. It was compiled from a template, so edit the source, never this output file.
+
+- Source Path: {{ sousTemplatePath }}
 `;
 }
 
@@ -292,6 +304,12 @@ To propose a change to a repository you do not maintain, commit it and run
 \`sous repo submit\`, which validates everything first and then opens a pull
 request through your provider's own command line tool.
 
+## Contributing
+
+Improvements are welcome, including new recipes. Contribution instructions in this repository are
+written for agents: \`CONTRIBUTING.md\` says why, and \`CLAUDE.md\` is where an agent without the sous
+core skills starts.
+
 ## Using it
 
 In any project that has a sous config:
@@ -316,9 +334,93 @@ sous repo link ${context.name} /path/to/this/checkout
 
 Builds say loudly when a repository is linked. Run \`sous repo unlink ${context.name}\`
 to go back to published versions.
+
+## License
+
+This repository has no license yet. Until it has one, others may read it but not reuse it; add a
+\`LICENSE\` file before publishing.
+`;
+}
+
+/**
+ * `CONTRIBUTING.md`: why this repository publishes no contribution
+ * instructions for people, and where an agent starts instead. It is
+ * `sous-io/sous-recipes`' own `CONTRIBUTING.md`, word for word apart from the
+ * name, because that repository is the model every scaffold follows.
+ *
+ * @param context - The repository being scaffolded.
+ */
+export function buildContributing(context: ScaffoldContext): string {
+  return `# Contributing to ${context.name}
+
+Sous is built for agentic coding, so this repository does not publish contribution instructions for
+people. Everything here is written for agents to read.
+
+Any agent working in this repository is assumed to have, at minimum, the sous core skills, such as
+\`about-sous\`, \`about-agent-skills\`, \`about-sous-repos\` and \`about-sous-recipes\`. They explain
+everything an agent needs to know to contribute: how a recipe is written, how its version is raised,
+and how a change is checked, proposed and released.
+
+An agent without those skills starts at \`CLAUDE.md\`, at the root of this repository.
+`;
+}
+
+/** Where the sous core skills can be read online, at their latest published version. */
+const CORE_SKILLS_URL =
+  "https://github.com/sous-io/sous-recipes/tree/main/recipes/core/sous-skills/skills";
+
+/** The official recipe repository every scaffold is modeled on. */
+const MODEL_REPOSITORY_URL = "https://github.com/sous-io/sous-recipes";
+
+/**
+ * The root `CLAUDE.md`: the entry point for an agent working in the repository.
+ * It points at the sous core skills rather than restating them, because they
+ * are the source of truth for how a recipe repository works. It follows
+ * `sous-io/sous-recipes`' own `CLAUDE.md`, minus what is only true there.
+ *
+ * @param context - The repository being scaffolded.
+ */
+export function buildClaudeMd(context: ScaffoldContext): string {
+  return `# ${context.name}
+
+This is a sous recipe repository. It publishes recipes: versioned bundles of agent skills, memories
+and partials that sous installs into the projects that subscribe to them.
+
+## Recipe Repositories Are Part of Sous
+
+Writing a recipe, raising its version, checking a change, proposing it and releasing it all work
+here exactly as they do in any other sous recipe repository. How a recipe repository works is part
+of sous itself, so the sous core skills teach it, and they are the official source of truth for it.
+This file does not repeat them. The agent MUST read these before changing anything here:
+
+- \`about-sous-repos\`: a recipe repository as a whole; the repo manifest, namespaces, the index,
+  release tags, what happens to a pull request and a merge, and proposing a change.
+- \`about-sous-recipes\`: one recipe; its manifest, how its version is raised, its variables, its
+  contents, its dependencies and its partials.
+- \`about-agent-skills\`: how a skill is written, including the rules every new skill follows.
+
+An agent in a project that uses sous already has these skills. An agent that cannot install sous or
+use it reads them directly, as plain markdown files, online, at their latest published version:
+
+- ${CORE_SKILLS_URL}
+
+## Where This Repository Came From
+
+\`sous repo init\` created this repository, modeled on \`sous-io/sous-recipes\`, the official recipe
+repository. Its files show a complete repository in use:
+
+- ${MODEL_REPOSITORY_URL}
 `;
 }
 
+/**
+ * The root `AGENTS.md`: one line sending an agent that reads `AGENTS.md`
+ * rather than `CLAUDE.md` to the same instructions.
+ */
+export function buildAgentsMd(): string {
+  return "Read `CLAUDE.md` in this directory; it holds the instructions for agents working in this\nrepository.\n";
+}
+
 /** The release workflow: validate every pull request, publish on merge. */
 export function buildReleaseWorkflow(): string {
   return `# Release automation for this sous recipe repository.

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

@@ -1,82 +0,0 @@
-# LiquidJS Built-in Filters
-
-Standard filters available in all `.tpl.` files. Chained with `|`.
-
-## String
-
-| Filter | Description | Example |
-|:-------|:------------|:--------|
-| `upcase` | Uppercase | `{{ "hello" | upcase }}` → `HELLO` |
-| `downcase` | Lowercase | `{{ "HELLO" | downcase }}` → `hello` |
-| `capitalize` | First char uppercase | `{{ "hello world" | capitalize }}` → `Hello world` |
-| `strip` | Remove leading/trailing whitespace | `{{ "  hi  " | strip }}` → `hi` |
-| `lstrip` | Remove leading whitespace | |
-| `rstrip` | Remove trailing whitespace | |
-| `strip_newlines` | Remove all newlines | |
-| `strip_html` | Remove HTML tags | |
-| `escape` | HTML-escape `<`, `>`, `&`, `"` | |
-| `url_encode` | Percent-encode a URL string | |
-| `url_decode` | Decode a percent-encoded string | |
-| `append` | Append a string | `{{ "foo" | append: "bar" }}` → `foobar` |
-| `prepend` | Prepend a string | `{{ "bar" | prepend: "foo" }}` → `foobar` |
-| `replace` | Replace all occurrences | `{{ "aabbcc" | replace: "b", "x" }}` → `aaxxcc` |
-| `replace_first` | Replace first occurrence | |
-| `remove` | Remove all occurrences | `{{ "aabbcc" | remove: "b" }}` → `aacc` |
-| `remove_first` | Remove first occurrence | |
-| `truncate` | Truncate to N chars (adds `...`) | `{{ "hello world" | truncate: 7 }}` → `hell...` |
-| `truncatewords` | Truncate to N words | `{{ "one two three" | truncatewords: 2 }}` → `one two...` |
-| `split` | Split string into array | `{{ "a,b,c" | split: "," }}` → `["a","b","c"]` |
-| `newline_to_br` | Replace `\n` with `<br>` | |
-
-## Array
-
-| Filter | Description | Example |
-|:-------|:------------|:--------|
-| `join` | Join array with separator | `{{ arr | join: ", " }}` |
-| `first` | First element | `{{ arr | first }}` |
-| `last` | Last element | `{{ arr | last }}` |
-| `reverse` | Reverse order | |
-| `sort` | Sort ascending (case-sensitive) | |
-| `sort_natural` | Sort ascending (case-insensitive) | |
-| `uniq` | Remove duplicates | |
-| `compact` | Remove nil/falsy values | |
-| `map` | Extract a property from each object | `{{ items | map: "name" }}` |
-| `where` | Filter objects by property value | `{{ items | where: "active", true }}` |
-| `concat` | Concatenate two arrays | `{{ arr1 | concat: arr2 }}` |
-| `slice` | Extract a sub-array | `{{ arr | slice: 1, 3 }}` |
-| `size` | Length of string or array | `{{ arr | size }}` |
-| `push` | Append element to array | |
-| `pop` | Remove last element | |
-| `shift` | Remove first element | |
-| `unshift` | Prepend element to array | |
-
-## Number
-
-| Filter | Description | Example |
-|:-------|:------------|:--------|
-| `plus` | Add | `{{ 4 | plus: 2 }}` → `6` |
-| `minus` | Subtract | `{{ 4 | minus: 2 }}` → `2` |
-| `times` | Multiply | `{{ 4 | times: 2 }}` → `8` |
-| `divided_by` | Divide | `{{ 10 | divided_by: 2 }}` → `5` |
-| `modulo` | Modulus | `{{ 10 | modulo: 3 }}` → `1` |
-| `abs` | Absolute value | `{{ -4 | abs }}` → `4` |
-| `ceil` | Round up | `{{ 4.1 | ceil }}` → `5` |
-| `floor` | Round down | `{{ 4.9 | floor }}` → `4` |
-| `round` | Round to nearest (or N decimal places) | `{{ 4.567 | round: 2 }}` → `4.57` |
-| `at_least` | Clamp to minimum | `{{ 3 | at_least: 5 }}` → `5` |
-| `at_most` | Clamp to maximum | `{{ 7 | at_most: 5 }}` → `5` |
-
-## Other
-
-| Filter | Description | Example |
-|:-------|:------------|:--------|
-| `default` | Fallback if nil/empty/false | `{{ val | default: "n/a" }}` |
-| `date` | Format a date | `{{ "now" | date: "%Y-%m-%d" }}` |
-| `size` | Length of string or array | `{{ "hello" | size }}` → `5` |
-| `json` | Serialize to JSON string | `{{ obj | json }}` |
-
-## Sous Custom Filters
-
-| Filter | Description |
-|:-------|:------------|
-| `bulletList` | Convert array to markdown bullet list (`- item` per line) |