wotann 0.5.0

package/skills/capability-evolver.md

@@ -0,0 +1,141 @@
+---
+name: capability-evolver
+description: Agent self-improvement loop — capture failure, propose patch, test, merge. Use after every failed task to compound learnings into durable capability.
+type: cognitive-framework
+source: openclaw
+---
+
+# Capability Evolver — The Self-Improvement Loop
+
+A reusable post-failure protocol that turns every "this didn't work" into a
+durable capability upgrade. The intuition: failure is the most expensive
+signal an agent generates, and discarding it is the deepest waste in
+agent engineering. This skill ensures every failure becomes a regression
+test, a documented case, and (when warranted) a code change.
+
+## When to invoke
+
+- After ANY failed task — a test that didn't pass, a wrong answer, a tool that errored
+- After a user correction — "no, do it like this" is a learning signal, not a chat turn
+- During a postmortem on a multi-step plan that took the wrong branch
+- When the same kind of failure has happened twice — the second time MUST trigger this skill
+- At the end of a session when reviewing the day's work
+
+## The Loop
+
+```
+1. CAPTURE   — write down exactly what failed, with the inputs that triggered it
+2. CLASSIFY  — is this a sense / understand / plan / act / reflect failure? (see turing-pyramid)
+3. PROPOSE   — write the smallest possible patch that prevents the failure
+4. TEST      — write a regression test that fails on the old behavior, passes on the new
+5. MERGE     — apply the patch; the test is now the durable proof
+6. RECORD    — save the case + patch + test to memory so future sessions know
+```
+
+## Process
+
+### Step 1 — Capture (do this BEFORE anything else)
+
+Open a capture document with these fields:
+
+```
+title: <one-line summary of the failure>
+date: <YYYY-MM-DD>
+trigger: <the exact input or context that caused the failure>
+expected: <what should have happened>
+actual: <what happened>
+error_chain: <traceback / log / observed wrong output>
+hypothesis: <best guess at the root cause — may be wrong, that's fine>
+```
+
+If you cannot fill in `trigger` and `actual` precisely, you are not yet ready
+for steps 2-6. Go reproduce the failure first.
+
+### Step 2 — Classify
+
+Apply the `turing-pyramid` skill to identify the layer of the failure. The
+classification determines the kind of patch:
+
+- Sense failures → broaden the working set (more files, more context, more memory)
+- Understand failures → fix parsers, schemas, or the prompt that interprets input
+- Plan failures → fix the decision rule, add a missing case, change priority
+- Act failures → fix the tool wrapper, add timeouts/retries, validate the call site
+- Reflect failures → add a logger, add a metric, add a test
+
+### Step 3 — Propose the patch
+
+The patch should be the SMALLEST change that prevents this specific failure
+without introducing regressions elsewhere. Default mode: surgical.
+
+Anti-pattern: refactoring three modules because "while I'm here". The user
+wanted the bug fixed, not a tour of your aesthetic preferences.
+
+### Step 4 — Write the regression test
+
+The test must:
+- Reproduce the exact `trigger` from Step 1
+- Assert against the `expected` behavior from Step 1
+- Fail on the OLD code (run it once on the old code to prove the test catches the bug)
+- Pass on the NEW code with the patch applied
+
+If the test passes on the OLD code, the test is NOT testing the bug. Try again.
+
+### Step 5 — Merge
+
+Apply the patch + test together as a single atomic unit. Never merge a fix
+without its test — that loses the durability of the lesson.
+
+### Step 6 — Record
+
+Save the capture document to memory using:
+- `mem_save` with `topic_key="cases/<domain>"` for the case + root cause + fix
+- `mem_save` with `topic_key="patterns/<domain>"` for the technique that worked
+
+A future agent session searching for "agent stuck in test loop" will surface
+your case and skip the failure path entirely.
+
+## Examples
+
+### Example — agent kept hardcoding test fixtures
+
+**Capture**: Agent generated `expect(result).toBe(42)` for every test, regardless of
+the actual return value. Tests passed but were meaningless.
+
+**Classify**: Plan-layer failure. The agent's plan included "make the test pass" not
+"make the test test the actual behavior".
+
+**Propose**: Tighten the test-engineer agent's system prompt to add: "tests must fail
+on broken implementations — verify by negating the expected value and re-running".
+
+**Test**: Add a regression test that mutates the implementation and asserts the test
+suite catches the mutation.
+
+**Merge**: PR includes the prompt change AND the regression test.
+
+**Record**: `mem_save(topic_key="cases/test-quality", title="Hardcoded test values defeat regression testing", ...)`.
+
+## Recurrence detection
+
+When recording, check if a similar `topic_key` already has 3+ entries. If yes,
+the failure is recurrent — escalate to a structural fix, not another patch.
+Recurrence means the patch surface is wrong; you need a deeper change.
+
+## Anti-patterns
+
+- Skipping the capture step ("I'll remember it"). You won't.
+- Patching without a test. Future-you will undo this fix in 3 weeks.
+- Recording the patch but not the failure mode — without the trigger, the case is unsearchable.
+- Using `try/catch` around the failing call as the "fix". That's hiding the failure, not preventing it.
+
+## Stopping criteria
+
+- Capture document is complete
+- Test is in the suite, passing
+- Patch is merged
+- Memory entry is written and searchable
+
+## Provenance
+
+OpenClaw's capability-evolver skill, adapted for WOTANN. Pairs naturally
+with the turing-pyramid skill (for layer classification) and the
+elite-longterm-memory skill (for the memory-recording step).

