docs: sync docs/, README, and update-docs skill with v0.0.5 features

- docs/cli-reference.md: add --report junit, -step-setup, -step-teardown,
  --isolation flags and examples
- docs/writing-runbooks.md: add sub-command separator section, fix negation
  description to word boundary matching
- docs/advanced.md: add per-step hooks, per-runbook isolation, report
  formats (JSON array, JUnit), config fields (step_setup, step_teardown,
  isolation)
- README.md: expand Features table and Key Concepts with all major features
- update-docs skill: extend scope to cover docs/, README.md alongside
  skills/ and CHANGELOG.md, add documentation tiers and cross-tier
  consistency checks

Author: runkids

.skillshare/skills/update-docs/SKILL.md

@@ -1,22 +1,32 @@
 ---
 name: mdproof-update-docs
 description: >-
-  Update skills/ documentation and CHANGELOG to match recent code changes,
-  cross-validating every flag and config field against Go source. Use this skill
-  whenever the user asks to: update docs, sync docs with code, document a new
-  flag or config option, fix stale docs, or refresh the skills reference after
-  implementing a feature. This skill covers skills/SKILL.md (main doc),
-  skills/references/ (assertions, advanced features), and CHANGELOG.md. If you
-  just implemented a feature and need to update documentation, this is the skill
-  to use. Never manually edit skills/ docs without cross-validating against Go
-  source first.
+  Update all documentation (skills/, docs/, README.md, CHANGELOG.md) to match
+  recent code changes, cross-validating every flag and config field against Go
+  source. Use this skill whenever the user asks to: update docs, sync docs with
+  code, document a new flag or config option, fix stale docs, or refresh
+  documentation after implementing a feature. This skill covers: docs/ (user-facing
+  guides: cli-reference.md, writing-runbooks.md, advanced.md), skills/SKILL.md
+  (AI agent skill), skills/references/ (assertions, advanced features),
+  README.md (project overview), and CHANGELOG.md. If you just implemented a
+  feature and need to update documentation, this is the skill to use. Never
+  manually edit docs without cross-validating against Go source first.
 argument-hint: "[feature-name | commit-range]"
 targets: [claude, codex]
 ---
 
-Sync skills/ documentation with recent code changes. $ARGUMENTS specifies scope: a feature name (e.g., `step-setup`), commit range, or omit to auto-detect from `git diff HEAD~1`.
+Sync all documentation with recent code changes. $ARGUMENTS specifies scope: a feature name (e.g., `step-setup`), commit range, or omit to auto-detect from `git diff HEAD~1`.
 
-**Scope**: This skill updates `skills/`, `CHANGELOG.md`. It does NOT write Go code (use `implement-feature`).
+**Scope**: This skill updates `docs/`, `skills/`, `README.md`, `CHANGELOG.md`. It does NOT write Go code (use `implement-feature`).
+
+**Documentation tiers** (update all that are affected):
+
+| Tier | Path | Audience | What lives here |
+|------|------|----------|-----------------|
+| User guides | `docs/` | End users, GitHub visitors | CLI reference, runbook authoring, advanced features |
+| AI skill | `skills/` | AI agents (Claude, Codex) | Compact reference for agent consumption |
+| Project overview | `README.md` | Everyone | Feature highlights, install, quick start |
+| Release notes | `CHANGELOG.md` | Users tracking versions | Use the `changelog` skill instead |
 
 ## Workflow
 
@@ -35,7 +45,22 @@ git diff HEAD~1 -- internal/core/types.go
 
 Map changed files to affected documentation:
 
-**Main skill doc** (`skills/SKILL.md`):
+**User guide — CLI reference** (`docs/cli-reference.md`):
+- `cmd/mdproof/main.go` → Flags table, Examples section, Subcommands
+- New flags or subcommands must appear here
+
+**User guide — Writing runbooks** (`docs/writing-runbooks.md`):
+- `internal/parser/` → step heading format, code block handling
+- `internal/executor/session.go` → persistent session, sub-commands
+- `internal/assertion/` → assertion types and syntax
+
+**User guide — Advanced features** (`docs/advanced.md`):
+- `internal/executor/session.go` → hooks, sub-commands, execution model
+- `internal/config/config.go` → Configuration section, all config fields
+- `internal/report/` → report format changes (JSON, JUnit, plain)
+- `cmd/mdproof/main.go` → new flags → new sections (isolation, coverage, etc.)
+
+**AI skill doc** (`skills/SKILL.md`):
 - `cmd/mdproof/main.go` → Quick Reference, CLI Flags table
 - `internal/core/types.go` → Writing Runbooks section (new step fields, report structure)
 - `internal/config/config.go` → mention config support in CLI Flags table
