feat: Cursor/Codex parity + README showcase + GitHub polish

Cursor parity:
  .cursor/rules — Cursor Composer context file with VP2026 domain facts,
  component quick reference, skill invocation guide, and what's implemented
  vs pending. Drop into any voice-anonymization project alongside the skills.

Codex parity:
  AGENTS.md — comprehensive Codex context (was deleted in v0.2, now restored
  and updated for zero-code architecture). Covers metric directions, B1 script
  extraction, experiment logging, project structure, and workflow commands.
  Copy into user's project root for Codex to pick up automatically.

README rewrite — /vp-ship showcase:
  Full end-to-end workflow: hypothesis → spike → attack → repro-check → ship.
  Shows realistic terminal output at each step including EER numbers,
  PASS_STRONG output, deferred gate check, and PR creation. Matches the
  gstack "How it works" pattern — concrete, honest about what's pending.

  Install section now has three parallel paths:
    Claude Code  → git clone to ~/.claude/skills/vpstack/
    Codex        → same clone + copy AGENTS.md to project
    Cursor       → same clone + copy .cursor/rules to project

  Status table shows exactly what works (B1, all 15 skills, logging,
  repro-check, all three clients) vs what's pending (B2, full eval, attacker).

23/23 tests pass.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

.cursor/rules

