@really-knows-ai/foundry 3.0.1 → 3.1.0

package/dist/CHANGELOG.md

@@ -1,5 +1,187 @@
 # Changelog
 
+## [3.1.0] - 2026-05-11
+
+The Foundry guide agent release. Foundry now ships a user-facing agent that
+routes configuration authoring through Foundry concepts — users ask the Foundry
+agent for outcomes, and the agent composes dependent work internally rather than
+handing users a chain of individual tools and skills.
+
+### Added
+
+- **Foundry guide agent** (`src/agents/foundry.md`). A user-facing agent with
+  identity marker *"You are the Foundry agent"* that maps user requests to
+  Foundry concepts, routes through the standard config-branch workflow, and
+  delegates to authoring skills internally.
+- **`foundry_refresh_agents` tool.** Deterministic stage-agent generation: runs
+  `opencode models`, deletes stale `.opencode/agents/foundry-*.md` files, and
+  writes fresh agent files — one per available model. Replaces the prior
+  skill-only protocol where the LLM had to implement the logic with shell
+  commands.
+- **`init-foundry` installs the guide agent.** Step 5 creates
+  `.opencode/agents/foundry.md` (preferring `dist/agents/foundry.md`, falling
+  back to `src/agents/foundry.md`), then instructs the user to restart OpenCode
+  and switch to the Foundry agent.
+- **Comprehensive guidance audit tests.** `tests/skills/foundry-guidance-audit.test.js`
+  (357 lines) and `tests/skills/authoring-guidance.test.js` (45 lines) enforce
+  that skills avoid dead-end delegation patterns, route through the Foundry
+  agent, keep internal tool-call syntax out of normal user guidance, and handle
+  config branches and dependencies internally.
+- **Packaging test** (`tests/plugin/packaging.test.js`). Verifies the published
+  package ships `dist/agents/` so `init-foundry` can locate the guide agent
+  template in a packaged install.
+
+### Changed
+
+- **Authoring skills reworked around the Foundry agent.** `add-flow`,
+  `add-cycle`, `add-artefact-type`, `add-law`, and `add-appraiser` now include a
+  `## Foundry Agent Preflight` section; and frame user requests as Foundry
+  outcomes, compose missing dependencies internally in validation order, and
+  hide internal tool-call syntax from normal user guidance (`foundry_git_branch`,
+  `foundry_git_finish`, `foundry_config_create_*`).
+- **Memory/config skills handle branches and dependencies internally.**
+  `init-memory`, `reset-memory`, `add-memory-entity-type`, `add-memory-edge-type`,
+  `add-extractor`, and the `rename-memory-*` / `drop-memory-*` /
+  `change-embedding-model` skills no longer tell the user to create config
+  branches or run prerequisite skills. All use *"move to a suitable `config/*`
+  branch internally when the current branch is safe"* with `work/*` /
+  `dry-run/*/*` / uncommitted-change guards.
+- **`add-extractor` composes cycle wiring internally.** The skill updates
+  relevant cycle definitions rather than presenting manual frontmatter editing
+  as the normal outcome.
+- **`add-cycle` hides generated stage-agent files.** Model selection guidance
+  now references *"Available session models are listed in your session
+  configuration"* instead of exposing `.opencode/agents/foundry-*.md`.
+- **Existing-file recovery keeps the agent in the loop.** When
+  `foundry_config_create_*` returns `{ ok: false }` because the target file
+  already exists, `add-artefact-type`, `add-appraiser`, `add-law`, and
+  `add-cycle` now read the existing content, incorporate the user's requested
+  changes, propose the merged result, and commit — rather than telling the user
+  to *"edit by hand."*
+- **Bootstrap context** (`helpers.js`) presents capabilities as Foundry
+  outcomes (*"ask the Foundry agent to add flow memory"*, *"ask the Foundry
+  agent to run that flow"*) instead of listing internal skills.
+- **`getting-started.md` reworked.** The walkthrough now routes through the
+  Foundry agent, removes direct `foundry_git_branch({` /
+  `foundry_git_finish({` / `Run \`add-*\`` / `foundry_config_validate_*({` /
+  `foundry_config_create_*({` references, and uses `pnpm add -D
+  @really-knows-ai/foundry`.
+- **`README.md` quick-start** updated for the install → init → ask-agent
+  workflow (`pnpm add -D @really-knows-ai/foundry`, ask the Foundry agent
+  to add a haiku flow).
+- **`refresh-agents` skill** delegates to `foundry_refresh_agents()`. The skill
+  is now a thin wrapper around the deterministic tool.
+- **`init-foundry`, `list-agents`, `sort.js`, `upgrade-foundry`** updated to
+  reference the `foundry_refresh_agents` tool.
+- **Docs** (`architecture.md`, `concepts.md`, `tools.md`) updated to reference
+  guide-agent installation and the refresh tool. Tool count increased from 66 to
+  67.
+
+### Fixed
+
+- **`dist/agents/` added to the published package.** The build script already
+  copied `src/agents/` to `dist/agents/`, but the `files` array in
+  `package.json` excluded `dist/agents/`. `init-foundry` can now locate the
+  guide agent template in a packaged install.
+- **`foundry_refresh_agents` preserves the guide agent.** Only
+  `foundry-*.md` stage agents are regenerated; `.opencode/agents/foundry.md`
+  survives refresh.
+
+## [3.0.3] - 2026-05-11
+
+A patch release that makes agent-file generation deterministic by moving
+`refresh-agents` from a skill-only protocol into a tested plugin tool.
+
+### Added
+
+- **`foundry_refresh_agents` tool.** Runs `opencode models`, deletes stale
+  `.opencode/agents/foundry-*.md` files, and generates fresh agent files — one
+  per available model. The tool is idempotent, handles missing directories, and
+  returns `{ ok: true, count: <n> }` on success. This replaces the prior
+  skill-only protocol where the LLM had to implement the logic with shell
+  commands, which was error-prone and non-deterministic.
+
+### Changed
+
+- **`refresh-agents` skill** now simply calls `foundry_refresh_agents()` and
+  reports the result.
+- **`init-foundry` skill** step 4 now calls `foundry_refresh_agents()` instead
+  of instructing the LLM to run the `refresh-agents` skill.
+- **`list-agents` skill** error message now references the tool.
+- **`sort.js`** missing-agent error now references the tool.
+- **`helpers.js`** bootstrap message now references the tool.
+- **Docs** (`tools.md`, `getting-started.md`, `architecture.md`, `concepts.md`)
+  updated to reference the tool. Tool count increased from 65 to 66.
+
+## [3.0.2] - 2026-05-11
+
+A documentation and tool-correctness patch driven by a failing
+haiku-flow setup session. Closes the loop on the laws-with-validators
+migration: the validator contract is now fully documented in
+`add-law`; the `add_law` tool appends additional laws to an existing
+file and rolls back its file write when the commit fails;
+`init-foundry` seeds a `node_modules/` ignore so npm-installed
+validator dependencies never collide with the config-tier write
+guard.
+
+### Validator contract is canonical in `add-law`
+
+- `add-law` SKILL.md gains a **§7a. Validator contract** that covers
+  the JSONL output shape (`file`, `text` required; `location`,
+  `severity` optional), command placeholders, working directory, skip
+  rule, and a worked Node example. Authors no longer need to read
+  plugin source to write a validator.
+- `add-artefact-type` step 5 drops its half-duplicate contract and
+  cross-references `add-law` §7a. Step 1 and step 4 now make clear
+  that the frontmatter `name:` field equals the artefact type's id
+  (lowercase, hyphenated); human-readable labels go in the
+  `## Definition` prose. Step 9 reflects the new append-aware
+  `add_law`.
+
+### Validator command placeholders split
+
+- `{pattern}` now renders the artefact type's `file-patterns:` as
+  space-separated, shell-quoted globs (e.g.
+  `'haikus/*.md' 'drafts/*.md'`). Use it when a validator does its
+  own globbing or accepts globs directly (e.g. `rg --glob`).
+- `{files}` renders the matching files in the worktree as
+  space-separated, shell-quoted paths. Use it when the validator
+  takes an explicit list of file paths.
+- A validator is skipped iff its command contains `{files}` and there
+  are no matching files. `{pattern}`-only and verbatim commands
+  always run.
+- **Migration:** any existing validator authored against the prior
+  semantics (where `{pattern}` substituted expanded paths) must be
+  updated to use `{files}` instead. Foundry was tagged 3.0.1 only
+  12 hours before this release; no migration helper is provided.
+
+### `foundry_config_add_law` correctness
+
+- The tool now appends a new law to an existing `laws.md` instead of
+  erroring on file-exists. It only errors when a law with the same
+  id is already present in the file — in that case the caller
+  switches to `foundry_config_edit_law`.
+- File writes are atomic with the commit. If the commit fails (most
+  commonly `unexpected_files`), the tool restores `laws.md` to its
+  prior content (or deletes it if it didn't exist before the call).
+  This eliminates the orphaned-file state that previously broke the
+  next call with "already exists".
+
+### `init-foundry` seeds `node_modules/`
+
+- `.gitignore` now starts with `.snapshots/`, `node_modules/`, and
+  `.DS_Store`. The new entry stops `npm install` from immediately
+  blocking every config-tier tool with `unexpected_files`.
+
+### Migration
+
+- Update any validator commands that used `{pattern}` for file
+  expansion to use `{files}` instead.
+- No action needed for projects already on 3.0.1 that have not yet
+  authored validators using `{pattern}`.
+- Existing projects can add `node_modules/` to `.gitignore` by hand;
+  the `init-foundry` change only affects newly-initialised projects.
+
 ## [3.0.1] - 2026-05-11
 
 A documentation and cleanup patch. No runtime behaviour change. `quench`

package/dist/README.md

@@ -142,16 +142,17 @@ Open OpenCode in your project repo and say:
 > run init-foundry
 ```
 
-Foundry scaffolds a `foundry/` directory, generates one `foundry-<model>` agent file
-per model available in your session, commits the structure, and then asks you to
-restart. All the foundational configuration directories are created; you will
-populate them next.
+Foundry scaffolds a `foundry/` directory, generates one `foundry-<model>` stage agent
+file per model available in your session, installs the user-facing `Foundry` guide
+agent, commits the structure, and asks you to restart.
 
-Restart OpenCode so the new `foundry-<model>` agents register — multi-model dispatch cannot route to agents it cannot discover.
+Restart OpenCode so the new agents register. After the restart, switch to the
+**Foundry** agent. The Foundry agent is the normal interface for authoring and
+running Foundry workflows.
 
-### Phase 3 — Build a flow without writing one
+### Phase 3 — Ask the Foundry agent for a flow
 
-Ask Foundry to set up a flow:
+With the **Foundry** agent active, ask it to set up a flow:
 
 ```
 > set up a flow that writes haikus

package/dist/agents/foundry.md

@@ -0,0 +1,37 @@
+---
+description: "Guide users through Foundry authoring and flow execution"
+mode: primary
+---
+You are the Foundry agent.
+
+Foundry is a framework for governed AI artefact generation. Your role is to help the user reach their stated Foundry outcome by understanding the goal, handling prerequisites, composing dependent configuration, and explaining progress in Foundry concepts.
+
+## Operating Principles
+
+- Treat user requests as goals to satisfy.
+- Use Foundry skills and tools internally.
+- Keep tool names, JSON arguments, and tool-call syntax out of normal user-facing instructions.
+- Create missing dependencies when they are part of the user's stated goal.
+- Handle config branches, validation, commits, and dependency ordering when safe.
+- Ask one focused question when intent, safety, or irreversible project state requires user input.
+- Report outcomes as Foundry concepts, files created or updated, validations run, and commits made.
+
+## Authoring Posture
+
+When the user asks to create or change a flow, work backwards from the requested outcome. A flow may require artefact types, laws, validators, appraisers, cycles, memory configuration, and branch setup. Create or reuse those pieces as needed instead of telling the user to invoke another skill.
+
+When a dependency is ambiguous, present the smallest useful choice. When a dependency is missing and the user's goal clearly requires it, create it. When a hard conflict exists, stop and explain the conflict in Foundry terms.
+
+## Safety Boundaries
+
+- Preserve user changes.
+- Do not overwrite unrelated files.
+- Do not bypass Foundry validation.
+- Do not create overlapping artefact file patterns.
+- Do not change Foundry configuration on an active `work/*` branch.
+- Do not continue configuration work from `dry-run/*/*`; finish the dry run first.
+- Do not push, publish, or create pull requests unless the user explicitly asks.
+
+## User-Facing Style
+
+Speak directly and concretely. Explain what you are creating and why it supports the user's goal. Prefer Foundry terms such as artefact type, law, validator, appraiser, cycle, and flow. Avoid exposing implementation details unless the user asks for them.

package/dist/docs/architecture.md

@@ -300,7 +300,9 @@ Different stages can run on different models for cognitive diversity. Cycle defi
 
 ### Agent files
 
-`refresh-agents` generates a `foundry-<slug>.md` agent file in `.opencode/agents/` for every model available in the session, where `<slug>` is the model ID with both `/` and `.` replaced by `-` (e.g. `anthropic-claude-opus-4-7.md`).
+The user-facing `Foundry` agent is installed by `init-foundry` as `.opencode/agents/foundry.md`. Users switch to this agent after restarting OpenCode. It guides authoring and flow execution while generated `foundry-*` stage agents remain hidden routing targets for specific models.
+
+`foundry_refresh_agents()` generates a `foundry-<slug>.md` agent file in `.opencode/agents/` for every model available in the session, where `<slug>` is the model ID with both `/` and `.` replaced by `-` (e.g. `anthropic-claude-opus-4-7.md`).
 
 ### Dispatch behaviour
 
@@ -336,7 +338,7 @@ Implementation: `src/plugin/tools/helpers.js` (`buildCyclePromptExtras`) and `sr
 │   │   ├── add-flow/
 │   │   ├── add-extractor/
 │   │   ├── list-agents/        # utility
-│   │   ├── refresh-agents/
+│   │   ├── refresh-agents/       # utility (now backed by foundry_refresh_agents tool)
 │   │   ├── upgrade-foundry/
 │   │   ├── init-memory/        # memory
 │   │   ├── add-memory-entity-type/
@@ -415,7 +417,8 @@ your-project/
 │   └── .secret                 # per-worktree HMAC key (mode 0600)
 ├── .opencode/
 │   └── agents/
-│       └── foundry-*.md        # generated by refresh-agents
+│       ├── foundry.md          # user-facing Foundry guide agent
+│       └── foundry-*.md        # generated stage agents for model routing
 ├── opencode.json
 └── ...
 ```

package/dist/docs/concepts.md

@@ -265,7 +265,7 @@ All deterministic pipeline operations are exposed as custom tools by the Foundry
 
 ## Skill
 
-A self-contained workflow written as markdown with YAML frontmatter. Foundry ships pipeline skills (`flow`, `orchestrate`, `forge`, `quench`, `appraise`, `human-appraise`), authoring skills (`add-*`, `init-foundry`), utility skills (`list-agents`, `refresh-agents`, `upgrade-foundry`), and memory skills (`init-memory`, `add-memory-*`, `rename-memory-*`, `drop-memory-*`, `reset-memory`, `change-embedding-model`). Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).
+A self-contained workflow written as markdown with YAML frontmatter. Foundry ships a user-facing `Foundry` guide agent plus skills for pipeline execution, authoring, maintenance, and memory administration. The guide agent is the normal interface for users; skills and tools provide the internal workflows it uses to initialise projects, create artefact types, define laws, configure appraisers, build cycles and flows, and run governed artefact generation. Skills are either **atomic** (do one thing) or **composite** (orchestrate other skills).
 
 ---
 

package/dist/docs/getting-started.md

@@ -26,24 +26,16 @@ OpenCode resolves the package itself — `npm install` is **not** required. Rest
 Optionally, if you want the package available to your project's local node_modules (for editor tooling or scripts), run:
 
 ```sh
-npm install --save-dev @really-knows-ai/foundry
+pnpm add -D @really-knows-ai/foundry
 ```
 
 ## Initialise
 
-In your project, invoke the `init-foundry` skill. It:
+Run the `init-foundry` skill.
 
-1. Creates the `foundry/` directory structure:
-   ```
-   foundry/
-     artefacts/.gitkeep
-     flows/.gitkeep
-     cycles/.gitkeep
-     laws/.gitkeep
-     appraisers/.gitkeep
-   ```
-2. Runs `refresh-agents` to generate `.opencode/agents/foundry-*.md` — one per available model — so cycles can dispatch to specific models later.
-3. Commits the scaffolding.
+Initialisation installs the user-facing `Foundry` agent at `.opencode/agents/foundry.md` and generates model-routing `foundry-*` stage agents for any models available in your OpenCode session.
+
+Restart OpenCode after initialisation. Then switch to the **Foundry** agent before authoring flows. The Foundry agent understands Foundry's authoring workflow and handles dependent setup such as artefact types, laws, validators, appraisers, cycles, and config branches.
 
 The `.foundry/` runtime directory (holding `.secret` for stage tokens) is created automatically on first plugin boot and added to `.gitignore`.
 
@@ -51,134 +43,67 @@ The `.foundry/` runtime directory (holding `.secret` for stage tokens) is create
 
 ## Author the configuration
 
-Foundry's configuration is five things: artefact types, laws, appraisers, cycles, and flows. You can write the files by hand, but the authoring skills do conflict checking, scaffolding, and validation — use them.
-
-Before using any schema-writing skill, open a config branch. All schema-mutation tools (`foundry_config_create_*`, `foundry_memory_create_*`, `foundry_extractor_create`, the memory admin family) refuse off `main` and off flow branches:
-
-```text
-foundry_git_branch({ kind: "config", description: "<short-name>" })
-```
-
-This typically puts you on `config/<short-name>` from `main`. Make all the
-edits below on this branch, then `foundry_git_finish({ message: "...",
-baseBranch: "main", confirm: true })` squashes the work back to
-`main` in one commit. To trial the in-progress edits against a real
-flow before merging, see "Trial config edits with dry-run" below.
-
-### 1. Define an artefact type
-
-Run `add-artefact-type`. It walks you through:
-
-- `id` (lowercase, hyphenated), `name`, prose description.
-- `file-patterns` — glob patterns describing which files this type owns. Forge's write scope is exactly these patterns; anything written outside them violates the cycle. The skill refuses patterns that overlap with existing types.
-- Appraiser config — how many appraisers evaluate this type and which personalities are allowed.
-- Optional `laws.md` — type-specific criteria, with optional validators for deterministic checks.
-
-Produces `foundry/artefacts/<id>/definition.md` (+ optional `laws.md`).
-
-### 2. Write laws
-
-Laws are subjective pass/fail criteria evaluated by appraisers. Two scopes:
-
-- **Global** — `foundry/laws/*.md`. All files are concatenated and apply to every artefact.
-- **Type-specific** — `foundry/artefacts/<type>/laws.md`.
-
-Run `add-law` to create one with conflict detection. Each law is a `## heading` (its identifier, referenced as `law:<id>` in feedback) with a description, passing criteria, and failing criteria.
-
-### 3. Create appraisers
-
-Appraisers are independent evaluators with named personalities. Run `add-appraiser`. Each appraiser may override the cycle-level appraise model via a `model` field. Artefact types pick which appraisers may evaluate them (`appraisers.allowed`).
+Foundry's configuration is five things: artefact types, laws, appraisers, cycles, and flows. The Foundry agent handles branch setup, conflict checking, scaffolding, and validation for normal authoring.
 
-### 4. Define a cycle
+### Author through the Foundry agent
 
-Run `add-cycle`. A cycle produces one artefact type and declares:
+Ask the Foundry agent to author or modify any part of the configuration. For example:
 
-- `output-type` — the artefact type (must already exist).
-- `inputs` — a contract (`any-of` or `all-of`) over other types. Empty for starting cycles.
-- `targets` — the cycle(s) that may run after this one. Empty for terminal cycles.
-- `human-appraise` / `deadlock-appraise` / `deadlock-iterations` — human-gate config.
-- `models` — optional per-stage model overrides.
+> Add a `haiku` artefact type with a `poetic-form` appraiser.
 
-Example:
+> Add a law that requires at least one sensory metaphor in every haiku.
 
-```markdown
----
-id: haiku-creation
-name: Haiku Creation
-output-type: haiku
-inputs:
-  type: any-of
-  artefacts:
-    - petition
-targets: []
-human-appraise: false
-deadlock-appraise: true
-deadlock-iterations: 5
-models:
-  appraise: openai/gpt-5
----
+> Create a cycle that produces haikus from petitions.
 
-# Haiku Creation
+> Set up a `make-haiku` flow starting from `haiku-ideation`.
 
-Writes a haiku satisfying the petition produced by haiku-ideation.
-```
+The agent opens a config branch, creates the files, validates them, and commits the result. To trial in-progress edits against a real flow before merging, see "Trial config edits with dry-run" below.
 
-The skill validates that every input type can be produced by some cycle in the flow and that targets are reachable.
+### Configuration reference
 
-### 5. Define a flow
+These are the five pieces of a Foundry configuration, in dependency order:
 
-Run `add-flow`. A flow groups cycles and declares starting points:
+1. **Artefact types** — define the output of each cycle. Each type has an `id`, `name`, prose description, `file-patterns` (forge's write scope), appraiser config, and optional type-specific `laws.md`. Produces `foundry/artefacts/<id>/definition.md`.
 
-```markdown
----
-id: make-haiku
-name: Make a Haiku
-starting-cycles:
-  - haiku-ideation
----
+2. **Laws** — subjective pass/fail criteria evaluated by appraisers. Two scopes: global (`foundry/laws/*.md`, concatenated for every artefact) and type-specific (`foundry/artefacts/<type>/laws.md`). Each law is a `## heading` (its identifier, referenced as `law:<id>` in feedback) with a description, passing criteria, and failing criteria.
 
-# Make a Haiku
-
-End-to-end flow: petition → haiku, with a human quality gate.
-
-## Cycles
-
-- haiku-ideation
-- haiku-creation
-```
+3. **Appraisers** — independent evaluators with named personalities. Each may override the cycle-level appraise model via a `model` field. Artefact types pick which appraisers may evaluate them (`appraisers.allowed`).
 
-Routing between cycles is owned by individual cycles via their `targets`, not by the flow.
+4. **Cycles** — produce one artefact type and declare `output-type`, `inputs` (a contract over other types), `targets` (reachable downstream cycles), human-gate config, and optional per-stage model overrides. Example:
 
-### 6. Validate before writing (optional)
+   ```markdown
+   ---
+   id: haiku-creation
+   name: Haiku Creation
+   output-type: haiku
+   inputs:
+     type: any-of
+     artefacts:
+       - petition
+   targets: []
+   human-appraise: false
+   deadlock-appraise: true
+   deadlock-iterations: 5
+   models:
+     appraise: openai/gpt-5
+   ---
+   ```
 
-Each `add-*` skill writes and commits in one step. When you want to validate a draft body without committing it, call the matching validator first:
+5. **Flows** — group cycles and declare starting points. Routing between cycles is owned by individual cycles via their `targets`.
 
-```text
-foundry_config_validate_artefact_type({ name, body })
-foundry_config_validate_law({ name, body })
-foundry_config_validate_appraiser({ name, body })
-foundry_config_validate_cycle({ name, body })
-foundry_config_validate_flow({ name, body })
-```
+### Hand-authoring configuration files
 
-Validators return `{ok: true}` on success or
-`{ok: false, errors: [...]}` on a parse / schema / overlap problem; nothing
-is written either way. Once the validator is happy, call the
-matching `_create_*` tool to commit it.
+Users who prefer to write configuration files by hand open a config branch first. The Foundry agent handles this automatically; hand-authoring is for users who choose to work outside the agent. See [`docs/tools.md`](./tools.md) for the full list of schema-mutation and validation tools.
 
 ---
 
 ## Run the flow
 
-Tell OpenCode something like:
-
-> Run the `make-haiku` flow to write a haiku about autumn rain.
-
-The `flow` skill will:
+To run a flow, ask the Foundry agent with your goal as the input (e.g. "Run the make-haiku flow to write a haiku about autumn rain"). The Foundry agent dispatches the `flow` skill, which:
 
-1. Check prerequisites and pick a starting cycle — matching your prose to a cycle's output type. If the request is ambiguous, it prompts (defaulting to `starting-cycles`). If a cycle's input contract can't be satisfied from files on disk, it won't be chosen.
-2. Create a work branch and scaffold `WORK.md` with the goal.
-3. Hand off to `orchestrate`, which drives the cycle:
+1. Checks prerequisites and picks a starting cycle — matching your prose to a cycle's output type. If the request is ambiguous, it prompts (defaulting to `starting-cycles`). If a cycle's input contract can't be satisfied from files on disk, it won't be chosen.
+2. Creates a work branch and scaffolds `WORK.md` with the goal.
+3. Hands off to `orchestrate`, which drives the cycle:
    - **forge** writes the artefact.
    - **quench** runs CLI validators (if configured).
    - **appraise** dispatches parallel appraiser sub-agents and consolidates their `law:<id>` feedback.
@@ -197,19 +122,14 @@ When you've changed a law, an appraiser, or a cycle on a `config/*`
 branch and want to see how the change behaves end-to-end before
 merging, use dry-run mode.
 
-```text
-# starting on a config/* branch with the in-progress edit
-foundry_git_branch({ kind: "dry-run", flowId: "make-haiku",
-                     description: "stricter-imagery-law" })
-# now on dry-run/<parent>/make-haiku-stricter-imagery-law
-
-# run the flow as you normally would
-# every foundry_* call is traced to .foundry/trace/<branch>.jsonl
-
-foundry_git_finish({ message: "trial: stricter imagery law", confirm: true })
-# writes .snapshots/<run-id>/{README.md, work/WORK*, diff.patch, trace.jsonl}
-# on the parent config/* working tree and force-deletes the dry-run branch
-```
+Starting on the `config/*` branch with the in-progress edit, ask the
+Foundry agent to trial the change with dry-run mode for the target flow
+and a short purpose such as `stricter-imagery-law`. The agent creates a
+`dry-run/<parent>/<flow>-<purpose>` branch, runs the flow, records every
+Foundry tool call in `.foundry/trace/<branch>.jsonl`, then finishes the
+dry-run with a findings summary. Finishing writes
+`.snapshots/<run-id>/{README.md, work/WORK*, diff.patch, trace.jsonl}`
+on the parent `config/*` working tree and deletes the dry-run branch.
 
 Inspect the snapshot at `.snapshots/<run-id>/`, decide whether to keep
 the config edit, and either commit/merge from the parent `config/*`
@@ -263,11 +183,11 @@ Foundry ships a typed, graph-shaped memory store that persists across cycles. Us
 
 ### Initialise
 
-Memory init and vocabulary edits are schema mutations, so they run
-on a config branch — open one first if you are not already on it
-(`foundry_git_branch({ kind: "config", description: "memory-setup" })`).
+Memory init and vocabulary edits are schema mutations, so they run on a
+config branch. The Foundry agent opens a suitable config branch when it
+is safe; if you are working by hand, open one first.
 
-Run the `init-memory` skill. It asks whether to enable embeddings (default: yes, targeting local Ollama `nomic-embed-text` on `http://localhost:11434/v1`) and then invokes `foundry_memory_init`, which deterministically:
+To enable memory, ask the Foundry agent to add flow memory. It asks whether to enable embeddings (default: yes, targeting local Ollama `nomic-embed-text` on `http://localhost:11434/v1`) and then initialises memory, which deterministically:
 
 - creates `foundry/memory/entities/` and `edges/` (each with `.gitkeep`) plus the top-level sibling `foundry-memory/relations/` for committed row data,
 - writes `foundry/memory/config.md` (frontmatter driven by your embeddings choice) and `foundry/memory/schema.json`,
@@ -278,6 +198,8 @@ Run the `init-memory` skill. It asks whether to enable embeddings (default: yes,
 
 Two concepts: **entity types** (things memory knows about, e.g. `class`, `method`) and **edge types** (directed relationships, e.g. `calls`, `references`).
 
+The Foundry agent handles vocabulary setup as part of the normal authoring path — declare what you need in prose and it creates the types. For reference or hand-authoring, the underlying skills are:
+
 - `add-memory-entity-type` — name + prose body (naming convention, what `value` should contain, likely related edges). The body is injected into the prompt of every cycle that reads/writes this type, so write it for an LLM reader.
 - `add-memory-edge-type` — name, `sources` (list of entity types or `any`), `targets` (list or `any`), and a prose body that describes **when** the edge holds and **what it does not cover**.
 

package/dist/docs/tools.md

@@ -2,7 +2,7 @@
 
 Generated from the v3.0.x public plugin API. The authoritative tool set is
 enforced by `tests/plugin/tool-registration.test.js` — if that snapshot
-drifts, this doc must be updated. Total: **65 tools**.
+drifts, this doc must be updated. Total: **66 tools**.
 
 All tools accept arguments as a JSON object and return JSON-stringified
 results. Errors are returned as a stringified `{error: "..."}` object (not
@@ -118,6 +118,9 @@ state machine, see [`docs/concepts.md`](./concepts.md) and
 - [`foundry_attestation_verify`](#foundry_attestation_verify)
 - [`foundry_attest`](#foundry_attest)
 
+**Maintenance**
+- [`foundry_refresh_agents`](#foundry_refresh_agents)
+
 **Memory — Data**
 - [`foundry_memory_put`](#foundry_memory_put)
 - [`foundry_memory_relate`](#foundry_memory_relate)
@@ -782,6 +785,23 @@ success. `{ error: ... }` when verification fails.
 
 ---
 
+## Maintenance
+
+### `foundry_refresh_agents`
+
+> Regenerate `.opencode/agents/foundry-*.md` stage-agent files from the currently available models.
+
+**Args:** none.
+
+**Returns:** `{ ok: true, count: <n> }` on success. `{ ok: false, error: "..." }` on failure.
+
+**Failure modes:**
+- `opencode models` exits non-zero or produces no output → returns an error describing the issue.
+
+**Side effects:** creates `.opencode/agents/` if absent; deletes stale generated `.opencode/agents/foundry-*.md` stage agents; writes one fresh stage-agent file per model returned by `opencode models`.
+
+---
+
 ## Config — Schema mutation
 
 These tools each write one named config artefact and produce a single

package/dist/scripts/sort.js

@@ -156,7 +156,7 @@ function resolveModel(route, frontmatter, agentsDir, io) {
   if (!io.exists(agentPath)) {
     return {
       error: `Missing required subagent: ${model}.md is not present in ${agentsDir}/. `
-        + `Run the refresh-agents skill to regenerate agent files, then restart.`,
+        + `Call foundry_refresh_agents() to regenerate agent files, then restart.`,
     };
   }
   return model;