feat: SKILL.md template system, 3-tier testing, DX tools (v0.3.3) (#41)

* refactor: extract command registry to commands.ts, add SNAPSHOT_FLAGS metadata

- NEW: browse/src/commands.ts — command sets + COMMAND_DESCRIPTIONS + load-time validation (zero side effects)
- server.ts imports from commands.ts instead of declaring sets inline
- snapshot.ts: SNAPSHOT_FLAGS array drives parseSnapshotArgs (metadata-driven, no duplication)
- All 186 existing tests pass

* feat: SKILL.md template system with auto-generated command references

- SKILL.md.tmpl + browse/SKILL.md.tmpl with {{COMMAND_REFERENCE}} and {{SNAPSHOT_FLAGS}} placeholders
- scripts/gen-skill-docs.ts generates SKILL.md from templates (supports --dry-run)
- Build pipeline runs gen:skill-docs before binary compilation
- Generated files have AUTO-GENERATED header, committed to git

* test: Tier 1 static validation — 34 tests for SKILL.md command correctness

- test/helpers/skill-parser.ts: extracts $B commands from code blocks, validates against registry
- test/skill-parser.test.ts: 13 parser/validator unit tests
- test/skill-validation.test.ts: 13 tests validating all SKILL.md files + registry consistency
- test/gen-skill-docs.test.ts: 8 generator tests (categories, sorting, freshness)

* feat: DX tools (skill:check, dev:skill) + Tier 2 E2E test scaffolding

- scripts/skill-check.ts: health summary for all SKILL.md files (commands, templates, freshness)
- scripts/dev-skill.ts: watch mode for template development
- test/helpers/session-runner.ts: Agent SDK wrapper for E2E skill tests
- test/skill-e2e.test.ts: 2 E2E tests + 3 stubs (auto-skip inside Claude Code sessions)
- E2E tests must run from plain terminal: SKILL_E2E=1 bun test test/skill-e2e.test.ts

* ci: SKILL.md freshness check on push/PR + TODO updates

- .github/workflows/skill-docs.yml: fails if generated SKILL.md files are stale
- TODO.md: add E2E cost tracking and model pinning to future ideas

* fix: restore rich descriptions lost in auto-generation

- Snapshot flags: add back value hints (-d <N>, -s <sel>, -o <path>)
- Snapshot flags: restore parenthetical context (@e refs, @c refs, etc.)
- Commands: is → includes valid states enum
- Commands: console → notes --errors filter behavior
- Commands: press → lists common keys (Enter, Tab, Escape)
- Commands: cookie-import-browser → describes picker UI
- Commands: dialog-accept → specifies alert/confirm/prompt
- Tips: restore → arrow (was downgraded to ->)

* test: quality evals for generated SKILL.md descriptions

Catches the exact regressions we shipped and caught in review:
- Snapshot flags must include value hints (-d <N>, -s <sel>, -o <path>)
- is command must list all valid states (visible/hidden/enabled/...)
- press command must list example keys (Enter, Tab, Escape)
- console command must describe --errors behavior
- Snapshot -i must mention @e refs, -C must mention @c refs
- All descriptions must be >= 8 chars (no empty stubs)
- Tips section must use → not ->

* feat: LLM-as-judge evals for SKILL.md documentation quality

4 eval tests using Anthropic API (claude-haiku, ~$0.01-0.03/run):
- Command reference table: clarity/completeness/actionability >= 4/5
- Snapshot flags section: same thresholds
- browse/SKILL.md overall quality
- Regression: generated version must score >= hand-maintained baseline

Requires ANTHROPIC_API_KEY. Auto-skips without it.
Run: bun run test:eval (or ANTHROPIC_API_KEY=sk-... bun test test/skill-llm-eval.test.ts)

* chore: bump version to 0.3.3, update changelog

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add ARCHITECTURE.md, update CLAUDE.md and CONTRIBUTING.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: conductor.json lifecycle hooks + .env propagation across worktrees

bin/dev-setup now copies .env from main worktree so API keys carry
over to Conductor workspaces automatically. conductor.json wires up
setup and archive hooks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: complete CHANGELOG for v0.3.3 (architecture, conductor, .env)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

SKILL.md

@@ -12,6 +12,8 @@ allowed-tools:
   - Read
 
 ---
+<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
+<!-- Regenerate: bun run gen:skill-docs -->
 
 # gstack browse: QA Testing & Dogfooding
 
@@ -239,15 +241,15 @@ $B css ".button" "background-color"
 
 The snapshot is your primary tool for understanding and interacting with pages.
 
-```bash
-$B snapshot -i           # Interactive elements only (buttons, links, inputs) with @e refs
-$B snapshot -c           # Compact (no empty structural elements)
-$B snapshot -d 3         # Limit depth to 3 levels
-$B snapshot -s "main"    # Scope to CSS selector
-$B snapshot -D           # Diff against previous snapshot (what changed?)
-$B snapshot -a           # Annotated screenshot with ref labels
-$B snapshot -o /tmp/x.png  # Output path for annotated screenshot
-$B snapshot -C           # Cursor-interactive elements (@c refs — divs with pointer, onclick)
+```
+-i        Interactive elements only (buttons, links, inputs) with @e refs
+-c        Compact (no empty structural nodes)
+-d <N>    Limit depth
+-s <sel>  Scope to CSS selector
+-D        Diff against previous snapshot (what changed?)
+-a        Annotated screenshot with ref labels
+-o <path> Output path for screenshot
+-C        Cursor-interactive elements (@c refs — divs with pointer, onclick)
 ```
 
 Combine flags: `$B snapshot -i -a -C -o /tmp/annotated.png`
@@ -266,77 +268,89 @@ Refs are invalidated on navigation — run `snapshot` again after `goto`.
 ### Navigation
 | Command | Description |
 |---------|-------------|
+| `back` | History back |
+| `forward` | History forward |
 | `goto <url>` | Navigate to URL |
-| `back` / `forward` | History navigation |
 | `reload` | Reload page |
 | `url` | Print current URL |
 
 ### Reading
 | Command | Description |
 |---------|-------------|
-| `text` | Cleaned page text |
-| `html [selector]` | innerHTML |
-| `links` | All links as "text -> href" |
-| `forms` | Forms + fields as JSON |
 | `accessibility` | Full ARIA tree |
+| `forms` | Form fields as JSON |
+| `html [selector]` | innerHTML |
+| `links` | All links as "text → href" |
+| `text` | Cleaned page text |
 
 ### Interaction
 | Command | Description |
 |---------|-------------|
 | `click <sel>` | Click element |
-| `fill <sel> <val>` | Fill input |
-| `select <sel> <val>` | Select dropdown |
-| `hover <sel>` | Hover element |
-| `type <text>` | Type into focused element |
-| `press <key>` | Press key (Enter, Tab, Escape) |
-| `scroll [sel]` | Scroll element into view |
-| `wait <sel>` | Wait for element (max 10s) |
-| `wait --networkidle` | Wait for network to be idle |
-| `wait --load` | Wait for page load event |
-| `upload <sel> <file...>` | Upload file(s) |
+| `cookie` | Set cookie |
 | `cookie-import <json>` | Import cookies from JSON file |
-| `cookie-import-browser [browser] [--domain <d>]` | Import cookies from real browser (opens picker UI, or direct import with --domain) |
-| `dialog-accept [text]` | Auto-accept dialogs |
-| `dialog-dismiss` | Auto-dismiss dialogs |
+| `cookie-import-browser [browser] [--domain d]` | Import cookies from real browser (opens picker UI, or direct with --domain) |
+| `dialog-accept [text]` | Auto-accept next alert/confirm/prompt |
+| `dialog-dismiss` | Auto-dismiss next dialog |
+| `fill <sel> <val>` | Fill input |
+| `header <name> <value>` | Set custom request header |
+| `hover <sel>` | Hover element |
+| `press <key>` | Press key (Enter, Tab, Escape, etc.) |
+| `scroll [sel]` | Scroll element into view |
+| `select <sel> <val>` | Select dropdown option |
+| `type <text>` | Type into focused element |
+| `upload <sel> <file...>` | Upload file(s) |
+| `useragent <string>` | Set user agent |
 | `viewport <WxH>` | Set viewport size |
+| `wait <sel|--networkidle|--load>` | Wait for element/condition |
 
 ### Inspection
 | Command | Description |
 |---------|-------------|
-| `js <expr>` | Run JavaScript |
-| `eval <file>` | Run JS file |
-| `css <sel> <prop>` | Computed CSS |
-| `attrs <sel>` | Element attributes |
-| `is <prop> <sel>` | State check (visible/hidden/enabled/disabled/checked/editable/focused) |
-| `console [--clear\|--errors]` | Console messages (--errors filters to error/warning) |
-| `network [--clear]` | Network requests |
+| `attrs <sel|@ref>` | Element attributes as JSON |
+| `console [--clear|--errors]` | Console messages (--errors filters to error/warning) |
+| `cookies` | All cookies as JSON |
+| `css <sel> <prop>` | Computed CSS value |
 | `dialog [--clear]` | Dialog messages |
-| `cookies` | All cookies |
-| `storage` | localStorage + sessionStorage |
+| `eval <file>` | Run JS file |
+| `is <prop> <sel>` | State check (visible/hidden/enabled/disabled/checked/editable/focused) |
+| `js <expr>` | Run JavaScript |
+| `network [--clear]` | Network requests |
 | `perf` | Page load timings |
+| `storage [set k v]` | localStorage + sessionStorage |
 
 ### Visual
 | Command | Description |
 |---------|-------------|
-| `screenshot [path]` | Screenshot |
+| `diff <url1> <url2>` | Text diff between pages |
 | `pdf [path]` | Save as PDF |
 | `responsive [prefix]` | Mobile/tablet/desktop screenshots |
-| `diff <url1> <url2>` | Text diff between pages |
+| `screenshot [path]` | Save screenshot |
+
+### Snapshot
+| Command | Description |
+|---------|-------------|
+| `snapshot [flags]` | Accessibility tree with @refs |
+
+### Meta
+| Command | Description |
+|---------|-------------|
+| `chain` | Multi-command from JSON stdin |
 
 ### Tabs
 | Command | Description |
 |---------|-------------|
-| `tabs` | List tabs |
-| `tab <id>` | Switch tab |
-| `newtab [url]` | Open tab |
 | `closetab [id]` | Close tab |
+| `newtab [url]` | Open new tab |
+| `tab <id>` | Switch to tab |
+| `tabs` | List open tabs |
 
 ### Server
 | Command | Description |
 |---------|-------------|
+| `restart` | Restart server |
 | `status` | Health check |
-| `stop` | Shutdown |
-| `restart` | Restart |
+| `stop` | Shutdown server |
 
 ## Tips