@mizyoel/mercury-mesh 0.9.4

package/.copilot/skills/git-workflow/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: "git-workflow"
+description: "Mercury Mesh branching model: dev-first workflow with insiders preview channel"
+domain: "version-control"
+confidence: "high"
+source: "team-decision"
+---
+
+## Context
+
+Mercury Mesh uses a three-branch model. **All feature work starts from `dev`, not `main`.**
+
+| Branch | Purpose | Publishes |
+|--------|---------|-----------|
+| `main` | Released, tagged, in-npm code only | `npm publish` on tag |
+| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge |
+| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync |
+
+## Branch Naming Convention
+
+Issue branches MUST use: `mesh/{issue-number}-{kebab-case-slug}`
+
+Examples:
+- `mesh/195-fix-version-stamp-bug`
+- `mesh/42-add-profile-api`
+
+> The legacy prefix `mesh/{issue-number}-{slug}` remains compatible during the migration phase.
+
+## Workflow for Issue Work
+
+1. **Branch from dev:**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git checkout -b mesh/{issue-number}-{slug}
+   ```
+
+2. **Mark issue in-progress:**
+   ```bash
+   gh issue edit {number} --add-label "status:in-progress"
+   ```
+
+3. **Create draft PR targeting dev:**
+   ```bash
+   gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft
+   ```
+
+4. **Do the work.** Make changes, write tests, commit with issue reference.
+
+5. **Push and mark ready:**
+   ```bash
+   git push -u origin mesh/{issue-number}-{slug}
+   gh pr ready
+   ```
+
+6. **After merge to dev:**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git branch -d mesh/{issue-number}-{slug}
+   git push origin --delete mesh/{issue-number}-{slug}
+   ```
+
+## Parallel Multi-Issue Work (Worktrees)
+
+When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead.
+
+### When to Use Worktrees vs Sequential
+
+| Scenario | Strategy |
+|----------|----------|
+| Single issue | Standard workflow above — no worktree needed |
+| 2+ simultaneous issues in same repo | Worktrees — one per issue |
+| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) |
+
+### Setup
+
+From the main clone (must be on dev or any branch):
+
+```bash
+# Ensure dev is current
+git fetch origin dev
+
+# Create a worktree per issue — siblings to the main clone
+git worktree add ../mesh-195 -b mesh/195-fix-stamp-bug origin/dev
+git worktree add ../mesh-193 -b mesh/193-refactor-loader origin/dev
+```
+
+**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../mesh-195`, `../mesh-pr-42`).
+
+Each worktree:
+- Has its own working directory and index
+- Is on its own `mesh/{issue-number}-{slug}` branch from dev
+- Shares the same `.git` object store (disk-efficient)
+
+### Per-Worktree Agent Workflow
+
+Each agent operates inside its worktree exactly like the single-issue workflow:
+
+```bash
+cd ../mesh-195
+
+# Work normally — commits, tests, pushes
+git add -A && git commit -m "fix: stamp bug (#195)"
+git push -u origin mesh/195-fix-stamp-bug
+
+# Create PR targeting dev
+gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft
+```
+
+All PRs target `dev` independently. Agents never interfere with each other's filesystem.
+
+### Runtime State in Worktrees
+
+The runtime directory (`.mesh/` or `.mesh/`) exists in each worktree as a copy. This is safe because:
+- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs)
+- Each agent appends to its own section; union merge reconciles on PR merge to dev
+- **Rule:** Never rewrite or reorder runtime state files in a worktree — append only
+
+### Cleanup After Merge
+
+After a worktree's PR is merged to dev:
+
+```bash
+# From the main clone
+git worktree remove ../mesh-195
+git worktree prune          # clean stale metadata
+git branch -d mesh/195-fix-stamp-bug
+git push origin --delete mesh/195-fix-stamp-bug
+```
+
+If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state.
+
+---
+
+## Multi-Repo Downstream Scenarios
+
+When work spans multiple repositories (e.g., Mercury Mesh-cli changes need Mercury Mesh-sdk changes, or a user's app depends on Mercury Mesh):
+
+### Setup
+
+Clone downstream repos as siblings to the main repo:
+
+```
+~/work/
+  Mercury Mesh-pr/          # main repo
+  Mercury Mesh-sdk/         # downstream dependency
+  user-app/          # consumer project
+```
+
+Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Mercury Mesh conventions, use `mesh/{issue-number}-{slug}`.
+
+### Coordinated PRs
+
+- Create PRs in each repo independently
+- Link them in PR descriptions:
+  ```
+  Closes #42
+
+  **Depends on:** Mercury Mesh-sdk PR #17 (Mercury Mesh-sdk changes required for this feature)
+  ```
+- Merge order: dependencies first (e.g., Mercury Mesh-sdk), then dependents (e.g., Mercury Mesh-cli)
+
+### Local Linking for Testing
+
+Before pushing, verify cross-repo changes work together:
+
+```bash
+# Node.js / npm
+cd ../Mercury Mesh-sdk && npm link
+cd ../Mercury Mesh-pr && npm link Mercury Mesh-sdk
+
+# Go
+# Use replace directive in go.mod:
+# replace github.com/org/Mercury Mesh-sdk => ../Mercury Mesh-sdk
+
+# Python
+cd ../Mercury Mesh-sdk && pip install -e .
+```
+
+**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs.
+
+### Worktrees + Multi-Repo
+
+These compose naturally. You can have:
+- Multiple worktrees in the main repo (parallel issues)
+- Separate clones for downstream repos
+- Each combination operates independently
+
+---
+
+## Anti-Patterns
+
+- ❌ Branching from main (branch from dev)
+- ❌ PR targeting main directly (target dev)
+- ❌ Non-conforming branch names (must be Mercury Mesh/{number}-{slug})
+- ❌ Committing directly to main or dev (use PRs)
+- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead)
+- ❌ Using worktrees for cross-repo work (use separate clones)
+- ❌ Leaving stale worktrees after PR merge (clean up immediately)
+
+## Promotion Pipeline
+
+- dev → insiders: Automated sync on green build
+- dev → main: Manual merge when ready for stable release, then tag
+- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent

package/.copilot/skills/github-multi-account/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: github-multi-account
+description: Detect and set up account-locked gh aliases for multi-account GitHub. The AI reads this skill, detects accounts, asks the user which is personal/work, and runs the setup automatically.
+confidence: high
+source: https://github.com/tamirdresher/Mercury Mesh-skills/tree/main/plugins/github-multi-account
+author: tamirdresher
+---
+
+# GitHub Multi-Account — AI-Driven Setup
+
+## When to Activate
+When the user has multiple GitHub accounts (check with `gh auth status`). If you see 2+ accounts listed, this skill applies.
+
+## What to Do (as the AI agent)
+
+### Step 1: Detect accounts
+Run: `gh auth status`
+Look for multiple accounts. Note which usernames are listed.
+
+### Step 2: Ask the user
+Ask: "I see you have multiple GitHub accounts: {list them}. Which one is your personal account and which is your work/EMU account?"
+
+### Step 3: Run the setup automatically
+Once the user confirms, do ALL of this for them:
+
+```powershell
+# 1. Define the functions
+$personal = "THEIR_PERSONAL_USERNAME"
+$work = "THEIR_WORK_USERNAME"
+
+# 2. Add to PowerShell profile
+$profilePath = $PROFILE.CurrentUserAllHosts
+if (!(Test-Path $profilePath)) { New-Item -Path $profilePath -Force | Out-Null }
+$existing = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue
+if ($existing -notmatch "gh-personal") {
+    $block = @"
+
+# === GitHub Multi-Account Aliases ===
+function gh-personal { gh auth switch --user $personal 2>`$null | Out-Null; gh @args }
+function gh-work { gh auth switch --user $work 2>`$null | Out-Null; gh @args }
+Set-Alias ghp gh-personal
+Set-Alias ghw gh-work
+"@
+    Add-Content -Path $profilePath -Value $block
+}
+
+# 3. Create CMD wrappers
+$binDir = Join-Path $env:USERPROFILE ".mesh\bin"
+if (!(Test-Path $binDir)) { New-Item -ItemType Directory -Path $binDir -Force | Out-Null }
+"@echo off`ngh auth switch --user $personal >nul 2>&1`ngh %*" | Out-File "$binDir\ghp.cmd" -Encoding ascii
+"@echo off`ngh auth switch --user $work >nul 2>&1`ngh %*" | Out-File "$binDir\ghw.cmd" -Encoding ascii
+
+# 4. Add to PATH
+$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
+if ($userPath -notmatch [regex]::Escape($binDir)) {
+    [Environment]::SetEnvironmentVariable("PATH", "$binDir;$userPath", "User")
+    $env:PATH = "$binDir;$env:PATH"
+}
+
+# 5. Load in current session
+function gh-personal { gh auth switch --user $personal 2>$null | Out-Null; gh @args }
+function gh-work { gh auth switch --user $work 2>$null | Out-Null; gh @args }
+Set-Alias ghp gh-personal
+Set-Alias ghw gh-work
+```
+
+### Step 4: Verify for the user
+Run these and show the results:
+```powershell
+ghp api user --jq '.login'   # should show personal username
+ghw api user --jq '.login'   # should show work username
+```
+
+### Step 5: Tell the user
+"All set! From now on use `ghp` for personal repos and `ghw` for work repos. I'll use them too."
+
+## After Setup — Usage Rules
+
+1. **NEVER** use bare `gh` for repo operations — always `ghp` or `ghw`
+2. **NEVER** manually `gh auth switch` — the aliases handle it
+3. Determine alias by repo owner:
+   - Personal account repos → `ghp` / `gh-personal`
+   - Work/EMU account repos → `ghw` / `gh-work`
+
+## Repo-Specific Account Binding
+
+This repo (`bradygaster/Mercury Mesh`) is bound to the **bradygaster** (personal) account.
+All `gh` operations in this repo MUST use `ghp` / `gh-personal`.
+
+## For Mercury Mesh Agents
+At the TOP of any script touching GitHub, define:
+```powershell
+function gh-personal { gh auth switch --user bradygaster 2>$null | Out-Null; gh @args }
+function gh-work { gh auth switch --user bradyg_microsoft 2>$null | Out-Null; gh @args }
+```

package/.copilot/skills/history-hygiene/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: history-hygiene
+description: Record final outcomes to history.md, not intermediate requests or reversed decisions
+domain: documentation, team-collaboration
+confidence: high
+source: earned (Kobayashi v0.6.0 incident, team intervention)
+---
+
+## Context
+
+History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake.
+
+## Patterns
+
+- **Record the final outcome**, not the initial request.
+- **Wait for confirmation** before writing to history — don't log intermediate states.
+- **If a decision reverses**, update the entry immediately — don't leave stale data.
+- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened.
+
+## Examples
+
+✓ **Correct:**
+- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)"
+- "Reverted to Node 18 per Brady's explicit request on 2024-01-15"
+
+✗ **Incorrect:**
+- "Brady directed v0.6.0" (when later reversed)
+- Recording what was *requested* instead of what *actually happened*
+- Logging entries before outcome is confirmed
+
+## Anti-Patterns
+
+- Writing intermediate or "for now" states to disk
+- Attributing decisions without confirming final direction
+- Treating history like a draft — history is the source of truth
+- Assuming readers will cross-reference or verify; they won't

package/.copilot/skills/humanizer/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: "humanizer"
+description: "Tone enforcement patterns for external-facing community responses"
+metadata:
+	domain: "communication, tone, community"
+	confidence: "low"
+	source: "manual (RFC #426 — PAO External Communications)"
+---
+
+## Context
+
+Use this skill whenever PAO drafts external-facing responses for issues or discussions.
+
+- Tone must be direct, human, and high-signal — never submissive, robotic, or corporate.
+- The Brand Language System and Persona Manifesto apply everywhere: **sharp signal is mandatory**.
+- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows.
+
+## Patterns
+
+1. **Signal-first opening** — Start with the readout, not pleasantries: "Signal received", "Telemetry locked", "Routing correction"
+2. **Active voice** — "We reproduced the fault" not "This is being investigated"
+3. **Second person** — Address the person directly ("you" not "the user")
+4. **Controlled connectors** — Use transitions with motion: "Current read:", "Next burn:", "Transmit this:"
+5. **Specific, not vague** — "This hits the casting module in v0.8.x" not "We are aware of issues"
+6. **Measured empathy** — Validate the signal without soft filler: "Real fault", "Valid concern", "Confirmed drift"
+7. **Action-oriented closes** — End with the next vector or telemetry request, never "happy to help"
+8. **Bounded uncertainty** — "Root cause is still in the dark. Here's what we ruled out" is better than false confidence
+9. **No apologies. No filler.** Never use "I'm sorry," "Thanks for reporting," "Great question," "Let us know," or similar padding
+10. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting
+11. **Baseline comparison** — Responses should align with tone of 5-10 gold-standard responses (>80% similarity threshold)
+12. **Tension without hostility** — The voice can challenge or sharpen; it does not belittle
+13. **Information request** — Ask for specific details, not open-ended "can you provide more info?"
+14. **No link-dumping** — Don't just paste URLs. Provide context: "Read the getting started guide — routing section" not just a bare link
+
+## Examples
+
+### 1. Welcome
+
+```text
+{author}, signal received. Welcome aboard.
+{substantive response}
+Telemetry remains open if the thread picks up drift.
+```
+
+### 2. Troubleshooting
+
+```text
+Telemetry locked, {author}.
+Current read: {explanation}
+{steps or workaround}
+If the drift persists, transmit {specific ask}.
+```
+
+### 3. Feature guidance
+
+```text
+Vector received. {context on current state}
+{guidance or workaround}
+Queued on the flight path: {tracking info if applicable}.
+```
+
+### 4. Redirect
+
+```text
+Routing correction, {author}. This belongs in {correct location}.
+{brief explanation of why}
+Open the thread there and carry this context forward: {handoff note}.
+```
+
+### 5. Acknowledgment
+
+```text
+Confirmed, {author}. Real fault.
+{what we know so far}
+Patch is not in the burn yet. Telemetry will update here when it is.
+```
+
+### 6. Closing
+
+```text
+Patch landed in {version/PR}.
+{brief summary of what changed}
+Re-enter the burn and confirm hull integrity.
+```
+
+### 7. Technical uncertainty
+
+```text
+Signal received, {author}. Root cause is still in the dark.
+Ruled out: {list}
+Transmit {specific ask}.
+That narrows the drift. Telemetry will update when the fault resolves.
+```
+
+## Anti-Patterns
+
+- ❌ Corporate speak: "We appreciate your patience as we investigate this matter"
+- ❌ Marketing hype: "Mercury Mesh is the BEST way to..." or "This amazing feature..."
+- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked"
+- ❌ Dismissive: "This works as designed" without acknowledging the signal
+- ❌ Over-promising: "We'll ship this next week" without commitment from the team
+- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance
+- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Mercury Mesh Team"
+- ❌ Excessive emoji: More than 1-2 emoji per response
+- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead
+- ❌ Link-dumping: Pasting URLs without context ("See: https://...")
+- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information

package/.copilot/skills/init-mode/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: "init-mode"
+description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)"
+metadata:
+   domain: "orchestration"
+   confidence: "high"
+   source: "extracted"
+   primary_tool: "ask_user"
+   primary_tool_use: "Confirm team roster with a selectable menu during Phase 1 proposal."
+---
+
+## Context
+
+Init Mode activates when `.mesh/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2).
+
+## Patterns
+
+### Phase 1: Propose the Team
+
+No team exists yet. Propose one — but **DO NOT create any files until the user confirms.**
+
+1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Brady, declare the mission."*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.**
+2. Ask: *"Commander, declare the mission. Share the language, stack, and what the system must do."*
+3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section):
+   - Determine team size (typically 4–5 + Scribe).
+   - Determine assignment shape from the user's project description.
+   - Derive resonance signals from the session and repo context.
+   - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.mesh/templates/casting/` directory. Prefer custom universes when available.
+   - Scribe is always "Scribe" — exempt from casting.
+   - Ralph is always "Ralph" — exempt from casting.
+4. Propose the team with their cast names. Example (names will vary per cast):
+
+```
+🏗️  {CastName1}  — Lead          Scope, decisions, code review
+⚛️  {CastName2}  — Frontend Dev  React, UI, components
+🔧  {CastName3}  — Backend Dev   APIs, database, services
+🧪  {CastName4}  — Tester        Tests, quality, edge cases
+📋  Scribe       — (silent)      Memory, decisions, session logs
+🔄  Ralph        — (monitor)     Work queue, backlog, keep-alive
+```
+
+5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu:
+   - **question:** *"Look right?"*
+   - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]`
+
+**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.**
+
+### Phase 2: Create the Team
+
+**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes").
+
+> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms.
+
+6. Create the `.mesh/` directory structure (see `.mesh/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/).
+
+**Casting state initialization:** Copy `.mesh/templates/casting-policy.json` to `.mesh/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id).
+
+**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.mesh/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing.
+
+**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`mesh-heartbeat.yml`, `mesh-issue-assign.yml`, `mesh-triage.yml`, `sync-mesh-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks.
+
+**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.mesh/` state across branches:
+```
+.mesh/decisions.md merge=union
+.mesh/agents/*/history.md merge=union
+.mesh/log/** merge=union
+.mesh/orchestration-log/** merge=union
+```
+The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically.
+
+7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"*
+
+8. **Post-setup input sources** (optional — ask after team is created, not during casting):
+   - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow
+   - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow
+   - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section
+   - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment
+   - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately.
+
+## Examples
+
+**Example flow:**
+1. Coordinator detects no team.md → Init Mode
+2. Runs `git config user.name` → "Brady"
+3. Asks: *"Brady, declare the mission."*
+4. User: *"TypeScript CLI tool with GitHub API integration"*
+5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe
+6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph
+7. Uses `ask_user` with choices → user selects "Yes, hire this team"
+8. Coordinator creates `.mesh/` structure, initializes casting state, seeds agents
+9. Says: *"✅ Team hired. Try: 'Keaton, set up the project structure'"*
+
+## Anti-Patterns
+
+- ❌ Creating files before user confirms Phase 1
+- ❌ Mixing agents from different universes in the same cast
+- ❌ Skipping the `ask_user` tool and assuming confirmation
+- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role"
+- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows)
+- ❌ Forgetting to initialize `.mesh/casting/` state files
+- ❌ Reading or storing `git config user.email` (PII violation)

