@really-knows-ai/foundry 3.0.2 → 3.2.0

package/dist/README.md

@@ -105,7 +105,7 @@ Add the plugin to `opencode.json`:
 
 Restart OpenCode so the plugin registers its tools and skills. You will see new
 tools and skills become available in OpenCode's command palette once the restart
-completes. The `init-foundry` skill and flow-management tools are now ready to use.
+completes. Flow-management tools are now ready to use.
 
 ---
 
@@ -132,26 +132,23 @@ Add the plugin to `opencode.json` (see Install section above):
 
 Then restart OpenCode so the plugin registers its tools and skills. You will see new
 tools and skills become available in OpenCode's command palette once the restart
-completes. The `init-foundry` skill and flow-management tools are now ready to use.
+completes. Flow-management tools are now ready to use.
 
 ### Phase 2 — Initialise
 
-Open OpenCode in your project repo and say:
+Restart OpenCode after adding the plugin. On boot, the plugin's config hook runs
+a decision tree: if `foundry/` is missing or its VERSION does not match the
+installed plugin version, it bootstraps the directory structure, generates
+`foundry-<model>` stage agent files, installs the user-facing `Foundry` guide
+agent, and tells you to restart again.
 
-```
-> 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.
-
-Restart OpenCode so the new `foundry-<model>` agents register — multi-model dispatch cannot route to agents it cannot discover.
+Restart OpenCode a second time 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/README.md

@@ -10,7 +10,7 @@ Getting oriented with Foundry means understanding both the concepts it uses and
 
 **Reading order:** Work through them in order; [getting-started.md](getting-started.md) builds hands-on confidence, and [concepts.md](concepts.md) provides reference depth. Most implementers spend 1–2 hours on getting-started before moving to Reference materials.
 
-- **getting-started.md** — Complete end-to-end installation, bootstrap (`init-foundry`), and first flow walkthrough. Read this immediately after installing the plugin and before authoring any of your own configuration. 
+- **getting-started.md** — Complete end-to-end installation, auto-bootstrapping, and first flow walkthrough. Read this immediately after installing the plugin and before authoring any of your own configuration. 
 
   It establishes the operating model, directory structure, and practical confidence in one pass. Includes hands-on guidance on authoring the five foundational concepts (artefact types, laws, appraisers, cycles, flows) with worked examples you can run against real code. Also covers the optional flow-memory path: initialise memory, declare vocabulary, add extractors, and opt a cycle into assay for codebase-aware flows.
 

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 the plugin's `config` hook 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
 
@@ -328,7 +330,7 @@ Implementation: `src/plugin/tools/helpers.js` (`buildCyclePromptExtras`) and `sr
 │   │   ├── quench/
 │   │   ├── appraise/
 │   │   ├── human-appraise/
-│   │   ├── init-foundry/       # authoring
+│   │   ├── add-artefact-type/  # authoring
 │   │   ├── add-artefact-type/
 │   │   ├── add-law/
 │   │   ├── add-appraiser/
@@ -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/
@@ -389,7 +391,7 @@ Implementation: `src/plugin/tools/helpers.js` (`buildCyclePromptExtras`) and `sr
 └── README.md
 ```
 
-### User project (after `init-foundry`)
+### User project (after auto-bootstrapping)
 
 ```
 your-project/
@@ -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

@@ -252,7 +252,7 @@ plain-files directory at `.snapshots/<runId>/` on the parent
 - `trace.jsonl` — the full tool-call trace.
 
 `runId` is `<branch-slug>-<ulid>`. Snapshots are gitignored
-(`.snapshots/` is added to `.gitignore` by `init-foundry`) and
+(`.snapshots/` is added to `.gitignore` by the plugin's auto-bootstrapping) and
 accumulate locally; `foundry_snapshot_list` enumerates them,
 `foundry_snapshot_show` returns a structured summary,
 `foundry_snapshot_delete` removes one, and
@@ -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,14 @@ 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:
+Restart OpenCode after adding the plugin. On boot, the plugin's config hook checks project state: if `foundry/` is missing or its VERSION does not match the installed plugin version, it bootstraps the directory structure, generates model-routing `foundry-*` stage agents, installs the user-facing `Foundry` guide agent, and prompts a second restart.
 
-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.
+Restart OpenCode again so the new agents register. 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 +41,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>" })
-```
+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.
 
-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.
+### Author through the Foundry agent
 
-### 1. Define an artefact type
+Ask the Foundry agent to author or modify any part of the configuration. For example:
 
