cyber-agentkit 1.1.0 → 2.0.0

package/skills/reference/README.md

@@ -1,16 +1,16 @@
 # Reference
 
-Loads, creates, updates, selects, deletes, and finds [references](https://cyber-uni.github.io/cyber-agentkit/concepts/reference-documents/): Markdown documents (or JSON, YAML, TOML, or text files, which are never merged) an agent reads on demand by name. It routes each request to the `reference` command, run from a launcher bundled in `scripts/`, and writes or deletes a reference only after the user approves it. Type `/reference` to run it yourself. Installed as a Claude Code plugin, it is `/cyber-agentkit:reference` (pnpm install: `pnpm-cyber-agentkit-reference`). Installed with pnpm, it is `pnpm-cyber-agentkit-reference`.
+Loads, finds, inspects, creates, customizes, and deletes [references](https://cyber-uni.github.io/cyber-agentkit/concepts/reference-documents/): Markdown documents (or JSON, YAML, TOML, or text files, which are never merged) an agent reads on demand by name. It routes each request to the `reference` command, run from a launcher bundled in `scripts/`, and writes or deletes a reference only after the user approves it. Type `/reference` to run it yourself. Installed as a Claude Code plugin, it is `/cyber-agentkit:reference` (pnpm install: `pnpm-cyber-agentkit-reference`). Installed with pnpm, it is `pnpm-cyber-agentkit-reference`.
 
 | Mode | When |
 | --- | --- |
-| Load | a skill's instructions name references, or an interface whose implementations, to load with this skill |
-| Create | writing a new reference for a project, a user, a plugin (`<plugin name>.<reference>.md`), or a skill's default (`<name>.default.md`); an implementation of an interface is `<id>.<key>.md` |
-| Update | changing a reference: the user's own in place, a plugin's by a customization that patches it |
-| Select | choosing which plugins, or the skill's default, a name builds on, which settles an ambiguous name |
-| Delete | removing a project or user contribution, saying first what answers the name afterwards |
+| Load | a skill's instructions name references, or an interface whose implementations, to load with this skill; it acts on each status and warning, and follows project sections for the folder the work is in |
 | Find | `search` for a topic, `list` every reference, or `implementations` of an interface |
-| Inspect | `show`; `show --trace` for how a name composed; `where` for the project and user files a customization goes to; `check` against an interface |
+| Inspect | `load`; `load --trace` for how a name composed; `where` for the files a customization goes to; `check` against an interface |
+| Create | writing a new reference from given text, for the repository, a folder, the user, a plugin (`<plugin name>.<reference>.md`), or a skill's default (`<name>.default.md`), or stubbing an interface; it shows where each section came from and offers the full document |
+| Update | editing the user's own hand-written file in place |
+| Customize | picking what a name builds on, changing its prose by request through a generator subagent, implementing an interface by request, or revising a stale generated document |
+| Delete | removing a repo, user, or project-section contribution, saying first what answers the name afterwards |
 | Wire a skill | giving a skill the line below |
 
 It ships in the `cyber-agentkit` plugin:

package/skills/reference/SKILL.md

@@ -1,28 +1,33 @@
 ---
 name: reference
-description: Use this skill when loading, creating, updating, deleting, finding, or inspecting a reference — a document agents read by name, Markdown or a JSON, YAML, TOML, or text file — or when wiring a skill to load one.
+description: Use this skill when loading, creating, customizing, updating, deleting, finding, or inspecting a reference (a document agents read by name, Markdown or a JSON, YAML, TOML, or text file), or when wiring a skill to load one.
 ---
 
 # Reference
 
-Route the request to one mode, then follow that mode. A **reference** is a document fetched by name, usually Markdown. A JSON, YAML, TOML, or text file (`<name>.json`) is also one: it is never merged, and the highest tier holding it answers whole. Only `references/` is read. A skill's `assets/` files are resolved by name with the `asset` skill. Each place that holds a **contribution** to a name is a **tier**: managed, project, user, a plugin, or the loading skill's **default** (`references/<name>.default.md` in its folder). Contributions compose bottom first: the plugins and the default, in the order `extends` gives, then user, then project, then managed. Each applies with its `merge`: `patch` (the default) replaces the text a section matches, `combine` adds after it, `replace` drops everything below, and `remove` turns the name off. An **interface** is a contract, declared in a `<id>.interface` reference, that other references implement. What answers a name is the `reference` command's decision. Never decide it by reading tier folders yourself.
+Route the request to one mode, then follow that mode.
+
+A **reference** is a document read by name. Each place that holds a **contribution** to a name is a **tier**:
+
+- the plugins that ship the name, and the loading skill's **default** (`references/<name>.default.md` in its folder). They form the stack, bottom first, in the order `extends` gives.
+- `user`: `~/.agents/references/`, for one person in every repository. It applies over the stack.
+- `repo`: `.agents/references/` at the repository root, for everyone working in it. It applies over `user`.
+- a **project section**: `.agents/references/<name>.md` in a folder below the root. It states only what differs for work in that folder, and follows the main document.
+- `managed`: an admin's folder for the running harness. It applies over the main document and over each project section.
+
+Each contribution applies with its `merge`: `patch` (the default) replaces the text a section matches, `combine` adds after it, `replace` drops everything below, and `remove` turns the name off. An **interface** is a contract, declared in a `<id>.interface` reference, that other references implement. What answers a name is the `reference` command's decision. Never decide it by reading tier folders yourself.
 
 ## Route
 
 | The request | Mode |
 | --- | --- |
-| a skill's instructions name references to load with this skill | [Load](#load) |
-| a skill's instructions name an interface whose implementations to load with this skill | [Load](#load) |
-| write a new reference, for a project, for the user, for a plugin to ship, or as a skill's default | [Create](#create) |
-| write a reference that implements an interface | [Create](#create) |
-| change what an existing reference says, the user's own or a plugin's | [Update](#update) |
-| choose which plugins a name builds on, or settle an ambiguous name | [Select](#select) |
-| remove a project or user contribution, or a selection | [Delete](#delete) |
-| find a reference for a topic, or see which ones exist | [Find](#find) |
-| find the implementations of an interface | [Find](#find) |
-| check that references have the shape their interface requires | [Inspect](#inspect) |
-| see a reference, or learn why a name composed as it did | [Inspect](#inspect) |
-| learn where a customization of a reference goes | [Inspect](#inspect) |
+| a skill's instructions name references, or an interface's implementations, to load with this skill | [Load](#load) |
+| find a reference for a topic, list them, or list an interface's implementations | [Find](#find) |
+| read a reference, learn why it composed as it did, where a customization goes, or check it against its interface | [Inspect](#inspect) |
+| write a new reference from text the author gives: for the repository, the user, a plugin to ship, or a skill's default; or stub an interface | [Create](#create) |
+| edit the user's own reference file in place | [Update](#update) |
+| choose what a name builds on, settle an ambiguous name, change what a reference says, or revise a stale one | [Customize](#customize) |
+| remove a repo, user, or project-section contribution | [Delete](#delete) |
 | make a skill load a reference | [Wire a skill](#wire-a-skill) |
 
 Ask only when the request fits two modes. Otherwise pick one; outside Load, say which. Invoked as `/reference` with no request, run `list` from [Find](#find) and ask what to do with one.
@@ -30,80 +35,81 @@ Ask only when the request fits two modes. Otherwise pick one; outside Load, say
 ## Run the command
 
 ```sh
-node <this skill's folder>/scripts/reference.mjs <subcommand> ... --root <repository root>
+node <this skill's folder>/scripts/reference.mjs <subcommand> ...
 ```
 
-`scripts/reference.mjs` is the package's `reference` command bundled into one file; it needs no `node_modules`. Pass `--root` every time, so the repository's own `.agents/references/` is read. A failure prints `error: <code>: <message>` and a warning `warning: <code>: <message>`, both on stderr.
+`scripts/reference.mjs` is the package's `reference` command bundled into one file; it needs no `node_modules`. It finds the repository root from the working folder. Add `--root <repository root>` only when the working folder is not in the repository. A command that cannot complete exits 1 (or 2 for a usage error) and prints one error value on stdout, with `error` and `code` lines. A warning prints `warning: <code>: <message>` on stderr in text output, and does not change the exit code.
 
-Outside Load, when it is missing or cannot run, use `pnpm exec cyber-agentkit reference` when the package is a direct dependency, else `npx -y cyber-agentkit@1.1.0 reference`, with the same arguments. Load never falls back to a package runner.
+Outside Load, when the script is missing or cannot run, use `pnpm exec cyber-agentkit reference` when the package is a direct dependency, else `npx -y cyber-agentkit@2.0.0 reference`, with the same arguments. Load never falls back to a package runner.
 
 ## Load
 
 Load `references/load.md` from this skill's folder and follow it, then return to the caller's work.
 
+## Find
+
+- For a topic, run `search <query>`. If nothing matches, say that nothing matched. Do not guess a name.
+- For every reference, run `list`. Add `--trace` for every contribution of each name and its outcome.
+- For every name matching a pattern, run `list '<pattern>'`. `*` stands for any run of characters and the rest is literal.
+- For the implementations of an interface, run `implementations <id>`. It lists each one a consumer can load, with its pin. Add `--trace` for each one it left out, with why.
+- When `list` or `search` carries a `defaults` field, say that skills' defaults were not searched, and why.
+
+## Inspect
+
+- To read a reference, run `load <name>`. Add `--metadata` for its composed frontmatter.
+- To learn why a name composed as it did, run `load <name> --trace`. Report the stack and what built it, the contribution each section came from, each project section, and each layer that was `shadowed`, `stale`, `not used`, or `not read`, with its reason.
+- To check a reference, run `check <name>...`: an interface document against its shape, an implementation against its interface, and every document for defects. With no name, it checks every name and reports every warning `load` would raise. It exits 0; report each entry under `failed` with its check, and each under `warned` with its warnings.
+- To learn where a customization goes, run `where <name>`. Add `--default <skill folder>` when a skill loads the name, and `--in <folder>` for a folder's project section. Report each file, who it reaches, and what hides it. A plugin's or a skill's default contribution is read-only; never offer it as a place to write.
+
 ## Create
 
 Load `references/create.md` from this skill's folder and follow it.
 
 ## Update
 
-1. Run `show <name> --trace`. Use the bare name. If the name is ambiguous, go to [Select](#select) first.
-2. Choose the folder to write: `.agents/references/` for the project, or `~/.agents/references/` for the user alone.
-3. If the trace shows a `used` file with a body in that folder, it is the user's own contribution. Edit that file in place, then go to step 6.
-4. Otherwise, write a customization above what is there. Run `where <name>` (add `--default <skill folder>` when a skill loads the name) for the heading paths of the document below each place. Write only the sections the user changes, each under the heading path it has there; `patch` keeps every section you do not name. To add after a section's text instead of replacing it, use `--merge combine`, or mark that one section `<!-- merge: combine -->` under its heading. To drop one section, mark it `<!-- merge: remove -->`.
-5. Start it with `create <name> --dry-run`, adding `--scope user` for the user's folder and `--template <path>` with the file holding those sections. Show the user the path and content, then run it without `--dry-run` on approval.
-6. Run `show <name> --trace` again. The written file must be `used`, and each section the user changed must list it.
+Use Update only for a file the user wrote by hand under `.agents/references/` or `~/.agents/references/`.
 
-## Select
+1. Run `load <name> --trace`. Find the `used` layer for that file.
+2. If its trace row records a `request`, it is generated. Never edit it by hand; go to [Customize](#customize).
+3. Show the user the change and the path. On approval, edit the file.
+4. Run `load <name> --trace` again. The file must be `used`, and `load <name>` must give no `marker-unmatched` warning.
 
-1. Run `where <name>`. Its `options` are the plugins holding the name, each as `<plugin>/<name>`, and `default` when a skill's default holds it.
-2. Ask the user which to build on, bottom first, even when one option is left. Ask whether it is for the project or the user alone.
-3. Run `select <name> <option>...`, adding `--scope user` for the user alone. It writes `extends` into `<name>.md` and keeps any body the file has.
-4. Run `show <name> --trace`. The stack must be what the user picked. To undo a selection, run `select <name> --clear`.
+## Customize
+
+Load `references/customize.md` from this skill's folder and follow it.
 
 ## Delete
 
-1. Run `show <name> --trace`. Use the bare name: delete removes only a file under `.agents/references/` or `~/.agents/references/`, or, for an author, in a plugin's or a skill's source folder in this repository.
-2. Choose the folder: `.agents/references/` for the project, or `~/.agents/references/` with `--scope user`. If the trace shows no file there, say so and stop. An installed plugin's, a managed, or an installed skill's contribution is never deleted; offer a customization with `merge: remove` through [Update](#update) instead.
-3. Run `delete <name> --dry-run`, adding `--scope user` for the user's folder. Show the user the path and what will answer the name afterwards, and say so when a selection goes with the file.
+1. Run `load <name> --trace`. Use the bare name.
+2. Choose the place: the repository (the default), the user with `--scope user`, or one folder's project section with `--in <folder>`. An author may also delete from a plugin's or a skill's source folder in this repository with `--plugin` or `--default`. An installed plugin's, a managed, or an installed skill's contribution is never deleted; offer a customization with `merge: remove` through [Customize](#customize) instead.
+3. Run `delete <name> --dry-run` with that place's flag. Show the user the path and what will answer the name afterwards, and say so when a selection goes with the file.
 4. On approval, run it without `--dry-run`.
-5. Run `show <name> --trace` again. The deleted file must be gone from the trace.
-
-## Find
-
-- For a topic, run `search <query>`. If nothing matches, say that nothing matched. Do not guess a name.
-- For every reference, run `list`. Add `--trace` for every contribution of each name and the outcome it gets.
-- For every name matching a pattern, such as every provider of a shared prefix, run `list '<pattern>'`. `*` stands for any run of characters and the rest is literal, so it returns only exact matches, unlike `search`.
-- For the implementations of an interface, run `implementations <id>`. It lists each one a consumer can load, with its pin; add `--trace` for each one it left out, with why.
-- When `list` or `search` carries a `defaults` field, say that skills' defaults were not searched, and why.
+5. Run `load <name> --trace` again. The deleted file must be gone from the trace.
 
-## Inspect
+## Wire a skill
 
-- To read a reference, run `show <name>`; add `--metadata` for its composed frontmatter.
-- To learn why a name composed as it did, run `show <name> --trace`. Report the stack and what built it, the contributions each section came from, and each layer that was `shadowed`, `not used`, or `not read`, with its reason.
-- To check a reference against its interface, run `check <name>...`; with no name, it checks every interface document and implementation. Report each failure with its check. Exit 1 means at least one failed.
-- To learn where a customization goes, run `where <name>`; when a skill loads the name, add `--default <that skill's folder>`. Report each place, who it reaches, and the heading paths below it. A plugin's or a skill's default contribution is read-only; never offer it as a place to write. If the user then wants the customization written, go to [Update](#update).
+A skill never runs the command itself. It carries one load line naming this skill and its package. Copy the line from the `README.md` in this skill's folder and replace the example names:
 
-## Wire a skill
+```text
+Load `<name>` and `<name>` with the `reference` skill of `cyber-agentkit`.
+Load the implementations of the `<id>` interface with the `reference` skill of `cyber-agentkit`.
+```
 
-A skill never runs the command itself. It names this skill in one line; copy that line from the `README.md` in this skill's folder, and replace the example names. The skill may ship its own default of a reference at `references/<name>.default.md` in its folder. Load adds it below every other contribution, and reads it on its own only when the command cannot run.
+A skill written for one harness may add that harness's typed form after the skill's name; the README lists each one. The skill may ship its own default of a name at `references/<name>.default.md` in its folder. Load adds it below every other contribution, and reads it on its own only when the command cannot run. A copy at `references/<name>.md` is not read as a default.
 
 ## Rules
 
-- **Only Create, Update, Select, and Delete write.** Load writes only a selection the user picked. Find, Inspect, and Wire a skill change no reference file.
-- **Never edit, move, rename, or delete a reference an installed plugin or skill ships, or a managed one.** Update customizes it instead. Its callers load it by name.
-- **Write only what the user approves.** Show the file and its path before you write or delete it.
+- **Only Create, Update, Customize, and Delete write.** Load writes only a pick the user made for an ambiguous name. Find, Inspect, and Wire a skill change no reference file.
+- **Never edit, move, rename, or delete a reference an installed plugin or skill ships, or a managed one.** Customize it instead. Its callers load it by name.
+- **Never edit a generated document by hand.** Customize it again with its request.
+- **Write only what the user approves.** Show the file and its path before you write or delete it. With no user present, write nothing.
 
 ## Validate
 
-Before reporting a Create, Update, Select, or Delete done:
+Before reporting a Create, Update, Customize, or Delete done:
 
-- The written or deleted file is under `.agents/references/` or `~/.agents/references/`, or, for Create and Delete, in a plugin's or a skill's source folder in this repository.
+- The written or deleted file is under `.agents/references/` at the root or in a folder below it, under `~/.agents/references/`, or, for Create and Delete, in a plugin's or a skill's source folder in this repository.
 - No file in an installed plugin or skill, or in a managed folder, changed.
 - The file and its path were shown to the user before the write or the delete, and a delete also said what answers the name afterwards.
-- After Create or Update, `show <name> --trace` reports the written file as `used`.
-- After Select, `show <name> --trace` reports the stack the user picked.
-- After Delete, `show <name> --trace` no longer finds the deleted file.
-- A created reference's top level is not a single heading holding all the others.
-- A created reference that declares `implements` passes `check <name>`.
-- `show <name>` gives no `marker-unmatched` warning for a file written or changed.
+- After a write, `load <name> --trace` reports the written file as `used`, or names what hides it.
+- A written reference that declares `implements` passes `check <name>`.

package/skills/reference/references/create.md

@@ -1,8 +1,8 @@
 # Create a reference
 
-## 1. Check that it should be a reference
+Create writes a new file from text the author gives, or an interface's stub. To change what an existing reference says in the customizer's own words, use Customize mode instead.
 
-Decide who starts the read:
+## 1. Check that it should be a reference
 
 - If the agent must decide from the task that it needs this, it is a **skill**, not a reference. Say so and stop.
 - If an `AGENTS.md` line, a skill, or a person will name it, it is a reference. Continue.
@@ -11,21 +11,21 @@ Decide who starts the read:
 
 | Who it is for | Where | Flag |
 | --- | --- | --- |
-| this repository | `.agents/references/<name>.md` at the root, or in a package's folder for that package alone | (none) |
+| everyone working in this repository | `.agents/references/<name>.md` at the root | (none) |
+| work in one folder of the repository | `<folder>/.agents/references/<name>.md` | `--in <folder>` |
 | the user, in every repository | `~/.agents/references/<name>.md` | `--scope user` |
-| every user of a plugin | `references/<name>.md` in the plugin's source folder, next to its `skills/` | `--plugin <plugin folder>` |
+| every user of a plugin | `references/<name>.md` in the plugin's source folder | `--plugin <plugin folder>` |
 | a skill, as its default | `references/<name>.default.md` in the skill's source folder | `--default <skill folder>` |
 
-`--plugin` and `--default` write only into a source folder in this repository, never into an installed copy. To change a reference that already exists, use Update instead.
+`--plugin` and `--default` write only into a source folder in this repository, never into an installed copy. A folder's project section states only what differs there, and takes no `--merge`.
 
 ## 3. Name it
 
 - Use lowercase words joined by `-`. A name is a file name, never a path, and never ends `.default`.
-- **A plugin prefixes every name it ships** with its own name and a dot: `cyber-asana.work-hierarchy`, not `work-hierarchy`. Without the prefix, every plugin that ships `work-hierarchy` contributes to one name, and the name is ambiguous until someone selects one.
-- A repository's or user's own reference needs no prefix. A skill's default takes the name its skill loads.
-- **An implementation of an interface takes the interface's id as its namespace**, not the plugin's: `<id>` when the interface's cardinality is `one`, `<id>.<key>` when it is `many`, such as `scaffold.recipe.typescript-lib`. Read the interface with `show <id>.interface`.
-- Run `show <name>`. If the name already resolves and the user wants a new document, pick another name; to change the existing one, switch to Update.
-- Do not rename a reference that a plugin has already shipped. Its callers load it by the old name. Rename one only in a release that also updates every caller.
+- **A plugin prefixes every name it ships** with its own name and a dot: `cyber-asana.work-hierarchy`, not `work-hierarchy`. A repository's or user's own reference needs no prefix. A skill's default takes the name its skill loads.
+- **An implementation of an interface takes the interface's id as its namespace**: `<id>` when the interface's cardinality is `one`, `<id>.<key>` when it is `many`. Read the interface with `load <id>.interface`.
+- Run `load <name>`. If the name already resolves and the author wants a new document, pick another name. To change the existing one, go to Customize mode.
+- When a plugin or a skill renames a name it ships, list the old name in the new file's `aliases` frontmatter, so load lines and customizations written for the old name still reach it.
 
 ## 4. Write it
 
@@ -43,29 +43,34 @@ Instructions only.
 ```
 
 - `description` and `tags` are what `search` matches. Always write a `description`.
-- Other frontmatter keys are allowed. `show --metadata` returns them under `metadata`, composed key by key across the contributions used.
-- If the user's text starts with a `#` title, drop the title and make the sections under it top-level `##` sections. `create` refuses a template whose top level is one heading holding the others.
+- If the author's text starts with a `#` title, drop the title and make the sections under it top-level `##` sections.
 - Write instructions an agent follows. Leave the rationale out.
 
 Run `create`; never write the file by hand:
 
-1. Run `create <name> --dry-run`, with the flag from step 2. Add `--template <path>` when a calling skill or the user supplies the text; without it, the command writes its own template. Add `--merge <operation>` when it should not patch: `combine` to add after what is below, `replace` to stand alone, `remove` to turn the name off.
-2. Show the user the path and the content it printed, and any `hint:` line.
-3. On approval, run the same command without `--dry-run`. Then run `show <name>`; add `--trace` to see the new file `used`.
+1. Run `create <name> --dry-run`, with the flag from step 2. Add `--template <path>` with the file holding the author's text; without it, the command writes its own template. Add `--merge <operation>` when it should not patch: `combine` to add after what is below, `replace` to stand alone, `remove` to turn the name off.
+2. Show the author the path, the content it printed, and any `hint:` or `warning:` line. A warning that a contribution above hides the file still writes it.
+3. On approval, run the same command without `--dry-run`.
 
-If `create` refuses, report its reason and write nothing. An existing file with a body means Update. A file holding only a selection gets the body added, and keeps its `extends`.
+If `create` refuses, report its reason and write nothing. An existing file with a body means Customize mode, or Update mode for a file the user wrote by hand.
 
-To implement an interface, run `create <name> --implements <id> --dry-run` instead of passing a template. It writes the interface's sections as `##` headings, stubs each one `**Unsupported.**`, and sets `implements: <id>@<version>` and `merge: replace`. Replace each stub with the section, or keep `**Unsupported.**` followed by one sentence on why. Then run `check <name>`; it must pass.
+A plugin's file or a skill's default that changes how another plugin's reference reads, such as a house style, lists `extends: [<other plugin>]` in its frontmatter and holds only the sections it changes. `create` records in `sources` the version of each plugin it extends, so `check` warns the author when that plugin moves on. Never give such a file `merge: replace`; `create` refuses it.
 
-A plugin that changes how another plugin's reference reads, such as a house style, ships the same name with `extends: [<other plugin>]` in its frontmatter, holding only the sections it changes; it patches the other plugin's text. A plugin that builds on the loading skill's default lists `default` in `extends`.
+## 5. Stub an interface
 
-## 5. Connect it to a caller
+Run `create <name> --implements <id> --dry-run` instead of passing a template. It writes each section of the interface as a `##` heading, stubbed `**Unsupported.**` with what the section holds, and sets `implements: <id>@<version>` and `merge: replace`. With `--in <folder>`, it writes a project section with neither. Show it, write it on approval, then replace each stub with the section, or keep `**Unsupported.**` followed by one sentence on why. A required section cannot stay unsupported. Run `check <name>`; it must pass.
 
-Nothing loads a reference by itself. Tell the user where to name it:
+## 6. Show the result
 
-- For a repository, add a line to `AGENTS.md`, or to the skill that needs it, such as: "Read the `testing` reference before writing tests."
-- For a plugin or a skill's default, add the load line to each skill that needs the reference, as Wire a skill says.
+1. Run `load <name> --trace`, adding `--default <skill folder>` for a skill's default. The new file must be `used`, or the trace names what hides it.
+2. Show the author where each section came from: for each row of the trace's `sections`, the heading and the contributions that built it.
+3. Offer the full document. When the author accepts, run `load <name>` and show what it prints.
 
-## 6. Verify
+For a plugin reference, run the command where the plugin is installed; otherwise, say that the plugin tier was not checked.
 
-Run `show <name> --trace`. The new file must be `used`. For a skill's default, add `--default <skill folder>`. For an implementation, `check <name>` must also pass. For a plugin reference, run the command where the plugin is installed; otherwise, report that the plugin tier was not checked.
+## 7. Connect it to a caller
+
+Nothing loads a reference by itself. Tell the author where to name it:
+
+- For a repository, add a line to `AGENTS.md`, or to the skill that needs it, such as: "Read the `testing` reference before writing tests."
+- For a plugin or a skill's default, add the load line to each skill that needs it, as Wire a skill says.

package/skills/reference/references/customize.md

@@ -0,0 +1,82 @@
+# Customize a reference
+
+Customize changes what a skill reads for a name, for the repository, for the user alone, or for one folder. The customizer picks what the name builds on, says in their own words what to change in the prose, or both. The `customize` command writes the file and its record and runs no model; you run the generator.
+
+With no user present, write nothing. When the command cannot run, write nothing and say so.
+
+## 1. Read what the name is now
+
+1. Run `load <name> --trace`. Add `--default <skill folder>` when a skill loads the name, and use it in every command below.
+2. Note the status, the stack, and each `repo`, `user`, or project-section layer. A layer that records a `request` is generated. A layer whose outcome is `stale` goes to [Revise a stale document](#5-revise-a-stale-document).
+
+## 2. Choose the target
+
+Ask who the change is for, and use that target's flags in every command below:
+
+| Who it is for | Flags |
+| --- | --- |
+| everyone working in this repository | (none) |
+| only the user, in every repository | `--scope user` |
+| work in one folder of the repository | `--in <folder>` |
+
+Run `where <name>` with those flags. Tell the customizer the file it writes, who it reaches, and what hides it. A hidden target is still written, with a warning.
+
+## 3. Pick what it builds on
+
+Skip this step for `--in <folder>`: a project section takes no picks.
+
+1. The options are the plugins that hold the name, each `<plugin>/<name>`, and `default` when a skill has one. An ambiguous name lists them in its `options`.
+2. Ask the customizer which to build on, bottom first, even when only one is left.
+3. Run `customize <name> --extends <step>... --dry-run` with the target's flags. A step is a plugin's name, `<plugin>:<merge>` (such as `house-style:combine`), or `default`. For steps that contribute only some sections, write the whole `extends` list to a YAML file and pass `--extends-file <file>`. To remove the picks, pass `--extends none`.
+4. Show the path and the content. On approval, run it without `--dry-run`.
+
+The picks record, as `declined`, every plugin holding the name that they leave out, so load stops asking about it. When load warns `plugin-not-selected` about a plugin installed later, ask the customizer whether to add it to the picks or leave it out; to leave it out, write the same picks again.
+
+Picks alone write a selection, or change only `extends` on a file that has a body. When that body records a request, the output suggests customizing again with it: offer step 4.
+
+## 4. Change the prose by request
+
+1. If the name is ambiguous, do step 3 first. Write the customizer's request, in their own words, to a temporary file.
+2. Run `customize <name> --base` with the target's flags and any new `--extends` picks. It prints what the generator reads, and writes nothing. It leaves out the target file, managed text, the tier above the target, and personal text.
+3. Spawn a generator subagent. Give it the prompt in [The generator](#the-generator), the printed base, and the request. Say whether to write a delta (the default) or a whole document (the customizer asked to replace everything). If you cannot spawn a subagent, follow that prompt yourself, reading only the base and the request.
+4. Write the draft to a temporary file. Run `customize <name> --request <request file> --body <draft file> --dry-run` with the target's flags, adding `--merge replace` for a whole document.
+5. Show the customizer the path and the draft. If they decline, write nothing. If they change the request, start this step again with the new request.
+6. Only after they approve, run the same command without `--dry-run`.
+7. Run `load <name> --trace`. The written file must be `used`, or the trace names what hides it.
+
+If `customize` refuses with `body-not-generated`, the target holds a body written by hand. Offer Update mode, or deleting it first.
+
+### Implement an interface by request
+
+To implement an interface for the name, add `--implements <id>` to the `--base` and to the write. The base then starts with the interface's stub. The draft is a whole document that holds every section of the interface, in its order. With `--in <folder>`, it is a project section for that folder alone, so one package can implement the interface its own way. After the write, run `check <name>`; it must pass.
+
+A name that is `missing` under a found interface's namespace needs `--implements <id>`; `customize` refuses it otherwise and says how to name the interface.
+
+## 5. Revise a stale document
+
+Load reports a generated document `stale` when a plugin it was built from changed or is gone. Revise it from its recorded request; the customizer does not restate it.
+
+1. From `load <name> --trace`, read the stale layer's `request`, its picks (`extends` in its `frontmatter`), and its `sources`.
+2. If a source's status is `missing`, its plugin is gone. Tell the customizer before you generate anything. They pick again (step 3), or go on without it.
+3. Revise the main document first: the `repo` or `user` document. Then revise each stale project section, one at a time, with `--in <folder>`. Each project section records the main document it was written against.
+4. For each one, write its recorded request to a file and follow step 4 with the same target. The recorded picks apply unless the customizer picked again. The base never holds the stale document, so the request is not applied over its own earlier result.
+5. A JSON, YAML, TOML, or text document is regenerated whole.
+
+If the customizer declines, write nothing; the document stays stale.
+
+## The generator
+
+Give the generator subagent this prompt, followed by the base and the request:
+
+> You write one reference document for the `reference` skill of `cyber-agentkit`. You get a base document and a customizer's request.
+>
+> - Apply the request to the base. Change only what the request asks for.
+> - Write one concise document of instructions an agent follows. Leave out rationale and history.
+> - Keep every heading path you use exactly as the base has it, so later loads match it. Add a new section only when the request needs one.
+> - For a delta (the default), write only the sections you change, each under its heading path from the base. To drop a section, write its heading followed by `<!-- merge: remove -->`.
+> - For a whole document, write every section, in the base's order.
+> - For a project section, write only what differs for work in that folder.
+> - For an interface, keep every section of the stub, in its order. Replace each stub with its content, or keep `**Unsupported.**` with one sentence on why. A required section cannot stay unsupported.
+> - Use top-level `##` sections and no `#` title. Write no frontmatter; the command records it.
+> - Use only the base and the request. Never add text from anywhere else, such as managed or admin instructions, or other files you can see.
+> - Reply with the document alone.

package/skills/reference/references/load.md

@@ -2,79 +2,100 @@
 
 Load the references a calling skill names, and hand them back as part of its instructions. The **caller** is the skill whose instructions sent you here; its **folder** is the directory its `SKILL.md` is in.
 
-When the caller names an interface ("Load the implementations of the `<id>` interface"), follow [Implementations of an interface](#implementations-of-an-interface) for it. Load any names it also lists with steps 1 to 4.
+When the caller names an interface ("Load the implementations of the `<id>` interface"), follow [Implementations of an interface](#implementations-of-an-interface) for it. Load any names it also lists with steps 1 to 6.
 
 ## 1. Run the command once
 
-Find the caller's folder from what the harness told you when the caller loaded: a `Base directory for this skill: <folder>` line, or the path of its `SKILL.md`, whose folder is the caller's. Then collect every name the caller listed, in its order, and run one command for all of them, from anywhere:
+Find the caller's folder from what the harness told you when the caller loaded: a `Base directory for this skill: <folder>` line, or the path of its `SKILL.md`. Collect every name the caller listed, in its order, and run one command for all of them:
 
 ```sh
-node <this skill's folder>/scripts/reference.mjs show <name>... --default <caller folder> --root <repository root>
+node <this skill's folder>/scripts/reference.mjs load <name>... --default <caller folder>
 ```
 
 - `<this skill's folder>` is the directory the `reference` skill's `SKILL.md` is in.
-- `--default <caller folder>` adds the caller's own defaults, `references/<name>.default.md` in its folder, below every other contribution.
-- When you cannot tell the caller's folder, leave out `--default`. The names then resolve without the caller's defaults; say so in step 4.
-- `<repository root>` is the root of the repository you are working in, so its `.agents/references/` customizations apply. Pass it even when it is the working directory.
-- Never use `npx`, `pnpm dlx`, `upx`, or any other package runner, and never download anything, not even when this command cannot run. Go to step 3 instead.
+- `--default <caller folder>` adds the caller's own defaults below every other contribution.
+- Add `--root <repository root>` only when the working folder is not in the repository you work in.
+- When you cannot tell the caller's folder, leave out `--default`. The names then load without the caller's defaults. Tell the user so in step 5.
+- Never use `npx`, `pnpm dlx`, `upx`, or any other package runner, and never download anything, not even when this command cannot run. Go to step 4 instead.
 
 Do not read `.agents/references/`, `~/.agents/`, any plugin's `references/`, or the caller's `references/` yourself. What answers a name is the command's decision.
 
-## 2. Read what it printed
+## 2. Read the result
 
-One name prints its document. Several print each as `<reference name="…">` … `</reference>`, in the order asked. A name that did not resolve prints `<reference name="…" status="…" />` in its place, and an `error: <code>: <message>` line on stderr names it. Exit 0 means every name resolved; 1 means at least one did not.
+The result is on stdout. One found name prints its document. Several print each as `<reference name="…">` … `</reference>`, in the order asked. A name that was not found prints `<reference name="…" status="…" code="…">message</reference>` in its place, also when it is the only name. Read the status and the code from that tag. The command exits 0 even when a name was not found.
 
-**The command ran** when every name you asked for appears in the output as a document or a `status=` marker; for a single name, exit 0 with a document on stdout, or exit 1 with an `error:` line naming it, also counts. Anything else (`Cannot find module`, `node: not found`, a stack trace, no mention of the names) means it did not run: go to step 3.
+A found document may end with project sections, each wrapped as `<project folder="…">` … `</project>`. Each one states what differs for work in that folder. A section marked `plugin="…"` comes from a plugin that folder's `package.json` lists.
 
-Per name:
+A warning prints on stderr as `warning: <code>: <message>`. It does not change the answer.
+
+**The command ran** when every name you asked for appears on stdout as a document or a status tag. Exit 1 or 2 with one error value on stdout (`error:` and `code:` lines) means it ran but could not answer: go to step 4 and report the error. Anything else (`Cannot find module`, `node: not found`, a stack trace, no mention of the names) means it did not run: go to step 4.
+
+## 3. Act on each name
 
 - **found**: use the document.
-- **missing** (`reference-missing`): carry on without it, and tell the user it was not loaded. Do not read the caller's default or search for a substitute: the command already included the default. When the error says a `remove` turned the name off, say nothing about it.
-- **ambiguous** (`reference-ambiguous`): more than one plugin holds the name and nothing says which to build on. The error lists the options: each `<plugin>/<name>`, and `default` when the caller has one.
-  - With a user present, list every option, even when only one is left, and ask which the name should build on. Write the pick with `reference select <name> <option>` (add `--scope user` when the user wants it for themselves only), then run step 1 again for that name alone and use what it prints.
-  - With no user present, carry on without it, and tell the user to settle it with `reference select <name> <option>`.
-- **invalid** (`reference-invalid`): the caller's load line names something that is not a reference name. Never read the path or file it names. Carry on without it, and tell the user it is a fault in the caller's instructions, to report to the caller's author.
+- **missing** with `reference-missing`: carry on without it, and tell the user it was not loaded. Do not read the caller's default or search for a substitute: the command already included the default.
+- **missing** with `reference-removed`: a `remove` turned the name off on purpose. Carry on without it, and say nothing about it. It is not a fault.
+- **ambiguous** with `reference-ambiguous`: more than one plugin holds the name and nothing says which to build on. The tag ends with `; options: …`: each `<plugin>/<name>`, and `default` when the caller has one.
+  - With a user present, list every option, including `default`, even when only one is left. Ask which the name should build on, and whether the pick is for the repository (the default) or only for them. Write the pick with `reference customize <name> --extends <step>`, where the step is the option's plugin part or `default`, adding `--default <caller folder>`, and `--scope user` when it is for them only. Then run step 1 again for that name alone and use what it prints.
+  - With no user present, carry on without it, and tell the user to settle it with Customize mode.
+- **invalid** with `reference-invalid`: the caller's load line names something that is not a reference name. Never read the path or file it names. Carry on without it, and tell the user it is a fault in the caller's instructions, to report to the caller's author.
+
+Pass every warning on to the user, one line each, and use the reference as loaded. A `reference-stale` warning means a generated document was built against plugins that have since changed: name the changed plugins from its message, and say that Customize mode revises the document from its recorded request. A `plugin-not-selected` warning means a plugin installed after the customizer picked what the name builds on also holds it, and is not used: name the plugin, and say that Customize mode adds it, or leaves it out so the warning stops.
+
+## 4. When the command did not run
+
+Read the caller's default of every name, and only then. Never read a default for a name the command reported, whatever its status. A name's default is the first of these in the caller's folder:
+
+1. `references/<name>.default.md`
+2. `references/<name>.default.json`, `.default.yaml`, `.default.yml`, `.default.toml`, then `.default.txt`
+
+A name with no such file is not loaded. Never read `references/<name>.md`; it is not a default.
+
+## 5. Report
+
+Tell the user, briefly:
 
-A `warning:` line does not change the answer. Pass one on only when it names `reference select`; it means a plugin answers over the caller's default, and the user can choose.
+- each name not loaded, and why: missing, ambiguous (with the options), or invalid (a fault for the caller's author). Leave out a name a `remove` turned off.
+- each warning, one line each.
+- when the command did not run: that it did not, the error it gave, and that each name came from the caller's default, so no managed text, project section, or repository or user customization applied. When a name has no default, add that `scripts/reference.mjs` ships with the npm package, so a `cyber-agentkit` plugin installed from git has none, and installing it from npm fixes it.
+- when you could not tell the caller's folder: that the names loaded without its defaults.
 
-## 3. When the command did not run
+Say nothing about the load when every name was found with no warning.
 
-Read the caller's default of **every** name: `<caller folder>/references/<name>.default.md`. A name with no such file is **not loaded**. Never read `<caller folder>/references/<name>.md`; it is not a default.
+## 6. Follow the references
 
-## 4. Report, then continue the caller's work
+Return to the caller. Follow each loaded document as part of its instructions. Carry on without a name that was not loaded.
 
-Tell the user, briefly, about every name that did not come from the command, and every name not loaded:
+Where instructions conflict, follow them in this order, highest first:
 
-- a name not loaded, and why: missing, ambiguous (with the options), or invalid (a fault for the caller's author);
-- when the command did not run: that it did not, the error it gave, and that each name came from the caller's default, so no project, user, or machine customization applied;
-- when the command did not run and a name has no default: that `scripts/reference.mjs` ships with the npm package, so a `cyber-agentkit` plugin installed from git has none, and installing it from npm fixes it;
-- when you could not tell the caller's folder: that the names were loaded without its defaults.
+1. company and team instructions the harness gives you;
+2. a single feature's own document the caller points you at;
+3. the resolved reference, or the default read when the command did not run.
 
-Say nothing about the load when every name came from the command, and nothing about a name a `remove` turned off.
+Within a resolved reference, the project section for the folder the work is in ranks over the main document. When sections of nested folders both apply, follow both, and the inner folder's section wins where they conflict. When one folder has a section marked `plugin="…"` and one without, follow both, and the one without wins where they conflict. Managed text needs no ranking: the command already applied it.
 
-Then return to the caller. Follow each loaded document as part of the caller's instructions. Carry on without a name that was not loaded.
+Follow a project section whenever your work is in its folder. When the work moves into a folder partway through the task, follow that folder's project section from then on, without loading again. Stop following it when the work leaves the folder.
 
 ## Implementations of an interface
 
-1. Run, from anywhere:
+1. Run:
 
    ```sh
-   node <this skill's folder>/scripts/reference.mjs implementations <id> --trace --format json --root <repository root>
+   node <this skill's folder>/scripts/reference.mjs implementations <id> --trace --format json
    ```
 
-   Add `--accept <versions>`, such as `--accept 1,2`, when the caller names the interface versions it knows. The same rules as step 1 apply: no package runner, no download, and no reading tier folders yourself.
-2. Exit 0 prints one JSON object. `implementations` lists each one the caller can load, with its `pin`, `description`, and the `unsupported` sections it does not honor; it is a string when there are none. `excluded` lists each one left out, with its `reasons`. Exit 1 prints an `error:` line on stderr, such as `no interface document <id>.interface`; then the interface is **not loaded**.
-3. Hand the list to the caller. The caller picks the implementations it needs; load each by its `pin` with steps 1 to 4.
-4. Tell the user, briefly, about each excluded implementation and its reasons, and about an interface not loaded and its error. The caller carries on without the implementations.
+   Add `--accept <versions>`, such as `--accept 1,2`, when the caller names the interface versions it knows. The rules of step 1 apply: add `--root` only outside the repository, no package runner, no download, and no reading tier folders yourself.
+2. Exit 0 prints one JSON object. `implementations` lists each one the caller can load, with its `pin`, `description`, and the `unsupported` sections it does not honor. It is empty when there are none. `excluded` lists each one left out, with its `reasons`. An unknown interface exits 1 with one error value on stdout, code `interface-unknown`; then the interface is not loaded.
+3. Hand the list to the caller. The caller picks the implementations it needs; load each by its `pin` with steps 1 to 6.
+4. Tell the user, briefly, about each excluded implementation and its reasons, and about an interface not loaded and its error.
 
 ## Validate
 
 Before returning to the caller:
 
-- Every name the caller listed is either loaded from the command, read from the caller's default because the command did not run, or named in the report as not loaded.
+- Every name the caller listed is loaded from the command, read from the caller's default because the command did not run, or named in the report as not loaded.
 - The caller's default was read only when the command did not run, never for a name the command reported.
-- An ambiguous name was settled with `reference select` only after the user picked an option.
-- Every interface the caller named is either listed with `implementations`, or named in the report as not loaded.
+- An ambiguous name was written with `reference customize --extends` only after the user picked an option and a scope.
+- Every warning was passed on, one line each.
 - No `npx`, `pnpm dlx`, `upx`, or download was run.
 - No file under a tier folder, and no path an invalid name gives, was read by you.
-- The report is empty when every name came from the command.