@@ -0,0 +1,57 @@
+# vpstack — Cursor Rules
+
+You are helping with VP2026 voice-privacy research. Read docs/domain.md for
+the full domain reference. This file gives you the essentials.
+
+## Critical domain facts
+
+- EER: HIGHER = more private. 50% = random attacker = perfect anonymization (the goal).
+- WER: LOWER = better utility.
+- Linkability: LOWER = harder to link speaker identities.
+- ALWAYS report semi-informed attacker EER — it's the official VP2026 ranking metric.
+- DO NOT use VP2020/VP2022/VP2024 numbers. Run baselines on your VP2026 data.
+
+## Running B1 McAdams baseline
+
+The B1 script lives in skills/vp-baseline-compare/SKILL.md as an inline template.
+Extract it and run:
+
+```bash
+# Write the script (see vp-baseline-compare/SKILL.md Step 4 for the full template)
+python3 /tmp/vp_b1_run.py --data_path /path/to/audio --seed 42
+# pip install soundfile scipy numpy  (if needed)
+```
+
+## Running skills in Cursor
+
+Skills (skills/*/SKILL.md) are step-by-step workflows. In Cursor:
+1. Open the relevant SKILL.md in the sidebar
+2. Follow the steps in Composer — run bash commands inline, write files to ~/.vpstack/
+3. Reference docs/domain.md for component tradeoffs and known issues
+
+## Experiment logging
+
+Write to ~/.vpstack/projects/{slug}/experiments/{exp_id}/summary.json
+Get slug: run `~/.claude/skills/vpstack/bin/vpstack-slug` in terminal.
+
+## What's implemented vs pending
+
+- B1 McAdams anonymization: WORKING (see Step 4 in vp-baseline-compare/SKILL.md)
+- B2 neural pipeline: PENDING v0.3
+- ASV attacker: requires official VP2026 challenge attacker script (not bundled)
+- Full EER/WER eval: PENDING v0.3
+
+## Component quick reference
+
+- HuBERT layers 1-4: speaker-leaning (avoid for content encoder)
+- HuBERT layer 6: standard B2 default
+- HuBERT layers 7-9: phonetic content peak (best disentanglement)
+- ECAPA-TDNN: speaker embeddings; farthest-point selection = stronger anonymization
+- HiFi-GAN: use LibriTTS-finetuned weights, not v1 universal (wrong sample rate)
+- McAdams alpha=0.8: canonical B1; alpha<0.6 = artifacts; alpha>0.95 = no anonymization
+
+## Rules
+
+- No VP2024 GPLv3 code
+- No bundled model weights
+- All metrics must be VP2026-specific (run your own baselines)

AGENTS.md

@@ -0,0 +1,115 @@
+# AGENTS.md — Context for Codex and other AI agents
+
+vpstack is a voice-privacy research toolkit for the VoicePrivacy 2026 challenge.
+Read this before writing any code or running any commands in this project.
+
+---
+
+## What this repo is
+
+vpstack gives AI coding agents domain knowledge for VP2026 voice anonymization research.
+No MCP server. No Python code in the repo. Skills are markdown files that tell Claude
+(or you) what bash commands to run. You are the execution engine.
+
+**If you're helping in a *user's* voice-anonymization project** (not this repo),
+copy `docs/domain.md` and `docs/claude-md-template.md` into that project for context.
+
+---
+
+## Critical domain facts — read before doing anything
+
+**Metrics (never get these backwards):**
+- EER (Equal Error Rate): **HIGHER = more private**. 50% = random = perfect anonymization.
+- WER (Word Error Rate): **LOWER = more useful**. 0% = perfect transcription.
+- Linkability (ZEBRA Cllr): **LOWER = harder to link speakers**.
+- Always report **semi-informed** attacker condition — that's the VP2026 ranking metric.
+
+**Baselines — run on YOUR VP2026 data, never use hardcoded numbers from older years:**
+- B1 (McAdams): signal-processing, CPU, fast. Weak anonymization. The floor to beat.
+- B2 (HuBERT + ECAPA-TDNN + HiFi-GAN): neural, GPU. Strong. The real target. NOT yet implemented in vpstack.
+
+**B1 McAdams script:** The skill `vp-baseline-compare` contains a self-contained Python
+script that Claude writes to `/tmp/vp_b1_run.py`. You can extract and run it directly:
+```bash
+# Extract and run B1 on your data
+python3 /tmp/vp_b1_run.py --data_path /path/to/your/audio --seed 42
+# Requires: pip install soundfile scipy numpy
+```
+
+---
+
+## Running VP2026 skills as Codex
+
+Skills are in `skills/*/SKILL.md`. Each is a step-by-step workflow.
+To execute a skill as Codex:
+
+1. Read the SKILL.md file
+2. Follow the steps — run bash commands, write files, ask the user questions
+3. Write experiment state to `~/.vpstack/projects/{slug}/`
+
+Get your project slug:
+```bash
+~/.claude/skills/vpstack/bin/vpstack-slug
+# or: python3 -c "import hashlib,os,subprocess; t=subprocess.check_output(['git','rev-parse','--show-toplevel']).decode().strip(); print(f'{os.path.basename(t)}-{hashlib.sha256(t.encode()).hexdigest()[:8]}')"
+```
+
+Log an experiment (Write tool or direct file write):
+```bash
+mkdir -p ~/.vpstack/projects/$SLUG/experiments/$EXP_ID
+cat > ~/.vpstack/projects/$SLUG/experiments/$EXP_ID/summary.json << 'EOF'
+{
+  "id": "your-exp-id",
+  "date": "2026-04-29T00:00:00Z",
+  "config_hash": "abc123",
+  "metrics": {"eer": 38.2, "wer": 8.1},
+  "method": "B1-alpha0.8",
+  "hypothesis": "your hypothesis text"
+}
+EOF
+```
+
+---
+
+## Workflow for a typical VP2026 experiment
+
+```bash
+# 1. Formalize hypothesis (read skills/vp-hypothesis/SKILL.md, follow steps)
+# 2. Run B1 anonymization
+python3 /tmp/vp_b1_run.py --data_path /path/to/data --seed 42
+
+# 3. Run attacker (requires VP2026 challenge attacker script)
+python3 run_attacker.py \
+  --anonymized_path /path/to/anon \
+  --enrollment_path /path/to/enrollment \
+  --trial_list /path/to/trials.txt \
+  --attacker_condition semi_informed \
+  --output_format json --seed 42
+
+# 4. Reproducibility check (read skills/vp-repro-check/SKILL.md)
+grep -E "^seed: [0-9]+" your_config.yaml || echo "FAIL: seed missing"
+grep -E "^(data|splits):" your_config.yaml || echo "FAIL: no splits"
+grep -E "TODO|FILL_ME" your_config.yaml && echo "FAIL: placeholder hparams"
+
+# 5. Log result (write summary.json as above)
+```
+
+---
+
+## Project structure
+
+```
+skills/           15 SKILL.md workflows — follow these step by step
+bin/              Bash scripts (slug, detect, skill-init, telemetry)
+docs/domain.md    Full VP2026 domain reference (metrics, components, known issues)
+docs/claude-md-template.md  Copy into user's project CLAUDE.md
+tests/            Activation + telemetry tests (bash-based)
+```
+
+---
+
+## Rules
+
+1. **Never import VP2024 GitHub code** — it's GPLv3. Implement from the Eval Plan PDF.
+2. **Never bundle pretrained weights** — fetch from HuggingFace at runtime.
+3. **VP2026 metrics only** — do not use VP2020/VP2022 numbers as references.
+4. **No Python code in this repo** — skills are markdown, bin/ is bash.