@mizyoel/mercury-mesh 0.9.4

package/.copilot/mcp-config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "EXAMPLE-github": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@anthropic/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}

package/.copilot/skills/agent-collaboration/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: "agent-collaboration"
+description: "Standard collaboration patterns for all Mercury Mesh agents — worktree awareness, decisions, cross-agent communication"
+domain: "team-workflow"
+confidence: "high"
+source: "extracted from charter boilerplate — identical content in 18+ agent charters"
+---
+
+## Context
+
+Every agent on the team follows identical collaboration patterns for worktree awareness, decision recording, and cross-agent communication. These were previously duplicated in every charter's Collaboration section (~300 bytes × 18 agents = ~5.4KB of redundant context). Now centralized here.
+
+The coordinator's spawn prompt already instructs agents to read decisions.md and their history.md. This skill adds the patterns for WRITING decisions and requesting help.
+
+## Patterns
+
+### Worktree Awareness
+Use the `TEAM ROOT` path provided in your spawn prompt. All `.mesh/` paths are relative to this root. If TEAM ROOT is not provided (rare), run `git rev-parse --show-toplevel` as fallback. Never assume CWD is the repo root.
+
+### Decision Recording
+After making a decision that affects other team members, write it to:
+`.mesh/decisions/inbox/{your-name}-{brief-slug}.md`
+
+Format:
+```
+### {date}: {decision title}
+**By:** {Your Name}
+**What:** {the decision}
+**Why:** {rationale}
+```
+
+### Cross-Agent Communication
+If you need another team member's input, say so in your response. The coordinator will establish an Airbridge. Don't try to do work outside your domain.
+
+### Reviewer Protocol
+If you have reviewer authority and reject work: the original author is locked out from revising that artifact. A different agent must own the revision. State who should revise in your rejection response.
+
+## Anti-Patterns
+- Don't read all agent charters — you only need your own context + decisions.md
+- Don't write directly to `.mesh/decisions.md` — always use the inbox drop-box
+- Don't modify other agents' history.md files — that's Scribe's job
+- Don't assume CWD is the repo root — always use TEAM ROOT

package/.copilot/skills/agent-conduct/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: "agent-conduct"
+description: "Shared hard rules enforced across all Mercury Mesh agents"
+domain: "team-governance"
+confidence: "high"
+source: "reskill extraction — Product Isolation Rule and Peer Quality Check appeared in all 20 agent charters"
+---
+
+## Context
+
+Every Mercury Mesh agent must follow these two hard rules. They were previously duplicated in every charter. Now they live here as a shared skill, loaded once.
+
+## Patterns
+
+### Product Isolation Rule (hard rule)
+Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular Mercury Mesh. "Our Mercury Mesh" must not impact "the Mercury Mesh." No hardcoded references to agent names (Flight, EECOM, FIDO, etc.) in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot").
+
+### Peer Quality Check (hard rule)
+Before finishing work, verify your changes don't break existing tests. Run the test suite for files you touched. If CI has been failing, check your changes aren't contributing to the problem. When you learn from mistakes, update your history.md.
+
+## Anti-Patterns
+- Don't hardcode dev team agent names in product code or tests
+- Don't skip test verification before declaring work done
+- Don't ignore pre-existing CI failures that your changes may worsen

package/.copilot/skills/architectural-proposals/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: "architectural-proposals"
+description: "How to write comprehensive architectural proposals that drive alignment before code is written"
+domain: "architecture, product-direction"
+confidence: "high"
+source: "earned (2026-02-21 interactive shell proposal)"
+tools:
+  - name: "view"
+    description: "Read existing codebase, prior decisions, and team context before proposing changes"
+    when: "Always read .mesh/decisions.md, relevant PRDs, and current architecture docs before writing proposal"
+  - name: "create"
+    description: "Create proposal in docs/proposals/ with structured format"
+    when: "After gathering context, before any implementation work begins"
+---
+
+## Context
+
+Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when:
+- Architecture shifts invalidate existing assumptions
+- Product direction changes require new foundation
+- Multiple waves/milestones will be affected by a decision
+- External dependencies (Copilot CLI, SDK APIs) change
+
+## Patterns
+
+### Proposal Structure (docs/proposals/)
+
+**Required sections:**
+1. **Problem Statement** — Why current state is broken (specific, measurable evidence)
+2. **Proposed Architecture** — Solution with technical specifics (not hand-waving)
+3. **What Changes** — Impact on existing work (waves, milestones, modules)
+4. **What Stays the Same** — Preserve existing functionality (no regression)
+5. **Key Decisions Needed** — Explicit choices with recommendations
+6. **Risks and Mitigations** — Likelihood + impact + mitigation strategy
+7. **Scope** — What's in v1, what's deferred (timeline clarity)
+
+**Optional sections:**
+- Implementation Plan (high-level milestones)
+- Success Criteria (measurable outcomes)
+- Open Questions (unresolved items)
+- Appendix (prior art, alternatives considered)
+
+### Tone Ceiling Enforcement
+
+**Always:**
+- Cite specific evidence (user reports, performance data, failure modes)
+- Justify recommendations with technical rationale
+- Acknowledge trade-offs (no perfect solutions)
+- Be specific about APIs, libraries, file paths
+
+**Never:**
+- Hype ("revolutionary", "game-changing")
+- Hand-waving ("we'll figure it out later")
+- Unsubstantiated claims ("users will love this")
+- Vague timelines ("soon", "eventually")
+
+### Wave Restructuring Pattern
+
+When a proposal invalidates existing wave structure:
+1. **Acknowledge the shift:** "This becomes Wave 0 (Foundation)"
+2. **Cascade impacts:** Adjust downstream waves (Wave 1, Wave 2, Wave 3)
+3. **Preserve non-blocking work:** Identify what can proceed in parallel
+4. **Update dependencies:** Document new blocking relationships
+
+**Example (Interactive Shell):**
+- Wave 0 (NEW): Interactive Shell — blocks all other waves
+- Wave 1 (ADJUSTED): npm Distribution — shell bundled in cli.js
+- Wave 2 (DEFERRED): MeshUI — waits for shell foundation
+- Wave 3 (ADJUSTED): Public Docs — now documents shell as primary interface
+
+### Decision Framing
+
+**Format:** "Recommendation: X (recommended) or alternatives?"
+
+**Components:**
+- Recommendation (pick one, justify)
+- Alternatives (what else was considered)
+- Decision rationale (why recommended option wins)
+- Needs sign-off from (which agents/roles must approve)
+
+**Example:**
+```
+### 1. Terminal UI Library: `ink` (recommended) or alternatives?
+
+**Recommendation:** `ink`  
+**Alternatives:** `blessed`, raw readline  
+**Decision rationale:** Component model enables testable UI. Battle-tested ecosystem.
+
+**Needs sign-off from:** Brady (product direction), Fortier (runtime performance)
+```
+
+### Risk Documentation
+
+**Format per risk:**
+- **Risk:** Specific failure mode
+- **Likelihood:** Low / Medium / High (not percentages)
+- **Impact:** Low / Medium / High
+- **Mitigation:** Concrete actions (measurable)
+
+**Example:**
+```
+### Risk 2: SDK Streaming Reliability
+
+**Risk:** SDK streaming events might drop messages or arrive out of order.  
+**Likelihood:** Low (SDK is production-grade).  
+**Impact:** High — broken streaming makes shell unusable.
+
+**Mitigation:**
+- Add integration test: Send 1000-message stream, verify all deltas arrive in order
+- Implement fallback: If streaming fails, fall back to polling session state
+- Log all SDK events to `.mesh/orchestration-log/sdk-events.jsonl` for debugging
+```
+
+## Examples
+
+**File references from interactive shell proposal:**
+- Full proposal: `docs/proposals/Mercury Mesh-interactive-shell.md`
+- User directive: `.mesh/decisions/inbox/copilot-directive-2026-02-21T202535Z.md`
+- Team decisions: `.mesh/decisions.md`
+- Current architecture: `docs/architecture/module-map.md`, `docs/prd-23-release-readiness.md`
+
+**Key patterns demonstrated:**
+1. Read user directive first (understand the "why")
+2. Survey current architecture (module map, existing waves)
+3. Research SDK APIs (exploration task to validate feasibility)
+4. Document problem with specific evidence (unreliable handoffs, zero visibility, UX mismatch)
+5. Propose solution with technical specifics (ink components, SDK session management, spawn.ts module)
+6. Restructure waves when foundation shifts (Wave 0 becomes blocker)
+7. Preserve backward compatibility (mercury-mesh.agent.md still works, VS Code mode unchanged)
+8. Frame decisions explicitly (5 key decisions with recommendations)
+9. Document risks with mitigations (5 risks, each with concrete actions)
+10. Define scope (what's in v1 vs. deferred)
+
+## Anti-Patterns
+
+**Avoid:**
+- ❌ Proposals without problem statements (solution-first thinking)
+- ❌ Vague architecture ("we'll use a shell") — be specific (ink components, session registry, spawn.ts)
+- ❌ Ignoring existing work — always document impact on waves/milestones
+- ❌ No risk analysis — every architecture has risks, document them
+- ❌ Unbounded scope — draw the v1 line explicitly
+- ❌ Missing decision ownership — always say "needs sign-off from X"
+- ❌ No backward compatibility plan — users don't care about your replatform
+- ❌ Hand-waving timelines ("a few weeks") — be specific (2-3 weeks, 1 engineer full-time)
+
+**Red flags in proposal reviews:**
+- "Users will love this" (citation needed)
+- "We'll figure out X later" (scope creep incoming)
+- "This is revolutionary" (tone ceiling violation)
+- No section on "What Stays the Same" (regression risk)
+- No risks documented (wishful thinking)

package/.copilot/skills/ci-validation-gates/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: "ci-validation-gates"
+description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22"
+domain: "ci-cd"
+confidence: "high"
+source: "extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident"
+---
+
+## Context
+
+CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here.
+
+## Patterns
+
+### Semver Validation Gate
+Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them.
+
+```yaml
+- name: Validate semver
+  run: |
+    VERSION="${{ github.event.release.tag_name }}"
+    VERSION="${VERSION#v}"
+    if ! npx semver "$VERSION" > /dev/null 2>&1; then
+      echo "❌ Invalid semver: $VERSION"
+      echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid."
+      exit 1
+    fi
+    echo "✅ Valid semver: $VERSION"
+```
+
+### NPM Token Type Verification
+NPM_TOKEN MUST be an Automation token, not a User token with 2FA:
+- User tokens require OTP — CI can't provide it → EOTP error
+- Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation
+- Verify before first publish in any workflow
+
+### Retry Logic for npm Registry Propagation
+npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable.
+- Propagation: typically 5-30s, up to 2min in rare cases
+- All verify steps: 5 attempts, 15-second intervals
+- Log each attempt: "Attempt 1/5: Checking package..."
+- Exit loop on success, fail after max attempts
+
+```yaml
+- name: Verify package (with retry)
+  run: |
+    MAX_ATTEMPTS=5
+    WAIT_SECONDS=15
+    for attempt in $(seq 1 $MAX_ATTEMPTS); do
+      echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..."
+      if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then
+        echo "✅ Package verified"
+        exit 0
+      fi
+      [ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS
+    done
+    echo "❌ Failed to verify after $MAX_ATTEMPTS attempts"
+    exit 1
+```
+
+### Draft Release Detection
+Draft releases don't emit `release: published` event. Workflows MUST:
+- Trigger on `release: published` (NOT `created`)
+- If using workflow_dispatch: verify release is published via GitHub API before proceeding
+
+### Build Script Protection
+Set `SKIP_BUILD_BUMP=1` (or `$env:SKIP_BUILD_BUMP = "1"` on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions.
+
+## Known Failure Modes (v0.8.22 Incident)
+
+| # | What Happened | Root Cause | Prevention |
+|---|---------------|-----------|------------|
+| 1 | 4-part version published, npm mangled it | No semver validation gate | `npx semver` check before every publish |
+| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only |
+| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals |
+| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases |
+| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 |
+
+## Anti-Patterns
+- ❌ Publishing without semver validation gate
+- ❌ Single-shot verification without retry
+- ❌ Hard-coded secrets in workflows
+- ❌ Silent CI failures — every error needs actionable output with remediation
+- ❌ Assuming npm publish is instantly queryable

package/.copilot/skills/cli-wiring/SKILL.md

@@ -0,0 +1,47 @@
+# Skill: CLI Command Wiring
+
+**Bug class:** Commands implemented in `packages/Mercury Mesh-cli/src/cli/commands/` but never routed in `cli-entry.ts`.
+
+## Checklist — Adding a New CLI Command
+
+1. **Create command file** in `packages/Mercury Mesh-cli/src/cli/commands/<name>.ts`
+   - Export a `run<Name>(cwd, options)` async function (or class with static methods for utility modules)
+
+2. **Add routing block** in `packages/Mercury Mesh-cli/src/cli-entry.ts` inside `main()`:
+   ```ts
+   if (cmd === '<name>') {
+     const { run<Name> } = await import('./cli/commands/<name>.js');
+     // parse args, call function
+     await run<Name>(process.cwd(), options);
+     return;
+   }
+   ```
+
+3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`):
+   ```ts
+   console.log(`  ${BOLD}<name>${RESET}     <description>`);
+   console.log(`             Usage: <name> [flags]`);
+   ```
+
+4. **Verify both exist** — the recurring bug is doing step 1 but missing steps 2-3.
+
+## Wiring Patterns by Command Type
+
+| Type | Example | How to wire |
+|------|---------|-------------|
+| Standard command | `export.ts`, `build.ts` | `run*()` function, parse flags from `args` |
+| Placeholder command | `loop`, `hire` | Inline in cli-entry.ts, prints pending message |
+| Utility/check module | `rc-tunnel.ts`, `copilot-bridge.ts` | Wire as diagnostic check (e.g., `isDevtunnelAvailable()`) |
+| Subcommand of another | `init-remote.ts` | Already used inside parent + standalone alias |
+
+## Common Import Pattern
+
+```ts
+import { BOLD, RESET, DIM, RED, GREEN, YELLOW } from './cli/core/output.js';
+```
+
+Use dynamic `await import()` for command modules to keep startup fast (lazy loading).
+
+## History
+
+- **#237 / PR #244:** 4 commands wired (rc, copilot-bridge, init-remote, rc-tunnel). aspire, link, loop, hire were already present.

package/.copilot/skills/client-compatibility/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: "client-compatibility"
+description: "Platform detection and adaptive spawning for CLI vs VS Code vs other surfaces"
+domain: "orchestration"
+confidence: "high"
+source: "extracted"
+---
+
+## Context
+
+Mercury Mesh runs on multiple Copilot surfaces (CLI, VS Code, JetBrains, GitHub.com). The coordinator must detect its platform and adapt spawning behavior accordingly. Different tools are available on different platforms, requiring conditional logic for agent spawning, SQL usage, and response timing.
+
+## Patterns
+
+### Platform Detection
+
+Before spawning agents, determine the platform by checking available tools:
+
+1. **CLI mode** — `task` tool is available → full spawning control. Use `task` with `agent_type`, `mode`, `model`, `description`, `prompt` parameters. Collect results via `read_agent`.
+
+2. **VS Code mode** — `runSubagent` or `agent` tool is available → conditional behavior. Use `runSubagent` with the task prompt. Drop `agent_type`, `mode`, and `model` parameters. Multiple subagents in one turn run concurrently (equivalent to background mode). Results return automatically — no `read_agent` needed.
+
+3. **Fallback mode** — neither `task` nor `runSubagent`/`agent` available → work inline. Do not apologize or explain the limitation. Execute the task directly.
+
+If both `task` and `runSubagent` are available, prefer `task` (richer parameter surface).
+
+### VS Code Spawn Adaptations
+
+When in VS Code mode, the coordinator changes behavior in these ways:
+
+- **Spawning tool:** Use `runSubagent` instead of `task`. The prompt is the only required parameter — pass the full agent prompt (charter, identity, task, hygiene, response order) exactly as you would on CLI.
+- **Parallelism:** Spawn ALL concurrent agents in a SINGLE turn. They run in parallel automatically. This replaces `mode: "background"` + `read_agent` polling.
+- **Model selection:** Accept the session model. Do NOT attempt per-spawn model selection or fallback chains — they only work on CLI. In Phase 1, all subagents use whatever model the user selected in VS Code's model picker.
+- **Scribe:** Cannot fire-and-forget. Batch Scribe as the LAST subagent in any parallel group. Scribe is light work (file ops only), so the blocking is tolerable.
+- **Launch table:** Skip it. Results arrive with the response, not separately. By the time the coordinator speaks, the work is already done.
+- **`read_agent`:** Skip entirely. Results return automatically when subagents complete.
+- **`agent_type`:** Drop it. All VS Code subagents have full tool access by default. Subagents inherit the parent's tools.
+- **`description`:** Drop it. The agent name is already in the prompt.
+- **Prompt content:** Keep ALL prompt structure — charter, identity, task, hygiene, response order blocks are surface-independent.
+
+### Feature Degradation Table
+
+| Feature | CLI | VS Code | Degradation |
+|---------|-----|---------|-------------|
+| Parallel fan-out | `mode: "background"` + `read_agent` | Multiple subagents in one turn | None — equivalent concurrency |
+| Model selection | Per-spawn `model` param (4-layer hierarchy) | Session model only (Phase 1) | Accept session model, log intent |
+| Scribe fire-and-forget | Background, never read | Sync, must wait | Batch with last parallel group |
+| Launch table UX | Show table → results later | Skip table → results with response | UX only — results are correct |
+| SQL tool | Available | Not available | Avoid SQL in cross-platform code paths |
+| Response order bug | Critical workaround | Possibly necessary (unverified) | Keep the block — harmless if unnecessary |
+
+### SQL Tool Caveat
+
+The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitHub.com. Any coordinator logic or agent workflow that depends on SQL (todo tracking, batch processing, session state) will silently fail on non-CLI surfaces. Cross-platform code paths must not depend on SQL. Use filesystem-based state (`.mesh/` files) for anything that must work everywhere.
+
+## Examples
+
+**Example 1: CLI parallel spawn**
+```typescript
+// Coordinator detects task tool available → CLI mode
+task({ agent_type: "general-purpose", mode: "background", model: "claude-sonnet-4.5", ... })
+task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4.5", ... })
+// Later: read_agent for both
+```
+
+**Example 2: VS Code parallel spawn**
+```typescript
+// Coordinator detects runSubagent available → VS Code mode
+runSubagent({ prompt: "...Fenster charter + task..." })
+runSubagent({ prompt: "...Hockney charter + task..." })
+runSubagent({ prompt: "...Scribe charter + task..." }) // Last in group
+// Results return automatically, no read_agent
+```
+
+**Example 3: Fallback mode**
+```typescript
+// Neither task nor runSubagent available → work inline
+// Coordinator executes the task directly without spawning
+```
+
+## Anti-Patterns
+
+- ❌ Using SQL tool in cross-platform workflows (breaks on VS Code/JetBrains/GitHub.com)
+- ❌ Attempting per-spawn model selection on VS Code (Phase 1 — only session model works)
+- ❌ Fire-and-forget Scribe on VS Code (must batch as last subagent)
+- ❌ Showing launch table on VS Code (results already inline)
+- ❌ Apologizing or explaining platform limitations to the user
+- ❌ Using `task` when only `runSubagent` is available
+- ❌ Dropping prompt structure (charter/identity/task) on non-CLI platforms

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

@@ -0,0 +1,114 @@
+---
+name: "cross-Mercury Mesh"
+description: "Coordinating work across multiple Mercury Mesh instances"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+tools:
+  - name: "Mercury Mesh-discover"
+    description: "List known meshes and their capabilities"
+    when: "When you need to find which Mercury Mesh can handle a task"
+  - name: "Mercury Mesh-delegate"
+    description: "Create work in another Mercury Mesh's repository"
+    when: "When a task belongs to another Mercury Mesh's domain"
+---
+
+## Context
+When an organization runs multiple Mercury Mesh instances (e.g., platform-Mercury Mesh, frontend-Mercury Mesh, data-Mercury Mesh), those meshes need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across meshes without creating tight coupling.
+
+Cross-Mercury Mesh orchestration applies when:
+- A task requires capabilities owned by another Mercury Mesh
+- An architectural decision affects multiple meshes
+- A feature spans multiple repositories with different meshes
+- A Mercury Mesh needs to request infrastructure, tooling, or support from another Mercury Mesh
+
+## Patterns
+
+### Discovery via Manifest
+Each Mercury Mesh publishes a `.mesh/manifest.json` declaring its name, capabilities, and contact information. meshes discover each other through:
+1. **Well-known paths**: Check `.mesh/manifest.json` in known org repos
+2. **Upstream config**: meshes already listed in `.mesh/upstream.json` are checked for manifests
+3. **Explicit registry**: A central `mesh-registry.json` can list all meshes in an org
+
+```json
+{
+  "name": "platform-Mercury Mesh",
+  "version": "1.0.0",
+  "description": "Platform infrastructure team",
+  "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"],
+  "contact": {
+    "repo": "org/platform",
+    "labels": ["Mercury Mesh:platform"]
+  },
+  "accepts": ["issues", "prs"],
+  "skills": ["helm-developer", "operator-developer", "pipeline-engineer"]
+}
+```
+
+### Context Sharing
+When delegating work, share only what the target Mercury Mesh needs:
+- **Capability list**: What this Mercury Mesh can do (from manifest)
+- **Relevant decisions**: Only decisions that affect the target Mercury Mesh
+- **Handoff context**: A concise description of why this work is being delegated
+
+Do NOT share:
+- Internal team state (casting history, session logs)
+- Full decision archives (send only relevant excerpts)
+- Authentication credentials or secrets
+
+### Work Handoff Protocol
+1. **Check manifest**: Verify the target Mercury Mesh accepts the work type (issues, PRs)
+2. **Create issue**: Use `gh issue create` in the target repo with:
+   - Title: `[cross-Mercury Mesh] <description>`
+   - Label: `Mercury Mesh:cross-Mercury Mesh` (or the Mercury Mesh's configured label)
+   - Body: Context, acceptance criteria, and link back to originating issue
+3. **Track**: Record the cross-Mercury Mesh issue URL in the originating Mercury Mesh's orchestration log
+4. **Poll**: Periodically check if the delegated issue is closed/completed
+
+### Feedback Loop
+Track delegated work completion:
+- Poll target issue status via `gh issue view`
+- Update originating issue with status changes
+- Close the feedback loop when delegated work merges
+
+## Examples
+
+### Discovering meshes
+```bash
+# List all meshes discoverable from upstreams and known repos
+Mercury Mesh discover
+
+# Output:
+#   platform-Mercury Mesh  →  org/platform  (kubernetes, helm, monitoring)
+#   frontend-Mercury Mesh  →  org/frontend  (react, nextjs, storybook)
+#   data-Mercury Mesh      →  org/data      (spark, airflow, dbt)
+```
+
+### Delegating work
+```bash
+# Delegate a task to the platform Mercury Mesh
+Mercury Mesh delegate platform-Mercury Mesh "Add Prometheus metrics endpoint for the auth service"
+
+# Creates issue in org/platform with cross-Mercury Mesh label and context
+```
+
+### Manifest in Mercury Mesh.config.ts
+```typescript
+export default defineMercury Mesh({
+  manifest: {
+    name: 'platform-Mercury Mesh',
+    capabilities: ['kubernetes', 'helm'],
+    contact: { repo: 'org/platform', labels: ['Mercury Mesh:platform'] },
+    accepts: ['issues', 'prs'],
+    skills: ['helm-developer', 'operator-developer'],
+  },
+});
+```
+
+## Anti-Patterns
+- **Direct file writes across repos** — Never modify another Mercury Mesh's `.mesh/` directory. Use issues and PRs as the communication protocol.
+- **Tight coupling** — Don't depend on another Mercury Mesh's internal structure. Use the manifest as the public API contract.
+- **Unbounded delegation** — Always include acceptance criteria and a timeout. Don't create open-ended requests.
+- **Skipping discovery** — Don't hardcode Mercury Mesh locations. Use manifests and the discovery protocol.
+- **Sharing secrets** — Never include credentials, tokens, or internal URLs in cross-Mercury Mesh issues.
+- **Circular delegation** — Track delegation chains. If Mercury Mesh A delegates to B which delegates back to A, something is wrong.