package/skills/chain-of-thought.md

@@ -0,0 +1,48 @@
+---
+name: chain-of-thought
+description: Make Claude show its reasoning step-by-step before producing the final answer
+context: fork
+paths: []
+---
+
+# Chain-of-Thought
+
+## When to Use
+- Multi-step reasoning problems (math, logic, planning)
+- Tasks where final-only answers tend to be wrong on the first try
+- Debugging assistant-output mistakes — visible reasoning is auditable
+- Whenever you'd otherwise re-prompt for "show your work"
+
+## What It Does
+Instructs the model to produce its intermediate reasoning before the final answer, then separates the two cleanly so downstream tools see only the final answer.
+
+## Output Shape
+```
+<reasoning>
+Step 1: …
+Step 2: …
+Step 3: …
+</reasoning>
+
+<answer>
+The final answer is …
+</answer>
+```
+
+## Instructions
+
+1. Identify the task type — pure reasoning vs. lookup. CoT helps the former, hurts the latter (added latency, no quality gain).
+2. Prefix the user's task with: "Think through this step by step. Show each step clearly. Then give the final answer."
+3. Wrap reasoning in `<reasoning>...</reasoning>` and the final answer in `<answer>...</answer>`.
+4. When parsing, take ONLY what's inside `<answer>` for downstream consumption.
+5. Reasoning is for humans — log it but do not feed it back into the model on the next turn (causes loop drift).
+
+## Tradeoffs
+- Adds 30-200% latency depending on task complexity
+- Adds 30-300% token cost
+- Improves correctness on multi-step problems by 10-40%
+- Best paired with Self-Consistency (sample N traces, vote)
+
+## References
+- Chain-of-Thought Prompting Elicits Reasoning in LLMs — https://arxiv.org/abs/2201.11903
+- Self-Consistency Improves CoT — https://arxiv.org/abs/2203.11171

package/skills/cicd-engineer.md

@@ -0,0 +1,68 @@
+---
+name: cicd-engineer
+description: GitHub Actions, CI/CD pipelines, deployment strategies
+context: fork
+paths: ["**/.github/workflows/**", "**/Jenkinsfile", "**/.gitlab-ci*", "**/.circleci/**", "**/azure-pipelines*"]
+---
+
+# CI/CD Engineer
+
+## When to Use
+- Authoring or reviewing GitHub Actions, GitLab CI, CircleCI, or Jenkins pipelines.
+- Diagnosing flaky or slow CI builds.
+- Designing release strategies: canary, blue-green, feature flags.
+- Wiring secrets, OIDC, or reusable workflows.
+- Setting up branch protection, required status checks, and auto-merge.
+
+## Rules
+- Pin third-party actions to full commit SHA, never floating tags.
+- Cache dependencies (`actions/cache` or equivalent) keyed by lockfile hash.
+- Keep CI jobs independent; use matrix for cross-platform runs.
+- Fail fast: short jobs first, long jobs last.
+- Never hardcode secrets; use repository/env secrets or OIDC to a cloud IAM.
+- Tag built artifacts with the git SHA so rollback is one click.
+
+## Patterns
+- **Trunk-based** development with short-lived branches and squash-merge.
+- **Blue-green** or **canary** deploys behind a load balancer health check.
+- **Reusable workflows** (`workflow_call`) to DRY up repetitive logic.
+- **OIDC** to AWS/GCP to eliminate long-lived cloud keys.
+- **Dependabot** or **Renovate** to keep actions and dependencies current.
+- **Build once, deploy many**: the same artifact flows through staging → prod.
+
+## Example
+```yaml
+# .github/workflows/ci.yml — cache + matrix + fail-fast
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22]
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
+      - uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+      - run: npm ci
+      - run: npm test -- --reporter=verbose
+```
+
+## Checklist
+- [ ] All third-party actions pinned to full SHA.
+- [ ] Dependencies cached; cache key includes lockfile hash.
+- [ ] Secrets scoped to environment, not repository.
+- [ ] Required status checks configured on protected branches.
+- [ ] Rollback plan documented and tested (at least once).
+
+## Common Pitfalls
+- **Floating tags** like `@main` or `@v1` — breakage when upstream force-pushes.
+- **Shared workspaces** across matrix jobs leaking state between shards.
+- **Unbounded timeouts** that leave jobs stuck for 6 hours on flakes.
+- **Deploy steps without health checks** that mark broken releases as green.
+- **Secrets leakage** from `echo $SECRET` or unredacted logs.

package/skills/cloud-architect.md

@@ -0,0 +1,59 @@
+---
+name: cloud-architect
+description: AWS, GCP, Azure architecture patterns, well-architected reviews
+context: fork
+paths: ["**/terraform/**", "**/cloudformation/**", "**/*.tf", "**/infra/**"]
+---
+
+# Cloud Architect
+
+## When to Use
+- Designing a new cloud workload or reviewing an existing one.
+- Choosing between serverless, containers, or VMs for a workload.
+- Running a Well-Architected Framework review (reliability, security, cost, performance, ops, sustainability).
+- Multi-region or multi-AZ high-availability planning.
+- Cost optimization passes or reserved-capacity analysis.
+
+## Rules
+- Start with SLO (availability, latency, RPO/RTO); architecture follows.
+- Prefer managed services unless you have a clear reason to self-operate.
+- Design for failure — every single-point-of-failure has a documented mitigation.
+- Make cost a first-class architectural constraint, not a post-hoc review.
+- Codify infrastructure (Terraform/Pulumi/CDK) — no click-ops in production.
+- Use IAM least-privilege scoped to resource ARN, not `*`.
+
+## Patterns
+- **Three-tier**: ALB → stateless app fleet → managed DB with read replicas.
+- **Event-driven**: producers → SQS/PubSub/EventBridge → consumers with DLQ.
+- **Multi-region active-passive**: Route 53 health check failover, DB replication with replay.
+- **Hub-and-spoke**: shared services VPC for networking primitives, workload VPCs peered.
+- **Landing zone**: Control Tower / GCP Organization / Azure Management Groups.
+
+## Example
+```hcl
+# Multi-AZ web tier with ELB health check and rolling instance refresh.
+resource "aws_autoscaling_group" "web" {
+  name                = "web-${var.env}"
+  min_size            = 3
+  max_size            = 12
+  desired_capacity    = 3
+  vpc_zone_identifier = module.vpc.private_subnets
+  health_check_type   = "ELB"
+  target_group_arns   = [aws_lb_target_group.web.arn]
+  instance_refresh { strategy = "Rolling" }
+}
+```
+
+## Checklist
+- [ ] Every tier spans at least two AZs.
+- [ ] Data encrypted at rest (KMS) and in transit (TLS 1.2+).
+- [ ] A cost estimate (Infracost) accompanies the PR.
+- [ ] Observability covers USE method: Utilization, Saturation, Errors.
+- [ ] Runbook entry exists for each known failure mode.
+
+## Common Pitfalls
+- **NAT gateway sprawl** — one per AZ adds real money; share where policy allows.
+- **Over-permissive IAM** — `Resource: "*"` on S3 or Secrets Manager.
+- **Egress blindness** — no logging or anomaly detection on outbound traffic.
+- **Autoscaling on CPU alone** for queue workers; use queue depth.
+- **Single-region DB** for "critical" workloads with no tested DR plan.

package/skills/code-review-deep.md

