moflo 4.9.20 → 4.9.22

package/.claude/guidance/shipped/moflo-spell-engine.md

@@ -1,38 +1,21 @@
-# Spell Engine — Running, Creating, and Customizing Spells
+# Spell Engine — Definition Format & Step Types
 
-**Purpose:** How to run spells via MCP tools, create new spell definitions, register custom step commands, and understand the shipped vs user override layering system. Reference when a user asks to run, create, or modify spells.
+**Purpose:** How to define a spell (YAML/JSON schema, arguments, steps, variable interpolation) and a reference for the nine built-in step command types. For execution mechanics (running, dry-run, error codes, pause/resume, layering, credentials), see `.claude/guidance/moflo-spell-runner.md`.
 
 ---
 
 ## Claude's Role During Spell Execution
 
-**Claude MUST treat the spell definition as a strict contract — execute only what it specifies, using only the capabilities it declares.** This applies equally whether the spell is run manually, via MCP, or on a schedule by the daemon.
+**Treat the spell definition as a strict contract — execute only what it specifies, using only the capabilities it declares.** This applies whether the spell runs manually, via MCP, or on a schedule.
 
 | Constraint | Detail |
 |-----------|--------|
 | Step config is the complete instruction | Do not add commands, flags, arguments, or actions beyond what `config` contains |
 | Capability restrictions are absolute | If a step restricts `fs:read` to `["./src/"]`, do not read files outside `./src/` even if helpful |
 | `CAPABILITY_DENIED` means stop | Do not attempt workarounds — report the denial and halt the step |
-| No improvisation between steps | Do not perform actions outside of step boundaries, even if "obvious" (e.g., do not auto-fix a failing step's output before passing it to the next step unless the spell defines a step for that) |
+| No improvisation between steps | Do not perform actions outside step boundaries, even if "obvious" |
 
-See `.claude/guidance/shipped/moflo-spell-sandboxing.md` for the full Execution Constraint Principle and capability type reference.
-
----
-
-## Running a Spell via MCP Tools
-
-**Use `mcp__moflo__spell_cast` to execute a spell from a YAML/JSON file.** The bridge layer handles parsing, validation, and runner lifecycle automatically.
-
-| MCP Tool | Purpose |
-|----------|---------|
-| `mcp__moflo__spell_cast` | Run spell from file content (YAML/JSON) |
-| `mcp__moflo__spell_execute` | Execute a spell definition object directly |
-| `mcp__moflo__spell_cancel` | Cancel a running spell by ID |
-| `mcp__moflo__spell_status` | Check if a spell is currently running |
-| `mcp__moflo__spell_suspend` | Pause a running spell for later resumption |
-| `mcp__moflo__spell_resume` | Resume a previously paused spell |
-
-**Dry-run mode validates without executing.** Pass `dryRun: true` to check definition validity, argument resolution, and step config schemas before committing to execution.
+See `.claude/guidance/moflo-spell-sandboxing.md` for the full Execution Constraint Principle and capability type reference.
 
 ---
 
@@ -102,7 +85,7 @@ steps:
 |---------|-------------|
 | `{args.environment}` | Spell argument value |
 | `{check-branch.stdout}` | Output field from step `check-branch` |
-| `{credentials.API_KEY}` | Credential value (redacted in logs) |
+| `{credentials.API_KEY}` | Credential value (redacted in logs — see `moflo-spell-runner.md`) |
 
 Interpolation works in all string values within step `config`. Nested object values and arrays are interpolated recursively.
 
@@ -122,7 +105,7 @@ steps:
 
 ## Step Command Types
 
-**Nine built-in step types are registered automatically.** Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. Additional step types can be added via pluggable step discovery — see `moflo-spell-custom-steps.md` for the JS/TS, YAML, and npm-package extension paths.
+**Nine built-in step types are registered automatically.** Each implements `execute()`, `validate()`, `describeOutputs()`, and optional `rollback()`. To add new step types via JS/TS files, YAML composite steps, or `moflo-step-*` npm packages, see `.claude/guidance/moflo-spell-custom-steps.md`.
 
 ### bash — Run a Shell Command
 
@@ -130,8 +113,8 @@ steps:
 - id: build
   type: bash
   config:
-    command: "npm run build"    # Required. Shell command to execute.
-    timeout: 30000              # Optional. Timeout in ms (default: 30000).
+    command: "npm run build"    # Required.
+    timeout: 30000              # Optional. Default 30000.
     failOnError: true           # Optional. Fail step on non-zero exit (default: true).
 ```
 
@@ -145,9 +128,9 @@ steps:
 - id: research
   type: agent
   config:
-    agentType: "researcher"     # Required. Agent type (researcher, coder, tester, etc.).
-    prompt: "Find all API endpoints in {args.directory}"  # Required. Task prompt.
-    background: false           # Optional. Run in background (default: false).
+    agentType: "researcher"     # Required. researcher, coder, tester, etc.
+    prompt: "Find all API endpoints in {args.directory}"  # Required.
+    background: false           # Optional. Default false.
 ```
 
 **Outputs:** `result` (string), `agentType` (string), `prompt` (string).
@@ -160,14 +143,14 @@ steps:
 - id: check-env
   type: condition
   config:
-    if: "{args.environment} === 'production'"  # Required. Expression to evaluate.
+    if: "{args.environment} === 'production'"  # Required.
     then: "deploy-prod"                        # Optional. Step ID to jump to if true.
     else: "deploy-staging"                     # Optional. Step ID to jump to if false.
 ```
 
 **Outputs:** `result` (boolean), `branch` (string: "then" or "else"), `nextStep` (string).
 
-The runner uses `nextStep` to jump to the target step ID. Jumps can go forward or backward. A max-iteration guard (`steps.length * 10`) prevents infinite loops.
+The runner uses `nextStep` to jump to the target step ID. Jumps may go forward or backward. A max-iteration guard (`steps.length * 10`) prevents infinite loops.
 
 ---
 
@@ -177,10 +160,10 @@ The runner uses `nextStep` to jump to the target step ID. Jumps can go forward o
 - id: process-files
   type: loop
   config:
-    over: ["{args.files}"]        # Required. Array to iterate (or variable reference).
-    maxIterations: 100            # Optional. Safety limit (default: 100).
-    itemVar: "file"               # Optional. Current item variable name (default: "item").
-    indexVar: "idx"               # Optional. Current index variable name (default: "index").
+    over: ["{args.files}"]        # Required. Array or variable reference.
+    maxIterations: 100            # Optional. Default 100.
+    itemVar: "file"               # Optional. Default "item".
+    indexVar: "idx"               # Optional. Default "index".
   steps:                          # Nested steps run for each item.
     - id: process-one
       type: bash
@@ -190,7 +173,7 @@ The runner uses `nextStep` to jump to the target step ID. Jumps can go forward o
 
 **Outputs:** `totalItems` (number), `iterations` (number), `truncated` (boolean), `items` (array).
 
-Nested `steps` are defined on the step definition (not inside `config`). The runner executes all nested steps per iteration, injecting `itemVar` and `indexVar` into the variable context. Previous values are saved and restored after the loop completes.
+Nested `steps` go on the step definition (not inside `config`). The runner injects `itemVar` and `indexVar` per iteration; previous values are saved and restored after the loop.
 
 ---
 
@@ -200,11 +183,11 @@ Nested `steps` are defined on the step definition (not inside `config`). The run
 - id: load-config
   type: memory
   config:
-    action: "read"              # Required. One of: read, write, search.
-    namespace: "workflow-state"  # Required. Memory namespace.
-    key: "last-deploy"          # Required for read/write. Memory key.
-    value: "{deploy.stdout}"    # Required for write. Value to store.
-    query: "deploy status"      # Required for search. Semantic query.
+    action: "read"              # Required. read | write | search.
+    namespace: "workflow-state"  # Required.
+    key: "last-deploy"          # Required for read/write.
+    value: "{deploy.stdout}"    # Required for write.
+    query: "deploy status"      # Required for search.
 ```
 
 **Outputs:** `value` (object), `found` (boolean), `written` (boolean), `results` (array), `count` (number).
@@ -217,10 +200,10 @@ Nested `steps` are defined on the step definition (not inside `config`). The run
 - id: confirm
   type: prompt
   config:
-    message: "Deploy to {args.environment}?"  # Required. Question text.
-    options: ["yes", "no"]                    # Optional. Multiple choice options.
-    default: "no"                              # Optional. Default if no input.
-    outputVar: "user_choice"                   # Optional. Variable to store response.
+    message: "Deploy to {args.environment}?"  # Required.
+    options: ["yes", "no"]                    # Optional. Multiple choice.
+    default: "no"                              # Optional.
+    outputVar: "user_choice"                   # Optional.
 ```
 
 **Outputs:** `response` (string), `message` (string), `outputVar` (string).
@@ -233,7 +216,7 @@ Nested `steps` are defined on the step definition (not inside `config`). The run
 - id: cooldown
   type: wait
   config:
-    duration: 5000  # Required. Wait duration in milliseconds.
+    duration: 5000  # Required. Milliseconds.
 ```
 
 **Outputs:** `waited` (number — actual wait time in ms).
@@ -264,103 +247,21 @@ Requires `playwright` as a peer dependency. The command checks for Playwright av
 - id: create-issue
   type: github
   config:
-    action: "create-issue"      # Required. create-issue, create-pr, add-label, comment, etc.
+    action: "create-issue"      # Required.
     title: "Bug: {args.title}"  # Required for create-issue/create-pr.
-    body: "Details here"        # Optional. Issue/PR body.
+    body: "Details here"        # Optional.
     repo: "owner/repo"          # Optional. Defaults to current repo.
 ```
 
 **Outputs:** `url` (string), `number` (number), `action` (string).
 
-Supports 8 actions: `create-issue`, `create-pr`, `add-label`, `remove-label`, `comment`, `close-issue`, `close-pr`, `merge-pr`. Requires `gh` CLI installed and authenticated.
-
----
-
-## Custom Step Commands
-
-**To register custom step types, see `moflo-spell-custom-steps.md`.** That doc covers the three extension paths (JS/TS step files, YAML composite steps, `moflo-step-*` npm packages), priority ordering, and how to configure `createRunner()` for discovery.
-
----
-
-## Shipped vs User Definition Layering
-
-**Shipped definitions are bundled defaults. User definitions override shipped ones by name match.**
-
-| Tier | Source | Priority |
-|------|--------|----------|
-| Shipped | Bundled in moflo package source (`workflows/shipped/`) | Lower |
-| User | Project-local path (configurable via `moflo.yaml`) | Higher — overrides shipped by name |
-
-### How Layering Works
-
-1. `loadSpellDefinitions()` loads shipped definitions first
-2. Then loads user definitions from configured directories
-3. If a user definition has the same `name` as a shipped one, the user version wins
-4. New names in user directories are additive (they extend, not replace, the set)
-
-### Loading Definitions Programmatically
-
-```typescript
-import { loadSpellDefinitions, loadSpellByName } from 'moflo/dist/src/cli/spells/index.js';
-
-const { spells, errors } = loadSpellDefinitions({
-  shippedDir: 'node_modules/moflo/workflows/shipped',
-  userDirs: ['.claude/workflows', 'workflows/'],
-});
-const result = loadSpellByName('deploy-staging', { /* same options */ });
-```
-
----
-
-## Error Handling and Rollback
-
-**The runner collects errors without throwing.** `SpellResult` always returns — check `result.success` and `result.errors`.
-
-| Error Code | Meaning |
-|------------|---------|
-| `DEFINITION_VALIDATION_FAILED` | Invalid YAML/JSON or schema violation |
-| `ARGUMENT_VALIDATION_FAILED` | Missing required argument or type mismatch |
-| `UNKNOWN_STEP_TYPE` | No step command registered for this type |
-| `STEP_VALIDATION_FAILED` | Step config fails command's schema validation |
-| `STEP_EXECUTION_FAILED` | Step threw during execution |
-| `STEP_TIMEOUT` | Step exceeded its timeout |
-| `STEP_CANCELLED` | Spell cancelled via AbortSignal |
-| `CONDITION_TARGET_NOT_FOUND` | Condition branch references nonexistent step ID |
-| `PAUSED_STATE_NOT_FOUND` | No paused state for spell ID on resume |
-| `PAUSED_STATE_EXPIRED` | Paused state exceeded stale timeout |
-| `ROLLBACK_FAILED` | Rollback of completed steps failed |
-| `SPELL_CANCELLED` | Entire spell was cancelled |
-
-### continueOnError
-
-**Set `continueOnError: true` on a step to keep running after failure.** The failed step is recorded in results but execution continues. Without this flag, a step failure triggers rollback of completed steps and terminates the spell.
-
----
-
-## Pause and Resume
-
-**Pause serializes spell state to memory. Resume reconstructs and continues from where it left off.**
-
-```typescript
-import { buildPausedState, persistPausedState, resumeSpell } from 'moflo/dist/src/cli/spells/index.js';
-
-// Pause after step 2 of 5
-const state = buildPausedState(spellId, definition, 2, variables, completedResults, args);
-await persistPausedState(state, memory);
-
-// Later: resume from step 3
-const result = await resumeSpell(spellId, { memory, variables: { override: 'value' } });
-```
-
-**Stale timeout is 24 hours by default.** Paused state older than this is rejected on resume and cleaned up. Use `cleanupStalePaused(memory)` to sweep expired entries.
-
-**Variable overrides on resume** allow injecting or modifying context between pause and resume (e.g., user edits a value in between).
+Supported actions: `create-issue`, `create-pr`, `add-label`, `remove-label`, `comment`, `close-issue`, `close-pr`, `merge-pr`. Requires `gh` CLI installed and authenticated.
 
 ---
 
 ## Creating New Spell Definitions
 
-**To create a spell for a user, write a `.yaml` file in their project's spell directory** (typically `.claude/workflows/` or a path configured in `moflo.yaml`).
+To create a spell, write a `.yaml` file in the project's spell directory (typically `.claude/workflows/`, or the path configured in `moflo.yaml`).
 
 1. Start with `name` and `steps`
 2. Add `arguments` for any user-provided values
@@ -378,38 +279,15 @@ const result = await resumeSpell(spellId, { memory, variables: { override: 'valu
 | Loop `over` resolves to an array | Loop command validates at execution |
 | No circular condition jumps | Max-iteration guard catches these |
 
----
-
-## Dry-Run Validation
-
-**Always dry-run before executing a new or modified spell.** Dry-run validates the definition, resolves arguments, and checks step configs without executing anything.
-
-```typescript
-import { runSpellFromContent } from 'moflo/dist/src/cli/spells/index.js';
-
-const result = await runSpellFromContent(yamlContent, 'my-spell.yaml', { dryRun: true });
-if (!result.success) {
-  console.error('Validation errors:', result.errors);
-}
-```
-
-Via MCP: pass `dryRun: true` to `mcp__moflo__spell_cast`.
-
----
-
-## Credential Handling
-
-**Credentials are accessed via `{credentials.KEY}` in interpolation.** The credential accessor is injected into the runner at creation time — spells never store credentials directly.
-
-Credential values listed in `RunnerOptions.credentialValues` are automatically redacted from step output to prevent accidental exposure in logs or results.
+**Always dry-run before executing a new or modified spell** (see `.claude/guidance/moflo-spell-runner.md` § Dry-Run Validation).
 
 ---
 
 ## See Also
 
-- `.claude/guidance/shipped/moflo-spell-custom-steps.md` — Pluggable step commands: JS/TS, YAML, and `moflo-step-*` npm packages
-- `.claude/guidance/shipped/moflo-spell-connectors.md` — Connectors: resource adapters, registry, step-vs-connector decision
-- `.claude/guidance/shipped/moflo-spell-sandboxing.md` — Capability-based security for steps
-- `.claude/guidance/shipped/moflo-spell-engine-architecture.md` — Architecture decisions for Epic #100
-- `.claude/guidance/shipped/moflo-core-guidance.md` — CLI, hooks, swarm, memory reference
-- `.claude/guidance/shipped/moflo-subagents.md` — Subagents protocol
+- `.claude/guidance/moflo-spell-runner.md` — Running spells, MCP tools, dry-run, error codes, pause/resume, credentials, definition layering
+- `.claude/guidance/moflo-spell-sandboxing.md` — Capability-based security for steps; required reading before authoring
+- `.claude/guidance/moflo-spell-custom-steps.md` — Pluggable step commands: JS/TS files, YAML composites, `moflo-step-*` packages
+- `.claude/guidance/moflo-spell-connectors.md` — Connectors: resource adapters, registry, step-vs-connector decision
+- `.claude/guidance/moflo-spell-troubleshooting.md` — Common failure modes (sandbox/network, permission gaps, environment)
+- `.claude/guidance/moflo-core-guidance.md` — CLI, hooks, swarm, memory reference

package/.claude/guidance/shipped/moflo-spell-runner.md

@@ -0,0 +1,134 @@
+# Spell Runner — Execution, Layering, Errors, and Recovery
+
+**Purpose:** How spells are run, validated, paused, resumed, and how errors and credentials are handled. For the YAML schema, step types, and authoring rules, see `.claude/guidance/moflo-spell-engine.md`.
+
+---
+
+## Running a Spell via MCP Tools
+
+**Use `mcp__moflo__spell_cast` to execute a spell from a YAML/JSON file.** The bridge layer handles parsing, validation, and runner lifecycle automatically.
+
+| MCP Tool | Purpose |
+|----------|---------|
+| `mcp__moflo__spell_cast` | Run spell from file content (YAML/JSON) |
+| `mcp__moflo__spell_execute` | Execute a spell definition object directly |
+| `mcp__moflo__spell_cancel` | Cancel a running spell by ID |
+| `mcp__moflo__spell_status` | Check whether a spell is currently running |
+| `mcp__moflo__spell_suspend` | Pause a running spell for later resumption |
+| `mcp__moflo__spell_resume` | Resume a previously paused spell |
+
+**Dry-run mode validates without executing.** Pass `dryRun: true` to check definition validity, argument resolution, and step config schemas before committing to execution.
+
+---
+
+## Dry-Run Validation
+
+**Always dry-run before executing a new or modified spell.** Dry-run validates the definition, resolves arguments, and checks step configs — nothing executes.
+
+```typescript
+import { runSpellFromContent } from 'moflo/dist/src/cli/spells/index.js';
+
+const result = await runSpellFromContent(yamlContent, 'my-spell.yaml', { dryRun: true });
+if (!result.success) {
+  console.error('Validation errors:', result.errors);
+}
+```
+
+Via MCP: pass `dryRun: true` to `mcp__moflo__spell_cast`.
+
+Dry runs also show the per-step permission report — see `.claude/guidance/moflo-spell-sandboxing.md` § Permission Levels.
+
+---
+
+## Shipped vs User Definition Layering
+
+**Shipped definitions are bundled defaults. User definitions override shipped ones by name match.**
+
+| Tier | Source | Priority |
+|------|--------|----------|
+| Shipped | Bundled in moflo package source (`workflows/shipped/`) | Lower |
+| User | Project-local path (configurable via `moflo.yaml`) | Higher — overrides shipped by name |
+
+### How Layering Works
+
+1. `loadSpellDefinitions()` loads shipped definitions first
+2. Then loads user definitions from configured directories
+3. If a user definition has the same `name` as a shipped one, the user version wins
+4. New names in user directories are additive (they extend, not replace, the set)
+
+### Loading Definitions Programmatically
+
+```typescript
+import { loadSpellDefinitions, loadSpellByName } from 'moflo/dist/src/cli/spells/index.js';
+
+const { spells, errors } = loadSpellDefinitions({
+  shippedDir: 'node_modules/moflo/workflows/shipped',
+  userDirs: ['.claude/workflows', 'workflows/'],
+});
+const result = loadSpellByName('deploy-staging', { /* same options */ });
+```
+
+---
+
+## Error Handling and Rollback
+
+**The runner collects errors without throwing.** `SpellResult` always returns — check `result.success` and `result.errors`.
+
+| Error Code | Meaning |
+|------------|---------|
+| `DEFINITION_VALIDATION_FAILED` | Invalid YAML/JSON or schema violation |
+| `ARGUMENT_VALIDATION_FAILED` | Missing required argument or type mismatch |
+| `UNKNOWN_STEP_TYPE` | No step command registered for this type |
+| `STEP_VALIDATION_FAILED` | Step config fails the command's schema validation |
+| `STEP_EXECUTION_FAILED` | Step threw during execution |
+| `STEP_TIMEOUT` | Step exceeded its timeout |
+| `STEP_CANCELLED` | Spell cancelled via AbortSignal |
+| `CONDITION_TARGET_NOT_FOUND` | Condition branch references a nonexistent step ID |
+| `PAUSED_STATE_NOT_FOUND` | No paused state for spell ID on resume |
+| `PAUSED_STATE_EXPIRED` | Paused state exceeded the stale timeout |
+| `ROLLBACK_FAILED` | Rollback of completed steps failed |
+| `SPELL_CANCELLED` | Entire spell was cancelled |
+
+### continueOnError
+
+**Set `continueOnError: true` on a step to keep running after failure.** The failed step is recorded in results but execution continues. Without this flag, a step failure triggers rollback of completed steps and terminates the spell.
+
+---
+
+## Pause and Resume
+
+**Pause serializes spell state to memory. Resume reconstructs and continues from where it left off.**
+
+```typescript
+import { buildPausedState, persistPausedState, resumeSpell } from 'moflo/dist/src/cli/spells/index.js';
+
+// Pause after step 2 of 5
+const state = buildPausedState(spellId, definition, 2, variables, completedResults, args);
+await persistPausedState(state, memory);
+
+// Later: resume from step 3
+const result = await resumeSpell(spellId, { memory, variables: { override: 'value' } });
+```
+
+**Stale timeout is 24 hours by default.** Paused state older than this is rejected on resume and cleaned up. Use `cleanupStalePaused(memory)` to sweep expired entries.
+
+**Variable overrides on resume** allow injecting or modifying context between pause and resume (e.g., user edits a value in between).
+
+---
+
+## Credential Handling
+
+**Credentials are accessed via `{credentials.KEY}` in interpolation.** The credential accessor is injected into the runner at creation time — spells never store credentials directly.
+
+Credential values listed in `RunnerOptions.credentialValues` are automatically redacted from step output to prevent accidental exposure in logs or results. The `credentials` capability gates access — see `.claude/guidance/moflo-spell-sandboxing.md`.
+
+---
+
+## See Also
+
+- `.claude/guidance/moflo-spell-engine.md` — Definition format, step types, variable interpolation
+- `.claude/guidance/moflo-spell-sandboxing.md` — Capability-based security and permission levels
+- `.claude/guidance/moflo-spell-troubleshooting.md` — Common failure modes when running spells
+- `.claude/guidance/moflo-spell-custom-steps.md` — Pluggable step commands
+- `.claude/guidance/moflo-spell-connectors.md` — Resource connectors and the registry
+- `.claude/guidance/moflo-core-guidance.md` — CLI, hooks, swarm, memory reference

package/.claude/guidance/shipped/moflo-spell-sandboxing.md

@@ -135,14 +135,14 @@ Each method calls `enforceScope()` internally. If the resource is outside the st
 | `bash` | `checkShell()` | **Enforced** |
 | `browser` | `checkBrowserEvaluate()`, `checkNet()` | **Enforced** |
 | `memory` | `checkMemory()` | **Enforced** |
-| `agent` | `checkAgent()` | **Enforced** (#258) |
-| `github` | `checkShell()` | **Enforced** (#258) |
-| Connectors | `checkNet()` via `GatedConnectorAccessor` | **Enforced** (#265) |
-| Credentials | `checkCredentials()` | **Enforced** (#268) |
+| `agent` | `checkAgent()` | **Enforced** |
+| `github` | `checkShell()` | **Enforced** |
+| Connectors | `checkNet()` via `GatedConnectorAccessor` | **Enforced** |
+| Credentials | `checkCredentials()` | **Enforced** |
 | Control flow (`condition`, `loop`, `parallel`, `composite`) | N/A | No I/O — child steps individually checked |
 | `wait`, `prompt` | N/A | No dangerous capabilities |
 
-**Gateway is non-optional** (#266): `WorkflowContext.gateway` is required. A `DenyAllGateway` is the default — any code path that reaches a gateway check without going through `step-executor` (which installs a properly-scoped gateway) will fail loudly rather than silently skipping enforcement.
+**Gateway is non-optional**: `WorkflowContext.gateway` is required. A `DenyAllGateway` is the default — any code path that reaches a gateway check without going through `step-executor` (which installs a properly-scoped gateway) will fail loudly rather than silently skipping enforcement.
 
 ---
 
@@ -250,60 +250,13 @@ Before shipping any new or edited spell step, walk through every item. Silently-
 
 When reviewing a spell PR, scan every bash step for a missing `permissionLevel` and ask: *does this step touch the network, or does it depend on network state from earlier?* If yes, `elevated` (or an explicit `net` grant) is required.
 
-## Troubleshooting
-
-### Symptom: bash step fails with DNS / SSH resolution errors inside a spell
-
-Typical error messages from inside a bash step:
-
-- `ssh: Could not resolve hostname github.com: Temporary failure in name resolution`
-- `fatal: Could not read from remote repository.`
-- `curl: (6) Could not resolve host ...`
-- `getaddrinfo ENOTFOUND ...`
-- Any other DNS/connection failure, even though the **same command works in your normal shell**.
-
-**Tell-tale clue:** the error mentions `Temporary failure in name resolution` (a glibc-specific wording). That means the step is running inside a Linux sandbox (`bwrap` on Linux / WSL), **not** your outer shell — Git Bash or PowerShell won't produce that exact message.
-
-**Root cause:** `src/cli/spells/core/bwrap-sandbox.ts` isolates the network by default:
-
-```ts
-if (!hasNet && !needsToolHomeAccess(options.permissionLevel)) {
-  args.push('--unshare-net');   // ← no network, no DNS
-}
-```
-
-A bash step gets network access only when **one** of these is true:
-
-1. The step declares a `net` capability, **or**
-2. The step's `permissionLevel` is `elevated` or `autonomous`.
-
-If neither applies, bwrap runs the command in a namespace with `--unshare-net`, and DNS silently fails. There is no log line announcing the network was taken away — you just see the command's own DNS error.
-
-**Fix:** for any bash step that does `git pull`/`git push`/`git fetch`, `gh` API calls, `curl`, `npm install`, or any other outbound network:
-
-```yaml
-- id: create-branch
-  type: bash
-  permissionLevel: elevated       # ← grants network in bwrap
-  config:
-    command: "git pull origin main && ..."
-```
-
-Or declare the `net` capability explicitly if the step doesn't need the full `elevated` profile (note: `bash-command.ts` must include `net` in its declared capabilities for the engine to accept the grant — otherwise you'll see `Capability violation: step type "bash" does not declare capability "net"`).
-
-**Quick diagnosis checklist** when a spell's bash step can't reach the network:
-
-1. Does the same command work in your outer shell? If yes, it's sandbox-related, not config.
-2. Is the error wording glibc-style (`Temporary failure in name resolution`)? → bwrap is involved.
-3. Open the spell YAML — does the failing step have `permissionLevel: elevated`? If not, add it and retry.
-4. If you use `set -e` in a multi-command bash step, **do it**. Without it, a trailing `... || true` (common for stash-pop cleanups) will mask the real network failure and you'll see a confusing error several steps later (e.g. "pathspec did not match" when a branch that was never pulled/created is later checked out).
-
 ## See Also
 
-- `.claude/guidance/shipped/moflo-spell-engine.md` — Spell engine usage and YAML format
-- `.claude/guidance/shipped/moflo-spell-connectors.md` — Optional resource adapters (not the enforcement layer)
-- `.claude/guidance/shipped/moflo-spell-engine-architecture.md` — Engine architecture and messaging
-- `.claude/guidance/shipped/moflo-core-guidance.md` — Full CLI/MCP reference
+- `.claude/guidance/moflo-spell-engine.md` — Spell definition format and step types
+- `.claude/guidance/moflo-spell-runner.md` — Running spells, dry-run, error codes, pause/resume
+- `.claude/guidance/moflo-spell-troubleshooting.md` — Sandbox/network failure modes (DNS errors, `--unshare-net`, `set -e` traps)
+- `.claude/guidance/moflo-spell-connectors.md` — Optional resource adapters (not the enforcement layer)
+- `.claude/guidance/moflo-core-guidance.md` — Full CLI/MCP reference
 - `src/cli/spells/core/permission-resolver.ts` — Capability → permission level derivation
 - `src/cli/spells/core/permission-disclosure.ts` — Risk classification and reporting
 - `src/cli/spells/core/permission-acceptance.ts` — Acceptance storage and gate