@really-knows-ai/foundry 3.0.2 → 3.1.0

package/dist/skills/add-extractor/SKILL.md

@@ -23,24 +23,17 @@ Before running this skill, verify all of the following:
    `git rev-parse --abbrev-ref HEAD` and confirm it matches
    `config/<description>`.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
-
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
-
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
-
-4. `foundry/memory/config.md` exists and has `enabled: true` (run
-   `init-memory` first if not). Every entity type the extractor will
-   populate must already be declared in `foundry/memory/entities/`
-   (use `add-memory-entity-type` to create any that are missing).
+3. If the branch does not start with `config/`, move to a suitable
+   `config/*` branch internally when the current branch is safe. If
+   the current branch is `work/*` or `dry-run/*/*`, stop and explain
+   the active work must be finished first. When unrelated uncommitted
+   changes could be affected by branching or writing files, ask before
+   proceeding.
+
+4. `foundry/memory/config.md` exists and has `enabled: true` (initialise
+   memory internally first if not). Missing memory entity or edge type
+   dependencies are created or composed internally when they are part of
+   the user's stated goal.
 
 ## Steps
 
@@ -50,7 +43,7 @@ Ask the user for, in this order (one question at a time):
 
 1. **Extractor name.** Lowercase kebab-case (`java-symbols`, `python-classes`, `tree-sitter-rust`). This becomes the filename under `foundry/memory/extractors/<name>.md` and the identifier referenced from cycle frontmatter.
 2. **Command.** The path to the executable (relative to the repo root, e.g. `scripts/extract-java-symbols.sh`) or a short shell command. This is passed to `/bin/sh -c` at runtime.
-3. **Entity types to populate (`memoryWrite`).** A list of entity type names already declared in this project's memory vocabulary. Validate against what exists; if the user names a type that doesn't exist, either offer to create it via `add-memory-entity-type` first or ask them to adjust.
+3. **Entity types to populate (`memoryWrite`).** A list of entity type names already declared in this project's memory vocabulary. Validate against what exists; if the user names a type that doesn't exist, compose or create it internally when it is part of the user's stated goal, or ask one focused question when schema design is ambiguous.
 4. **Timeout** (optional). Duration string like `30s`, `2m`, or a number of milliseconds. Defaults to 60 seconds if omitted.
 5. **Brief description.** 1–3 paragraphs of prose describing what this extractor extracts, what it requires on `PATH`, and any re-run triggers. This body is injected into the forge prompt of every cycle that uses this extractor, so clarity here translates to better downstream generation.
 