package/.copilot/skills/mesh-conventions/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: "mercury mesh-conventions"
+description: "Core conventions and patterns used in the Mercury Mesh codebase"
+domain: "project-conventions"
+confidence: "high"
+source: "manual"
+---
+
+## Context
+These conventions apply to all work on the Mercury Mesh CLI tool (`create-Mercury Mesh`). Mercury Mesh is a zero-dependency Node.js package that adds AI agent teams to any project. Understanding these patterns is essential before modifying any Mercury Mesh source code.
+
+## Patterns
+
+### Zero Dependencies
+Mercury Mesh has zero runtime dependencies. Everything uses Node.js built-ins (`fs`, `path`, `os`, `child_process`). Do not add packages to `dependencies` in `package.json`. This is a hard constraint, not a preference.
+
+### Node.js Built-in Test Runner
+Tests use `node:test` and `node:assert/strict` — no test frameworks. Run with `npm test`. Test files live in `test/`. The test command is `node --test test/`.
+
+### Error Handling — `fatal()` Pattern
+All user-facing errors use the `fatal(msg)` function which prints a red `✗` prefix and exits with code 1. Never throw unhandled exceptions or print raw stack traces. The global `uncaughtException` handler calls `fatal()` as a safety net.
+
+### ANSI Color Constants
+Colors are defined as constants at the top of `index.js`: `GREEN`, `RED`, `DIM`, `BOLD`, `RESET`. Use these constants — do not inline ANSI escape codes.
+
+### File Structure
+- `.mesh/` — Team state (user-owned, never overwritten by upgrades)
+- `.mesh/templates/` — Template files copied from `templates/` (Mercury Mesh-owned, overwritten on upgrade)
+- `.github/agents/mercury-mesh.agent.md` — Coordinator prompt (Mercury Mesh-owned, overwritten on upgrade)
+- `templates/` — Source templates shipped with the npm package
+- `.mesh/skills/` — Team skills in SKILL.md format (user-owned)
+- `.mesh/decisions/inbox/` — Drop-box for parallel decision writes
+
+### Windows Compatibility
+Always use `path.join()` for file paths — never hardcode `/` or `\` separators. Mercury Mesh must work on Windows, macOS, and Linux. All tests must pass on all platforms.
+
+### Init Idempotency
+The init flow uses a skip-if-exists pattern: if a file or directory already exists, skip it and report "already exists." Never overwrite user state during init. The upgrade flow overwrites only Mercury Mesh-owned files.
+
+### Copy Pattern
+`copyRecursive(src, target)` handles both files and directories. It creates parent directories with `{ recursive: true }` and uses `fs.copyFileSync` for files.
+
+## Examples
+
+```javascript
+// Error handling
+function fatal(msg) {
+  console.error(`${RED}✗${RESET} ${msg}`);
+  process.exit(1);
+}
+
+// File path construction (Windows-safe)
+const agentDest = path.join(dest, '.github', 'agents', 'mercury-mesh.agent.md');
+
+// Skip-if-exists pattern
+if (!fs.existsSync(ceremoniesDest)) {
+  fs.copyFileSync(ceremoniesSrc, ceremoniesDest);
+  console.log(`${GREEN}✓${RESET} .mesh/ceremonies.md`);
+} else {
+  console.log(`${DIM}ceremonies.md already exists — skipping${RESET}`);
+}
+```
+
+## Anti-Patterns
+- **Adding npm dependencies** — Mercury Mesh is zero-dep. Use Node.js built-ins only.
+- **Hardcoded path separators** — Never use `/` or `\` directly. Always `path.join()`.
+- **Overwriting user state on init** — Init skips existing files. Only upgrade overwrites Mercury Mesh-owned files.
+- **Raw stack traces** — All errors go through `fatal()`. Users see clean messages, not stack traces.
+- **Inline ANSI codes** — Use the color constants (`GREEN`, `RED`, `DIM`, `BOLD`, `RESET`).