fix: resolve merge conflict with main, bump to v0.15.2.0

Main advanced to v0.15.1.0 (Session Intelligence + Design Without Shotgun).
Our voice triggers branch bumped to v0.15.2.0 on top.

Conflicts resolved:
- CHANGELOG.md: placed our v0.15.2.0 entry above main's v0.15.1.0 and v0.15.0.0
- VERSION/package.json: bumped to 0.15.2.0
- design-html/SKILL.md.tmpl: took main's updated description + kept our voice-triggers
- design-html/SKILL.md: regenerated from resolved template

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

CONTRIBUTING.md

@@ -40,8 +40,8 @@ No setup needed. Learnings are logged automatically. View them with `/learn`.
    ln -sfn /path/to/your/gstack-fork .claude/skills/gstack
    cd .claude/skills/gstack && bun install && bun run build && ./setup
    ```
-   Setup creates the per-skill symlinks (`qa -> gstack/qa`, etc.) and asks your
-   prefix preference. Pass `--no-prefix` to skip the prompt and use short names.
+   Setup creates per-skill directories with SKILL.md symlinks inside (`qa/SKILL.md -> gstack/qa/SKILL.md`)
+   and asks your prefix preference. Pass `--no-prefix` to skip the prompt and use short names.
 5. **Fix the issue** — your changes are live immediately in this project
 6. **Test by actually using gstack** — do the thing that annoyed you, verify it's fixed
 7. **Open a PR from your fork**
@@ -64,9 +64,11 @@ your local edits instead of the global install.
 gstack/                          <- your working tree
 ├── .claude/skills/              <- created by dev-setup (gitignored)
 │   ├── gstack -> ../../         <- symlink back to repo root
-│   ├── review -> gstack/review  <- short names (default)
-│   ├── ship -> gstack/ship      <- or gstack-review, gstack-ship if --prefix
-│   └── ...                      <- one symlink per skill
+│   ├── review/                  <- real directory (short name, default)
+│   │   └── SKILL.md -> gstack/review/SKILL.md
+│   ├── ship/                    <- or gstack-review/, gstack-ship/ if --prefix
+│   │   └── SKILL.md -> gstack/ship/SKILL.md
+│   └── ...                      <- one directory per skill
 ├── review/
 │   └── SKILL.md                 <- edit this, test with /review
 ├── ship/
@@ -77,7 +79,9 @@ gstack/                          <- your working tree
 └── ...
 ```
 
-Skill symlink names depend on your prefix setting (`~/.gstack/config.yaml`).
+Setup creates real directories (not symlinks) at the top level with a SKILL.md
+symlink inside. This ensures Claude discovers them as top-level skills, not nested
+under `gstack/`. Names depend on your prefix setting (`~/.gstack/config.yaml`).
 Short names (`/review`, `/ship`) are the default. Run `./setup --prefix` if you
 prefer namespaced names (`/gstack-review`, `/gstack-ship`).
 
@@ -320,7 +324,7 @@ ln -sfn /path/to/your/gstack-checkout .claude/skills/gstack
 ### Step 2: Run setup to create per-skill symlinks
 
 The `gstack` symlink alone isn't enough. Claude Code discovers skills through
-individual symlinks (`qa -> gstack/qa`, `ship -> gstack/ship`, etc.), not through
+individual top-level directories (`qa/SKILL.md`, `ship/SKILL.md`, etc.), not through
 the `gstack/` directory itself. Run `./setup` to create them:
 
 ```bash
@@ -344,8 +348,8 @@ Remove the project-local symlink. Claude Code falls back to `~/.claude/skills/gs
 rm .claude/skills/gstack
 ```
 
-The per-skill symlinks (`qa`, `ship`, etc.) still point to `gstack/...`, so they'll
-resolve to the global install automatically.
+The per-skill directories (`qa/`, `ship/`, etc.) contain SKILL.md symlinks that point
+to `gstack/...`, so they'll resolve to the global install automatically.
 
 ### Switching prefix mode
 
@@ -388,6 +392,56 @@ When community PRs accumulate, batch them into themed waves:
 
 See [PR #205](../../pull/205) (v0.8.3) for the first wave as an example.
 
+## Upgrade migrations
+
+When a release changes on-disk state (directory structure, config format, stale
+files) in ways that `./setup` alone can't fix, add a migration script so existing
+users get a clean upgrade.
+
+### When to add a migration
+
+- Changed how skill directories are created (symlinks vs real dirs)
+- Renamed or moved config keys in `~/.gstack/config.yaml`
+- Need to delete orphaned files from a previous version
+- Changed the format of `~/.gstack/` state files
+
+Don't add a migration for: new features (users get them automatically), new
+skills (setup discovers them), or code-only changes (no on-disk state).
+
+### How to add one
+
+1. Create `gstack-upgrade/migrations/v{VERSION}.sh` where `{VERSION}` matches
+   the VERSION file for the release that needs the fix.
+2. Make it executable: `chmod +x gstack-upgrade/migrations/v{VERSION}.sh`
+3. The script must be **idempotent** (safe to run multiple times) and
+   **non-fatal** (failures are logged but don't block the upgrade).
+4. Include a comment block at the top explaining what changed, why the
+   migration is needed, and which users are affected.
+
+Example:
+
+```bash
+#!/usr/bin/env bash
+# Migration: v0.15.2.0 — Fix skill directory structure
+# Affected: users who installed with --no-prefix before v0.15.2.0
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+"$SCRIPT_DIR/bin/gstack-relink" 2>/dev/null || true
+```
+
+### How it runs
+
+During `/gstack-upgrade`, after `./setup` completes (Step 4.75), the upgrade
+skill scans `gstack-upgrade/migrations/` and runs every `v*.sh` script whose
+version is newer than the user's old version. Scripts run in version order.
+Failures are logged but never block the upgrade.
+
+### Testing migrations
+
+Migrations are tested as part of `bun test` (tier 1, free). The test suite
+verifies that all migration scripts in `gstack-upgrade/migrations/` are
+executable and parse without syntax errors.
+
 ## Shipping your changes
 
 When you're happy with your skill edits: