@really-knows-ai/foundry 3.5.7 → 3.5.9

package/dist/docs/getting-started.md

@@ -26,7 +26,7 @@ directory structure, generates stage agents, and installs the Foundry guide
 agent automatically.
 
 After restart, type **hello foundry**. The assistant will tell you whether a
-further restart is needed and when to switch to the Foundry agent.
+further restart is needed and when to switch to the **Foundry** agent.
 
 Optionally, if you want the package available to your project's local node_modules (for editor tooling or scripts), run:
 
@@ -44,7 +44,7 @@ assistant will read the Foundry bootstrap context and respond with guidance:
 - If Foundry is already set up: it will tell you to switch to the Foundry agent
   directly.
 
-switch to the **Foundry** agent before authoring flows. The Foundry agent
+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.
 
@@ -59,6 +59,12 @@ Foundry's configuration is five things: artefact types, laws, appraisers, cycles
 
 ### Author through the Foundry agent
 
+The Foundry agent walks through a four-phase wizard protocol — **Understand,
+Plan, Confirm, Build** — asking one question at a time. Configuration files are
+created only after you confirm the plan. This wizard eliminates hand-authoring
+of normal setup by using the structured config creation tools on a `config/*`
+branch.
+
 Ask the Foundry agent to author or modify any part of the configuration. For example:
 
 > Add a `haiku` artefact type with a `poetic-form` appraiser.
@@ -77,11 +83,27 @@ These are the five pieces of a Foundry configuration, in dependency order:
 
 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`.
 
-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.
+2. **Laws** — rules or 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.
 
 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`).
 
-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:
+4. **Cycles** — produce one artefact type from a definition with these fields:
+
+   | Field | Purpose |
+   |-------|---------|
+   | `id` | Unique identifier |
+   | `name` | Human-readable label |
+   | `output-type` | The artefact type this cycle produces |
+   | `inputs` | Contract over upstream types (e.g. `any-of`, `all-of`) |
+   | `targets` | Reachable downstream cycles for flow routing |
+   | `always-human-appraise` | Bypass LLM appraisers on every iteration |
+   | `deadlock-human-appraise` | Escalate to human appraiser at iteration limit |
+   | `max-iterations` | Maximum forge iterations before deadlock |
+   | `assay` | Optional extractor config for pre-forge measurement |
+   | `memory` | Optional entity read/write permissions |
+   | `models` | Per-stage model overrides (e.g. `appraise`, `forge`) |
+
+   Example:
 
    ```markdown
    ---
@@ -93,9 +115,9 @@ These are the five pieces of a Foundry configuration, in dependency order:
      artefacts:
        - petition
    targets: []
-   human-appraise: false
-   deadlock-appraise: true
-   deadlock-iterations: 5
+   always-human-appraise: false
+   deadlock-human-appraise: true
+   max-iterations: 5
    models:
      appraise: openai/gpt-5
    ---
@@ -114,15 +136,15 @@ Users who prefer to write configuration files by hand open a config branch first
 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. 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:
+2. Creates a work branch and scaffolds `WORK.md` with frontmatter (`flow`, `cycle`) and the `# Goal` section. No artefact table is stored in the workfile; artefacts are discovered from branch diffs.
+3. Hands off to `orchestrate`, which drives the cycle. Orchestrate setup fills the remaining frontmatter (`stages`, `max-iterations`, model overrides, `assay` config) from the cycle definition, then runs the loop:
    - **forge** writes the artefact.
-   - **quench** runs CLI validators (if configured).
-   - **appraise** dispatches parallel appraiser sub-agents and consolidates their `law:<id>` feedback.
-   - **human-appraise** (if configured, or on deadlock) asks you for input.
+   - **quench** runs deterministic validation inside the orchestrator, executing any validators attached to laws.
+   - **appraise** fans out parallel appraiser sub-agents via `dispatch_multi` and internally consolidates their `law:<id>` feedback.
+   - **human-appraise** (if configured, or at the iteration limit) asks you for input.
    - If any unresolved feedback remains, another forge iteration begins.
 4. When the cycle completes, the flow skill checks the cycle's `targets`. If a target's input contract is satisfied, it asks whether to proceed.