@@ -111,23 +104,18 @@ git add foundry/memory/extractors/<name>.md scripts/<command>
 git commit -m "feat(memory): add '<name>' extractor"
 ```
 
-### 6. Guide the user on wiring it in
+### 6. Compose into a cycle when the user's goal requires it
 
-After creation, tell the user how to opt a cycle into this extractor:
+When the user's stated goal is to add memory extraction to a flow or cycle, compose this extractor into the relevant cycle definition. See **Composing cycle definitions** below.
 
-> To use this extractor, add the following to the cycle's frontmatter:
->
-> ```yaml
-> memory:
->   write: [<each type in memoryWrite>]   # must include every type the extractor writes
-> assay:
->   extractors: [<this extractor's name>]
-> ```
->
-> Then run the `flow` or `orchestrate` skill. On the first iteration of the cycle, the assay stage will execute this extractor before forge.
+## Dependency composition
+
+Missing memory entity or edge type dependencies are **composed internally** when they are part of the user's stated goal. Compose into the appropriate memory vocabulary when schema design is ambiguous — ask one focused question rather than stalling.
 
 ## What this skill must not do
 
 - **Must not** run the extractor script itself to verify it works. That is the author's job.
-- **Must not** modify cycle definitions. Opting a cycle into the extractor is an explicit editorial step for the user to take.
-- **Must not** create entity or edge types that don't already exist. Compose into `add-memory-entity-type` / `add-memory-edge-type` for any missing vocabulary.
+
+## Composing cycle definitions
+
+When the user's stated goal includes opting an existing cycle into this extractor, update the cycle definition internally to add the `extractors` and `memoryWrite` fields. Ask for confirmation or one focused question when cycle selection or wiring is ambiguous.

package/dist/skills/add-flow/SKILL.md

@@ -6,119 +6,74 @@ description: Creates a new foundry flow definition.
 
 # Add Flow
 
-You help the user create a new foundry flow. A foundry flow is a set of foundry cycles with declared starting points — cycles own their own routing via targets and input contracts.
+You help the user create a complete Foundry flow for their stated outcome. A flow may require artefact types, laws, validators, appraisers, and cycles before the flow file itself can validate. Work backwards from the requested outcome and create missing dependencies in validation order.
 
-## Prerequisites
+## Foundry Agent Preflight
 
-Before running this skill, verify all three of the following:
+If you are clearly operating as the Foundry agent, continue.
 
-1. The `foundry/` directory exists in the project root. If it does not
-   exist, stop and tell the user:
+If you are not clearly operating as the Foundry agent, pause and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+> This work is best handled by the Foundry agent. Restart OpenCode if you have just initialised Foundry, switch to the **Foundry** agent, and continue this request there.
 
-2. The current git branch is a `config/*` branch. Run
-   `git rev-parse --abbrev-ref HEAD` and confirm it matches
-   `config/<description>`.
+This is an advisory guard. Continue only when the active instructions make it clear you are the Foundry agent or the user explicitly asks to proceed here.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
+## Config Branch Handling
 
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
+Before writing Foundry configuration:
 
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+- Confirm `foundry/` exists. If it is missing, initialise Foundry first when that serves the user's goal.
+- Check the current branch.
+- On `main` or another clean non-work branch, create a `config/<short-description>` branch internally.
+- On `config/*`, continue on the current branch.
+- On `work/*`, stop and explain that active flow work must be finished before configuration changes.
+- On `dry-run/*/*`, stop and explain that the dry run must be finished before configuration changes.
+- If unrelated uncommitted changes could be affected by branching or writing files, ask before proceeding.
 
-## Protocol
-
-### 1. Gather basics
-
-From the user's prompt, establish:
-- `id` — lowercase, hyphenated identifier
-- `name` — human-readable name
-- A prose description of what this foundry flow achieves end-to-end
-
-If any of these are missing, ask.
-
-### 2. Check for id conflicts
-
-Read all existing flow definitions in `foundry/flows/*.md`.
-
-- Exact id match → hard conflict, must choose a different id
-- Semantically similar name or description → warn and ask if the new foundry flow is genuinely distinct
-
-### 3. Determine foundry cycles and starting cycles
-
-Ask the user which foundry cycles this flow includes. List available cycles from `foundry/cycles/*.md` for reference.
+Do not tell the user to call branch tools directly.
 
-Then ask: which of these are **starting cycles** — the cycles that can be entered first when the flow begins?
-
-- Starting cycles typically have no input dependencies
-- Multiple starting cycles are fine — the user (or context) determines which one to run first
-
-### 4. Validate cycle graph
-
-For each non-starting cycle, verify it is reachable:
-- At least one other cycle in the flow has it as a target
-- Its input contract can be satisfied by cycles in the flow
-
-If a cycle is unreachable (no cycle targets it and it's not a starting cycle), warn:
-
-> Cycle `<id>` is not a starting cycle and no other cycle targets it. It will never be reached in this flow.
-
-### 5. Draft the definition
+## Protocol
 
-Present the flow definition to the user:
+### 1. Understand the outcome
 
-```markdown
----
-id: <id>
-name: <name>
-starting-cycles:
-  - <cycle-id>
----
+Extract or ask for the flow purpose, expected final artefact, output location, and any quality constraints. Prefer practical defaults for common requests.
 
-# <Name>
+### 2. Inventory existing configuration
 
-<description>
+Read existing flows in `foundry/flows/*.md`, cycles in `foundry/cycles/*.md`, artefact types in `foundry/artefacts/*/definition.md`, laws in `foundry/laws/*.md`, and appraisers in `foundry/appraisers/*.md`. Identify reusable pieces and conflicts.
 
-## Cycles
+Reject duplicate flow IDs — if a flow with the same ID already exists, choose a different ID. Warn about semantic duplicates (different ID but near-identical purpose) and ask whether the new flow is genuinely distinct.
 
-- <cycle-id>
-- <cycle-id>
-```
+### 3. Design the dependency set
 
-The `starting-cycles` field lists entry points. `## Cycles` lists all cycles in the flow (no ordering implied — routing is owned by individual cycle definitions via their `targets` field).
+Create missing dependencies in validation order:
 
-Ask: does this capture the flow correctly?
+1. Artefact type and file patterns.
+2. Type-specific laws.
+3. Deterministic validators attached to laws.
+4. Appraisers or appraiser selection.
+5. Cycles that produce the artefact types.
+6. Flow tying starting cycles and cycle list together.
 
-### 6. Validate the draft
+For the haiku example, default to a `haiku` artefact type, `haikus/*.md` file pattern, laws for form, imagery, and mood, a deterministic syllable validator where project dependencies allow it, two or three distinct appraisers, one cycle, and one flow.
 
-Call `foundry_config_validate_flow({ name: "<id>", body: "<full markdown>" })`.
+After designing cycles, validate the cycle graph: verify each non-starting cycle is reachable from a starting cycle through the `targets` graph, and verify each cycle's input contracts can be satisfied by other cycles in the flow. Warn about unreachable cycles or unsatisfiable contracts before proceeding.
 
-If the result is `{ ok: false, errors: [...] }`, address each error (adjust the body) and re-run until you get `{ ok: true }`. Common issues: missing required frontmatter keys, references to artefact types or flows that don't exist yet.
+### 4. Confirm ambiguous choices
 
-### 7. Create the file
+Ask only for choices that affect the user's goal or safety. Reuse compatible existing configuration when it clearly fits.
 
-Call `foundry_config_create_flow({ name: "<id>", body: "<full markdown>" })`. The tool:
+### 5. Validate and create each piece
 
-- re-validates the body (TOCTOU);
-- writes `foundry/flows/<id>.md`;
-- produces one git commit on the current `config/*` branch.
+For each definition, use the `foundry_config_validate_*` tool family to validate it first. Resolve any validation errors, then use the corresponding `foundry_config_create_*` tool to create it. Summarise each created file and commit hash in Foundry terms.
 
-If the tool returns `{ ok: false, errors }` because the target file already exists, the user should edit the file by hand on this `config/*` branch — `foundry_config_create_flow` does not support updates.
+### 6. Final summary
 
-Show the user the resulting commit hash from the response.
+Report the flow, starting cycles, artefact type, laws, validators, appraisers, and files created. Tell the user they can now ask the Foundry agent to run the flow.
 
-## What you do NOT do
+## Safety Rules
 
-- You do not create foundry cycles — that is a separate skill
-- You do not skip dependency validation
+- Do not create overlapping artefact file patterns.
+- Do not skip dependency validation.
+- Do not expose internal tool-call syntax to the user.
+- Do not continue when a branch or worktree state could overwrite user changes.

package/dist/skills/add-law/SKILL.md

@@ -8,34 +8,29 @@ description: Creates a new law, checking for conflicts with existing laws.
 
 You help the user create a new law. You ensure it's well-scoped, doesn't conflict with existing laws, and ends up in the right file.
 
-## Prerequisites
+## Foundry Agent Preflight
 
-Before running this skill, verify all three of the following:
+If you are clearly operating as the Foundry agent, continue.
 
-1. The `foundry/` directory exists in the project root. If it does not
-   exist, stop and tell the user:
+If you are not clearly operating as the Foundry agent, pause and tell the user:
 
-   > Foundry is not initialized in this project. Run the
-   > `init-foundry` skill first to create the foundry/ directory
-   > structure.
+> This work is best handled by the Foundry agent. Restart OpenCode if you have just initialised Foundry, switch to the **Foundry** agent, and continue this request there.
 
-2. The current git branch is a `config/*` branch. Run
-   `git rev-parse --abbrev-ref HEAD` and confirm it matches
-   `config/<description>`.
+This is an advisory guard. Continue only when the active instructions make it clear you are the Foundry agent or the user explicitly asks to proceed here.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
+## Config Branch Handling
 
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
+Before writing Foundry configuration:
 
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+- Confirm `foundry/` exists. If it is missing, initialise Foundry first when that serves the user's goal.
+- Check the current branch.
+- On `main` or another clean non-work branch, create a `config/<short-description>` branch internally.
+- On `config/*`, continue on the current branch.
+- On `work/*`, stop and explain that active flow work must be finished before configuration changes.
+- On `dry-run/*/*`, stop and explain that the dry run must be finished before configuration changes.
+- If unrelated uncommitted changes could be affected by branching or writing files, ask before proceeding.
+
+Do not tell the user to call branch tools directly.
 
 ## Protocol
 
@@ -49,7 +44,7 @@ If the user doesn't specify, ask:
 
 > Should this law apply globally to all artefact types, or to a specific type?
 
-If they name a type, verify it exists in `foundry/artefacts/`. If it doesn't, tell them and ask if they want to create the artefact type first.
+If the user names a type-specific law for an artefact type that does not exist, create the artefact type first when that supports the user's stated goal. Use the `add-artefact-type` workflow internally, and ask for the file pattern only when it cannot be inferred safely.
 
 ### 2. Draft the law
 
@@ -154,7 +149,7 @@ Show the user the resulting commit hash from the response.
 
 ### 7. Verify uniqueness
 
-After the file is created, confirm the law id is unique across all law files. If a collision exists, ask the user to rename and edit by hand on this branch.
+After the file is created, confirm the law id is unique across all law files. If a collision exists, read the colliding law, present the conflict to the user, propose a rename or merge, ask one focused question about the user's preference, then write and commit the resolution.
 
 ### 7a. Validator contract
 
@@ -299,4 +294,4 @@ Validate the result. If the tool returns `{ ok: true }`, show the user the commi
 
 - You do not skip the conflict check
 - You do not silently overwrite existing laws
-- You do not create artefact types — that is a separate skill
+- You do not create artefact types unless the user's stated goal clearly requires it; ask one focused question when multiple designs are plausible

package/dist/skills/add-memory-edge-type/SKILL.md

@@ -21,23 +21,17 @@ Before running this skill, verify all of the following:
    `git rev-parse --abbrev-ref HEAD` and confirm it matches
    `config/<description>`.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
-
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
-
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
-
-4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
-   if not). Entity types referenced in `sources` and `targets` must
-   already exist (or be added first).
+3. If the branch does not start with `config/`, move to a suitable
+   `config/*` branch internally when the current branch is safe. If
+   the current branch is `work/*` or `dry-run/*/*`, stop and explain
+   the active work must be finished first. When unrelated uncommitted
+   changes could be affected by branching or writing files, ask before
+   proceeding.
+
+4. Memory is initialised (`foundry/memory/` exists; initialise memory
+   internally first if not). Entity types referenced in `sources` and
+   `targets` must already exist (or be created or composed internally
+   when they are part of the user's stated goal).
 
 ## Steps
 

package/dist/skills/add-memory-entity-type/SKILL.md

@@ -24,22 +24,15 @@ Before running this skill, verify all of the following:
    `git rev-parse --abbrev-ref HEAD` and confirm it matches
    `config/<description>`.
 
-3. If the branch does not start with `config/`, instruct the user to
-   create one before continuing:
+3. If the branch does not start with `config/`, move to a suitable
+   `config/*` branch internally when the current branch is safe. If
+   the current branch is `work/*` or `dry-run/*/*`, stop and explain
+   the active work must be finished first. When unrelated uncommitted
+   changes could be affected by branching or writing files, ask before
+   proceeding.
 
-   > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
-   >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
-
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
-
-4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
-   if not).
+4. Memory is initialised (`foundry/memory/` exists; initialise memory
+   internally first if not).
 
 ## Steps
 
@@ -71,4 +64,4 @@ Before running this skill, verify all of the following:
    git commit -m "feat(memory): add entity type <name>"
    ```
 
-6. **Guidance to the user**: suggest they also add relevant edge types using `add-memory-edge-type`.
+6. **Dependency composition**: if related edge types would serve the user's stated goal, compose them internally with one focused question for ambiguity.

package/dist/skills/change-embedding-model/SKILL.md

@@ -28,15 +28,13 @@ Before running this skill, verify all of the following:
    create one before continuing:
 
    > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
+   > If configuration changes are needed, move to a suitable `config/*`
+   > branch internally when the current branch is safe. If the current
+   > branch is `work/*` or `dry-run/*/*`, stop and explain the active
+   > work must be finished first.
    >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
-
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+   > After the prerequisite is handled, continue the user's original
+   > request from the current context.
 
 4. Memory is initialised and enabled. The new provider is reachable
    from this machine. Allow enough time and bandwidth to re-embed

package/dist/skills/drop-memory-edge-type/SKILL.md

@@ -27,15 +27,13 @@ Before running this skill, verify all of the following:
    create one before continuing:
 
    > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
+   > If configuration changes are needed, move to a suitable `config/*`
+   > branch internally when the current branch is safe. If the current
+   > branch is `work/*` or `dry-run/*/*`, stop and explain the active
+   > work must be finished first.
    >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
-
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+   > After the prerequisite is handled, continue the user's original
+   > request from the current context.
 
 4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
    if not).

