fix: preserve Codex cached token usage

.archon/workflows/defaults/archon-adversarial-dev.yaml

@@ -117,7 +117,7 @@ nodes:
   - id: adversarial-sprint
     depends_on: [init-workspace]
     idle_timeout: 600000
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
     loop:
       prompt: |
         # Adversarial Development — Sprint Loop

.archon/workflows/defaults/archon-feature-development.yaml

@@ -8,7 +8,7 @@ description: |
 nodes:
   - id: implement
     command: archon-implement
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   - id: create-pr
     command: archon-create-pr

.archon/workflows/defaults/archon-fix-github-issue.yaml

@@ -133,7 +133,7 @@ nodes:
     command: archon-fix-issue
     depends_on: [bridge-artifacts]
     context: fresh
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   # ═══════════════════════════════════════════════════════════════
   # PHASE 5: VALIDATE

.archon/workflows/defaults/archon-idea-to-pr.yaml

@@ -52,7 +52,7 @@ nodes:
     command: archon-implement-tasks
     depends_on: [confirm-plan]
     context: fresh
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   # ═══════════════════════════════════════════════════════════════════
   # PHASE 4: VALIDATE

.archon/workflows/defaults/archon-piv-loop.yaml

@@ -415,7 +415,7 @@ nodes:
   - id: implement
     depends_on: [implement-setup]
     idle_timeout: 600000
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
     loop:
       prompt: |
         # PIV Loop — Implementation Agent

.archon/workflows/defaults/archon-plan-to-pr.yaml

@@ -42,7 +42,7 @@ nodes:
     command: archon-implement-tasks
     depends_on: [confirm-plan]
     context: fresh
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
 
   # ═══════════════════════════════════════════════════════════════════
   # PHASE 4: VALIDATE

.archon/workflows/defaults/archon-ralph-dag.yaml

@@ -189,7 +189,7 @@ nodes:
   - id: implement
     depends_on: [validate-prd]
     idle_timeout: 600000
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
     loop:
       prompt: |
         # Ralph Agent — Autonomous Story Implementation

.archon/workflows/defaults/archon-refactor-safely.yaml

@@ -207,7 +207,7 @@ nodes:
   # ═══════════════════════════════════════════════════════════════
 
   - id: execute-refactor
-    model: claude-opus-4-6[1m]
+    model: opus[1m]
     prompt: |
       You are executing a refactoring plan with strict safety guardrails.
 

.archon/workflows/defaults/archon-workflow-builder.yaml

@@ -61,7 +61,8 @@ nodes:
       5. Whether this should be a simple DAG or include a loop node
 
       Be specific and concrete. Each proposed node should have a clear type
-      (bash, prompt, command, or loop) and a one-line description of what it does.
+      (bash, prompt, command, script, loop, or approval) and a one-line
+      description of what it does.
     model: haiku
     allowed_tools: []
     output_format:
@@ -115,7 +116,7 @@ nodes:
 
       nodes:
         - id: node-id-kebab-case
-          # Choose ONE of: prompt, bash, command, loop
+          # Choose ONE of: prompt, bash, command, script, loop, approval
 
           # --- prompt node (AI-executed) ---
           prompt: |
@@ -131,6 +132,17 @@ nodes:
           # --- command node (references a .archon/commands/ file) ---
           command: command-name
 
+          # --- script node (TypeScript via bun, or Python via uv — no AI, stdout = $<nodeId>.output) ---
+          # Use for deterministic data transforms the shell would mangle (JSON parsing, etc.)
+          script: |
+            const raw = String.raw`$other-node.output`;
+            const data = JSON.parse(raw);
+            console.log(JSON.stringify({ count: data.items.length }));
+          runtime: bun                       # required: 'bun' (.ts/.js) or 'uv' (.py)
+          # deps: [requests]                 # uv only
+          # Or reference a named script in .archon/scripts/:
+          # script: extract-labels           # no extension; bun resolves .ts/.js, uv resolves .py
+
           # --- loop node (iterative AI execution) ---
           loop:
             prompt: |
@@ -139,17 +151,22 @@ nodes:
             max_iterations: 10
             fresh_context: true  # optional: reset context each iteration
 
+          # --- approval node (human gate — pauses workflow) ---
+          approval:
+            message: "Review the plan above. Approve to continue."
+            # capture_response: true         # store reviewer comment as $<nodeId>.output
+
           # Common options for all node types:
           depends_on: [other-node-id]       # DAG edges
           when: "$<other-node>.output == 'value'"  # conditional execution
           trigger_rule: all_success          # all_success | one_success | all_done