@@ -51,6 +76,9 @@ Map changed files to affected documentation:
 - `cmd/mdproof/main.go` → new flags → new sections
 - `internal/report/` → report format changes (plain, JSON, JUnit)
 
+**Project overview** (`README.md`):
+- Any new user-visible feature → Features table, Key Concepts section
+
 **CHANGELOG** (`CHANGELOG.md`):
 - Any user-visible change → use the `changelog` skill instead
 
@@ -73,16 +101,58 @@ For each affected area, verify docs match source:
    grep -n 'json:"' internal/core/types.go
    ```
 
-4. Compare each against what's documented in `skills/SKILL.md` and `skills/references/`:
-   - **New flag in code** → add to CLI Flags table + Quick Reference
-   - **New config field** → add to Configuration File section in advanced-features.md
-   - **Removed flag/field** → remove from docs
-   - **Changed behavior** → update description
+4. Compare each against what's documented in `docs/`, `skills/`, and `README.md`:
+   - **New flag in code** → add to `docs/cli-reference.md` Flags table + `skills/SKILL.md` CLI Flags table + Quick Reference
+   - **New config field** → add to `docs/advanced.md` Configuration section + `skills/references/advanced-features.md` Configuration File section
+   - **New execution behavior** → add to `docs/writing-runbooks.md` + `skills/SKILL.md` Writing Runbooks
+   - **New major feature** → add to `README.md` Features table + Key Concepts
+   - **Removed flag/field** → remove from all docs
+   - **Changed behavior** → update description in all affected docs
    - **Every `--flag` / `-flag` in docs** must have a matching hit in source
 
 ### Step 3: Update Documentation
 
-Apply changes following the established structure:
+Apply changes following the established structure. Update **all tiers** that are affected — a new flag needs to appear in `docs/cli-reference.md`, `skills/SKILL.md`, and possibly `README.md`.
+
+#### docs/cli-reference.md structure:
+
+| Section | What to update |
+|---------|---------------|
+| Flags table | Must match `cmd/mdproof/main.go` flag definitions exactly |
+| Subcommands | New subcommands (sandbox, upgrade) |
+| Examples | Add usage examples for new flags |
+
+#### docs/writing-runbooks.md structure:
+
+| Section | What to update |
+|---------|---------------|
+| Code Blocks | New execution behaviors (sub-commands, separators) |
+| Persistent Shell Session | Changes to env persistence model |
+| Assertions | New assertion types or changed behavior |
+| Directives | New HTML comment directives |
+| Inline Testing | Changes to `--inline` mode |
+
+#### docs/advanced.md structure:
+
+| Section | What to update |
+|---------|---------------|
+| Hooks | Per-runbook hooks + per-step hooks |
+| Configuration | `mdproof.json` fields — must match Config struct |
+| Per-Runbook Isolation | Isolation mode changes |
+| Report Formats | JSON, JUnit, plain text changes |
+| Coverage | `--coverage` mode |
+| Watch Mode | `--watch` mode |
+| Container Safety | Strict mode, sandbox changes |
+| CI Integration | CI usage patterns |
+
+#### README.md structure:
+
+| Section | What to update |
+|---------|---------------|
+| Features table | New major features (For AI Agents / For Humans) |
+| Key Concepts | New concepts users should know about |
+| Assertions table | New assertion types |
+| Quick Start | Only if the basic workflow changes |
 
 #### skills/SKILL.md structure:
 
@@ -123,13 +193,15 @@ Apply changes following the established structure:
 
 ### Step 4: Consistency Checks
 
-After updating, verify cross-references are consistent:
+After updating, verify cross-references are consistent across all doc tiers:
 
-1. **Assertion count** — `skills/SKILL.md` says "Six types" → count actual types in assertions-guide.md
-2. **Config example** — JSON example in advanced-features.md must include all Config struct fields
-3. **Flag table** — CLI Flags in SKILL.md must be a complete subset of flags in main.go
-4. **Quick Reference** — examples must use correct flag ordering (flags before file path — Go's `flag` package requirement)
-5. **Report fields** — any jq assertion examples must reference fields that actually exist in the JSON report
+1. **Flag completeness** — every flag in `cmd/mdproof/main.go` must appear in both `docs/cli-reference.md` and `skills/SKILL.md`
+2. **Config completeness** — every `json:"..."` field in Config struct must appear in both `docs/advanced.md` and `skills/references/advanced-features.md` config examples
+3. **Assertion count** — `skills/SKILL.md` says "Six types" → count actual types in assertions-guide.md and `docs/writing-runbooks.md`
+4. **Cross-tier consistency** — `docs/` and `skills/` must not contradict each other (e.g., different flag descriptions, different default values)
+5. **README coverage** — every major feature in Key Concepts should have a corresponding section in `docs/advanced.md`
+6. **Flag ordering** — all CLI examples across all docs must put flags before file paths (Go's `flag` package requirement)
+7. **Report fields** — any jq assertion examples must reference fields that actually exist in the JSON report
 
 ### Step 5: Verify
 
@@ -149,36 +221,48 @@ List all changes made with rationale:
 == Documentation Updates ==
 
 Modified:
+  docs/cli-reference.md
+    - Added -step-setup/-step-teardown to Flags table
+    - Added per-step hooks example
+
+  docs/advanced.md
+    - Added Per-Step Setup/Teardown section
+    - Updated Configuration table with step_setup/step_teardown
+
   skills/SKILL.md
     - Added -step-setup/-step-teardown to CLI Flags table
-    - Added sub-command separator section to Writing Runbooks
 
   skills/references/advanced-features.md
-    - Added Per-Step Setup/Teardown section
     - Updated Configuration File example with step_setup/step_teardown
 
+  README.md
+    - Added per-step hooks to Features table and Key Concepts
+
 No code changes.
 ```
 
 ## Source-to-Doc Mapping Quick Reference
 