package/dist/skills/drop-memory-entity-type/SKILL.md

@@ -28,15 +28,13 @@ Before running this skill, verify all of the following:
    create one before continuing:
 
    > Foundry configuration changes must be made on a config/* branch.
-   > From a clean main branch, call:
+   > If configuration changes are needed, move to a suitable `config/*`
+   > branch internally when the current branch is safe. If the current
+   > branch is `work/*` or `dry-run/*/*`, stop and explain the active
+   > work must be finished first.
    >
-   > `foundry_git_branch({ kind: "config", description: "<short-name>" })`
-   >
-   > Then re-run this skill.
-
-   If the user is on a `dry-run/*/*` branch, they must finish
-   that dry-run first (`foundry_git_finish({ message, confirm: true })`)
-   before re-running this skill on the parent `config/*`.
+   > After the prerequisite is handled, continue the user's original
+   > request from the current context.
 
 4. Memory is initialised (`foundry/memory/` exists; run `init-memory`
    if not).

package/dist/skills/dry-run/SKILL.md

@@ -22,24 +22,18 @@ files or memory rows behind on `config/<x>`.
 2. Working tree is clean.
 3. The flow id and a one-line description of the goal are known.
 
-If on `main`, edit on a `config/<x>` branch first:
-`foundry_git_branch({ kind: "config", description: "<short-name>" })`.
+If on `main`, edit on a `config/<x>` branch first. If configuration
+changes are needed, move to a suitable `config/*` branch internally
+when the current branch is safe. If the current branch is `work/*` or
+`dry-run/*/*`, stop and explain the active work must be finished first.
 
 ## Protocol
 
 ### 1. Branch into dry-run mode
 
-```text
-foundry_git_branch({
-  kind: "dry-run",
-  flowId: "<flow-id>",
-  description: "<dry-run-purpose-slug>"
-})
-```
-
-This creates `dry-run/<x>/<flow>-<purpose>` and truncates the trace
-file. From here every `foundry_*` tool call is logged to
-`.foundry/trace/<branch-slug>.jsonl`.
+The assistant creates a `dry-run/<x>/<flow>-<purpose>` branch and
+truncates the trace file. From here every internal tool call is logged
+to `.foundry/trace/<branch-slug>.jsonl`.
 
 ### 2. Run the flow
 
@@ -57,12 +51,8 @@ they appear in the trace.
 
 ### 4. Finish: snapshot + discard
 
-```text
-foundry_git_finish({
-  message: "<one-paragraph findings>",
-  confirm: true
-})
-```
+Finish the dry-run with a one-paragraph findings message and explicit
+confirmation.
 
 The tool:
 
@@ -92,15 +82,8 @@ dry-run mode for another run. Snapshots accumulate; prune them with
 
 ### 6. Finish the config
 
-When ready, finish `config/<x>` to `main`:
-
-```text
-foundry_git_finish({
-  message: "<config description>",
-  baseBranch: "main",
-  confirm: true
-})
-```
+When ready, finish `config/<x>` to `main` with a config description and
+explicit confirmation.
 
 Snapshots are gitignored and stay in the local working tree; they do
 not merge with the config.

package/dist/skills/flow/SKILL.md

@@ -20,7 +20,7 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 ## Starting a flow
 
 1. Call `foundry_config_flow` with the flow ID — get the flow definition
-2. Call `foundry_git_branch` with `kind: "work"`, the flow ID, and a short description — create the work branch (e.g. `foundry_git_branch({ kind: "work", flowId, description })`)
+2. Create a work branch for the flow using the flow ID and a short description
 3. Determine the starting cycle:
    - Any cycle listed in the flow can be the starting cycle. The flow's `starting-cycles` list is a hint for when the user's request is ambiguous.
    - Map the user's goal to a cycle by matching the requested output (e.g. "write a short story from the tennis haiku" → `create-short-story`; "write a haiku" → `create-haiku`).

package/dist/skills/init-foundry/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: init-foundry
 type: atomic
-description: Initialize a Foundry project by creating the foundry/ directory structure
+description: Initialise a Foundry project by creating the foundry/ directory structure
 ---
 
-# Initialize Foundry
+# Initialise Foundry
 
 Set up the `foundry/` directory structure in the current project.
 
@@ -50,42 +50,47 @@ Set up the `foundry/` directory structure in the current project.
    The plugin will idempotently append `.foundry/` itself on first
    boot, so you do not need to add that line.
 
-4. **Generate foundry agent files**
+4. **Generate model-routing agent files**
 
-   Run the `refresh-agents` skill to generate `.opencode/agents/foundry-*.md` files for multi-model routing.
+   Call `foundry_refresh_agents()` to generate model-routing `.opencode/agents/foundry-*.md` files.
 
-5. **Commit the structure**
+5. **Install the Foundry guide agent**
+
+   Create `.opencode/agents/foundry.md` from the packaged Foundry guide
+   agent template. Copy whichever template path exists: prefer
+   `dist/agents/foundry.md` when running from the built package, then
+   fall back to `src/agents/foundry.md` when running from a source
+   checkout. This user-facing agent is installed during `init-foundry`;
+   `foundry_refresh_agents()` manages only generated `foundry-*` stage
+   agents.
+
+6. **Commit the structure**
 
    ```bash
