@north-light/crouter 0.3.260 → 0.3.261

package/dist/builtin-memory/internal/plugins.md

@@ -290,6 +290,16 @@ An exec manifest accepts only `schemaVersion` and `mounts`. Its leaves declare `
 
 Every branch child is a branch (without `rootEntry`) or leaf. A leaf declares `params`, `output` (array of `{ name, type, required, constraint }`), and a non-empty `effects` array. Params use crtr's public vocabulary — one positional max, long-form `flag`s (types `string|int|bool|path|enum`, `choices` for enum), `stdin`, `context-file`; kebab-case names, no aliases. Two client-side affordances ride on a `positional` or `flag`: `encoding: "text"|"base64"` on a `type: "path"` param sends the named local FILE's content instead of the path string, and `defaultFromEnv: "UPPER_SNAKE"` fills an omitted `string`/`path` param from that environment variable on the calling machine, counting as supplied (so it satisfies `required` and is sent) — unlike a static `default`, which is a parse convenience only and never ships. `defaultFromEnv` is rejected alongside `default` or `repeatable`. The declaration mirrors crtr's stable help descriptors, not its internal TypeScript defs — no closures, dynamic state, or renderers.
 
+### Extensible branches and repository fragments
+
+Use `"extensible": true` only on a plugin branch mounted at `parent: []` when repositories should add native children beneath that branch. It is mutually exclusive with `passthrough`: a passthrough branch owns all remaining tokens and cannot have contributed children. The marker does not change the plugin's transport or its own children; those children remain first, and a repository root that reuses one of their names rejects the entire fragment.
+
+A repository CLI framework generates one fragment per opted-in branch at `<project-root>/.crouter/commands/<effective-branch>.json`; the repository developer commits the generated file, never hand-writing it. The effective branch is the composed command name, so a cross-plugin collision uses its origin-qualified identity (for example, `first:demo.json` extends only `first:demo`). On every invocation crtr walks the caller's existing project-root chain nearest first and reads only the first matching fragment; a corrected file is live on the next invocation without installation, caching, or restart.
+
+A fragment accepts only `schemaVersion: 1`, its required `exec` `transport`, and non-empty `mounts`; it shares the `commands.json` node, parameter, output, and effects grammar documented above rather than defining another command language. Its executable is project-root-relative, contained in that root, a regular executable file, and is direct-spawned only for an explicit leaf invocation. Fragment roots attach beneath the extensible branch and may be branches or direct leaves, so `parent: []` never declares `rootEntry`; non-empty parents resolve only within the fragment's own forest, and `passthrough` is forbidden everywhere in a fragment. HTTP transport is not supported for fragments.
+
+A contributed exec leaf receives the same one-request/one-envelope protocol described in [Exec protocol](#exec-protocol), with the full walked command path and `context.extension { branch, root }` instead of `context.plugin`; it runs with the caller's cwd and full environment. It is trusted repository code running with the caller's authority, not sandboxed code. Native help renders contributed commands without provenance; when a present fragment is rejected, only that extensible branch's help shows an `<extension-issue>` pointing to the file, while `crtr sys doctor` reports the full `command_extension_invalid` remediation and also catches fragments for branches that are not extensible. Recovery is to fix or regenerate the committed fragment.
+
 ### Execution and trust boundaries
 
 An exec leaf direct-spawns its executable (no shell) only on explicit invocation — never on install, help, or discovery — with `--crtr-command-protocol 1`, the caller's cwd, and the full environment. It is **trusted local code running with the caller's authority**: crtr does not sandbox it, filter the environment, mint a credential, or interpret its backend authentication. This is an execution trust boundary, not a sandbox.