-          timeout: 120000                    # ms, for bash nodes
+          timeout: 120000                    # ms, for bash and script nodes
       ```
 
       ## Variable Reference
       - `$ARGUMENTS` — user's input text
       - `$ARTIFACTS_DIR` — pre-created directory for workflow artifacts
-      - `$<nodeId>.output` — stdout from a bash node or AI response from a prompt node
+      - `$<nodeId>.output` — stdout from a bash/script node or AI response from a prompt node
       - `$<nodeId>.output.field` — JSON field from a node with output_format
       - `$BASE_BRANCH` — base git branch
 
@@ -158,12 +175,14 @@ nodes:
       2. The `description:` MUST follow the "Use when / Triggers / Does / NOT for" pattern
       3. Every node MUST have a unique kebab-case `id`
       4. Use `depends_on` to define execution order
-      5. Use `bash` nodes for deterministic operations (file checks, git commands, installs)
-      6. Use `prompt` nodes for AI reasoning tasks
-      7. Use `output_format` on prompt nodes when downstream nodes need structured data
-      8. Use `allowed_tools: []` on classification/analysis nodes that don't need tools
-      9. Use `denied_tools: [Edit, Bash]` when a node should only use Write (not edit existing files)
-      10. Prefer `model: haiku` for simple classification tasks to save cost
+      5. Use `bash` nodes for deterministic shell operations (file checks, git commands, installs)
+      6. Use `script` nodes for typed data transforms (TypeScript JSON parsing, Python with deps) — stdout is captured as output, stderr is forwarded as a warning. $nodeId.output is NOT shell-quoted in script bodies — parse with JSON.parse / json.loads, not shell interpolation
+      7. Use `prompt` nodes for AI reasoning tasks
+      8. Use `approval` nodes to pause for human review at risky gates (plan→execute boundary, destructive actions)
+      9. Use `output_format` on prompt nodes when downstream nodes need structured data
+      10. Use `allowed_tools: []` on classification/analysis nodes that don't need tools
+      11. Use `denied_tools: [Edit, Bash]` when a node should only use Write (not edit existing files)
+      12. Prefer `model: haiku` for simple classification tasks to save cost
 
       ## Output
 

.claude/skills/archon/SKILL.md

@@ -42,12 +42,54 @@ Determine the user's intent and dispatch to the appropriate guide:
 | **Variable substitution reference** | Read `references/variables.md` |
 | **CLI command reference** | Read `references/cli-commands.md` |
 | **Run an interactive workflow** | Read `references/interactive-workflows.md` — transparent relay protocol |
+| **Workflow good practices / anti-patterns** | Read `references/good-practices.md` — read before designing a non-trivial workflow |
+| **Troubleshoot a failing / stuck workflow** | Read `references/troubleshooting.md` — log locations, common failure modes |
 | **Run a workflow (default)** | Continue with "Running Workflows" below |
 
 If the intent is ambiguous, ask the user to clarify.
 
 ---
 
+## Richer Context: [archon.diy](https://archon.diy)
+
+The references in this skill are a distilled subset. The full, canonical docs live at **[archon.diy](https://archon.diy)** (Starlight site from `packages/docs-web/`). If the skill's reference pages don't cover what you need — an edge case, a worked example, a diagram, a deeper section on a feature — fetch the matching page from archon.diy.
+
+### When to reach for the live docs
+
+- You need an end-to-end example that's longer than what the skill shows (e.g. full patterns for hooks, MCP config, sandbox schema, approval flows)
+- You're explaining a concept to the user and want the most readable framing (the `book/` series is written as a tutorial, not a reference)
+- You hit a feature the skill only mentions in passing (e.g. `agents:` inline sub-agents, advanced Codex options, the full SyncHookJSONOutput schema)
+- The user asks "where is this documented?" — point them at the archon.diy URL, not a skill file path
+
+### URL map
+
+| Topic | URL |
+|-------|-----|
+| Landing + install | [archon.diy](https://archon.diy) |
+| Getting started (installation, quick start, concepts) | [archon.diy/getting-started/](https://archon.diy/getting-started/overview/) |
+| The book (tutorial-style walkthrough) | [archon.diy/book/](https://archon.diy/book/) |
+| Workflow authoring guide | [archon.diy/guides/authoring-workflows/](https://archon.diy/guides/authoring-workflows/) |
+| Command authoring guide | [archon.diy/guides/authoring-commands/](https://archon.diy/guides/authoring-commands/) |
+| Node type guides | [archon.diy/guides/loop-nodes/](https://archon.diy/guides/loop-nodes/), [/approval-nodes/](https://archon.diy/guides/approval-nodes/), [/script-nodes/](https://archon.diy/guides/script-nodes/) |
+| Per-node features (Claude only) | [/hooks/](https://archon.diy/guides/hooks/), [/mcp-servers/](https://archon.diy/guides/mcp-servers/), [/skills/](https://archon.diy/guides/skills/) |
+| Global workflows/commands/scripts | [archon.diy/guides/global-workflows/](https://archon.diy/guides/global-workflows/) |
+| Variables reference | [archon.diy/reference/variables/](https://archon.diy/reference/variables/) |
+| CLI reference | [archon.diy/reference/cli/](https://archon.diy/reference/cli/) |
+| Security model (env, sandbox, target-repo `.env` stripping) | [archon.diy/reference/security/](https://archon.diy/reference/security/) |
+| Architecture | [archon.diy/reference/architecture/](https://archon.diy/reference/architecture/) |
+| Configuration (`.archon/config.yaml` full schema) | [archon.diy/reference/configuration/](https://archon.diy/reference/configuration/) |
+| Troubleshooting | [archon.diy/reference/troubleshooting/](https://archon.diy/reference/troubleshooting/) |
+| Adapter setup (Slack/Telegram/GitHub/Web/Discord/Gitea/GitLab) | [archon.diy/adapters/](https://archon.diy/adapters/) |
+| Deployment (Docker, cloud, Windows) | [archon.diy/deployment/](https://archon.diy/deployment/) |
+
+URL shape is `archon.diy/<section>/<page>/` — the paths mirror the filenames under `packages/docs-web/src/content/docs/`.
+
+### Precedence
+
+This skill's reference pages are the primary source for routine workflow authoring, CLI use, and setup. Reach for archon.diy when the skill is incomplete for your case — don't go to the live docs first by default (skill refs load into context faster and are tuned for agents).
+
+---
+
 ## Running Workflows
 
 ### Core Command
@@ -152,9 +194,9 @@ nodes:
     depends_on: [first-node]
 ```
 