-| Source file | Doc file | What to check |
-|------------|----------|---------------|
-| `cmd/mdproof/main.go` | `skills/SKILL.md` | CLI Flags table, Quick Reference |
-| `internal/config/config.go` | `skills/references/advanced-features.md` | Configuration File section |
-| `internal/core/types.go` | `skills/references/assertions-guide.md` | Report field references in jq examples |
-| `internal/assertion/` | `skills/references/assertions-guide.md` | Assertion types and behavior |
-| `internal/executor/session.go` | `skills/references/advanced-features.md` | Execution model, hooks, sub-commands |
-| `internal/report/plain.go` | `skills/references/advanced-features.md` | Plain text report behavior |
-| `internal/report/junit.go` | `skills/references/advanced-features.md` | JUnit report behavior |
+| Source file | Doc files to update | What to check |
+|------------|---------------------|---------------|
+| `cmd/mdproof/main.go` | `docs/cli-reference.md`, `skills/SKILL.md` | Flags table, Quick Reference, Examples |
+| `internal/config/config.go` | `docs/advanced.md`, `skills/references/advanced-features.md` | Configuration section, config JSON example |
+| `internal/core/types.go` | `docs/writing-runbooks.md`, `skills/references/assertions-guide.md` | Report field references in jq examples |
+| `internal/assertion/` | `docs/writing-runbooks.md`, `skills/references/assertions-guide.md` | Assertion types, syntax, behavior |
+| `internal/executor/session.go` | `docs/writing-runbooks.md`, `docs/advanced.md`, `skills/references/advanced-features.md` | Execution model, hooks, sub-commands, persistent session |
+| `internal/report/` | `docs/advanced.md`, `skills/references/advanced-features.md` | Report format behavior (JSON, JUnit, plain) |
+| `internal/parser/` | `docs/writing-runbooks.md`, `skills/SKILL.md` | Step headings, code block handling, inline parsing |
+| Any new feature | `README.md` | Features table, Key Concepts |
 | `CHANGELOG.md` | (use `changelog` skill) | User-facing release notes |
 
 ## Rules
 
 - **Source of truth is Go code** — docs must match what the code actually does
 - **Every flag/config claim must be verified** — grep source before writing docs