@@ -0,0 +1,82 @@
+---
+name: code-review-deep
+description: Comprehensive code review checklist covering correctness, security, performance, readability, testing, and operational risk. Use when reviewing a non-trivial PR, when stakes are high, or when the existing code-reviewer pass missed something. Stricter and more checklist-driven than the default code-reviewer skill.
+type: workflow
+---
+
+# Code Review — Deep Pass
+
+Most code reviews catch syntax. Deep reviews catch the things that bite in production: race conditions, missing input validation, eventual-consistency bugs, fragile tests that lock in the wrong behavior. This skill is a structured pass for when "looks good" is not good enough.
+
+## When to invoke
+
+- A PR touches authentication, money, data deletion, or shared infra.
+- A junior author needs a worked example of what a thorough review looks like.
+- A previous review missed a class of issue and the team wants a re-review.
+- Pre-merge gate for security-sensitive code.
+
+## The six-dimension pass
+
+Run each dimension as a separate read of the diff. Do not interleave — that is how things get missed.
+
+### 1. Correctness
+- Off-by-one and boundary conditions on indices, slices, ranges.
+- Edge cases: empty input, null, max int, unicode, concurrent calls.
+- Error paths: what happens when a dependency fails? Is it silent?
+- Idempotency: does retrying a failed call double-charge?
+
+### 2. Security
+- All user input validated at the system boundary (length, charset, schema).
+- Parameterized queries — no string concatenation into SQL or shell.
+- Authorization checks on every protected endpoint (not just authentication).
+- Secrets not logged, not in error responses, not committed.
+- CSRF protection on state-changing endpoints with cookie auth.
+- SSRF protection on URL inputs that the server fetches.
+
+### 3. Performance
+- N+1 queries — does this loop trigger one DB call per iteration?
+- Hot paths allocate the right structures (Map vs Object, Set vs Array).
+- Cache invalidation: who invalidates this, and when?
+- Big-O on the input the call is realistically given.
+- Tail latency: p99 paths should not have unbounded retries.
+
+### 4. Readability and design
+- Names match what the function actually does.
+- Functions are small (< 50 lines) and one-purpose.
+- No deep nesting (> 4 levels) — extract or invert.
+- Public API has type-level guarantees (branded types, discriminated unions).
+- No mutation of inputs — return new objects.
+
+### 5. Testing
+- Tests assert on outcomes, not implementation details.
+- Tests would fail if the implementation regressed.
+- Tests cover the new behavior added by the diff, not just the happy path.
+- Mocks reflect real external behavior; no `mock.expect_anything()`.
+- Coverage is meaningful, not a number to satisfy CI.
+
+### 6. Operational risk
+- Migrations are backward compatible (expand-contract).
+- Feature flag if the change is risky and reversible.
+- Logging at decision points so on-call can debug at 3 AM.
+- Metrics emitted on the critical path (latency, error rate, throughput).
+- Rollback plan documented in the PR description.
+
+## Severity rubric
+
+For each finding, label with one of:
+- **CRITICAL** — must block merge (data loss, security, broken auth).
+- **HIGH** — should block merge unless author has strong rebuttal.
+- **MEDIUM** — fix in this PR if cheap, or follow-up issue.
+- **LOW** — nice to have; document but don't block.
+
+## Anti-patterns
+
+- **Drive-by nits** without higher-priority findings — wastes everyone's time.
+- **Approving with "just one comment"** when the comment is a CRITICAL.
+- **Reviewing the same file twice in one pass** — split your attention by dimension.
+
+## Related
+
+- `code-reviewer` — single-dimension review (lighter weight)
+- `security-reviewer` — security-only deep dive
+- `superpowers:requesting-code-review` — author-side prep before review