-Run `add-artefact-type`. It walks you through:
+> Add a `haiku` artefact type with a `poetic-form` appraiser.
 
-- `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.
+> Add a law that requires at least one sensory metaphor in every haiku.
 
-Produces `foundry/artefacts/<id>/definition.md` (+ optional `laws.md`).
+> Create a cycle that produces haikus from petitions.
 
-### 2. Write laws
+> Set up a `make-haiku` flow starting from `haiku-ideation`.
 
-Laws are subjective pass/fail criteria evaluated by appraisers. Two scopes:
+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.
 
-- **Global** — `foundry/laws/*.md`. All files are concatenated and apply to every artefact.
-- **Type-specific** — `foundry/artefacts/<type>/laws.md`.
+### Configuration reference
 
-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.
+These are the five pieces of a Foundry configuration, in dependency order:
 
-### 3. Create appraisers
+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`.
 
-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`).
+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.
 
-### 4. Define a cycle
+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`).
 
-Run `add-cycle`. A cycle produces one artefact type and declares:
+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:
 
-- `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.
-
-Example:
-
-```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
----
-
-# Haiku Creation
-
-Writes a haiku satisfying the petition produced by haiku-ideation.
-```
-
-The skill validates that every input type can be produced by some cycle in the flow and that targets are reachable.
-
-### 5. Define a flow
-
-Run `add-flow`. A flow groups cycles and declares starting points:
-
-```markdown
----
-id: make-haiku
-name: Make a Haiku
-starting-cycles:
-  - haiku-ideation
----
-
-# Make a Haiku
-
-End-to-end flow: petition → haiku, with a human quality gate.
-
-## Cycles
-
-- haiku-ideation
-- haiku-creation
-```
-
-Routing between cycles is owned by individual cycles via their `targets`, not by the flow.
-
-### 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 +120,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 +181,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 +196,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/lib/foundational-guards.js

@@ -8,6 +8,6 @@ export function requireFoundryRoot(io) {
   if (io.exists('foundry')) return { ok: true };
   return {
     ok: false,
-    error: 'foundry/ directory not found at worktree root. Run the init-foundry skill to scaffold it.',
+    error: 'foundry/ directory not found at worktree root. Restart OpenCode to initialise Foundry.',
   };
 }

package/dist/scripts/lib/memory/admin/init.js

@@ -87,7 +87,7 @@ function buildSchema(embeddingsEnabled, model, dimensions) {
 
 async function validatePrerequisites(io, p) {
   if (!(await io.exists('foundry'))) {
-    throw new Error('foundry/ does not exist; run init-foundry first');
+    throw new Error('foundry/ does not exist. Restart OpenCode to initialise Foundry.');
   }
   if (await io.exists(p.root)) {
     throw new Error('foundry/memory/ already exists');

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;

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

@@ -8,34 +8,29 @@ description: Creates a new appraiser personality, checking for semantic overlap
 
 You help the user create a new appraiser personality. You ensure it's genuinely distinct from existing appraisers and scaffold the definition 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
 
@@ -118,26 +113,16 @@ Call `foundry_config_create_appraiser({ name: "<id>", body: "<full markdown>" })
 - writes `foundry/appraisers/<id>.md`;
 - produces one git commit on the current `config/*` branch.
 
-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_appraiser` does not support updates.
+If the tool returns `{ ok: false, errors }` because the target file already exists, read the existing file, incorporate the user's requested changes into the current body, propose the merged result for review, then write and commit the updated file.
 
 Show the user the resulting commit hash from the response.
 
 ### 8. Mention artefact type configuration
 
-After creating the appraiser, remind the user:
-
-> Appraiser `<id>` is now available. To use it for a specific artefact type, add it to the `appraisers.allowed` list in that type's `definition.md` frontmatter:
->
-> ```yaml
-> appraisers:
->   count: 3
->   allowed: [<id>, ...]
-> ```
->
-> If no `allowed` list is specified, all available appraisers (including this new one) are eligible.
+After creating the appraiser, offer to connect it to relevant artefact-type configuration when doing so supports the user's stated goal. If the user confirms, update the artefact type's `appraisers.allowed` list on the same config branch.
 
 ## What you do NOT do
 
 - You do not skip the semantic overlap check
-- You do not modify artefact type definitions — that is the user's choice
+- You do not modify artefact type definitions without the user's confirmation
 - You do not create appraisers with duplicate ids