+- **Update all tiers** — a new flag must appear in `docs/`, `skills/`, and possibly `README.md`
 - **No speculative docs** — never document planned but unimplemented features
-- **No code changes** — this skill only touches `skills/` and `CHANGELOG.md`
-- **Preserve style** — match existing doc structure and tone
+- **No code changes** — this skill only touches documentation files
+- **Preserve style** — match existing doc structure and tone per tier
 - **Flag ordering** — all CLI examples must put flags before file paths
 - **Config field names** — use the exact `json:"..."` tag from Config struct (snake_case)
+- **`docs/` vs `skills/`** — `docs/` is for human end users (more prose, examples, mermaid diagrams); `skills/` is for AI agents (compact, structured, precise)

README.md

@@ -138,9 +138,13 @@ mdproof sandbox api-proof.md     # auto-provisions a container
 **For Humans**
 - Documentation IS the test — no context switching
 - Readable — anyone can understand what's being tested
-- Lifecycle hooks — build, setup, teardown
+- Lifecycle hooks — `--build`, `--setup`/`--teardown`, `-step-setup`/`-step-teardown`
 - Container-first — safe by default, sandbox mode
-- Persistent sessions — env vars flow across steps
+- Persistent sessions — env vars flow across steps and `---` sub-commands
+- Per-runbook isolation — `--isolation per-runbook` for clean `$HOME`/`$TMPDIR`
+- Step filtering — `--steps 1,3`, `--from N`, `--fail-fast`
+- Coverage & watch — `--coverage` for CI gating, `--watch` for live re-runs
+- Inline testing — `--inline` validates code examples in any `.md`
 - Zero dependencies — pure Go stdlib, single binary
 
 </td>
@@ -223,10 +227,17 @@ No `Expected:` section → exit code decides (0 = pass).
 
 ### Key Concepts
 
-- **Persistent session** — all steps share one bash process; `export` vars persist across steps
+- **Persistent session** — all steps share one bash process; `export` vars persist across steps and `---` sub-commands
 - **Container-first** — strict mode (default) refuses to run outside containers; use `mdproof sandbox` or `--strict=false`
-- **Hooks** — `--build` (once), `--setup` / `--teardown` (per runbook) for lifecycle management
-- **Directives** — `<!-- runbook: timeout=30s retry=3 -->` for per-step control
+- **Hooks** — `--build` (once), `--setup` / `--teardown` (per runbook), `-step-setup` / `-step-teardown` (per step)
+- **Directives** — `<!-- runbook: timeout=30s retry=3 depends=2 -->` for per-step control
+- **Sub-commands** — `---` separator splits a code block into independent subshells with shared env
+- **Isolation** — `--isolation per-runbook` gives each runbook a fresh `$HOME` and `$TMPDIR`
+- **Step filtering** — `--steps 1,3,5` or `--from N` to run a subset; `--fail-fast` to stop early
+- **Coverage** — `--coverage` reports assertion coverage; `--coverage-min N` for CI gating
+- **Watch mode** — `--watch` re-runs tests on file changes
+- **Inline testing** — `--inline` extracts `<!-- mdproof:start/end -->` blocks from any `.md`
+- **Snapshots** — `snapshot:` assertions with `-u` to update
 
 ## Documentation
 

docs/advanced.md

@@ -78,9 +78,26 @@ flowchart LR
 | `build` | Once, before all runbooks | Abort — nothing runs |
 | `setup` | Per runbook, before steps | All steps skipped |
 | `teardown` | Per runbook, after steps | Informational only |
+| `step-setup` | Per step, before step body | Step marked failed, body skipped |
+| `step-teardown` | Per step, after step body | Informational only |
 
 Setup and teardown run inside the same bash session as the steps, so they share environment variables. Build runs as a separate process.
 