package/skills/code-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: code-reviewer
+description: Severity-based code review with confidence filtering
+context: fork
+paths: []
+---
+
+# Code Reviewer
+
+## Review Process
+1. Read the FULL diff (not just changed lines — read surrounding context).
+2. Classify each finding by severity and confidence.
+3. Only report findings with confidence >= 70%.
+
+## Severity Levels
+- **CRITICAL**: Security vulnerability, data loss risk, or correctness bug.
+- **HIGH**: Logic error, missing error handling, or performance regression.
+- **MEDIUM**: Code quality issue, naming concern, or missing test.
+- **LOW**: Style preference, minor optimization, or documentation gap.
+
+## What to Check
+- [ ] Security: injection, XSS, CSRF, exposed secrets
+- [ ] Correctness: edge cases, null handling, off-by-one
+- [ ] Error handling: uncaught exceptions, missing try/catch
+- [ ] Performance: N+1 queries, unnecessary re-renders, missing indexes
+- [ ] Types: any usage, unsafe assertions, missing null checks
+- [ ] Tests: coverage of new code paths, edge case coverage
+
+## What NOT to Do
+- Don't nitpick style in unchanged code.
+- Don't suggest refactors unrelated to the change.
+- Don't report findings you're <70% confident about.

package/skills/code-simplifier.md

@@ -0,0 +1,35 @@
+---
+name: code-simplifier
+description: Reduce complexity while preserving exact behavior
+context: fork
+paths: []
+---
+
+# Code Simplifier
+
+## Process
+1. Read the full file to understand context.
+2. Identify complexity hotspots (deep nesting, long functions, many parameters).
+3. Apply simplifications one at a time.
+4. Run tests after EACH change to confirm behavior is preserved.
+
+## Techniques
+- **Extract function**: Long function → smaller named functions.
+- **Early return**: Deep nesting → guard clauses at the top.
+- **Inline variable**: Variable used once → inline it.
+- **Remove dead code**: Code that can never execute → delete it.
+- **Simplify conditional**: Complex boolean → named predicate function.
+- **Replace loop with functional**: map/filter/reduce where clearer.
+
+## Rules
+- NEVER change behavior. The simplification must be a pure refactor.
+- NEVER add features during simplification.
+- Run tests after every change (regression = rollback).
+- If a simplification makes the code less readable, don't do it.
+- Three similar lines of code is better than a premature abstraction.
+
+## Metrics
+- Cognitive complexity (SonarQube): aim for <15 per function.
+- Lines per function: aim for <50.
+- Parameters per function: aim for <5.
+- Nesting depth: aim for <4.

package/skills/codebase-recon.md

@@ -0,0 +1,101 @@
+---
+name: codebase-recon
+description: Reconnaissance pass through git history and structure before reading code — finds hotspots, bug magnets, and bus-factor risks
+context: fork
+paths: []
+---
+
+# Codebase Reconnaissance
+
+Use this BEFORE you read code in a project you're new to (or haven't touched in months). Reduces blind exploration; gets you to the right files in 5 minutes instead of 30.
+
+## When to use
+
+- You just `git clone`d an unfamiliar repo and need to make a non-trivial change.
+- You're picking up a feature in a part of the codebase you haven't touched in 3+ months.
+- You're auditing a codebase for security/quality and need to know "where do I look first."
+- A teammate asks "why does X behave this way?" and you don't already know.
+
+## Workflow
+
+### 1. Project shape (60 seconds)
+
+```bash
+# Top-level layout
+ls -la
+cat README.md 2>/dev/null | head -80
+cat CLAUDE.md AGENTS.md GEMINI.md 2>/dev/null | head -80
+
+# Languages and ratio
+find . -type f -name "*.ts" -o -name "*.tsx" -o -name "*.py" -o -name "*.swift" -o -name "*.rs" -o -name "*.go" \
+  | xargs wc -l 2>/dev/null | tail -1
+```
+
+### 2. Bug-magnet hotspots (60 seconds)
+
+```bash
+# Files with the most commits — these are where the action happens
+git log --pretty=format: --name-only --since="6.months.ago" \
+  | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+
+# Files with the most BUG-FIX commits — these are where bugs live
+git log --pretty=format: --name-only --grep='fix\|bug' \
+  --since="6.months.ago" | grep -v '^$' | sort | uniq -c | sort -rn | head -10
+
+# Files with the most authors — these are where contention/coordination happens
+git log --pretty=format:"%an %P" --since="1.year.ago" --name-only \
+  | awk '/^[a-zA-Z]/{a=$1} /^[^a-zA-Z]/&&NF{print a, $0}' \
+  | sort -u -k2 | awk '{print $2}' | sort | uniq -c | sort -rn | head -10
+```
+
+### 3. Recent activity (30 seconds)
+
+```bash
+# Last 20 commits with stat
+git log --oneline --stat --no-merges -n 20 | head -100
+
+# Currently uncommitted work (am I about to step on someone's branch?)
+git status -s
+git diff --stat HEAD..origin/main 2>/dev/null
+```
+
+### 4. Bus-factor signals (30 seconds)
+
+```bash
+# Single-author files — high bus-factor risk
+git log --pretty=format:"%an" --name-only \
+  | awk 'BEGIN{RS=""} {n=split($0,lines,"\n"); a=lines[1]; for(i=2;i<=n;i++) if(lines[i]) print a"|"lines[i]}' \
+  | sort | uniq -c | sort -rn \
+  | awk '$1==1{print}' | head -10
+```
+
+### 5. Test density check
+
+```bash
+# Ratio of test files to source files in directories you'll touch
+find src/<target-dir> -name "*.ts" | wc -l
+find tests/ -name "*<target>*" -o -name "<target>*.test.*" | wc -l
+```
+
+### 6. Synthesize
+
+After running 1–5, write a 5-bullet summary BEFORE opening any source file:
+
+- **Project shape**: language, monolith vs multi-package, top-level dirs of interest
+- **Hotspots**: 3 files I should read first because they change a lot
+- **Bug magnets**: 2 files with the most fix-commits
+- **Bus-factor risks**: 1 file with one author who isn't around
+- **Test coverage signal**: do my target dirs have tests?
+
+Then start reading code.
+
+## Anti-patterns (do NOT do these)
+
+- Open a random file because the name looks promising. Use the hotspot list.
+- Read files with 0 recent commits — they're stable; you don't need them yet.
+- Skip the `git log --grep='fix'` step; bug-magnets are the highest-information files in any codebase.
+- Read the full README; skim for architecture diagrams and skip prose.
+
+## Why this works
+
+The Pareto principle for codebases: 80% of the value lives in 20% of the files. Git history is the highest-signal heuristic for finding those 20% — better than directory size, line count, or filename keywords. A file with 50 commits in 6 months is *where the work is happening*; a file with 0 commits is *out of scope*.

package/skills/command-block-replay.md

@@ -0,0 +1,58 @@
+---
+name: command-block-replay
+description: Warp-style block-based command replay. Treats each shell command as a self-contained block (command + output + status + timestamp) so you can scroll back, replay individual blocks, and export a session as a structured timeline. Use when reviewing a debug session or building a runnable repro from history.
+type: workflow
+---
+
+# Command Block Replay
+
+Most terminals are append-only character streams. Warp turned that into BLOCKS — each command and its output paired into a single addressable unit. WOTANN ports the data model so the same UX is available for any session.
+
+## What a block is
+
+```
+{
+  id:        "blk_abc",
+  command:   "npm test -- watcher",
+  output:    "[PASS] watcher.test.ts (3.2s)",
+  status:    "succeeded",
+  timestamp: "2026-04-30T17:21:09Z",
+  exitCode:  0
+}
+```
+
+Not every block has an exitCode (cancelled blocks don't). Status is one of:
+`pending`, `running`, `succeeded`, `failed`, `cancelled`.
+
+## When to use this skill
+
+- Reviewing a debug session — pick out the exact commands that mattered.
+- Building a repro — export only the blocks that produced the failure.
+- Sharing a session — paste a serialized list, not raw terminal output.
+
+## How to replay
+
+1. Start a session in WOTANN's daemon. Each command is auto-blocked.
+2. After the bug reproduces, run `wotann blocks list --status failed`.
+3. Pick the block(s) you want to share. `wotann blocks export blk_abc blk_def`.
+4. Hand the export to a teammate. They can `wotann blocks replay <file>` to re-run the same commands in order.
+
+## What replay does NOT do
+
+- Replay does NOT rerun cancelled or pending blocks — you have to re-issue them by hand.
+- Replay does NOT re-set environment variables. The runtime keeps env hygiene per block.
+- Replay does NOT promise identical output. Many commands depend on time, network, or filesystem state.
+
+## When to skip blocks
+
+- Blocks that ran during exploratory typing — pin only the ones that produced signal.
+- Blocks that printed secrets — use `--redact` to mask before exporting.
+
+## Programmatic API
+
+```ts
+import { createBlock, startBlock, attachOutput, finalizeBlock } from
+  "wotann/lib/orchestration/agent-flows/command-blocks";
+```
+
+Each function is pure and returns a new block — never mutates input. See the source for full signatures.