-### Four Node Types
+### Node Types
 
-Each node has exactly ONE of: `command`, `prompt`, `bash`, or `loop`.
+Each node has exactly ONE of: `command`, `prompt`, `bash`, `script`, `loop`, `approval`, or `cancel`.
 
 **Command node** — runs a `.archon/commands/*.md` file:
 ```yaml
@@ -177,6 +219,22 @@ Each node has exactly ONE of: `command`, `prompt`, `bash`, or `loop`.
   timeout: 15000
 ```
 
+**Script node** — TypeScript/JavaScript (via `bun`) or Python (via `uv`), no AI, stdout captured as output:
+```yaml
+- id: transform
+  script: |
+    const raw = process.argv.slice(2).join(' ') || '{}';
+    console.log(JSON.stringify({ parsed: JSON.parse(raw) }));
+  runtime: bun           # 'bun' (.ts/.js) or 'uv' (.py) — REQUIRED
+  timeout: 30000         # Optional, ms, default 120000
+
+# Or reference a named script from .archon/scripts/ or ~/.archon/scripts/
+- id: analyze
+  script: analyze-metrics   # loads .archon/scripts/analyze-metrics.py
+  runtime: uv
+  deps: ["pandas>=2.0"]     # Optional, uv only — 'uv run --with <dep>'
+```
+
 **Loop node** — iterates AI prompt until completion:
 ```yaml
 - id: implement
@@ -188,6 +246,29 @@ Each node has exactly ONE of: `command`, `prompt`, `bash`, or `loop`.
     until_bash: "bun run test"    # Optional: exit 0 = done
 ```
 
+**Approval node** — pauses the workflow for human review. Requires `interactive: true` at the workflow level for Web UI delivery:
+```yaml
+interactive: true   # workflow level — required for web UI
+
+nodes:
+  - id: review-gate
+    approval:
+      message: "Review the plan above before proceeding."
+      capture_response: true      # Optional: user's comment → $review-gate.output
+      on_reject:                  # Optional: AI rework on rejection instead of cancel
+        prompt: "Revise based on feedback: $REJECTION_REASON"
+        max_attempts: 3           # Range 1-10, default 3
+    depends_on: [plan]
+```
+
+**Cancel node** — terminates the workflow with a reason. Typically gated with `when:`:
+```yaml
+- id: stop-if-unsafe
+  cancel: "Refusing to proceed: input flagged UNSAFE."
+  depends_on: [classify]
+  when: "$classify.output != 'SAFE'"
+```
+
 For the full authoring guide with all fields, conditions, trigger rules, and patterns: Read `references/workflow-dag.md`
 
 ### Creating a Command File
@@ -230,7 +311,7 @@ For details: Read `references/dag-advanced.md`
 
 ### Example Files
 