+### Per-Step Setup/Teardown
+
+Distinct from per-runbook hooks, these run before/after **each step**:
+
+```bash
+mdproof -step-setup 'rm -rf /tmp/test-state && mkdir -p /tmp/test-state' test.md
+mdproof -step-teardown 'echo step done' test.md
+mdproof -step-setup 'reset-db' -step-teardown 'dump-logs' test.md
+```
+
+- Step-setup stdout is **not** mixed into step stdout
+- JSON report includes `step_setup` and `step_teardown` objects with `exit_code`, `stdout`, `stderr`
+- When neither flag is provided, no `step_setup`/`step_teardown` fields appear in the report
+- With retry (`<!-- runbook: retry=N -->`), each attempt runs the full cycle: setup → body → teardown
+
 ## Configuration
 
 Create `mdproof.json` in the runbook directory:
@@ -90,8 +107,11 @@ Create `mdproof.json` in the runbook directory:
   "build": "make build",
   "setup": "docker-compose up -d",
   "teardown": "docker-compose down",
+  "step_setup": "rm -rf /tmp/test-state",
+  "step_teardown": "echo step done",
   "timeout": "5m",
   "strict": false,
+  "isolation": "per-runbook",
   "env": {
     "LOG_LEVEL": "debug",
     "API_URL": "http://localhost:8080"
@@ -104,8 +124,11 @@ Create `mdproof.json` in the runbook directory:
 | `build` | string | Command to run once before all runbooks |
 | `setup` | string | Command to run before each runbook |
 | `teardown` | string | Command to run after each runbook |
+| `step_setup` | string | Command to run before each step |
+| `step_teardown` | string | Command to run after each step |
 | `timeout` | string | Default per-step timeout (e.g. `"2m"`, `"30s"`) |
 | `strict` | boolean | Container-only execution (default: `true`) |
+| `isolation` | string | `"shared"` (default) or `"per-runbook"` |
 | `env` | object | Environment variables seeded into all steps |
 
 Sandbox settings can also be configured:
@@ -122,6 +145,46 @@ Sandbox settings can also be configured:
 
 CLI flags override config file values.
 
+## Per-Runbook Isolation
+
+By default, all runbooks share the host's `$HOME` and `$TMPDIR`. With `--isolation per-runbook`, each runbook gets a fresh temp directory as `$HOME` with `$TMPDIR` under `$HOME/tmp`, cleaned up after each runbook:
+
+```bash
+mdproof --isolation per-runbook ./runbooks/
+```
+
+Or in `mdproof.json`:
+
+```json
+{ "isolation": "per-runbook" }
+```
+
+- Build hook (`--build`) runs in the original environment — not affected by isolation
+- Setup/teardown hooks inherit the isolated `$HOME`/`$TMPDIR`
+- Invalid values produce an error at config load time
+- CLI `--isolation` overrides the config file value
+
+## Report Formats
+
+### JSON
+
+```bash
+mdproof --report json test.md          # single object to stdout
+mdproof --report json ./runbooks/      # JSON array to stdout
+mdproof -o results.json ./runbooks/    # always writes JSON array to file
+```
+
+Single-file mode outputs one JSON object; directory mode outputs a JSON array.
+
+### JUnit XML
+
+```bash
+mdproof --report junit ./runbooks/              # stdout
+mdproof --report junit -o results.xml ./runbooks/  # file
+```
+
+Produces JUnit XML for native CI test result display (GitHub Actions, GitLab CI, Jenkins). Sub-command exit codes and stderr are included in failure bodies.
+
 ## Coverage
 
 Analyze assertion coverage of your runbooks without executing them:
@@ -251,7 +314,7 @@ Once installed, your AI agent can autonomously:
 
 - Write runbook files with correct naming (`*-proof.md`, `*_runbook.md`)
 - Use all 6 assertion types (substring, exit_code, regex, jq, snapshot, negated)
-- Configure hooks (build, setup, teardown) and `mdproof.json`
+- Configure hooks (build, setup, teardown, step-setup, step-teardown) and `mdproof.json`
 - Apply directives (timeout, retry, depends)
 - Handle container safety (`MDPROOF_ALLOW_EXECUTE=1`)
 - Run with the right flags and interpret results