@sous-io/sous 0.2.20 → 0.2.21

package/docs/markdown/repositories-authoring.md

@@ -36,8 +36,10 @@ 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
 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 a repository's
-trust story rests on being readable without running any of its code.
+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
+dry run and in `sous repo release --check`. What trusting a repository authorizes is described under
+[Trust](repositories.md#trust).
 
 ## Write a recipe
 

package/docs/markdown/repositories.md

@@ -164,9 +164,12 @@ Do you trust this repository? (y/N)
 ```
 
 Trusting a repository trusts every namespace and recipe in it, including recipes published later,
-and it is the last gate before a recipe can run scripts on your machine; sous cannot tell you
-whether one deserves that, and says so rather than implying otherwise. Where there is no terminal
-to ask on, the run fails and names the repositories and the exact command that grants the trust:
+and it is the only security boundary sous draws. Trust authorizes those recipes to run code on your
+machine with your own permissions, whether sous runs it during a build or your agent runs it (a
+skill's scripts, a hook), and sous sandboxes neither. Before a repository is trusted nothing from it
+runs, and the question itself reads only its index. Sous cannot tell you whether a repository
+deserves that, and says so rather than implying otherwise. Where there is no terminal to ask on, the
+run fails and names the repositories and the exact command that grants the trust:
 
 ```text
 Error: One repository has to be trusted before this can continue, and sous is not
@@ -187,6 +190,14 @@ Error: One repository has to be trusted before this can continue, and sous is no
 through the `local` provider goes through the same ceremony, because its recipes still run on
 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.
+
 ## The official repository, and the built-in core
 
 Sous publishes one official repository, [`sous-io/sous-recipes`](https://github.com/sous-io/sous-recipes).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sous-io/sous",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "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-sous/SKILL.tpl.md

@@ -51,6 +51,20 @@ Edit them only in the recipe repository, where they are the sources. Never edit
 copy of them inside a consuming project; that copy is build output and is overwritten on
 the next sous run.
 
+## Trust and Activation
+
+Trust is the only security boundary sous draws. Adding a repository is trusting it, and
+that authorizes its recipes to run code on this machine: code sous runs itself and code an
+agent runs, such as skill scripts and hooks. Sous sandboxes neither; trusted code runs
+with the user's own permissions. Before a repository is trusted, nothing from it runs; the
+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.
+
 ## Sous's Own Documentation
 
 Sous's full documentation ships inside the installed package as plain markdown

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

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

package/src/lib/repos/formats/repo-manifest.ts

@@ -4,9 +4,10 @@
  * point sous reads to learn what a repo publishes: its namespaces, and where
  * each recipe folder lives.
  *
- * The manifest is deliberately declarative and executable-free. Trust in the
- * Repositories system rests on being able to read a repo's whole surface
- * without running any of its code, so manifests are YAML or JSON only.
+ * The manifest is deliberately declarative and executable-free: it is data, so
+ * sous can read, validate and browse it before the repository is trusted, in a
+ * dry run and in `repo release --check` without executing anything. So
+ * manifests are YAML or JSON only.
  */
 
 import { z } from "zod";

package/src/lib/repos/load-manifest.ts

@@ -1,9 +1,9 @@
 /**
  * Reading Repositories files off disk.
  *
- * Manifests are HAND-WRITTEN, and deliberately never JavaScript: trust in the
- * Repositories system rests on being able to read a repo's whole surface
- * without executing any of its code. So a manifest is YAML (`.yaml`, `.yml`) or
+ * Manifests are HAND-WRITTEN, and deliberately never JavaScript: a manifest is
+ * data, so sous can read, validate and browse it without executing anything,
+ * including before the repository is trusted. So a manifest is YAML (`.yaml`, `.yml`) or
  * JSON (`.json`, `.jsonc`), and the JSON dialect is permissive, allowing line
  * comments, block comments and trailing commas, so a manifest can explain
  * itself.
@@ -112,7 +112,8 @@ export function loadManifestFile(filePath: string): unknown {
   throw new ConfigError(
     `Cannot read the manifest at ${filePath}: '${extension}' is not a manifest format.\n` +
       `  A manifest is written as ${MANIFEST_EXTENSIONS.join(", ")}. Manifests are never ` +
-      `JavaScript, because sous must be able to read a repository without running its code.`
+      `JavaScript, because a manifest is data that sous reads, validates and browses ` +
+      `without executing anything, including before the repository is trusted.`
   );
 }
 

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

@@ -45,9 +45,9 @@ export function exampleRecipePath(context: ScaffoldContext): string {
 export function buildRepoManifest(context: ScaffoldContext): string {
   return `# The repo manifest: what this repository publishes.
 #
-# It is read before anything is downloaded, and it is never executable, so
-# anyone deciding whether to trust this repository can read its whole surface
-# without running any of its code.
+# It is data, never code: sous reads it before anything is downloaded, so a
+# project can browse and validate what this repository publishes, and decide
+# whether to trust it, without executing anything.
 
 formatVersion: 1