-- `examples/dag-workflow.yaml` — workflow with conditions, bash nodes, structured output
+- `examples/dag-workflow.yaml` — workflow with conditions, bash + script + loop nodes, structured output
 - `examples/command-template.md` — Command file skeleton with all variables
 
 ---

.claude/skills/archon/examples/dag-workflow.yaml

@@ -1,7 +1,8 @@
-# Example: Workflow with all four node types
+# Example: Workflow demonstrating multiple node types
 #
-# Demonstrates: bash nodes, structured output, when: conditions,
-# trigger_rule, per-node model, context: fresh, loop nodes, and output substitution.
+# Demonstrates: bash nodes, script nodes (TypeScript via bun), structured output,
+# when: conditions, trigger_rule, per-node model, context: fresh, loop nodes,
+# and output substitution.
 #
 # IMPORTANT: This is a reference example. Design your actual workflow
 # around the user's specific needs — the number of nodes, their types,
@@ -42,6 +43,27 @@ nodes:
       fi
     timeout: 5000
 
+  # ── SCRIPT NODE: TypeScript (bun runtime), no AI, stdout captured as output ──
+  # Deterministic parsing the shell would mangle — extracts labels cleanly as JSON.
+  #
+  # NOTE: `$fetch-issue.output` is substituted *raw* into the script body (no shell
+  # quoting — see reference/variables.md). Wrapping it in a String.raw template
+  # preserves backslashes and newlines in the JSON payload without needing any
+  # escaping. Safe here because gh issue view --json emits clean JSON.
+  - id: extract-labels
+    script: |
+      const raw = String.raw`$fetch-issue.output`;
+      try {
+        const issue = JSON.parse(raw);
+        const labels = (issue.labels ?? []).map((l) => l.name);
+        console.log(JSON.stringify({ labels, count: labels.length }));
+      } catch {
+        console.log(JSON.stringify({ labels: [], count: 0 }));
+      }
+    runtime: bun
+    depends_on: [fetch-issue]
+    timeout: 10000
+
   # ── PROMPT NODE: Inline AI prompt with structured output ──
   - id: classify
     prompt: |

.claude/skills/archon/references/authoring-commands.md

@@ -4,14 +4,29 @@ Commands are plain Markdown files containing AI prompt templates. They are the a
 
 ## File Location
 
+Commands are discovered from three scopes, highest-precedence first:
+
 ```
-.archon/commands/
-├── my-command.md           # Custom command
-├── review-code.md          # Another custom command
-└── defaults/               # Optional: override bundled defaults
-    └── archon-assist.md    # Overrides the bundled archon-assist
+<repoRoot>/.archon/commands/     # 1. Repo-scoped (wins)
+├── my-command.md                #    Custom command for this repo
+├── archon-assist.md             #    Overrides the bundled archon-assist
+└── triage/                      #    Subfolders allowed, 1 level deep
+    └── review.md                #    Resolves as 'review', not 'triage/review'
+
+~/.archon/commands/              # 2. Home-scoped (user-level, shared across all repos)
+├── review-checklist.md          #    Personal helper available in every repo
+└── pr-style-guide.md
+
+<bundled defaults>                # 3. Shipped with Archon (archon-assist, etc.)
 ```
 
+**Resolution rules:**
+
+- Filename-without-extension is the command name (e.g. `my-command.md` → `my-command`).
+- 1-level subfolders are supported for grouping; resolution is still by filename (`triage/review.md` → `review`).
+- Repo scope overrides home scope overrides bundled, by name.
+- Duplicate basenames **within a scope** (e.g. two different `review.md` files in `triage/` and `security/`) are a user error — keep names unique within each scope.
+
 Commands are referenced by name (without `.md`) in workflow YAML files.
 
 ## File Format
@@ -78,11 +93,14 @@ Command names must:
 ## Discovery and Priority
 
 When a workflow references `command: my-command`, Archon searches in this order:
-1. `.archon/commands/my-command.md` (repo custom)
-2. `.archon/commands/defaults/my-command.md` (repo default overrides)
+
+1. `<repoRoot>/.archon/commands/my-command.md` (repo scope)
+2. `~/.archon/commands/my-command.md` (home scope — shared across every repo on the machine)
 3. Bundled defaults (shipped with Archon)
 
-First match wins. To override a bundled command, create a file with the same name in your repo.
+First match wins. To override a bundled command, drop a file with the same name at either scope. To override a home-scoped command for a specific repo, drop a file with the same name in that repo's `.archon/commands/`.
+
+> **Web UI note**: Home-scoped commands appear in the workflow builder's node palette under a dedicated "Global (~/.archon/commands/)" section, distinct from project and bundled entries.
 
 ## Referencing Commands from Workflows