-5. When all desired cycles are done, the flow skill summarises the output and asks how to finish — squash-merge, PR, or leave the branch.
+5. When all desired cycles are complete, the flow skill asks you to attest the work via `foundry_attest`, which verifies cycle completion, writes and commits `ATTEST.md`. After attestation succeeds, `foundry_git_finish` squash-merges to the base branch with a signed attestation block, preserves the work branch as an archive, and creates the final signed commit. See [`docs/tools.md`](./tools.md#foundry_attest) for the attestation contract.
 
 Every stage ends with a micro-commit. Violations of the write invariant (writing to disallowed files) hard-stop the cycle.
 
@@ -154,7 +176,7 @@ never committed by foundry. See the `dry-run` skill for the full loop.
 
 While a flow is running, the state of the world is in four places:
 
-- `WORK.md` — current cycle, goal, and artefact table.
+- `WORK.md` — current cycle, goal, and frontmatter state. Artefacts are discovered from branch diffs against the current cycle output type; see `foundry_artefacts_list`.
 - `WORK.feedback.yaml` — feedback items and their lifecycle history.
 - `WORK.history.yaml` — append-only stage execution log.
 - `git log` — one commit per stage.
@@ -185,7 +207,7 @@ Use `foundry_stage_retry()` when the underlying problem is fixed and you want to
 
 ## Cleaning up
 
-When a flow completes, `foundry_git_finish` handles integration with audit guarantees. On `work/*` branches, it commits `WORK.*` cleanup, preserves the branch as `archive/work/<flow>-<desc>-<hash>` for immutable forensic history, squash-merges to the base branch, and creates a signed commit whose message embeds the canonical Foundry attestation block. See [`docs/tools.md`](./tools.md#foundry_git_finish) for the full contract.
+When a flow completes, the flow skill asks you to attest the work via `foundry_attest`, which verifies cycle completion, writes `ATTEST.md` at `HEAD`, and commits it. After attestation succeeds, `foundry_git_finish` handles integration with audit guarantees: it commits `WORK.*` cleanup, preserves the branch as `archive/work/<flow>-<desc>-<hash>` for immutable forensic history, squash-merges to the base branch, and creates a signed commit whose message embeds the canonical Foundry attestation block. See [`docs/tools.md`](./tools.md#foundry_attest) and [`docs/tools.md`](./tools.md#foundry_git_finish) for the full contracts.
 
 ---
 

package/dist/docs/memory-maintenance.md

@@ -4,7 +4,7 @@ Contributor-facing notes. This file records the derived details from the
 Cozo docs / plugin surface that cost us time to establish. Add entries when a
 fix required non-trivial spelunking, so the next maintainer can reuse the result.
 
-## Backend status (as of 3.0.0)
+## Backend status
 
 The memory subsystem persists to `cozo-node@0.7.6`, which wraps the Rust
 `cozodb` engine. Both are effectively unmaintained:
@@ -23,7 +23,7 @@ property-graph with HNSW, Cypher dialect), **SurrealDB embedded**,
 **DuckDB + vss + PGQ**, and **SQLite + `sqlite-vec`** with hand-rolled
 graph traversal. The migration is structured so the public memory tool
 surface (`foundry_memory_*`) and the on-disk durable artefacts
-(`foundry-memory/entities/*.md`, `foundry-memory/edges/*.md`,
+(`foundry/memory/entities/*.md`, `foundry/memory/edges/*.md`,
 `foundry-memory/relations/*.ndjson`) remain stable; only the live
 in-process store changes.
 
@@ -126,7 +126,7 @@ Extractors are defined at `foundry/memory/extractors/<name>.md` with a `command`
 
 ## Memory layout: two trees
 
-Since Phase 2 (3.0.0), memory is split across two top-level trees:
+Memory is split across two top-level trees:
 
 - `foundry/memory/` — *config*. Holds `config.md`, `schema.json`,
   `entities/<name>.md`, `edges/<name>.md`, `extractors/<name>.md`,

package/dist/docs/tools.md

@@ -1,8 +1,8 @@
 # Foundry Public Tool Reference
 
-Generated from the v3.0.x public plugin API. The authoritative tool set is
+Generated from the current public plugin API for Foundry 3.5.8. The authoritative tool set is
 enforced by `tests/plugin/tool-registration.test.js` — if that snapshot
-drifts, this doc must be updated. Total: **66 tools**.
+drifts, this doc must be updated. Total: **65 tools**.
 
 All tools accept arguments as a JSON object and return JSON-stringified
 results. Errors are returned as a stringified `{error: "..."}` object (not
@@ -39,13 +39,15 @@ state machine, see [`docs/concepts.md`](./concepts.md) and
 
   | Namespace | Applies to | Notes |
   |-----------|------------|-------|
-  | `config/<description>` | `foundry_config_create_*` (5), `foundry_memory_create_entity_type`, `foundry_memory_create_edge_type`, `foundry_memory_rename_*`, `foundry_memory_drop_*`, `foundry_memory_reset`, `foundry_memory_init`, `foundry_memory_change_embedding_model`, `foundry_extractor_create` | Config and schema mutation only. |
+  | `config/<description>` | `foundry_config_create_artefact_type`, `foundry_config_create_appraiser`, `foundry_config_create_flow`, `foundry_config_create_cycle`, `foundry_config_add_law`, `foundry_config_edit_law`, `foundry_memory_create_entity_type`, `foundry_memory_create_edge_type`, `foundry_memory_rename_*`, `foundry_memory_drop_*`, `foundry_memory_reset`, `foundry_memory_init`, `foundry_memory_change_embedding_model`, `foundry_extractor_create` | Config and schema mutation only. |
   | `work/<flow>-<desc>` or `dry-run/<x>/<y>` | `foundry_orchestrate`, `foundry_stage_begin`, `foundry_stage_end`, `foundry_stage_retry`, `foundry_workfile_*`, `foundry_artefacts_*`, `foundry_feedback_*`, `foundry_assay_run`, `foundry_validate_run`, `foundry_memory_put`, `foundry_memory_relate`, `foundry_memory_unrelate` | Flow-data mutation only. |
   | Any branch | `foundry_workfile_get`, `foundry_artefacts_list`, `foundry_feedback_list`, `foundry_history_list`, `foundry_config_*` read tools, `foundry_config_validate_*`, `foundry_appraisers_select`, `foundry_memory_get`, `foundry_memory_list`, `foundry_memory_neighbours`, `foundry_memory_query`, `foundry_memory_search`, `foundry_memory_dump`, `foundry_memory_validate`, `foundry_snapshot_*` | No branch guard and no failed-flow guard. |
   | Self-classifying | `foundry_git_branch`, `foundry_git_finish` | Each tool checks its own branch rules. Leaving the failed branch is the recovery path. |
 
   Off-namespace calls return a structured refusal envelope naming the required namespace and the current branch.
 
+> **Memory admin callability:** Schema-mutation and destructive memory admin tools (`foundry_memory_init`, `foundry_memory_create_entity_type`, `foundry_memory_create_edge_type`, `foundry_memory_rename_entity_type`, `foundry_memory_rename_edge_type`, `foundry_memory_drop_entity_type`, `foundry_memory_drop_edge_type`, `foundry_memory_reset`, `foundry_memory_change_embedding_model`) require `config/*` branches and non-failed flow. Read-only diagnostics (`foundry_memory_get`, `foundry_memory_list`, `foundry_memory_neighbours`, `foundry_memory_query`, `foundry_memory_search`, `foundry_memory_dump`, `foundry_memory_validate`) are broadly callable. `foundry_memory_vacuum` uses only the failed-flow guard and is not config-branch guarded.
+
 ## Tool index
 
 **Lifecycle**
@@ -238,12 +240,17 @@ frontmatter.
 **Args:**
 - `lastResult` (object, optional): `{ ok: boolean, error?: string }` — output of the
   prior action.
+- `lastResults` (array, optional): Output of prior `dispatch_multi` actions.
 - `cycleDef` (string, optional): Test-mode override path to a cycle file.
+- `baseBranch` (string, optional, default `main`): Base branch for diff and merge.
+- `defaultModel` (string, optional): Model override for all dispatch prompts.
 
 **Returns:** one of:
 - `{ action: "dispatch", stage, cycle, prompt, token, ... }` — caller
   should dispatch a subagent. The `prompt` field is augmented with cycle
   memory context (entity types, edge types, extractor briefs) when configured.
+- `{ action: "dispatch_multi", tasks: [...], ... }` — caller should
+  dispatch multiple subagents in parallel (used for parallel appraiser dispatch).
 - `{ action: "human_appraise", ... }` — surface to the user.
 - `{ action: "done", ... }` — cycle complete.
 - `{ action: "blocked", ... }` — cycle stalled.
@@ -261,6 +268,8 @@ failed flow.
 **Side effects:** mints/persists dispatch tokens (in-memory pending
 store); commits via `commitWithPolicy` when finalising stages (refuses
 on unexpected files); appends WORK.md artefact rows when finalising.
+Runs quench synchronously when laws contain validators; runs appraise
+via `gatherAppraiseContext` + `consolidateAppraise`.
 
 ### `foundry_workfile_create`
 
@@ -325,7 +334,7 @@ flow** (escape hatch).
 
 ### `foundry_artefacts_list`
 
-> List artefact changes on the current work branch for the current cycle.
+> List artefact changes on the current work branch for the current cycle. Artefacts are discovered from branch diff status (git diff against base branch), filtered by the current cycle's output-type file patterns.
 
 **Args:**
 - none.
@@ -359,7 +368,7 @@ existing equivalent item was returned). `{ error: ... }` otherwise.
 **Stage requirements:** requires active stage. Tag is gated by stage
 base:
 - `forge` → forbidden (forge stages do not add feedback).
-- `quench` → tag must be exactly `validation`.
+- `quench` → tag must start with `law:`.
 - `appraise` → tag must start with `law:`.
 - `human-appraise` → tag must be exactly `human`.
 - `assay` → forbidden. Extractor failures mark the workfile failed and end
@@ -542,7 +551,8 @@ that id is registered.
 `file-patterns`.
 
 **Stage requirements:** none (callable outside any stage; intended to be
-invoked by quench, but not enforced). Refused on a failed flow.
+invoked by quench, but not enforced). Requires a `work/*` or `dry-run/*`
+branch (flow-data mutation namespace). Refused on a failed flow.
 
 **Side effects:** spawns subprocesses via `execSync` in the worktree —
 external commands may have arbitrary side effects, which is why the tool
@@ -654,11 +664,13 @@ can branch away to recover.
 | current branch       | mode      | what happens                                                                                                                              |
 | -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | `work/<x>`                 | work      | commits `WORK.*` cleanup on the work branch, preserves the branch as `archive/work/<x>-<hash>`, squash-merges to `baseBranch`, creates a signed commit whose message embeds the canonical Foundry attestation block. |
-| `config/<x>`               | config    | squash-merges to `baseBranch`, force-deletes the config branch. No WORK cleanup.                                                          |
+| `config/<x>`               | config    | squash-merges to `baseBranch`, force-deletes the config branch. No WORK cleanup. |
 | `dry-run/<x>/<y>`          | dry-run   | writes `.snapshots/<run-id>/{README.md, work/WORK*, diff.patch, trace.jsonl}` on the parent `config/<x>` working tree; force-deletes the dry-run branch. No merge, no commit. |
 | base branch (`main` by default) | noop | `{ ok: true, noop: true, ... }`.                                                                                                           |
 | anything else              | refused   | `{ ok: false, error: "... nothing to finish ..." }`.                                                                                      |
 
+**Work-branch precondition (work mode):** `ATTEST.md` must exist at HEAD, created by a prior `foundry_attest({ confirm: true })` call. Without it, the work mode refuses.
+
 **Returns:**
 - Plan (when `confirm` is not true):
   - Work mode: `{ ok: false, error: "... requires {confirm: true}...",
@@ -789,8 +801,7 @@ schema checks without writing. Laws use a different shape: `add_law`
 creates a new entry, `edit_law` updates an existing one, and
 `foundry_config_validate_law` covers schema validation for either.
 
-Common args across the `_create_*` tools: `name` (string), `body`
-(string, markdown). Common returns across the whole family:
+Common returns across the whole family:
 `{ ok: true, path, sha }` on success; `{ ok: false, errors: [...] }`
 on validation failure; `{ error, affected_files: [...] }` on
 commit-policy refusal (the worktree was dirty with files outside
@@ -805,9 +816,11 @@ to update an existing law in place.
 > `foundry/artefacts/<typeId>/`.
 
 **Args:**
-- `name` (string, required): typeId (kebab-case slug).
-- `body` (string, required): markdown body with frontmatter
-  (`file-patterns`, optional `description`, etc.).
+- `id` (string, required): Artefact type id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `filePatterns` (string[], required): Glob patterns for matching artefacts.
+- `description` (string, required): Prose description of the artefact type.
+- `appraisers` (object, optional): `{ allowed: string[], count: number }` — appraiser pool and selection count.
 
 **Returns:** `{ ok: true, path, sha }` on success;
 `{ ok: false, errors: [...] }` on schema failure;
@@ -832,49 +845,53 @@ current `config/*` branch.
 
 ### `foundry_config_add_law`
 
-> Add a new law markdown entry. Locator depends on `target.kind`.
+> Add a new law entry.
 
 **Args:**
-- `name` (string, required): law id (kebab-case slug). Used in the
-  commit message.
-- `body` (string, required): markdown body for the law, starting with
-  a `## <law-id>` heading.
-- `target` (object, required):
-  - `{ kind: "global", file: "<name>.md" }` — appends or writes
-    `foundry/laws/<file>`.
-  - `{ kind: "type-specific", typeId: "<id>" }` — appends or writes
-    `foundry/artefacts/<typeId>/laws.md`.
-
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
-
-**Failure modes:** as for `foundry_config_create_artefact_type`, plus
-`target` shape errors:
-- Missing or non-object `target` → `{ ok: false, errors: ["target
-  argument is required (object with kind + locator)"] }`.
-- Unknown `target.kind` → `{ ok: false, errors: ["unknown
-  target.kind: <kind>"] }`.
-- Missing `target.file` for `global` / missing `target.typeId` for
-  `type-specific` → `{ ok: false, errors: [...] }`.
-- Target file already exists →
-  `{ ok: false, errors: ["… already exists; use foundry_config_edit_law
-  to update an existing law in place"] }`.
+- `id` (string, required): Law id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `description` (string, required): Prose description of the law.
+- `passing` (string, required): Feedback text when the law passes.
+- `failing` (string, required): Feedback text when the law fails.
+- `target` (object, required): `{ kind: "global"|"type-specific", file?: string, typeId?: string }` — locator for the law target.
+- `validators` (array, optional): Array of `{ name: string, command: string }` objects defining validator commands.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on validation failure;
+`{ error, affected_files }` on commit-policy refusal.
+
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
+
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure → `{ ok: false, errors: [...] }`.
+- Target file already exists → `{ ok: false, errors: ["… already
+  exists; use foundry_config_edit_law to update an existing law in place"] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
+
+**Side effects:** writes the law file and commits it on the current
+`config/*` branch.
 
 ### `foundry_config_edit_law`
 
-> Replace the body of an existing law in place, preserving sibling
-> laws in the same file. Locates the law by id across both global laws
-> and per-type `laws.md` files.
+> Update an existing law's fields in place. Locates the law by id across
+> both global laws and per-type `laws.md` files.
 
 **Args:**
-- `id` (string, required): law id to edit.
-- `body` (string, required): full new markdown body for the law,
-  starting with a `## <law-id>` heading.
+- `id` (string, required): Law id to edit.
+- `name` (string, optional): New human-readable name.
+- `description` (string, optional): New prose description.
+- `passing` (string, optional): New passing feedback text.
+- `failing` (string, optional): New failing feedback text.
+- `validators` (array, optional): New validator list replacing the current one.
 
 **Returns:** `{ ok: true, id, path, source }` on success, where
 `source` is `"global"` or `"type:<typeId>"`. Returns
 `{ ok: false, errors: ["Law \"<id>\" not found"] }` when no law of
-that id exists, or `{ ok: false, errors: [...] }` when the new body
+that id exists, or `{ ok: false, errors: [...] }` when the update
 fails law schema validation.
 
 **Stage requirements:** none (no active stage); requires a `config/*`
@@ -888,48 +905,92 @@ the current `config/*` branch with message `config: edit law <id>`.
 > Create a new appraiser personality at `foundry/appraisers/<id>.md`.
 
 **Args:**
-- `name` (string, required): appraiser id.
-- `body` (string, required): markdown body with frontmatter
-  (`description`, optional `model`, …).
+- `id` (string, required): Appraiser id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `description` (string, required): Prose description of the appraiser's role.
+- `model` (string, optional): Model override for this appraiser.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on schema failure;
+`{ error, affected_files }` on commit-policy refusal.
 
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
+
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure (missing description, semantic overlap
+  with an existing appraiser, …) → `{ ok: false, errors: [...] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
 
-**Failure modes:** as for `foundry_config_create_artefact_type`,
-applied to the appraiser schema (missing description, semantic overlap
-with an existing appraiser, …).
+**Side effects:** writes the appraiser file and commits it on the
+current `config/*` branch.
 
 ### `foundry_config_create_flow`
 
 > Create a new flow definition under `foundry/flows/<flowId>/`.
 
 **Args:**
-- `name` (string, required): flowId (kebab-case slug).
-- `body` (string, required): markdown body with frontmatter
-  (`description`, `cycles: [...]`).
+- `id` (string, required): Flow id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `startingCycles` (string[], required): Ordered list of cycle ids for this flow.
+- `description` (string, required): Prose description of the flow.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on schema failure;
+`{ error, affected_files }` on commit-policy refusal.
+
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
 
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure → `{ ok: false, errors: [...] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
 
-**Failure modes:** as for `foundry_config_create_artefact_type`,
-applied to the flow schema.
+**Side effects:** writes the flow file and commits it on the
+current `config/*` branch.
 
 ### `foundry_config_create_cycle`
 
 > Create a new cycle markdown file under `foundry/cycles/<cycleId>.md`.
 
 **Args:**
-- `name` (string, required): cycleId (kebab-case slug).
-- `body` (string, required): markdown body with frontmatter
-  (`flowId`, `output`, optional `inputs`, `memory`, `models`, …).
+- `id` (string, required): Cycle id (kebab-case slug).
+- `name` (string, required): Human-readable name.
+- `outputType` (string, required): Artefact type id for this cycle's output.
+- `inputs` (object, optional): `{ type: "any-of"|"all-of", artefacts: string[] }` — input filtering rules.
+- `targets` (string[], optional): Target artefact file paths.
+- `alwaysHumanAppraise` (boolean, optional): Force human appraisal on every run.
+- `deadlockHumanAppraise` (boolean, optional): Fall back to human appraisal on deadlock.
+- `maxIterations` (number, optional): Maximum forge-quench-appraise iterations.
+- `assay` (object, optional): `{ extractors: string[] }` — extractors to run in the assay stage.
+- `memory` (object, optional): `{ read: string[], write: string[] }` — memory permissions.
+- `models` (object, optional): Per-stage model overrides.
+- `description` (string, optional): Prose description of the cycle.
+
+**Returns:** `{ ok: true, path, sha }` on success;
+`{ ok: false, errors: [...] }` on schema failure;
+`{ error, affected_files }` on commit-policy refusal.
+
+**Stage requirements:** none (no active stage); requires a
+`config/*` branch.
 
-**Returns / Stage requirements / Side effects:** as for
-`foundry_config_create_artefact_type`.
+**Failure modes:**
+- Off `config/*` branch → branch-guard refusal envelope.
+- Failed flow → tool-name-prefixed error.
+- Schema validation failure (unknown `outputType`, unknown
+  `memory.read` / `memory.write` types, unknown referenced appraisers,
+  …) → `{ ok: false, errors: [...] }`.
+- Worktree has changes outside `foundry/**` →
+  `{ error, affected_files }`.
 
-**Failure modes:** as for `foundry_config_create_artefact_type`,
-applied to the cycle schema (unknown `output` artefact-type, unknown
-`memory.read` / `memory.write` types, unknown referenced appraisers,
-…).
+**Side effects:** writes the cycle file and commits it on the
+current `config/*` branch.
 
 ---
 
@@ -1181,7 +1242,7 @@ read-disallowed.
 
 **Args:**
 - `type`, `name` (string, required).
-- `depth` (number, optional, default 1).
+- `depth` (number, optional, default 1, maximum 5).
 - `edge_types` (string[], optional): Restrict traversal to named edges;
   defaults to all known edges.
 
@@ -1211,7 +1272,7 @@ cycle cannot read; query contains a forbidden keyword.
 
 **Args:**
 - `query_text` (string, required).
-- `k` (number, optional, default 5).
+- `k` (number, optional, default 5, maximum 100).
 - `type_filter` (string[], optional): default = all readable entity
   types.