-   git add foundry/ .gitignore .opencode/agents/foundry-*.md
-   git commit -m "feat: initialize Foundry project structure"
+   git add foundry/ .gitignore .opencode/agents/foundry.md .opencode/agents/foundry-*.md
+   git commit -m "feat: initialise Foundry project structure"
    ```
 
-6. **Guide next steps**
+7. **Guide next steps**
 
    Tell the user:
 
-   > Foundry is initialized. **Restart OpenCode** for the new foundry agents to take effect.
+   > Foundry is initialised. **Restart OpenCode** so the new Foundry agents register.
    >
-   > The first time the plugin boots in this project, it will create the
-   > `.foundry/` runtime directory (which holds the per-worktree HMAC key) and
-   > idempotently append `.foundry/` to your `.gitignore` so the secret never
-   > gets committed. The `.snapshots/` line was added by this skill to keep
-   > dry-run snapshots out of git.
+   > After the restart, switch to the **Foundry** agent. The Foundry agent is the user-facing guide for setting up artefact types, laws, validators, appraisers, cycles, and flows.
    >
-   > Here's how to set up your first pipeline:
+   > Then ask the Foundry agent for the outcome you want, for example:
    >
-   > 1. **Define an artefact type** — use the `add-artefact-type` skill
-   > 2. **Add laws** — use the `add-law` skill to define quality criteria
-   > 3. **Create appraiser personalities** — use the `add-appraiser` skill
-   > 4. **Define a cycle** — use the `add-cycle` skill
-   > 5. **Create a flow** — use the `add-flow` skill
+   > `set up a flow that writes haikus`
    >
-   > Then run your flow with the `flow` skill.
+   > The first time the plugin boots in this project, it will create the
+   > `.foundry/` runtime directory and idempotently append `.foundry/` to
+   > `.gitignore` so the per-worktree HMAC key stays out of git. The
+   > `.snapshots/` line was added by this skill to keep dry-run snapshots
+   > out of git.
    >
    > **Optional: Flow Memory**
    >
-   > If your flows need persistent knowledge (entities, relationships, semantic
-   > search), use the `init-memory` skill to scaffold flow memory. Memory is
-   > useful for projects that need to track code structure, dependencies, or
-   > domain knowledge across flow runs.
+   > If your flows need persistent knowledge, ask the Foundry agent to add
+   > flow memory. Memory is useful for projects that need to track code
+   > structure, dependencies, or domain knowledge across flow runs.