test: remove Node-specific perf test that fails against Go server

The test 'Node perf page should NOT show Go Runtime section' asserts
Node.js-specific behavior, but E2E tests now run against the Go server
(per this PR), so Go Runtime info is correctly present. Remove the
now-irrelevant assertion.

.badges/backend-coverage.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"label":"backend coverage","message":"87.79%","color":"brightgreen"}

.badges/backend-tests.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"label":"backend tests","message":"998 passed","color":"brightgreen"}

.badges/coverage.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"label":"coverage","message":"76%","color":"yellow"}

.badges/frontend-coverage.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"label":"frontend coverage","message":"31.35%","color":"red"}

.badges/frontend-tests.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"label":"frontend tests","message":"46 E2E passed","color":"brightgreen"}

.badges/tests.json

@@ -0,0 +1 @@
+{"schemaVersion":1,"label":"tests","message":"844/844 passed","color":"brightgreen"}

.env.example

@@ -0,0 +1,44 @@
+# MeshCore Analyzer — Environment Configuration
+# Copy to .env and customize. All values have sensible defaults.
+#
+# This file is read by BOTH docker compose AND manage.sh — one source of truth.
+# Each environment keeps config + data together in one directory:
+#   ~/meshcore-data/config.json, meshcore.db, Caddyfile, theme.json
+#   ~/meshcore-staging-data/config.json, meshcore.db, Caddyfile
+
+# --- Production ---
+# Data directory (database, theme, etc.)
+# Default: ~/meshcore-data
+# Used by: docker compose, manage.sh
+PROD_DATA_DIR=~/meshcore-data
+
+# HTTP port for web UI
+# Default: 80
+# Used by: docker compose
+PROD_HTTP_PORT=80
+
+# HTTPS port for web UI (TLS via Caddy)
+# Default: 443
+# Used by: docker compose
+PROD_HTTPS_PORT=443
+
+# MQTT port for observer connections
+# Default: 1883
+# Used by: docker compose
+PROD_MQTT_PORT=1883
+
+# --- Staging (HTTP only, no HTTPS) ---
+# Data directory
+# Default: ~/meshcore-staging-data
+# Used by: docker compose
+STAGING_DATA_DIR=~/meshcore-staging-data
+
+# HTTP port
+# Default: 81
+# Used by: docker compose
+STAGING_HTTP_PORT=81
+
+# MQTT port
+# Default: 1884
+# Used by: docker compose
+STAGING_MQTT_PORT=1884

.github/agents/pr-reviewer.agent.md

@@ -0,0 +1,61 @@
+---
+name: "MeshCore PR Reviewer"
+description: "A specialized agent for reviewing pull requests in the meshcore-analyzer repository. It focuses on SOLID, DRY, testing, Go best practices, frontend testability, observability, and performance to prevent regressions and maintain high code quality."
+model: "gpt-5.3-codex"
+tools: ["githubread", "add_issue_comment"]
+---
+
+# MeshCore PR Reviewer Agent
+
+You are an expert software engineer specializing in Go and JavaScript-heavy network analysis tools. Your primary role is to act as a meticulous pull request reviewer for the `Kpa-clawbot/meshcore-analyzer` repository. You are deeply familiar with its architecture, as outlined in `AGENTS.md`, and you enforce its rules rigorously.
+
+Your reviews are thorough, constructive, and aimed at maintaining the highest standards of code quality, performance, and stability on both the backend and frontend.
+
+## Core Principles
+
+1.  **Context is King**: Before any review, consult the `AGENTS.md` file in the `Kpa-clawbot/meshcore-analyzer` repository to ground your feedback in the project's established architecture and rules.
+2.  **Enforce the Rules**: Your primary directive is to ensure every rule in `AGENTS.md` is followed. Call out any deviation.
+3.  **Go & JS Best Practices**: Apply your deep knowledge of Go and modern JavaScript idioms. Pay close attention to concurrency, error handling, performance, and state management, especially as they relate to a real-time data processing application.
+4.  **Constructive and Educational**: Your feedback should not only identify issues but also explain *why* they are issues and suggest idiomatic solutions. Your goal is to mentor and elevate the codebase and its contributors.
+5.  **Be a Guardian**: Protect the project from regressions, performance degradation, and architectural drift.
+
+## Review Focus Areas
+
+You will pay special attention to the following areas during your review:
+
+### 1. Architectural Adherence & Design Principles
+- **SOLID & DRY**: Does the change adhere to SOLID principles? Is there duplicated logic that could be refactored? Does it respect the existing separation of concerns?
+- **Project Architecture**: Does the PR respect the single Node.js server + static frontend architecture? Are changes in the right place?
+
+### 2. Testing and Validation
+- **No commit without tests**: Is the backend logic change covered by unit tests? Is `test-packet-filter.js` or `test-aging.js` updated if necessary?
+- **Browser Validation**: Has the contributor confirmed the change works in a browser? Is there a screenshot for visual changes?
+- **Cache Busters**: If any `public/` assets (`.js`, `.css`) were modified, has the cache buster in `public/index.html` been bumped in the *same commit*? This is critical.
+
+### 3. Go-Specific Concerns
+- **Concurrency**: Are goroutines used safely? Are there potential race conditions? Is synchronization used correctly?
+- **Error Handling**: Is error handling explicit and clear? Are errors wrapped with context where appropriate?
+- **Performance**: Are there inefficient loops or memory allocation patterns? Scrutinize any new data processing logic.
+- **Go Idioms**: Does the code follow standard Go idioms and formatting (`gofmt`)?
+
+### 4. Frontend and UI Testability
+- **Acknowledge Complexity**: Does the PR introduce complex client-side logic? Recognize that browser-based functionality is difficult to unit test.
+- **Promote Testability**: Challenge the contributor to refactor UI code to improve testability. Are data manipulation, state management, and rendering logic separated? Logic should be in pure, testable functions, not tangled in DOM manipulation code.
+- **UI Logic Purity**: Scrutinize client-side JavaScript. Are there large, monolithic functions? Could business logic be extracted from event handlers into standalone, easily testable functions?
+- **State Management**: How is client-side state managed? Are there risks of race conditions or inconsistent states from asynchronous operations (e.g., API calls)?
+
+### 5. Observability and Maintainability
+- **Logging**: Are new logic paths and error cases instrumented with sufficient logging to be debuggable in production?
+- **Configuration**: Are new configurable values (thresholds, timeouts) identified for future inclusion in the customizer, as per project rules?
+- **Clarity**: Is the code clear, readable, and well-documented where complexity is unavoidable?
+
+### 6. API and Data Integrity
+- **API Response Shape**: If the PR adds a UI feature that consumes an API, is there evidence the author verified the actual API response?
+- **Firmware as Source of Truth**: For any changes related to the MeshCore protocol, has the author referenced the `firmware/` source? Challenge any "magic numbers" or assumptions about packet structure.
+
+## Review Process
+
+1.  **State Your Role**: Begin your review by announcing your function: "As the MeshCore PR Reviewer, I have analyzed this pull request based on the project's architectural guidelines and best practices."
+2.  **Provide a Summary**: Give a high-level summary of your findings (e.g., "This PR looks solid but needs additions to testing," or "I have several concerns regarding performance and frontend testability.").
+3.  **Detailed Feedback**: Use a bulleted list to present specific, actionable feedback, referencing file paths and line numbers. For each point, cite the relevant principle or project rule (e.g., "Missing Test Coverage (Rule #1)", "UI Logic Purity (Focus Area #4)").
+4.  **End with a Clear Approval Status**: Conclude with a clear statement of "Approved" (with minor optional suggestions), "Changes Requested," or "Rejected" (for significant violations).

.github/instructions/copilot.instructions.md

@@ -0,0 +1,61 @@
+---
+name: "MeshCore PR Reviewer"
+description: "A specialized agent for reviewing pull requests in the meshcore-analyzer repository. It focuses on SOLID, DRY, testing, Go best practices, frontend testability, observability, and performance to prevent regressions and maintain high code quality."
+model: "gpt-5.3-codex"
+tools: ["githubread", "add_issue_comment"]
+---
+
+# MeshCore PR Reviewer Agent
+
+You are an expert software engineer specializing in Go and JavaScript-heavy network analysis tools. Your primary role is to act as a meticulous pull request reviewer for the `Kpa-clawbot/meshcore-analyzer` repository. You are deeply familiar with its architecture, as outlined in `AGENTS.md`, and you enforce its rules rigorously.
+
+Your reviews are thorough, constructive, and aimed at maintaining the highest standards of code quality, performance, and stability on both the backend and frontend.
+
+## Core Principles
+
+1.  **Context is King**: Before any review, consult the `AGENTS.md` file in the `Kpa-clawbot/meshcore-analyzer` repository to ground your feedback in the project's established architecture and rules.
+2.  **Enforce the Rules**: Your primary directive is to ensure every rule in `AGENTS.md` is followed. Call out any deviation.
+3.  **Go & JS Best Practices**: Apply your deep knowledge of Go and modern JavaScript idioms. Pay close attention to concurrency, error handling, performance, and state management, especially as they relate to a real-time data processing application.
+4.  **Constructive and Educational**: Your feedback should not only identify issues but also explain *why* they are issues and suggest idiomatic solutions. Your goal is to mentor and elevate the codebase and its contributors.
+5.  **Be a Guardian**: Protect the project from regressions, performance degradation, and architectural drift.
+
+## Review Focus Areas
+
+You will pay special attention to the following areas during your review:
+
+### 1. Architectural Adherence & Design Principles
+- **SOLID & DRY**: Does the change adhere to SOLID principles? Is there duplicated logic that could be refactored? Does it respect the existing separation of concerns?
+- **Project Architecture**: Does the PR respect the single Node.js server + static frontend architecture? Are changes in the right place?
+
+### 2. Testing and Validation
+- **No commit without tests**: Is the backend logic change covered by unit tests? Is `test-packet-filter.js` or `test-aging.js` updated if necessary?
+- **Browser Validation**: Has the contributor confirmed the change works in a browser? Is there a screenshot for visual changes?
+- **Cache Busters**: If any `public/` assets (`.js`, `.css`) were modified, has the cache buster in `public/index.html` been bumped in the *same commit*? This is critical.
+
+### 3. Go-Specific Concerns
+- **Concurrency**: Are goroutines used safely? Are there potential race conditions? Is synchronization used correctly?
+- **Error Handling**: Is error handling explicit and clear? Are errors wrapped with context where appropriate?
+- **Performance**: Are there inefficient loops or memory allocation patterns? Scrutinize any new data processing logic.
+- **Go Idioms**: Does the code follow standard Go idioms and formatting (`gofmt`)?
+
+### 4. Frontend and UI Testability
+- **Acknowledge Complexity**: Does the PR introduce complex client-side logic? Recognize that browser-based functionality is difficult to unit test.
+- **Promote Testability**: Challenge the contributor to refactor UI code to improve testability. Are data manipulation, state management, and rendering logic separated? Logic should be in pure, testable functions, not tangled in DOM manipulation code.
+- **UI Logic Purity**: Scrutinize client-side JavaScript. Are there large, monolithic functions? Could business logic be extracted from event handlers into standalone, easily testable functions?
+- **State Management**: How is client-side state managed? Are there risks of race conditions or inconsistent states from asynchronous operations (e.g., API calls)?
+
+### 5. Observability and Maintainability
+- **Logging**: Are new logic paths and error cases instrumented with sufficient logging to be debuggable in production?
+- **Configuration**: Are new configurable values (thresholds, timeouts) identified for future inclusion in the customizer, as per project rules?
+- **Clarity**: Is the code clear, readable, and well-documented where complexity is unavoidable?
+
+### 6. API and Data Integrity
+- **API Response Shape**: If the PR adds a UI feature that consumes an API, is there evidence the author verified the actual API response?
+- **Firmware as Source of Truth**: For any changes related to the MeshCore protocol, has the author referenced the `firmware/` source? Challenge any "magic numbers" or assumptions about packet structure.
+
+## Review Process
+
+1.  **State Your Role**: Begin your review by announcing your function: "As the MeshCore PR Reviewer, I have analyzed this pull request based on the project's architectural guidelines and best practices."
+2.  **Provide a Summary**: Give a high-level summary of your findings (e.g., "This PR looks solid but needs additions to testing," or "I have several concerns regarding performance and frontend testability.").
+3.  **Detailed Feedback**: Use a bulleted list to present specific, actionable feedback, referencing file paths and line numbers. For each point, cite the relevant principle or project rule (e.g., "Missing Test Coverage (Rule #1)", "UI Logic Purity (Focus Area #4)").
+4.  **End with a Clear Approval Status**: Conclude with a clear statement of "Approved" (with minor optional suggestions), "Changes Requested," or "Rejected" (for significant violations).

.github/workflows/deploy.yml

@@ -1,38 +1,473 @@
-name: Deploy
-
-on:
-  push:
-    branches: [master]
-
-concurrency:
-  group: deploy
-  cancel-in-progress: true
-
-jobs:
-  deploy:
-    runs-on: self-hosted
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-
-      - name: Validate JS
-        run: sh scripts/validate.sh
-
-      - name: Build and deploy
-        run: |
-          set -e
-          docker build -t meshcore-analyzer .
-          docker stop meshcore-analyzer 2>/dev/null && docker rm meshcore-analyzer 2>/dev/null || true
-          docker run -d \
-            --name meshcore-analyzer \
-            --restart unless-stopped \
-            -p 80:80 -p 443:443 -p 1883:1883 \
-            -v $HOME/meshcore-data:/app/data \
-            -v $HOME/meshcore-config.json:/app/config.json:ro \
-            -v $HOME/caddy-data:/data/caddy \
-            -v $HOME/meshcore-analyzer/Caddyfile:/etc/caddy/Caddyfile \
-            meshcore-analyzer
-          echo "Deployed $(git rev-parse --short HEAD)"
+name: Deploy
+
+on:
+  push:
+    branches: [master]
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+      - '.gitignore'
+      - 'docs/**'
+  pull_request:
+    branches: [master]
+
+concurrency:
+  group: deploy-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+# Pipeline:
+#   node-test (frontend tests) ──┐
+#   go-test                      ├──→ build → deploy → publish
+#                                └─ (both wait)
+#
+# Proto validation flow:
+#   1. go-test job: verify .proto files compile (syntax check)
+#   2. deploy job: capture fresh fixtures from prod, validate protos match actual API responses
+
+jobs:
+  # ───────────────────────────────────────────────────────────────
+  # 1. Go Build & Test — compiles + tests Go modules, coverage badges
+  # ───────────────────────────────────────────────────────────────
+  go-test:
+    name: "✅ Go Build & Test"
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Skip if docs-only change
+        id: docs-check
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+            NON_DOCS=$(echo "$CHANGED" | grep -cvE '\.(md)$|^LICENSE$|^\.gitignore$|^docs/' || true)
+            if [ "$NON_DOCS" -eq 0 ]; then
+              echo "docs_only=true" >> $GITHUB_OUTPUT
+              echo "📄 Docs-only PR — skipping heavy CI"
+            fi
+          fi
+
+      - name: Set up Go 1.22
+        if: steps.docs-check.outputs.docs_only != 'true'
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.22'
+          cache-dependency-path: |
+            cmd/server/go.sum
+            cmd/ingestor/go.sum
+
+      - name: Build and test Go server (with coverage)
+        if: steps.docs-check.outputs.docs_only != 'true'
+        run: |
+          set -e -o pipefail
+          cd cmd/server
+          go build .
+          go test -coverprofile=server-coverage.out ./... 2>&1 | tee server-test.log
+          echo "--- Go Server Coverage ---"
+          go tool cover -func=server-coverage.out | tail -1
+
+      - name: Build and test Go ingestor (with coverage)
+        if: steps.docs-check.outputs.docs_only != 'true'
+        run: |
+          set -e -o pipefail
+          cd cmd/ingestor
+          go build .
+          go test -coverprofile=ingestor-coverage.out ./... 2>&1 | tee ingestor-test.log
+          echo "--- Go Ingestor Coverage ---"
+          go tool cover -func=ingestor-coverage.out | tail -1
+
+      - name: Verify proto syntax (all .proto files compile)
+        if: steps.docs-check.outputs.docs_only != 'true'
+        run: |
+          set -e
+          echo "Installing protoc..."
+          sudo apt-get update -qq
+          sudo apt-get install -y protobuf-compiler
+          
+          echo "Checking proto syntax..."
+          for proto in proto/*.proto; do
+            echo "  ✓ $(basename "$proto")"
+            protoc --proto_path=proto --descriptor_set_out=/dev/null "$proto"
+          done
+          echo "✅ All .proto files are syntactically valid"
+
+      - name: Generate Go coverage badges
+        if: always() && steps.docs-check.outputs.docs_only != 'true'
+        run: |
+          mkdir -p .badges
+
+          # Parse server coverage
+          SERVER_COV="0"
+          if [ -f cmd/server/server-coverage.out ]; then
+            SERVER_COV=$(cd cmd/server && go tool cover -func=server-coverage.out | tail -1 | grep -oP '[\d.]+(?=%)')
+          fi
+          SERVER_COLOR="red"
+          if [ "$(echo "$SERVER_COV >= 80" | bc -l 2>/dev/null)" = "1" ]; then
+            SERVER_COLOR="green"
+          elif [ "$(echo "$SERVER_COV >= 60" | bc -l 2>/dev/null)" = "1" ]; then
+            SERVER_COLOR="yellow"
+          fi
+          echo "{\"schemaVersion\":1,\"label\":\"go server coverage\",\"message\":\"${SERVER_COV}%\",\"color\":\"${SERVER_COLOR}\"}" > .badges/go-server-coverage.json
+          echo "Go server coverage: ${SERVER_COV}% (${SERVER_COLOR})"
+
+          # Parse ingestor coverage
+          INGESTOR_COV="0"
+          if [ -f cmd/ingestor/ingestor-coverage.out ]; then
+            INGESTOR_COV=$(cd cmd/ingestor && go tool cover -func=ingestor-coverage.out | tail -1 | grep -oP '[\d.]+(?=%)')
+          fi
+          INGESTOR_COLOR="red"
+          if [ "$(echo "$INGESTOR_COV >= 80" | bc -l 2>/dev/null)" = "1" ]; then
+            INGESTOR_COLOR="green"
+          elif [ "$(echo "$INGESTOR_COV >= 60" | bc -l 2>/dev/null)" = "1" ]; then
+            INGESTOR_COLOR="yellow"
+          fi
+          echo "{\"schemaVersion\":1,\"label\":\"go ingestor coverage\",\"message\":\"${INGESTOR_COV}%\",\"color\":\"${INGESTOR_COLOR}\"}" > .badges/go-ingestor-coverage.json
+          echo "Go ingestor coverage: ${INGESTOR_COV}% (${INGESTOR_COLOR})"
+
+          echo "## Go Coverage" >> $GITHUB_STEP_SUMMARY
+          echo "| Module | Coverage |" >> $GITHUB_STEP_SUMMARY
+          echo "|--------|----------|" >> $GITHUB_STEP_SUMMARY
+          echo "| Server | ${SERVER_COV}% |" >> $GITHUB_STEP_SUMMARY
+          echo "| Ingestor | ${INGESTOR_COV}% |" >> $GITHUB_STEP_SUMMARY
+
+      - name: Cancel workflow on failure
+        if: failure()
+        run: |
+          curl -s -X POST \
+            -H "Authorization: Bearer ${{ github.token }}" \
+            "https://api.github.com/repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/cancel"
+
+      - name: Upload Go coverage badges
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: go-badges
+          path: .badges/go-*.json
+          retention-days: 1
+          if-no-files-found: ignore
+
+  # ───────────────────────────────────────────────────────────────
+  # 2. Node.js Tests — backend unit tests + Playwright E2E, coverage
+  # ───────────────────────────────────────────────────────────────
+  node-test:
+    name: "🧪 Node.js Tests"
+    runs-on: [self-hosted, Linux]
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Skip if docs-only change
+        id: docs-check
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
+            NON_DOCS=$(echo "$CHANGED" | grep -cvE '\.(md)$|^LICENSE$|^\.gitignore$|^docs/' || true)
+            if [ "$NON_DOCS" -eq 0 ]; then
+              echo "docs_only=true" >> $GITHUB_OUTPUT
+              echo "📄 Docs-only PR — skipping heavy CI"
+            fi
+          fi
+
+      - name: Set up Node.js 22
+        if: steps.docs-check.outputs.docs_only != 'true'
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Set up Go 1.22
+        if: steps.docs-check.outputs.docs_only != 'true'
+        uses: actions/setup-go@v6
+        with:
+          go-version: '1.22'
+          cache-dependency-path: cmd/server/go.sum
+
+      - name: Build Go server for E2E tests
+        if: steps.docs-check.outputs.docs_only != 'true'
+        run: |
+          cd cmd/server
+          go build -o ../../corescope-server .
+          echo "Go server built successfully"
+
+      - name: Install npm dependencies
+        if: steps.docs-check.outputs.docs_only != 'true'
+        run: npm ci --production=false
+
+      - name: Detect changed files
+        if: steps.docs-check.outputs.docs_only != 'true'
+        id: changes
+        run: |
+          BACKEND=$(git diff --name-only HEAD~1 | grep -cE '^(server|db|decoder|packet-store|server-helpers|iata-coords)\.js$' || true)
+          FRONTEND=$(git diff --name-only HEAD~1 | grep -cE '^public/' || true)
+          TESTS=$(git diff --name-only HEAD~1 | grep -cE '^test-|^tools/' || true)
+          CI=$(git diff --name-only HEAD~1 | grep -cE '\.github/|package\.json|test-all\.sh|scripts/' || true)
+          # If CI/test infra changed, run everything
+          if [ "$CI" -gt 0 ]; then BACKEND=1; FRONTEND=1; fi
+          # If test files changed, run everything
+          if [ "$TESTS" -gt 0 ]; then BACKEND=1; FRONTEND=1; fi
+          echo "backend=$([[ $BACKEND -gt 0 ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+          echo "frontend=$([[ $FRONTEND -gt 0 ]] && echo true || echo false)" >> $GITHUB_OUTPUT
+          echo "Changes: backend=$BACKEND frontend=$FRONTEND tests=$TESTS ci=$CI"
+
+      - name: Run backend tests with coverage
+        if: steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.backend == 'true'
+        run: |
+          npx c8 --reporter=text-summary --reporter=text sh test-all.sh 2>&1 | tee test-output.txt
+          
+          TOTAL_PASS=$(grep -oP '\d+(?= passed)' test-output.txt | awk '{s+=$1} END {print s}')
+          TOTAL_FAIL=$(grep -oP '\d+(?= failed)' test-output.txt | awk '{s+=$1} END {print s}')
+          BE_COVERAGE=$(grep 'Statements' test-output.txt | tail -1 | grep -oP '[\d.]+(?=%)')
+          
+          mkdir -p .badges
+          BE_COLOR="red"
+          [ "$(echo "$BE_COVERAGE > 60" | bc -l 2>/dev/null)" = "1" ] && BE_COLOR="yellow"
+          [ "$(echo "$BE_COVERAGE > 80" | bc -l 2>/dev/null)" = "1" ] && BE_COLOR="brightgreen"
+          echo "{\"schemaVersion\":1,\"label\":\"backend tests\",\"message\":\"${TOTAL_PASS} passed\",\"color\":\"brightgreen\"}" > .badges/backend-tests.json
+          echo "{\"schemaVersion\":1,\"label\":\"backend coverage\",\"message\":\"${BE_COVERAGE}%\",\"color\":\"${BE_COLOR}\"}" > .badges/backend-coverage.json
+          
+          echo "## Backend: ${TOTAL_PASS} tests, ${BE_COVERAGE}% coverage" >> $GITHUB_STEP_SUMMARY
+
+      - name: Run backend tests (quick, no coverage)
+        if: steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.backend == 'false'
+        run: npm run test:unit
+
+      - name: Install Playwright browser
+        if: steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.frontend == 'true'
+        run: |
+          # Install chromium (skips download if already cached on self-hosted runner)
+          npx playwright install chromium 2>/dev/null || true
+          # Install system deps only if missing (apt-get is slow)
+          npx playwright install-deps chromium 2>/dev/null || true
+
+      - name: Instrument frontend JS for coverage
+        if: steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.frontend == 'true'
+        run: sh scripts/instrument-frontend.sh
+
+      - name: Start instrumented test server on port 13581
+        if: steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.frontend == 'true'
+        run: |
+          # Kill any stale server on 13581
+          fuser -k 13581/tcp 2>/dev/null || true
+          sleep 2
+          ./corescope-server -port 13581 -public public-instrumented &
+          echo $! > .server.pid
+          echo "Server PID: $(cat .server.pid)"
+          # Health-check poll loop (up to 30s)
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:13581/api/stats > /dev/null 2>&1; then
+              echo "Server ready after ${i}s"
+              break
+            fi
+            if [ "$i" -eq 30 ]; then
+              echo "Server failed to start within 30s"
+              echo "Last few lines from server logs:"
+              ps aux | grep "corescope-server" || echo "No server process found"
+              exit 1
+            fi
+            sleep 1
+          done
+
+      - name: Run Playwright E2E + coverage collection concurrently
+        if: steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.frontend == 'true'
+        run: |
+          # Run E2E tests and coverage collection in parallel — both use the same server
+          BASE_URL=http://localhost:13581 node test-e2e-playwright.js 2>&1 | tee e2e-output.txt &
+          E2E_PID=$!
+          BASE_URL=http://localhost:13581 node scripts/collect-frontend-coverage.js 2>&1 | tee fe-coverage-output.txt &
+          COV_PID=$!
+
+          # Wait for both — E2E must pass, coverage is best-effort
+          E2E_EXIT=0
+          wait $E2E_PID || E2E_EXIT=$?
+          wait $COV_PID || true
+
+          # Fail if E2E failed
+          [ $E2E_EXIT -ne 0 ] && exit $E2E_EXIT
+          true
+
+      - name: Generate frontend coverage badges
+        if: always() && steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.frontend == 'true'
+        run: |
+          E2E_PASS=$(grep -oP '[0-9]+(?=/)' e2e-output.txt | tail -1)
+          
+          mkdir -p .badges
+          # Merge E2E + coverage collector data if both exist
+          if [ -f .nyc_output/frontend-coverage.json ] || [ -f .nyc_output/e2e-coverage.json ]; then
+            npx nyc report --reporter=text-summary --reporter=text 2>&1 | tee fe-report.txt
+            FE_COVERAGE=$(grep 'Statements' fe-report.txt | head -1 | grep -oP '[\d.]+(?=%)' || echo "0")
+            FE_COVERAGE=${FE_COVERAGE:-0}
+            FE_COLOR="red"
+            [ "$(echo "$FE_COVERAGE > 50" | bc -l 2>/dev/null)" = "1" ] && FE_COLOR="yellow"
+            [ "$(echo "$FE_COVERAGE > 80" | bc -l 2>/dev/null)" = "1" ] && FE_COLOR="brightgreen"
+            echo "{\"schemaVersion\":1,\"label\":\"frontend coverage\",\"message\":\"${FE_COVERAGE}%\",\"color\":\"${FE_COLOR}\"}" > .badges/frontend-coverage.json
+            echo "## Frontend: ${FE_COVERAGE}% coverage" >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "{\"schemaVersion\":1,\"label\":\"frontend tests\",\"message\":\"${E2E_PASS:-0} E2E passed\",\"color\":\"brightgreen\"}" > .badges/frontend-tests.json
+
+      - name: Stop test server
+        if: always() && steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.frontend == 'true'
+        run: |
+          if [ -f .server.pid ]; then
+            kill $(cat .server.pid) 2>/dev/null || true
+            rm -f .server.pid
+            echo "Server stopped"
+          fi
+
+      - name: Run frontend E2E (quick, no coverage)
+        if: steps.docs-check.outputs.docs_only != 'true' && steps.changes.outputs.frontend == 'false'
+        run: |
+          fuser -k 13581/tcp 2>/dev/null || true
+          ./corescope-server -port 13581 -public public &
+          SERVER_PID=$!
+          # Wait for server to be ready (up to 15s)
+          for i in $(seq 1 15); do
+            curl -sf http://localhost:13581/api/stats > /dev/null 2>&1 && break
+            sleep 1
+          done
+          BASE_URL=http://localhost:13581 node test-e2e-playwright.js || true
+          kill $SERVER_PID 2>/dev/null || true
+
+      - name: Cancel workflow on failure
+        if: failure()
+        run: |
+          curl -s -X POST \
+            -H "Authorization: Bearer ${{ github.token }}" \
+            "https://api.github.com/repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/cancel"
+
+      - name: Upload Node.js test badges
+        if: always()
+        uses: actions/upload-artifact@v5
+        with:
+          name: node-badges
+          path: .badges/
+          retention-days: 1
+          if-no-files-found: ignore
+
+  # ───────────────────────────────────────────────────────────────
+  # 3. Build Docker Image
+  # ───────────────────────────────────────────────────────────────
+  build:
+    name: "🏗️ Build Docker Image"
+    if: github.event_name == 'push'
+    needs: [go-test, node-test]
+    runs-on: [self-hosted, Linux]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up Node.js 22
+        uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+
+      - name: Build Go Docker image
+        run: |
+          echo "${GITHUB_SHA::7}" > .git-commit
+          APP_VERSION=$(node -p "require('./package.json').version") \
+          GIT_COMMIT="${GITHUB_SHA::7}" \
+          docker compose --profile staging-go build staging-go
+          echo "Built Go staging image"
+
+  # ───────────────────────────────────────────────────────────────
+  # 4. Deploy Staging — start on port 82, healthcheck, smoke test
+  # ───────────────────────────────────────────────────────────────
+  deploy:
+    name: "🚀 Deploy Staging"
+    if: github.event_name == 'push'
+    needs: [build]
+    runs-on: [self-hosted, Linux]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Start staging on port 82
+        run: |
+          # Force remove stale containers
+          docker rm -f corescope-staging-go 2>/dev/null || true
+          # Clean up stale ports
+          fuser -k 82/tcp 2>/dev/null || true
+          docker compose --profile staging-go up -d staging-go
+
+      - name: Healthcheck staging container
+        run: |
+          for i in $(seq 1 120); do
+            HEALTH=$(docker inspect corescope-staging-go --format '{{.State.Health.Status}}' 2>/dev/null || echo "starting")
+            if [ "$HEALTH" = "healthy" ]; then
+              echo "Staging healthy after ${i}s"
+              break
+            fi
+            if [ "$i" -eq 120 ]; then
+              echo "Staging failed health check after 120s"
+              docker logs corescope-staging-go --tail 50
+              exit 1
+            fi
+            sleep 1
+          done
+
+      - name: Smoke test staging API
+        run: |
+          if curl -sf http://localhost:82/api/stats | grep -q engine; then
+            echo "Staging verified — engine field present ✅"
+          else
+            echo "Staging /api/stats did not return engine field"
+            exit 1
+          fi
+
+  # ───────────────────────────────────────────────────────────────
+  # 5. Publish Badges & Summary
+  # ───────────────────────────────────────────────────────────────
+  publish:
+    name: "📝 Publish Badges & Summary"
+    if: github.event_name == 'push'
+    needs: [deploy]
+    runs-on: [self-hosted, Linux]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Download Go coverage badges
+        continue-on-error: true
+        uses: actions/download-artifact@v5
+        with:
+          name: go-badges
+          path: .badges/
+
+      - name: Download Node.js test badges
+        continue-on-error: true
+        uses: actions/download-artifact@v5
+        with:
+          name: node-badges
+          path: .badges/
+
+      - name: Publish coverage badges to repo
+        continue-on-error: true
+        run: |
+          git config user.name "github-actions"
+          git config user.email "actions@github.com"
+          git remote set-url origin https://x-access-token:${{ github.token }}@github.com/${{ github.repository }}.git
+          git add .badges/ -f
+          git diff --cached --quiet || (git commit -m "ci: update test badges [skip ci]" && git push) || echo "Badge push failed"
+
+      - name: Post deployment summary
+        run: |
+          echo "## Staging Deployed ✓" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Commit:** \`$(git rev-parse --short HEAD)\` — $(git log -1 --format=%s)" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Staging:** http://<VM_HOST>:82" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "To promote to production:" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
+          echo "ssh deploy@\$VM_HOST" >> $GITHUB_STEP_SUMMARY
+          echo "cd /opt/corescope-deploy" >> $GITHUB_STEP_SUMMARY
+          echo "./manage.sh promote" >> $GITHUB_STEP_SUMMARY
+          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

.gitignore

@@ -4,5 +4,27 @@ data/
 *.db
 *.db-journal
 config.json
+.env
 data-lincomatic/
 config-lincomatic.json
+theme.json
+firmware/
+coverage/
+public-instrumented/
+.nyc_output/
+.setup-state
+# Squad: ignore runtime state (logs, inbox, sessions)
+.squad/orchestration-log/
+.squad/log/
+.squad/decisions/inbox/
+.squad/sessions/
+# Squad: SubSquad activation file (local to this machine)
+.squad-workstream
+# Temp scripts / build artifacts
+recover-delta.sh
+merge.sh
+replacements.txt
+reps.txt
+cmd/server/server.exe
+cmd/ingestor/ingestor.exe
+# CI trigger

.squad/agents/bishop/charter.md

@@ -0,0 +1,48 @@
+# Bishop — Tester
+
+Unit tests, Playwright E2E, coverage gates, and quality assurance for CoreScope.
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**Stack:** Node.js native test runner, Playwright, c8 + nyc (coverage), supertest
+**User:** User
+
+## Responsibilities
+
+- Unit tests: test-packet-filter.js, test-aging.js, test-decoder.js, test-decoder-spec.js, test-server-helpers.js, test-server-routes.js, test-packet-store.js, test-db.js, test-frontend-helpers.js, test-regional-filter.js, test-regional-integration.js, test-live-dedup.js
+- Playwright E2E: test-e2e-playwright.js (8 browser tests, default localhost:3000)
+- E2E tools: tools/e2e-test.js, tools/frontend-test.js
+- Coverage: Backend 85%+ (c8), Frontend 42%+ (Istanbul + nyc). Both only go up.
+- Review authority: May approve or reject work from Hicks and Newt based on test results
+
+## Boundaries
+
+- Test the REAL code — import actual modules, don't copy-paste functions into test files
+- Use vm.createContext for frontend helpers (see test-frontend-helpers.js pattern)
+- Playwright tests default to localhost:3000 — NEVER run against prod
+- Every bug fix gets a regression test
+- Every new feature must add tests — test count only goes up
+- Run `npm test` to verify all tests pass before approving
+
+## Review Authority
+
+- May approve or reject based on test coverage and quality
+- On rejection: specify what tests are missing or failing
+- Lockout rules apply
+
+## Key Test Commands
+
+```
+npm test                    # all backend tests + coverage summary
+npm run test:unit           # fast: unit tests only
+npm run test:coverage       # all tests + HTML coverage report
+node test-packet-filter.js  # filter engine
+node test-decoder.js        # packet decoder
+node test-server-routes.js  # API routes via supertest
+node test-e2e-playwright.js # 8 Playwright browser tests
+```
+
+## Model
+
+Preferred: auto

.squad/agents/bishop/history.md

@@ -0,0 +1,76 @@
+# Bishop — History
+
+## Project Context
+
+CoreScope has 14 test files, 4,290 lines of test code. Backend coverage 85%+, frontend 42%+. Tests use Node.js native runner, Playwright for E2E, c8/nyc for coverage, supertest for API routes. vm.createContext pattern used for testing frontend helpers in Node.js.
+
+User: User
+
+## Learnings
+
+- Session started 2026-03-26. Team formed: Kobayashi (Lead), Hicks (Backend), Newt (Frontend), Bishop (Tester).
+- E2E run 2026-03-26: 12/16 passed, 4 failed. Results:
+  - ✅ Home page loads
+  - ✅ Nodes page loads with data
+  - ❌ Map page loads with markers — No markers found (empty DB, no geo data)
+  - ✅ Packets page loads with filter
+  - ✅ Node detail loads
+  - ✅ Theme customizer opens
+  - ✅ Dark mode toggle
+  - ✅ Analytics page loads
+  - ✅ Map heat checkbox persists in localStorage
+  - ✅ Map heat checkbox is clickable
+  - ✅ Live heat disabled when ghosts mode active
+  - ✅ Live heat checkbox persists in localStorage
+  - ✅ Heatmap opacity persists in localStorage
+  - ❌ Live heatmap opacity persists — browser closed before test ran (bug: browser.close() on line 274 is before tests 14-16)
+  - ❌ Customizer has separate map/live opacity sliders — same browser-closed bug
+  - ❌ Map re-renders on resize — same browser-closed bug
+- BUG FOUND: test-e2e-playwright.js line 274 calls `await browser.close()` before tests 14, 15, 16 execute. Those 3 tests will always fail. The `browser.close()` must be moved after all tests.
+- The "Map page loads with markers" failure is expected with an empty local DB — no nodes with coordinates exist to render markers.
+- FIX APPLIED 2026-03-26: Moved `browser.close()` from between test 13 and test 14 to after test 16 (just before the summary). Tests 14 ("Live heatmap opacity persists") and 15 ("Customizer has separate map/live opacity sliders") now pass. Test 16 ("Map re-renders on resize") now runs but fails due to empty DB (no markers to count) — same root cause as test 3. Result: 14/16 pass, 2 fail (both map-marker tests, expected with empty DB).
+- TESTS ADDED 2026-03-26: Issue #127 (copyToClipboard) — 8 unit tests in test-frontend-helpers.js using vm.createContext + DOM/clipboard mocks. Tests cover: fallback path (execCommand success/fail/throw), clipboard API path, null/undefined input, textarea lifecycle, no-callback usage. Pattern: `makeClipboardSandbox(opts)` helper builds sandbox with configurable navigator.clipboard and document.execCommand mocks. Total frontend helper tests: 47→55.
+- TESTS ADDED 2026-03-26: Issue #125 (packet detail dismiss) — 1 E2E test in test-e2e-playwright.js. Tests: click row → pane opens (empty class removed) → click ✕ → pane closes (empty class restored). Skips gracefully when DB has no packets. Inserted before analytics group, before browser.close().
+- E2E SPEED OPTIMIZATION 2026-03-26: Rewrote test-e2e-playwright.js for performance per Kobayashi's audit. Changes:
+  - Replaced ALL 19 `waitUntil: 'networkidle'` → `'domcontentloaded'` + targeted `waitForSelector`/`waitForFunction`. networkidle stalls ~500ms+ per navigation due to persistent WebSocket + Leaflet tiles.
+  - Eliminated 11 of 12 `waitForTimeout` sleeps → event-driven waits (waitForSelector, waitForFunction). Only 1 remains: 500ms for packet filter debounce (was 1500ms).
+  - Reordered tests into page groups to eliminate 7 redundant navigations (page.goto 14→7): Home(1,6,7), Nodes(2,5), Map(3,9,10,13,16), Packets(4), Analytics(8), Live(11,12), NoNav(14,15).
+  - Reduced default timeout from 15s to 10s.
+  - All 17 test names and assertions preserved unchanged.
+  - Verified: 17/17 tests pass against local server with generated test data.
+- COVERAGE PIPELINE TIMING (measured locally, Windows):
+  - Phase 1: Istanbul instrumentation (22 JS files) — **3.7s**
+  - Phase 2: Server startup (COVERAGE=1) — **~2s** (ready after pre-warm)
+  - Phase 3: Playwright E2E (test-e2e-playwright.js, 17 tests) — **3.7s**
+  - Phase 4: Coverage collector (collect-frontend-coverage.js) — **746s (12.4 min)** ← THE BOTTLENECK
+  - Phase 5: nyc report generation — **1.8s**
+  - TOTAL: ~757s (~12.6 min locally). CI reports ~13 min (matches).
+  - ROOT CAUSE: collect-frontend-coverage.js is a 978-line script that launches a SECOND Playwright browser and exhaustively clicks every UI element on every page to maximize code coverage. It contains:
+    - 169 explicit `waitForTimeout()` calls totaling 104.1s (1.74 min) of hard sleep
+    - 21 `waitUntil: 'networkidle'` navigations (each adds ~2-15s depending on page load + WebSocket/tile activity)
+    - Visits 12 pages: Home, Nodes, Packets, Map, Analytics, Customizer, Channels, Live, Traces, Observers, Perf, plus global router/theme exercises
+    - Heaviest sections by sleep: Packets (13s), Analytics (13.8s), Nodes (11.6s), Live (11.7s), App.js router (10.4s)
+    - The networkidle waits are the real killer — they stall ~500ms-15s EACH waiting for WebSocket + Leaflet tiles to settle
+  - Note: test-e2e-interactions.js (called in combined-coverage.sh) does not exist — it fails silently via `|| true`
+  - OPTIMIZATION OPPORTUNITIES: Replace networkidle→domcontentloaded (same fix as E2E tests), replace waitForTimeout with event-driven waits, reduce/batch page navigations, parallelize independent page exercises
+- REGRESSION TESTS ADDED 2026-03-27: Memory optimization (observation deduplication). 8 new tests in test-packet-store.js under "=== Observation deduplication (transmission_id refs) ===" section. Tests verify: (1) observations don't duplicate raw_hex/decoded_json, (2) transmission fields accessible via store.byTxId.get(obs.transmission_id), (3) query() and all() still return transmission fields for backward compat, (4) multiple observations share one transmission_id, (5) getSiblings works after dedup, (6) queryGrouped returns transmission fields, (7) memory estimate reflects dedup savings. 4 tests fail pre-fix (expected — Hicks hasn't applied changes yet), 4 pass (backward compat). Pattern: use hasOwnProperty() to distinguish own vs inherited/absent fields.
+- REVIEW 2026-03-27: Hicks RAM fix (observation dedup). REJECTED. Tests pass (42 packet-store + 204 route), but 5 server.js consumers access `.hash`, `.raw_hex`, `.decoded_json`, `.payload_type` on lean observations from `byObserver.get()` or `tx.observations` without enrichment. Broken endpoints: (1) `/api/nodes/bulk-health` line 1141 `o.hash` undefined, (2) `/api/nodes/network-status` line 1220 `o.hash` undefined, (3) `/api/analytics/signal` lines 1298+1306 `p.hash`/`p.raw_hex` undefined, (4) `/api/observers/:id/analytics` lines 2320+2329+2361 `p.payload_type`/`p.decoded_json` undefined + lean objects sent to client as recentPackets, (5) `/api/analytics/subpaths` line 2711 `o.hash` undefined. All are regional filtering or analytics code paths that use `byObserver` directly. Fix: either enrich at these call sites or store `hash` on observations (it's small). The enrichment pattern works for `getById()`, `getSiblings()`, and `/api/packets/:id` but was not applied to the 5 other consumers. Route tests pass because they don't assert on these specific field values in analytics responses.
+- BATCH REVIEW 2026-03-27: Reviewed 6 issue fixes pushed without sign-off. Full suite: 971 tests, 0 failures across 11 test files. Cache busters uniform (v=1774625000). Verdicts:
+  - #133 (phantom nodes): ✅ APPROVED. 12 assertions on removePhantomNodes, real db.js code, edge cases (idempotency, real node preserved, stats filtering).
+  - #123 (channel hash): ⚠️ APPROVED WITH NOTES. 6 new decoder tests cover channelHashHex (zero-padding) and decryptionStatus (no_key ×3, decryption_failed). Missing: `decrypted` status untested (needs valid crypto key), frontend rendering of "Ch 0xXX (no key)" untested.
+  - #126 (offline node on map): ✅ APPROVED. 3 regression tests: ambiguous prefix→null, unique prefix→resolves, dead node stays dead. Caching verified. Excellent quality.
+  - #130 (disappearing nodes): ✅ APPROVED. 8 pruneStaleNodes tests cover dim/restore/remove for API vs WS nodes. Real live.js via vm.createContext.
+  - #131 (auto-updating nodes): ⚠️ APPROVED WITH NOTES. 8 solid isAdvertMessage tests (real code). BUT 5 WS handler tests are source-string-match checks (`src.includes('loadNodes(true)')`) — these verify code exists but not that it works at runtime. No runtime test for debounce batching behavior.
+  - #129 (observer comparison): ✅ APPROVED. 11 comprehensive tests for comparePacketSets — all edge cases, performance (10K hashes <500ms), mathematical invariant. Real compare.js via vm.createContext.
+  - NOTES FOR IMPROVEMENT: (1) #131 debounce behavior should get a runtime test via vm.createContext, not string checks. (2) #123 could benefit from a `decrypted` status test if crypto mocking is feasible. Neither is blocking.
+- TEST GAP FIX 2026-03-27: Closed both noted gaps from batch review:
+  - #123 (channel hash decryption `decrypted` status): 3 new tests in test-decoder.js. Used require.cache mocking to swap ChannelCrypto module with mock that returns `{success:true, data:{...}}`. Tests cover: (1) decrypted status with sender+message (text formatted as "Sender: message"), (2) decrypted without sender (text is just message), (3) multiple keys tried, first match wins (verifies iteration order + call count). All verify channelHashHex, type='CHAN', channel name, sender, timestamp, flags. require.cache is restored in finally block.
+  - #131 (WS handler runtime tests): Rewrote 5 `src.includes()` string-match tests to use vm.createContext with runtime execution. Created `makeNodesWsSandbox()` helper that provides controllable setTimeout (timer queue), mock DOM, tracked api/invalidateApiCache calls, and real `debouncedOnWS` logic. Tests run actual nodes.js init() and verify: (1) ADVERT triggers refresh with 5s debounce, (2) non-ADVERT doesn't trigger refresh, (3) debounce collapses 3 ADVERTs into 1 API call, (4) _allNodes cache reset forces re-fetch, (5) scroll/selection preserved (panel innerHTML + scrollTop untouched by WS handler). Total: 87 frontend helper tests (same count — 5 replaced, not added), 61 decoder tests (+3).
+  - Technique learned: require.cache mocking is effective for testing code paths that depend on external modules (like ChannelCrypto). Store original, replace exports, restore in finally. Controllable setTimeout (capturing callbacks in array, firing manually) enables testing debounce logic without real timers.
+
+- **Massive session 2026-03-27 (FULL DAY):** Reviewed and approved all 6 fixes, closed 2 test gaps, validated E2E:
+  - **Batch PR review:** #123 (channel hash), #126 (ambiguous prefixes), #130 (live map), #131 (WS auto-update), #129 (observer comparison) — 2 gaps identified, resolved.
+  - **Gap 1 closed:** #123 decrypted status mocked via require.cache (ChannelCrypto module swap). 3 new decoder tests.
+  - **Gap 2 closed:** #131 WS debounce runtime tests via vm.createContext. 5 source-match tests replaced with actual execution tests. Controllable setTimeout technique verified.
+  - **Test counts:** 109 db tests (+14 phantom), 204 route tests (+5 WS), 90 frontend tests (+3 pane), 61 decoder tests (+3 channel), 25 Go ingestor tests, 42 Go server tests.
+  - **E2E validation:** 16 Playwright tests passing, all routes functional with merged 1.237M observation DB. Browser smoke tests verified. Coverage 85%+ backend, 42%+ frontend.

.squad/agents/hicks/charter.md

@@ -0,0 +1,41 @@
+# Hicks — Backend Dev
+
+Server, decoder, packet-store, SQLite, API, MQTT, WebSocket, and performance for CoreScope.
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**Stack:** Node.js 18+, Express 5, SQLite (better-sqlite3), MQTT (mqtt), WebSocket (ws)
+**User:** User
+
+## Responsibilities
+
+- server.js — Express API routes, MQTT ingestion, WebSocket broadcast
+- decoder.js — Custom MeshCore packet parser (header, path, payload, adverts)
+- packet-store.js — In-memory ring buffer + indexes (O(1) lookups)
+- db.js — SQLite schema, prepared statements, migrations
+- server-helpers.js — Shared backend helpers (health checks, geo distance)
+- Performance optimization — caching, response times, no O(n²)
+- Docker/deployment — Dockerfile, manage.sh, docker-compose
+- MeshCore protocol — read firmware source before protocol changes
+
+## Boundaries
+
+- Do NOT modify frontend files (public/*.js, public/*.css, index.html)
+- Always read AGENTS.md before starting work
+- Always read firmware source (firmware/src/) before protocol changes
+- Run `npm test` before considering work done
+- Cache busters are Newt's job, but flag if you change an API response shape
+
+## Key Files
+
+- server.js (2,661 lines) — main backend
+- decoder.js (320 lines) — packet parser
+- packet-store.js (668 lines) — in-memory store
+- db.js (743 lines) — SQLite layer
+- server-helpers.js (289 lines) — shared helpers
+- iata-coords.js — airport coordinates for regional filtering
+
+## Model
+
+Preferred: auto

.squad/agents/hicks/history.md

@@ -0,0 +1,30 @@
+# Hicks — History
+
+## Project Context
+
+CoreScope is a real-time LoRa mesh packet analyzer. Node.js + Express + SQLite backend, vanilla JS SPA frontend. Custom decoder.js fixes path_length bug from upstream library. In-memory packet store provides O(1) lookups for 30K+ packets. TTL response cache achieves 7,000× speedup on bulk health endpoint.
+
+User: User
+
+## Learnings
+
+- Session started 2026-03-26. Team formed: Kobayashi (Lead), Hicks (Backend), Newt (Frontend), Bishop (Tester).
+- Split the monolithic "Frontend coverage (instrumented Playwright)" CI step into 5 discrete steps: Instrument frontend JS, Start test server (with health-check poll replacing sleep 5), Run Playwright E2E tests, Extract coverage + generate report, Stop test server. Cleanup/report steps use `if: always()` so server shutdown happens even on test failure. Server PID shared across steps via .server.pid file. "Frontend E2E only" fast-path left untouched.
+- Fixed memory explosion in packet-store.js: observations no longer duplicate transmission fields (hash, raw_hex, decoded_json, payload_type, route_type). Instead, observations store only `transmission_id` as a reference. Added `_enrichObs()` to hydrate observations at API boundaries (getById, getSiblings, enrichObservations). Replaced `.all()` with `.iterate()` for streaming load. Updated `_transmissionsForObserver()` to use transmission_id instead of hash. For a 185MB DB with 50K transmissions × 23 observations avg, this eliminates ~1.17M copies of hex dumps and JSON — projected ~2GB RAM savings.
+- Built standalone Go MQTT ingestor (`cmd/ingestor/`). Ported decoder.js → Go (header parsing, path extraction, all payload types, advert decoding with flags/lat/lon/name). Ported db.js v3 schema (transmissions + observations + nodes + observers). Ported computeContentHash (SHA-256 based, path-independent). Uses modernc.org/sqlite (pure Go, no CGO) and paho.mqtt.golang. 25 tests passing (decoder golden fixtures from production data + DB schema compatibility). Supports same config.json format as Node.js server. Handles Format 1 (raw packet) messages; companion bridge format deferred. System Go was 1.17 — installed Go 1.22.5 to support modern dependencies.
+- Built standalone Go web server (`cmd/server/`) — READ side of the Go rewrite. 35+ REST API endpoints ported from server.js. All queries go directly to SQLite (no in-memory packet store). WebSocket broadcast via SQLite polling. Static file server with SPA fallback. Uses gorilla/mux for routing, gorilla/websocket for WS, modernc.org/sqlite for DB. 42 tests passing (20 DB query tests, 20+ route integration tests, 2 WebSocket tests). `go vet` clean. Binary compiles to single executable. Analytics endpoints that required Node.js in-memory store (topology, distance, hash-sizes, subpaths) return structural stubs — core data (RF stats, channels, node health, etc.) fully functional via SQL. System Go 1.17 → installed Go 1.22 for build. Each cmd/* module has its own go.mod (no root-level go.mod).
+- Go server API parity fix: Rewrote QueryPackets from observation-centric (packets_v view) to transmission-centric (transmissions table + correlated subqueries). This fixes both performance (9s to sub-100ms for unfiltered queries on 1.2M rows) and response shape. Packets now return first_seen, timestamp (= first_seen), observation_count, and NOT created_at/payload_version/score. Node responses now include last_heard (= last_seen fallback), hash_size (null), hash_size_inconsistent (false). Added schema version detection (v2 vs v3 observations table). Fixed QueryGroupedPackets first_seen. Added GetRecentTransmissionsForNode. All tests pass, build clean with Go 1.22.
+- Fixed #133 (node count keeps climbing): `db.getStats().totalNodes` used `SELECT COUNT(*) FROM nodes` which counts every node ever seen — 6800+ on a ~200-400 node mesh. Changed `totalNodes` to count only nodes with `last_seen` within 7 days. Added `totalNodesAllTime` for the full historical count. Also filtered role counts in `/api/stats` to the same 7-day window. Added `countActiveNodes` and `countActiveNodesByRole` prepared statements in db.js. 6 new tests (95 total in test-db.js). The existing `idx_nodes_last_seen` index covers the new queries.
+- Go server FULL API parity: Rewrote QueryGroupedPackets from packets_v VIEW scan (8s on 1.2M rows) to transmission-centric query (<100ms). Fixed GetStats to use 7-day window for totalNodes + added totalNodesAllTime. Split GetRoleCounts into 7-day (for /api/stats) and all-time (for /api/nodes). Added packetsLastHour + node lat/lon/role to /api/observers via batch queries (GetObserverPacketCounts, GetNodeLocations). Added multi-node filter support (/api/packets?nodes=pk1,pk2). Fixed /api/packets/:id to return parsed path_json in path field. Populated bulk-health per-node stats from SQL. Updated test seed data to use dynamic timestamps for 7-day filter compatibility. All 42+ tests pass, go vet clean.
+- Fixed #133 ROOT CAUSE (phantom nodes): `autoLearnHopNodes` in server.js was calling `db.upsertNode()` for every unresolved hop prefix, creating thousands of fake "repeater" nodes with short public_keys (just the 2-4 byte hop prefix). Removed the `upsertNode` call entirely — unresolved hops are now simply cached to skip repeat DB lookups, and display as raw hex prefixes via hop-resolver. Added `db.removePhantomNodes()` that deletes nodes with `LENGTH(public_key) <= 16` (real pubkeys are 64 hex chars). Called at server startup to purge existing phantoms. 14 new test assertions (109 total in test-db.js).
+- Fixed #126 (offline node showing on map due to hash prefix collision): `updatePathSeenTimestamps()` and `autoLearnHopNodes()` used `LIKE prefix%` DB queries that non-deterministically picked the first match when multiple nodes shared a hash prefix (e.g. `1CC4` and `1C82` both start with `1C` under 1-byte hash_size). Extracted `resolveUniquePrefixMatch()` that checks for uniqueness — ambiguous prefixes (matching 2+ nodes) are skipped and cached in a negative-cache Set. This prevents dead nodes from getting `last_heard` updates from packets that actually belong to a different node. 3 new tests (207 total in test-server-routes.js).
+- Fixed #123 (channel hash for undecrypted GRP_TXT): Added `channelHashHex` (zero-padded uppercase hex) and `decryptionStatus` ('decrypted'|'no_key'|'decryption_failed') fields to `decodeGrpTxt` in decoder.js. Distinguishes between "no channel keys configured" vs "keys tried but decryption failed." Frontend packets.js updated: list preview shows "🔒 Ch 0xXX (status)", detail pane hex breakdown and message area show channel hash with status label. 6 new tests (58 total in test-decoder.js).
+- Ported in-memory packet store to Go (`cmd/server/store.go`). PacketStore loads all transmissions + observations from SQLite at startup via streaming query (no .all()), builds 5 indexes (byHash, byTxID, byObsID, byObserver, byNode), picks longest-path observation per transmission for display fields. QueryPackets and QueryGroupedPackets serve from memory with full filter support (type, route, observer, hash, since, until, region, node). Poller ingests new transmissions into store via IngestNewFromDB. Server/routes fall back to direct DB queries when store is nil (backward-compatible with tests). All 42+ existing tests pass, go vet clean, go build clean. System Go 1.17 requires using Go 1.22.5 at C:\go1.22\go\bin.
+- Fixed 3 critically slow Go endpoints by switching from SQLite queries against packets_v VIEW (1.2M rows) to in-memory PacketStore queries. `/api/channels` 7.2s→37ms (195×), `/api/channels/:hash/messages` 8.2s→36ms (228×), `/api/analytics/rf` 4.2s→90ms avg (47×). Key optimizations: (1) byPayloadType index reduces channels scan from 52K to 17K packets, (2) struct-based JSON decode avoids map[string]interface{} allocations, (3) per-transmission work hoisted out of 1.2M observation loop for RF, (4) eliminated second-pass time.Parse over 1.2M observations (track min/max timestamps as strings instead), (5) pre-allocated slices with capacity hints, (6) 15-second TTL cache for RF analytics (separate mutex to avoid contention with store RWMutex). Cache invalidation is TTL-only because live mesh generates continuous ingest events. Also fixed `/api/analytics/channels` to use store. All handlers fall back to DB when store is nil (test compat).
+- **Massive session 2026-03-27 (FULL DAY):** Delivered 6 critical fixes + Go rewrite completed:
+  - **#133 PHANTOM NODES (ROOT CAUSE):** Backend `autoLearnHopNodes()` removed upsertNode call. Added `db.removePhantomNodes()` (pubkey ≤16 chars). Called at startup. Cascadia: 7,308 → ~200-400 active nodes. 14 new tests, all passing.
+  - **#133 ACTIVE WINDOW:** `/api/stats` `totalNodes` now 7-day window. Added `totalNodesAllTime` for historical. Role counts filtered to 7-day. Go server GetStats updated for parity.
+  - **#126 AMBIGUOUS PREFIXES:** `resolveUniquePrefixMatch()` requires unique prefix match. Ambiguous prefixes skipped, cached in negative-cache. Prevents dead nodes from wrong packet attribution.
+  - **#123 CHANNEL HASH:** Decoder tracks `channelHashHex` + `decryptionStatus` ('decrypted'|'no_key'|'decryption_failed'). All 4 fixes tested, deployed.
+  - **Go API Parity:** QueryGroupedPackets transmission-centric 8s→<100ms. Response shapes match Node.js exactly. All 42+ Go tests passing.
+  - **Database merge:** Staging 185MB (50K tx + 1.2M obs) merged into prod 21MB. 0 data loss. Merged DB 51,723 tx + 1,237,186 obs. Deploy time 8,491ms, memory 860MiB RSS (v.s. 2.7GB pre-RAM-fix). Backups retained 7 days.

.squad/agents/hudson/charter.md

@@ -0,0 +1,41 @@
+# Hudson — DevOps Engineer
+
+## Identity
+- **Name:** Hudson
+- **Role:** DevOps Engineer
+- **Emoji:** ⚙️
+
+## Scope
+- CI/CD pipeline (`.github/workflows/deploy.yml`)
+- Docker configuration (`Dockerfile`, `docker/`)
+- Deployment scripts (`manage.sh`)
+- Production infrastructure and monitoring
+- Server configuration and environment setup
+- Performance profiling and optimization of CI/build pipelines
+- Database operations (backup, recovery, migration)
+- Coverage collection pipeline (`scripts/collect-frontend-coverage.js`)
+
+## Boundaries
+- Does NOT write application features — that's Hicks (backend) and Newt (frontend)
+- Does NOT write application tests — that's Bishop
+- MAY modify test infrastructure (CI config, coverage tooling, test runners)
+- MAY modify server startup/config for deployment purposes
+- Coordinates with Kobayashi on infrastructure decisions
+
+## Key Files
+- `.github/workflows/deploy.yml` — CI/CD pipeline
+- `Dockerfile`, `docker/` — Container config
+- `manage.sh` — Deployment management script
+- `scripts/` — Build and coverage scripts
+- `config.example.json` — Configuration template
+- `package.json` — Dependencies and scripts
+
+## Principles
+- Infrastructure as code — all config in version control
+- CI must stay under 10 minutes (currently ~14min — fix this)
+- Never break the deploy pipeline
+- Test infrastructure changes locally before pushing
+- Read AGENTS.md before any work
+
+## Model
+Preferred: auto

.squad/agents/hudson/history.md

@@ -0,0 +1,88 @@
+## Learnings — Pre-Session Archived Notes (2026-03-26 to 2026-03-27 early)
+
+Historical context from earlier phases:
+
+### V8 Heap Analysis (2026-03-27 06:00 UTC)
+- Tested NODE_OPTIONS=4GB heap for staging with 1.17M observations
+- Result: 2.7GB peak RAM (35% of 7.7GB VM), successful load completion
+- Lesson: Default 1.7GB heap insufficient for large datasets; explicit NODE_OPTIONS needed
+
+### Production Issue Diagnosis (2026-03-27 02:20 UTC)
+- Root cause identified: SQLite WAL checkpoint failure causing 100% CPU
+- Database entered locked state; transaction retries caused spin loop
+- Solution: Restart container to recover from locked state
+- Corrupted WAL file was non-recoverable (4.7MB unrecoverable log)
+
+### Azure VM Cost Analysis (requested 2026-03-27)
+- Current: Standard_D2as_v5 (2 vCPU, 8GB) ~-75/mo
+- Alternative: Standard_B2s (2 vCPU, 4GB) ~-18/mo for testing
+- Recommendation: Reserved instances for 30-40% savings if stable
+
+### Staging DB Setup Planning (2026-03-27 ~04:41 UTC)
+- Prod DB location: Docker volume (21MB, fresh after incident)
+- Old DB: ~/meshcore-data-old/meshcore.db (185MB, problematic)
+- Staging destination: ~/meshcore-staging-data/ (copy for debugging)
+- Key insight: Docker Compose migration requires volume → bind mount data migration
+
+### Docker Compose Architecture Design (2026-03-27, Issue #132 M1)
+- Created docker-compose.yml with prod + staging services
+- Prod: ports 80/443/1883; Staging: ports 81/1884 (HTTP only)
+- Data: bind mounts (~/meshcore-data, ~/meshcore-staging-data)
+- Caddy TLS: Docker volumes (prod/staging separate)
+- env vars: Configurable ports, configurable data paths
+- Profiles: Staging only starts with --profile staging
+
+### manage.sh Orchestration Updates (2026-03-27, Issue #132 M2)
+- Added Compose mode detection + legacy single-container fallback
+- New commands: start/stop/restart/status/logs/promote
+- Staging-specific: prepare_staging_db(), prepare_staging_config()
+- All existing tests pass (62 packet-filter, 29 aging)
+
+---
+---
+
+## Massive Session - 2026-03-27 (FULL DAY)
+
+### Database Merge Execution
+- **Status:** ✅ Complete, deployed to production
+- **Pre-merge verification:** Disk space confirmed, schemas both v3, counts captured
+- **Backup creation:** Timestamped /home/deploy/backups/pre-merge-20260327-071425/ with prod + staging DBs
+- **Merge execution:** Staging DB used as base (superset). Transmissions INSERT OR IGNORE by hash. Observations all unique. Nodes/observers latest-wins + sum counts.
+- **Results:** 51,723 tx + 1,237,186 obs merged. Hash uniqueness verified. Spot check passed.
+- **Deployment:** Docker Compose managed meshcore-prod (replaced old Docker volume approach). Load time 8,491ms. Memory 860MiB RSS (no NODE_OPTIONS needed — RAM fix proved effective).
+- **Health:** Healthy within 30s. External access via https://analyzer.00id.net ✅
+
+### Infrastructure Changes
+- deploy user SSH key + docker group re-added via Azure CLI
+- Old Docker volumes removed
+- NODE_OPTIONS hack removed (no longer needed post-RAM-fix)
+
+### Docker Compose Migration
+- **Volume paths unified:** caddy-data (prod), caddy-data-staging (staging)
+- **Data directories:** ~/meshcore-data (prod), ~/meshcore-staging-data (staging) via bind mounts
+- **Config files:** Separate config.prod.json, config.staging.json
+- **Caddyfile:** Separate Caddyfile.prod (HTTPS), Caddyfile.staging (HTTP :81)
+
+### Staging Environment Setup
+- **Data:** ~/meshcore-staging-data/ with copy of problematic DB (185MB) for debugging
+- **Purpose:** Debug corrupted WAL from 100% CPU incident
+- **MQTT:** Port 1884 (separate from prod 1883)
+- **HTTP:** Plaintext port 81 (no HTTPS)
+
+### CI Pipeline Updates
+- **Docker Compose v2 auto-check:** CI deploy job now auto-installs docker-compose-plugin if missing (self-healing per user directive)
+- **Staging auto-deploy:** Build image once, deploy staging auto on every master push. Health check via Docker Compose.
+- **Production manual:** No auto-restart of prod. Promotion via ./manage.sh promote (Hudson only).
+
+### Testing & Validation
+- ✅ docker-compose config validation
+- ✅ Service startup verification
+- ✅ Volume mount verification (data persistence)
+- ✅ Health check behavior (Docker Compose native)
+
+### Key Decisions Applied
+- Only Hudson touches prod infrastructure (user directive)
+- Go staging runs on port 82 (future phase)
+- Backups retained 7 days post-merge
+- Manual promotion flow (no auto-promotion to prod)
+

.squad/agents/kobayashi/charter.md

@@ -0,0 +1,37 @@
+# Kobayashi — Lead
+
+Architecture, code review, and decision-making for CoreScope.
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**Stack:** Node.js 18+, Express 5, SQLite, vanilla JS frontend, Leaflet, WebSocket, MQTT
+**User:** User
+
+## Responsibilities
+
+- Review architecture decisions and feature proposals
+- Code review — approve or reject with actionable feedback
+- Scope decisions — what to build, what to defer
+- Documentation updates (README, docs/)
+- Ensure AGENTS.md rules are followed (plan before implementing, tests required, cache busters, etc.)
+- Coordinate multi-domain changes spanning backend and frontend
+
+## Boundaries
+
+- Do NOT write implementation code — delegate to Hicks (backend) or Newt (frontend)
+- May write small fixes during code review if the change is trivial
+- Architecture proposals require user sign-off before implementation starts
+
+## Review Authority
+
+- May approve or reject work from Hicks, Newt, and Bishop
+- On rejection: specify whether to reassign or escalate
+- Lockout rules apply — rejected author cannot self-revise
+
+## Key Files
+
+- AGENTS.md — project rules (read before every review)
+- server.js — main backend (2,661 lines)
+- public/ — frontend modules (22 files)
+- package.json — dependencies (keep minimal)

.squad/agents/kobayashi/history.md

@@ -0,0 +1,33 @@
+# Kobayashi — History
+
+## Project Context
+
+CoreScope is a real-time LoRa mesh packet analyzer. Node.js + Express + SQLite backend, vanilla JS SPA frontend with Leaflet maps, WebSocket live feed, MQTT ingestion. Production at v2.6.0, ~18K lines, 85%+ backend test coverage.
+
+User: User
+
+## Learnings
+
+- Session started 2026-03-26. Team formed: Kobayashi (Lead), Hicks (Backend), Newt (Frontend), Bishop (Tester).
+- **E2E Playwright performance audit (2026-03-26):** 16 tests, single browser/context/page (good). Key bottlenecks: (1) `waitUntil: 'networkidle'` used ~20 times — catastrophic for SPA with WebSocket + map tiles, (2) ~17s of hardcoded `waitForTimeout` sleeps, (3) redundant `page.goto()` to same routes across tests, (4) CI installs Playwright browser on every run with no caching, (5) coverage collection launches a second full browser session, (6) `sleep 5` server startup instead of health-check polling. Estimated 40-50% total runtime reduction achievable.
+- **Issue triage session (2026-03-27):** Triaged 4 open issues, assigned to team:
+  - **#131** (Feature: Auto-update nodes tab) → Newt (⚛️). Requires WebSocket real-time updates in nodes.js, similar to existing packets feed.
+  - **#130** (Bug: Disappearing nodes on live map) → Newt (⚛️). High severity, multiple Cascadia Mesh community reports. Likely status calculation or map filter bug. Nodes visible in static list but vanishing from live map.
+  - **#129** (Feature: Packet comparison between observers) → Newt (⚛️). Feature request from letsmesh analyzer. Side-by-side packet filtering for two repeaters to diagnose repeater issues.
+  - **#123** (Feature: Show channel hash on decrypt failure) → Hicks (🔧). Core contributor (lincomatic) request. Decoder needs to track why decrypt failed (no key vs. corruption) and expose channel hash + reason in API response.
+- **Massive session — 2026-03-27 (full day):**
+  - **#133 root cause (phantom nodes):** `autoLearnHopNodes()` creates stub nodes for unresolved hop prefixes (2-8 hex chars). Cascadia showed 7,308 nodes (6,638 repeaters) when real size ~200-400. With `hash_size=1`, collision rate high → infinite phantom generation.
+  - **DB merge decision:** Staging DB (185MB, 50K transmissions, 1.2M observations) is superset. Use as merge base. Transmissions dedup by hash (unique), observations all preserved (unique by observer), nodes/observers latest-wins + sum counts. 6-phase execution plan: pre-flight, backup, merge, deploy, validate, cleanup.
+  - **Coordination:** Assigned Hicks phantom cleanup (backend), Newt live page pruning (frontend), Hudson merge execution (DevOps).
+  - **Outcome:** All 4 triaged issues fixed (#131, #130, #129, #123), #133 (phantom nodes) fully resolved, #126 (ambiguous hop prefixes) fixed as bonus, database merged successfully (0 data loss, 2 min downtime, 51,723 tx + 1.237M obs), Go rewrite (MQTT ingestor + web server) completed and ready for staging.
+  - **Team expanded:** Hudson joined for DevOps work, Ripley joined as Support Engineer.
+- **Go staging bug triage (2026-03-28):** Filed 8 issues for Go staging bugs missed during API parity work. All found by actually loading the analytics page in a browser — none caught by endpoint-level parity checks.
+  - **#142** (Channels tab: wrong count, all decrypted, undefined fields) → Hicks
+  - **#136** (Hash stats tab: empty) → Hicks
+  - **#138** (Hash issues: no inconsistencies/collision risks shown) → Hicks
+  - **#135** (Topology tab: broken) → Hicks
+  - **#134** (Route patterns: broken) → Hicks
+  - **#140** (bulk-health API: 12s response time) → Hicks
+  - **#137** (Distance tab: broken) → Hicks
+  - **#139** (Commit link: bad contrast) → Newt
+  - **Post-mortem:** Parity was verified by comparing individual endpoint response shapes in isolation. Nobody loaded the analytics page in a browser and looked at it. The agents tested API responses without browser validation of the full UI — exactly the failure mode AGENTS.md rule #2 exists to prevent.

.squad/agents/newt/charter.md

@@ -0,0 +1,45 @@
+# Newt — Frontend Dev
+
+Vanilla JS UI, Leaflet maps, live visualization, theming, and all public/ modules for CoreScope.
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**Stack:** Vanilla HTML/CSS/JavaScript (ES5/6), Leaflet maps, WebSocket, Canvas animations
+**User:** User
+
+## Responsibilities
+
+- public/*.js — All 22 frontend modules (app.js, packets.js, live.js, map.js, nodes.js, channels.js, analytics.js, customize.js, etc.)
+- public/style.css, public/live.css, public/home.css — Styling via CSS variables
+- public/index.html — SPA shell, cache busters (MUST bump on every .js/.css change)
+- packet-filter.js — Wireshark-style filter engine (standalone, testable in Node.js)
+- Leaflet map rendering, VCR playback controls, Canvas animations
+- Theme customizer (IIFE in customize.js, THEME_CSS_MAP)
+
+## Boundaries
+
+- Do NOT modify server-side files (server.js, db.js, packet-store.js, decoder.js)
+- All colors MUST use CSS variables — never hardcode #hex outside :root
+- Use shared helpers from roles.js (ROLE_COLORS, TYPE_COLORS, getNodeStatus, getHealthThresholds)
+- Prefer `n.last_heard || n.last_seen` for display and status
+- No per-packet API calls from frontend — fetch bulk, filter client-side
+- Run `node test-packet-filter.js` and `node test-frontend-helpers.js` after filter/helper changes
+- Always bump cache busters in the SAME commit as code changes
+
+## Key Files
+
+- live.js (2,178 lines) — largest frontend module, VCR playback
+- analytics.js (1,375 lines) — global analytics dashboard
+- customize.js (1,259 lines) — theme customizer IIFE
+- packets.js (1,669 lines) — packet feed, detail pane, hex breakdown
+- app.js (775 lines) — SPA router, WebSocket, globals
+- nodes.js (765 lines) — node directory, detail views
+- map.js (699 lines) — Leaflet map rendering
+- packet-filter.js — standalone filter engine
+- roles.js — shared color maps and helpers
+- hop-resolver.js — client-side hop resolution
+
+## Model
+
+Preferred: auto

.squad/agents/newt/history.md

@@ -0,0 +1,24 @@
+# Newt — History
+
+## Project Context
+
+CoreScope is a real-time LoRa mesh packet analyzer with a vanilla JS SPA frontend. 22 frontend modules, Leaflet maps, WebSocket live feed, VCR playback, Canvas animations, theme customizer with CSS variables. No build step, no framework. ES5/6 for broad browser support.
+
+User: User
+
+## Learnings
+
+- Session started 2026-03-26. Team formed: Kobayashi (Lead), Hicks (Backend), Newt (Frontend), Bishop (Tester).
+- **Issue #127 fix:** Firefox clipboard API fails silently when `navigator.clipboard.writeText()` is called outside a secure context or without proper user gesture handling. Added `window.copyToClipboard()` shared helper to `roles.js` that tries Clipboard API first, falls back to hidden textarea + `document.execCommand('copy')`. Updated all 3 clipboard call sites: `nodes.js` (Copy URL — the reported bug), `packets.js` (Copy Link — had ugly `prompt()` fallback), `customize.js` (Copy to Clipboard — already worked but now uses shared helper). Cache busters bumped. All tests pass (47 frontend, 62 packet-filter).
+- **Issue #125 fix:** Added dismiss/close button (✕) to the packet detail pane on desktop. Extracted `closeDetailPanel()` shared helper and `PANEL_CLOSE_HTML` constant — DRY: Escape handler and click handler both call it. Close button uses event delegation on `#pktRight`, styled with CSS variables (`--text-muted`, `--text`, `--surface-1`) matching the mobile `.mobile-sheet-close` pattern. Hidden when panel is in `.empty` state. Clicking a different row still re-opens with new data. Files changed: `public/packets.js`, `public/style.css`. Cache busters NOT bumped (another agent editing index.html).
+- **Issue #122 fix:** Node tooltip (line 45) and node detail panel (line 120) in `channels.js` used `last_seen` alone for "Last seen" display. Changed both to `last_heard || last_seen` per AGENTS.md pitfall. Pattern: always prefer `last_heard || last_seen` for any time-ago display. **Server note for Hicks:** `/api/nodes/search` and `/api/nodes/:pubkey` endpoints don't return `last_heard` — only the bulk `/api/nodes` list endpoint computes it from the in-memory packet store. These endpoints need the same `last_heard` enrichment for the frontend fix to fully take effect. Also, `/api/analytics/channels` has a separate bug: `lastActivity` is overwritten unconditionally (no `>=` check) so it shows the oldest packet's timestamp, not the newest.
+- **Issue #130 fix:** Live map `pruneStaleNodes()` (added for #133) was completely removing stale nodes from the map, while the static map dims them with CSS. Root cause: API-loaded nodes and WS-only nodes were treated identically — both got deleted when stale. Fix: mark API-loaded nodes with `_fromAPI = true` in `loadNodes()`. `pruneStaleNodes()` now dims API nodes (fillOpacity 0.25, opacity 0.15) instead of removing them, and restores full opacity when they become active again. WS-only dynamic nodes are still removed to prevent memory leaks. Pattern: **live map should match static map behavior** — never remove database-loaded nodes, only change their visual state. 3 new tests added (63 total frontend tests passing).
+- **Issue #129 fix:** Added observer packet comparison feature (`#/compare` page). Users select two observers from dropdowns, click Compare, and see which packets each observer saw in the last 24 hours. Data flow: fetches packets per observer via existing `/api/packets?observer=X&limit=10000&since=24h`, computes set intersection/difference client-side using `comparePacketSets()` (O(n) via Set lookups — no nested loops). UI: three summary cards (both/only-A/only-B with counts and percentages), horizontal stacked bar chart, packet type breakdown for shared packets, and tabbed detail tables (up to 200 rows each, clickable to packet detail). URL is shareable: `#/compare?a=ID1&b=ID2`. Added 🔍 compare button to observers page header. Pure function `comparePacketSets` exposed on `window` for testability. 11 new tests (87 total frontend tests). Files: `public/compare.js` (new), `public/style.css`, `public/observers.js`, `public/index.html`, `test-frontend-helpers.js`. Cache busters bumped.
+- **Browser validation of 6 fixes (2026-03-27):** Validated against live prod at `https://analyzer.00id.net`. Results: ✅ #133 (phantom nodes) — API returns 50 nodes, reasonable count, no runaway growth. ✅ #123 (channel hash on undecrypted) — GRP_TXT packets with `decryption_failed` status show `channelHashHex` field; packet detail renders `🔒 Channel Hash: 0xE2 (decryption failed)` via `packets.js:1254-1259`. ⏭ #126 (offline node on map) — skipped, requires specific dead node. ✅ #130 (disappearing nodes on live map) — `pruneStaleNodes()` confirmed at `live.js:1474` dims API-loaded nodes (`fillOpacity:0.25`) instead of removing; `_fromAPI=true` flag set at `live.js:1279`. ✅ #131 (auto-updating node list) — `nodes.js:210-216` wires `debouncedOnWS` handler that triggers `loadNodes(true)` on ADVERT messages; `isAdvertMessage()` at `nodes.js:852` checks `payload_type===4`. ✅ #129 (observer comparison) — `compare.js` deployed with full UI: observer dropdowns, `comparePacketSets()` Set logic, summary cards, bar chart, type breakdown. 16 observers available in prod. Pattern: always verify deployed JS matches source — cache buster `v=1774625000` confirmed consistent across all script tags.
+- **Packet detail pane fresh-load fix:** The `detail-collapsed` class added for issue #125's close button wasn't applied on initial render, so the empty right panel was visible on fresh page load. Fix: added `detail-collapsed` to the `split-layout` div in the initial `innerHTML` template (packets.js:183). Pattern: when adding a CSS toggle class, always consider the initial DOM state — if nothing is selected, the default state must match "nothing selected." 3 tests added (90 total frontend). Cache busters bumped.
+- **Massive session 2026-03-27 (FULL DAY):** Delivered 4 critical frontend fixes + live page improvements:
+  - **#130 LIVE MAP STALE DIMMING:** `pruneStaleNodes()` distinguishes API-loaded (`_fromAPI`) from WS-only. Dims API nodes (fillOpacity 0.25, opacity 0.15) instead of removing. Matches static map behavior. 3 new tests, all passing.
+  - **#131 NODES TAB WS AUTO-UPDATE:** `loadNodes(refreshOnly)` pattern resets cache + invalidateApiCache + re-fetches. Preserves scroll/selection/listeners. WS handler now triggers on ADVERT messages (payload_type===4). All tests passing.
+  - **#129 OBSERVER COMPARISON PAGE:** New `#/compare` route with shareable params `?a=ID1&b=ID2`. `comparePacketSets()` pure function (O(n) Set operations). UI: summary cards, bar chart, type breakdown, detail tables. 🔍 compare button on observers header.
+  - **#133 LIVE PAGE NODE PRUNING:** Prune every 60s using `getNodeStatus()` from roles.js (per-role health thresholds: 24h companions/sensors, 72h infrastructure). `_liveSeen` timestamp set on insert, updated on re-observation. Bounded memory usage. 
+  - **Database merge:** All frontend endpoints working with merged 1.237M observation DB. Load speed verified. All 4 fixes tested end-to-end in browser.

.squad/agents/ralph/charter.md

@@ -0,0 +1,21 @@
+# Ralph — Work Monitor
+
+Tracks the work queue and keeps the team moving. Always on the roster.
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**User:** User
+
+## Responsibilities
+
+- Scan for untriaged issues, assigned work, open PRs, CI failures
+- Drive the work-check loop until the board is clear
+- Report board status on request
+- Never stop until explicitly told to idle
+
+## Boundaries
+
+- Does not write code
+- Does not make architecture decisions
+- Routes work to appropriate agents via the coordinator

.squad/agents/ralph/history.md

@@ -0,0 +1,16 @@
+# Project Context
+
+- **Project:** meshcore-analyzer
+- **Created:** 2026-03-26
+
+## Core Context
+
+Agent Ralph initialized and ready for work.
+
+## Recent Updates
+
+📌 Team initialized on 2026-03-26
+
+## Learnings
+
+Initial setup complete.

.squad/agents/ripley/charter.md

@@ -0,0 +1,50 @@
+# Ripley — Support Engineer
+
+Deep knowledge of every frontend behavior, API response, and user-facing feature in CoreScope. Fields community questions, triages bug reports, and explains "why does X look like Y."
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**Stack:** Vanilla JS frontend (public/*.js), Node.js backend, SQLite, WebSocket, MQTT
+**User:** Kpa-clawbot
+
+## Responsibilities
+
+- Answer user questions about UI behavior ("why is this node gray?", "why don't I see my repeater?")
+- Triage community bug reports and feature requests on GitHub issues
+- Know every frontend module intimately — read all public/*.js files before answering
+- Know the API response shapes — what each endpoint returns and how the frontend uses it
+- Know the status/health system — roles.js thresholds, active/stale/degraded/silent states
+- Know the map behavior — marker colors, opacity, filtering, live vs static
+- Know the packet display — filter syntax, detail pane, hex breakdown, decoded fields
+- Reproduce reported issues by checking live data via API
+
+## Boundaries
+
+- Does NOT write code — routes fixes to Hicks (backend) or Newt (frontend)
+- Does NOT deploy — routes to Hudson
+- MAY comment on GitHub issues with explanations and triage notes
+- MAY suggest workarounds to users while fixes are in progress
+
+## Key Knowledge Areas
+
+- **Node colors/status:** roles.js defines ROLE_COLORS, health thresholds per role. Gray = stale/silent. Dimmed = opacity 0.25 on live map.
+- **last_heard vs last_seen:** Always prefer `last_heard || last_seen`. last_heard from packet store (all traffic), last_seen from DB (adverts only).
+- **Hash prefixes:** 1-byte or 2-byte hash_size affects node disambiguation. hash_size_inconsistent flag.
+- **Packet types:** ADVERT, TXT_MSG, GRP_TXT, REQ, CHAN, POS — what each means.
+- **Observer vs Node:** Observers are MQTT-connected gateways. Nodes are mesh devices.
+- **Live vs Static map:** Live map shows real-time WS data + API nodes. Static map shows all known nodes from API.
+- **Channel decryption:** channelHashHex, decryptionStatus (decrypted/no_key/decryption_failed)
+- **Geo filter:** polygon + bufferKm in config.json, excludes nodes outside boundary
+
+## How to Answer Questions
+
+1. Read the relevant frontend code FIRST — don't guess
+2. Check the live API data if applicable (analyzer.00id.net is public)
+3. Explain in user-friendly terms, not code jargon
+4. If it's a bug, route to the right squad member
+5. If it's expected behavior, explain WHY
+
+## Model
+
+Preferred: auto

.squad/agents/ripley/history.md

@@ -0,0 +1,21 @@
+# Ripley — Support Engineer History
+
+## Core Context
+- Project: CoreScope — real-time LoRa mesh packet analyzer
+- User: Kpa-clawbot
+- Joined the team 2026-03-27 to handle community support and triage
+
+## Learnings
+
+- **Staleness thresholds (2026-03-27):** Nodes have per-role health calculations:
+  - **Companions & sensors:** 24-hour stale threshold
+  - **Infrastructure (repeaters, rooms):** 72-hour stale threshold
+  - All-time node count tracked separately (new 	otalNodesAllTime field in /api/stats)
+  - 7-day active window used for stats endpoint 	otalNodes display
+  - Source: getNodeStatus() in 
+oles.js, used by live page pruning every 60s
+
+- **Phantom nodes incident (2026-03-27):** Cascadia mesh instance showed 7,308 nodes (6,638 repeaters) when real count ~200-400. Root cause: utoLearnHopNodes() created stubs for unresolved hop prefixes. Fixed at backend + frontend real-time pruning. Now properly cleaned at startup.
+
+- **Database state (2026-03-27):** Staging DB (185MB, 50K transmissions, 1.2M observations) successfully merged with prod (21MB). Merged DB now 51,723 tx + 1,237,186 obs. Load time 8,491ms, memory 860MiB RSS. No data loss. Backups retained 7 days.
+

.squad/agents/scribe/charter.md

@@ -0,0 +1,26 @@
+# Scribe — Session Logger
+
+Silent agent that maintains decisions, logs, and cross-agent context for CoreScope.
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**User:** User
+
+## Responsibilities
+
+- Merge decision inbox files (.squad/decisions/inbox/) → decisions.md
+- Write orchestration log entries (.squad/orchestration-log/)
+- Write session logs (.squad/log/)
+- Cross-agent context sharing — append team updates to affected agents' history.md
+- Archive old decisions when decisions.md exceeds ~20KB
+- Summarize history.md files when they exceed ~12KB
+- Git commit .squad/ changes after work
+
+## Boundaries
+
+- Never speak to the user
+- Never modify code files
+- Only write to .squad/ files
+- Always deduplicate when merging inbox entries
+- Use ISO 8601 UTC timestamps for all log files

.squad/agents/scribe/history.md

@@ -0,0 +1,31 @@
+# Project Context
+
+- **Project:** meshcore-analyzer
+- **Created:** 2026-03-26
+
+## Core Context
+
+Agent Scribe: Silent session logger maintaining decisions, orchestration logs, and cross-agent context.
+
+## Recent Updates
+
+**2026-03-28T02:30:00Z — Session finalization**
+- Processed spawn manifest: Hicks (5 fixes), Newt (1 fix), Coordinator (infrastructure). Total session: 58 issues filed, 58 closed.
+- Decision inbox verified empty — all prior entries (protobuf contract, infrastructure, test isolation, clipboard helper) already merged and committed
+- Orchestration logs written: 8 entries covering 28+ closed issues, 2 Go services, DB merge, staging deployment
+- decisions.md verified: ~360 lines, 15+ decisions logged, under archival threshold
+- Scribe history updated for this session
+- Note: Orchestration log files are gitignored (runtime state) — tracked via decisions.md and agent history
+
+**2026-03-27 — Prior sessions**
+- Team: 7 agents (Kobayashi, Hicks, Newt, Bishop, Hudson, Ripley, Scribe)
+- Merged 5+ decisions into decisions.md
+- Processed protobuf contract architecture decision
+- Logged infrastructure connection details
+
+## Learnings
+
+- Charter: Never speak to user, only modify .squad/ files, deduplicate on merge, use ISO 8601 UTC timestamps
+- Inbox patterns: Check for duplicates before merging, note timestamp to avoid re-processing
+- Git: Orchestration logs are gitignored (runtime), tracked decisions/history are committed
+- Session state: 58 issues = major output; decisions and orchestration logs capture team intent

.squad/casting/history.json

@@ -0,0 +1,11 @@
+{
+  "assignments": [
+    {
+      "assignment_id": "meshcore-analyzer-001",
+      "universe": "aliens",
+      "created_at": "2026-03-26T04:22:08Z",
+      "agents": ["Kobayashi", "Hicks", "Newt", "Bishop"],
+      "reason": "Initial team casting for CoreScope project"
+    }
+  ]
+}

.squad/casting/policy.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "universes_allowed": ["aliens"],
+  "max_per_universe": 10,
+  "overflow_strategy": "diegetic_expansion"
+}

.squad/casting/registry.json

@@ -0,0 +1,52 @@
+{
+  "entries": [
+    {
+      "persistent_name": "Kobayashi",
+      "role": "Lead",
+      "universe": "aliens",
+      "created_at": "2026-03-26T04:22:08Z",
+      "legacy_named": false,
+      "status": "active"
+    },
+    {
+      "persistent_name": "Hicks",
+      "role": "Backend Dev",
+      "universe": "aliens",
+      "created_at": "2026-03-26T04:22:08Z",
+      "legacy_named": false,
+      "status": "active"
+    },
+    {
+      "persistent_name": "Newt",
+      "role": "Frontend Dev",
+      "universe": "aliens",
+      "created_at": "2026-03-26T04:22:08Z",
+      "legacy_named": false,
+      "status": "active"
+    },
+    {
+      "persistent_name": "Bishop",
+      "role": "Tester",
+      "universe": "aliens",
+      "created_at": "2026-03-26T04:22:08Z",
+      "legacy_named": false,
+      "status": "active"
+    },
+    {
+      "persistent_name": "Hudson",
+      "role": "DevOps Engineer",
+      "universe": "aliens",
+      "created_at": "2026-03-27T02:00:00Z",
+      "legacy_named": false,
+      "status": "active"
+    },
+    {
+      "persistent_name": "Ripley",
+      "role": "Support Engineer",
+      "universe": "aliens",
+      "created_at": "2026-03-27T16:12:00Z",
+      "legacy_named": false,
+      "status": "active"
+    }
+  ]
+}

.squad/ceremonies.md

@@ -0,0 +1,41 @@
+# Ceremonies
+
+> Team meetings that happen before or after work. Each squad configures their own.
+
+## Design Review
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | before |
+| **Condition** | multi-agent task involving 2+ agents modifying shared systems |
+| **Facilitator** | lead |
+| **Participants** | all-relevant |
+| **Time budget** | focused |
+| **Enabled** | ✅ yes |
+
+**Agenda:**
+1. Review the task and requirements
+2. Agree on interfaces and contracts between components
+3. Identify risks and edge cases
+4. Assign action items
+
+---
+
+## Retrospective
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | after |
+| **Condition** | build failure, test failure, or reviewer rejection |
+| **Facilitator** | lead |
+| **Participants** | all-involved |
+| **Time budget** | focused |
+| **Enabled** | ✅ yes |
+
+**Agenda:**
+1. What happened? (facts only)
+2. Root cause analysis
+3. What should change?
+4. Action items for next iteration

.squad/decisions.md

@@ -0,0 +1,56 @@
+# Squad Decisions
+
+## Active Decisions
+
+### 2026-03-28T05:30:00Z: User directive — soft-delete nodes
+**By:** User (via Copilot)
+**What:** Don't delete stale nodes from DB — mark them as inactive instead. Add an `active` boolean column (or use last_seen threshold). All node queries (API, stats, analytics) should exclude inactive nodes. Historical data preserved but not shown on the site.
+**Why:** User request — keep historical data, just don't pollute the UI with stale nodes.
+
+### 2026-03-27T22:00:00Z: Proto fixture capture in CI
+**By:** Copilot (User directive)
+**What:** Proto fixture capture in CI should run against prod (the stable reference), not staging. Staging may have broken code. Prod is known-good.
+**Why:** Ensures fixture definitions are derived from a stable, known-good API contract. Prevents broken staging deployments from breaking proto contracts.
+
+### 2026-03-27T20:56:00Z: Architecture decision — Protobuf API contract
+**By:** Copilot (Architecture decision)
+**What:** All frontend/backend interfaces get protobuf definitions as the single source of truth. Go generates structs with JSON tags from protos. Node stays unchanged — protos are derived FROM Node's current JSON shapes. Proto definitions MUST use inheritance and composition (no repeating field definitions). Data flow: SQLite → proto struct → JSON. JSON blobs from DB deserialize against proto structs for validation.
+**Why:** Eliminates the endless parity bugs between Node and Go. Compiler-enforced contract instead of agent-verified field matching. DRY — shared message types composed, not duplicated.
+
+### 2026-03-27T02:18:00Z: Infrastructure connection details
+**By:** Squad Coordinator (capturing session discoveries)
+**What:** Production VM connection details established this session:
+- **VM Name:** meshcore-vm
+- **Resource Group:** MESHCORE-WEST-RG
+- **Region:** westus2
+- **Size:** Standard_D2as_v5 (Linux)
+- **Public IP:** (see VM_HOST env var)
+- **SSH User:** deploy
+- **SSH Command:** `ssh deploy@$VM_HOST`
+- **Azure CLI:** v2.84.0 (upgraded from 2.11.1 this session — stale .pyc files cleared)
+- **CI Runner:** self-hosted on this same VM ("meshcore-vm")
+- **App path:** TBD (Hudson investigating via SSH)
+- **DB path:** TBD (Hudson investigating via SSH)
+**Why:** Team needs a single reference for prod access. Hudson, Hicks, and any future agent doing prod debugging needs these details.
+
+### 2026-03-27T00:06:00Z: User directive — auto-close issues with commit messages
+**By:** User (via Copilot)
+**What:** Always use "Fixes #N" or "Closes #N" in commit messages so GitHub auto-closes issues on push. Don't just reference issue numbers in description text.
+**Why:** User request — captured for team memory. Previous commit listed issues but didn't trigger auto-close.
+
+### 2026-03-26T19:10:00Z: User directive — test data isolation
+**By:** User (via Copilot)
+**What:** Seeded test data for E2E tests must be isolated — never pollute production or deployed containers. Use a separate test-only DB or inject via test harness. Seed before tests, tear down after. No seed scripts in Docker image.
+**Why:** User request — captured for team memory.
+
+### 2026-03-26T19:00:00Z: Shared clipboard helper in roles.js
+**Author:** Newt  
+**What:** Added `window.copyToClipboard(text, onSuccess, onFail)` to `roles.js` as the single clipboard implementation for all frontend modules.
+**Rationale:** Three separate files had their own clipboard logic (nodes.js, packets.js, customize.js) — one had no fallback, one used `prompt()`, one had a proper fallback. DRY principle: one implementation, used everywhere. The helper tries `navigator.clipboard.writeText()` first, falls back to hidden textarea + `document.execCommand('copy')` for Firefox and older browsers.
+**Impact:** Any future copy-to-clipboard needs should use `window.copyToClipboard()` instead of calling the Clipboard API directly.
+
+## Governance
+
+- All meaningful changes require team consensus
+- Document architectural decisions here
+- Keep history focused on work, decisions focused on direction

.squad/decisions/decisions.md

@@ -0,0 +1,354 @@
+# Squad Decisions Log
+
+---
+
+## Decision: User Directives
+
+### 2026-03-27T04:27 — Docker Compose v2 Plugin Check
+**By:** User (via Copilot)  
+**Decision:** CI pipeline should check if `docker compose` (v2 plugin) is installed on the self-hosted runner and install it if needed, as part of the deploy job itself.  
+**Rationale:** Self-healing CI is preferred over manual VM setup; the VM may not have docker compose v2 installed.
+
+### 2026-03-27T04:39 — Staging DB: Use Old Problematic DB
+**By:** User (via Copilot)  
+**Decision:** Staging environment's primary purpose is debugging the problematic DB that caused 100% CPU on prod. Use the old DB (`~/meshcore-data-old/` on the VM) for staging. Prod keeps its current (new) DB. Never put the problematic DB on prod.  
+**Rationale:** This is the reason the staging environment was built.
+
+### 2026-03-27T06:09 — Plan Go Rewrite (MQTT Separation)
+**By:** User (via Copilot)  
+**Decision:** Start planning a Go rewrite. First step: separate MQTT ingestion (writes to DB) from the web server (reads from DB + serves API/frontend). Two separate services.  
+**Rationale:** Node.js single-thread + V8 heap limitations cause fragility at scale (185MB DB → 2.7GB heap → OOM). Go eliminates heap cap problem and enables real concurrency.
+
+### 2026-03-27T06:31 — NO PII in Git
+**By:** User (via Copilot)  
+**Decision:** NEVER write real names, usernames, email addresses, or any PII to files committed to git. Use "User" for attribution and "deploy" for SSH/server references. This is a PUBLIC repo.  
+**Rationale:** PII was leaked to the public repo and required a full git history rewrite to remove.
+
+### 2026-03-27T02:19 — Production/Infrastructure Touches: Hudson Only
+**By:** User (via Copilot)  
+**Decision:** Production/infrastructure touches (SSH, DB ops, server restarts, Azure operations) should only be done by Hudson (DevOps). No other agents should touch prod directly.  
+**Rationale:** Separation of concerns — dev agents write code, DevOps deploys and manages prod.
+
+### 2026-03-27T03:36 — Staging Environment Architecture
+**By:** User (via Copilot)  
+**Decision:**
+1. No Docker named volumes — always bind mount from `~/meshcore-data` (host location, easy to access)
+2. Staging container runs on plaintext port (e.g., port 81, no HTTPS)
+3. Use Docker Compose to orchestrate prod + staging containers on the same VM
+4. `manage.sh` supports launching prod only OR prod+staging with clear messaging
+5. Ports must be configurable via `manage.sh` or environment, with sane defaults
+
+### 2026-03-27T03:43 — Staging Refinements: Shared Data
+**By:** User (via Copilot)  
+**Decision:**
+1. Staging copies prod DB on launch (snapshot into staging data dir when started)
+2. Staging connects to SAME MQTT broker as prod (not its own Mosquitto)
+
+**Rationale:** Staging needs real data (prod-like conditions) to be useful for testing.
+
+### 2026-03-27T17:13 — Scribe Auto-Run After Agent Batches
+**By:** User (via Copilot)  
+**Decision:** Scribe must run after EVERY batch of agent work automatically. No manual triggers. No reminders needed. This is a process guarantee, not a suggestion.  
+**Rationale:** Coordinator has been forgetting to spawn Scribe after agent batches complete. This is a process failure. Scribe auto-spawn ends the forgetfulness.
+
+---
+
+## Decision: Technical Fixes
+
+### Issue #126 — Skip Ambiguous Hop Prefixes
+**By:** Hicks (Backend Dev)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+When resolving hop prefixes to full node pubkeys, require a **unique match**. If prefix matches 2+ nodes in DB, skip it and cache in `ambiguousHopPrefixes` (negative cache). Prevents hash prefix collisions (e.g., `1CC4` vs `1C82` sharing prefix `1C` under 1-byte hash_size) from attributing packets to wrong nodes.
+
+**Impact:**
+- Hopresixes that collide won't update `lastPathSeenMap` for any node (conservative, correct)
+- `disambiguateHops()` still does geometric disambiguation for route visualization
+- Performance: `LIMIT 2` query efficient; ambiguous results cached
+
+---
+
+### Issue #133 — Phantom Nodes & Active Window
+**By:** Hicks (Backend Dev)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+**Part 1: Remove phantom node creation**
+- `autoLearnHopNodes()` no longer calls `db.upsertNode()` for unresolved hops
+- Added `db.removePhantomNodes()` — deletes nodes where `LENGTH(public_key) <= 16` (real keys are 64 hex chars)
+- Called at startup to purge existing phantoms from prior behavior
+- Hop-resolver still handles unresolved prefixes gracefully
+
+**Part 2: totalNodes now 7-day active window**
+- `/api/stats` `totalNodes` returns only nodes seen in last 7 days (was all-time)
+- New field `totalNodesAllTime` for historical tracking
+- Role counts (repeaters, rooms, companions, sensors) also filtered to 7-day window
+- Frontend: no changes needed (same field name, smaller correct number)
+
+**Impact:** Frontend `totalNodes` now reflects active mesh size. Go server should apply same 7-day filter when querying.
+
+---
+
+### Issue #123 — Channel Hash on Undecrypted Messages
+**By:** Hicks  
+**Status:** Implemented
+
+Fixed test coverage for decrypted status tracking on channel messages.
+
+---
+
+### Issue #130 — Live Map: Dim Stale Nodes, Don't Remove
+**By:** Newt (Frontend)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+`pruneStaleNodes()` in `live.js` now distinguishes API-loaded nodes (`_fromAPI`) from WS-only dynamic nodes. API nodes dimmed (reduced opacity) when stale instead of removed. WS-only nodes still pruned to prevent memory leaks.
+
+**Rationale:** Static map shows stale nodes with faded markers; live map was deleting them, causing user-reported disappearing nodes. Parity expected.
+
+**Pattern:** Database-loaded nodes never removed from map during session. Future live map features should respect `_fromAPI` flag.
+
+---
+
+### Issue #131 — Nodes Tab Auto-Update via WebSocket
+**By:** Newt (Frontend)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+WS-driven page updates must reset local caches: (1) set local cache to null, (2) call `invalidateApiCache()`, (3) re-fetch. New `loadNodes(refreshOnly)` pattern skips full DOM rebuild, only updates data rows. Preserves scroll, selection, listeners.
+
+**Trap:** Two-layer caching (local variable + API cache) prevents re-fetches. All three reset steps required.
+
+**Pattern:** Other pages doing WS-driven updates should follow same approach.
+
+---
+
+### Issue #129 — Observer Comparison Page
+**By:** Newt (Frontend)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+Added `comparePacketSets(hashesA, hashesB)` as standalone pure function exposed on `window` for testability. Computes `{ onlyA, onlyB, both }` via Set operations (O(n)).
+
+**Pattern:** Comparison logic decoupled from UI, reusable. Client-side diff avoids new server endpoint. 24-hour window keeps data size reasonable (~10K packets max).
+
+---
+
+### Issue #132 — Detail Pane Collapse
+**By:** Newt (Frontend)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+Detail pane collapse uses CSS class on parent container. Add `detail-collapsed` class to `.split-layout`, which sets `.panel-right` to `display: none`. `.panel-left` with `flex: 1` fills 100% width naturally.
+
+**Pattern:** CSS class toggling on parent cleaner than inline styles, easier to animate, keeps layout logic in CSS.
+
+---
+
+## Decision: Infrastructure & Deployment
+
+### Database Merge — Prod + Staging
+**By:** Kobayashi (Lead) / Hudson (DevOps)  
+**Date:** 2026-03-27  
+**Status:** ✅ Complete
+
+Merged staging DB (185MB, 50K transmissions + 1.2M observations) into prod DB (21MB). Dedup strategy:
+- **Transmissions:** `INSERT OR IGNORE` on `hash` (unique key)
+- **Observations:** All unique by observer, all preserved
+- **Nodes/Observers:** Latest `last_seen` wins, sum counts
+
+**Results:**
+- Merged DB: 51,723 transmissions, 1,237,186 observations
+- Deployment: Docker Compose managed `meshcore-prod` with bind mounts
+- Load time: 8,491ms, Memory: 860MiB RSS (no NODE_OPTIONS needed, RAM fix effective)
+- Downtime: ~2 minutes
+- Backups: Retained at `/home/deploy/backups/pre-merge-20260327-071425/` until 2026-04-03
+
+---
+
+### Unified Docker Volume Paths
+**By:** Hudson (DevOps)  
+**Date:** 2026-03-27  
+**Status:** Applied
+
+Reconciled `manage.sh` and `docker-compose.yml` Docker volume names:
+- Caddy volume: `caddy-data` everywhere (prod); `caddy-data-staging` for staging
+- Data directory: Bind mount via `PROD_DATA_DIR` env var, default `~/meshcore-data`
+- Config/Caddyfile: Mounted from repo checkout for prod, staging data dir for staging
+- Removed deprecated `version` key from docker-compose.yml
+
+**Consequence:** `./manage.sh start` and `docker compose up prod` now produce identical mounts. Anyone with data in old `caddy-data-prod` volume will need Caddy to re-provision TLS certs automatically.
+
+---
+
+### Staging DB Setup & Production Data Locations
+**By:** Hudson (DevOps)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+**Production Data Locations:**
+- **Prod DB:** Docker volume `meshcore-data` → `/var/lib/docker/volumes/meshcore-data/_data/meshcore.db` (21MB, fresh)
+- **Prod config:** `/home/deploy/meshcore-analyzer/config.json` (bind mount, read-only)
+- **Caddyfile:** `/home/deploy/meshcore-analyzer/caddy-config/Caddyfile` (bind mount, read-only)
+- **Old (broken) DB:** `~/meshcore-data-old/meshcore.db` (185MB, DO NOT DELETE)
+- **Staging data:** `~/meshcore-staging-data/` (copy of broken DB + config)
+
+**Rules:**
+- DO NOT delete `~/meshcore-data-old/` — backup of problematic DB
+- DO NOT modify staging DB before staging container ready
+- Only Hudson touches prod infrastructure
+
+---
+
+## Decision: Go Rewrite — API & Storage
+
+### Go MQTT Ingestor (cmd/ingestor/)
+**By:** Hicks (Backend Dev)  
+**Date:** 2026-03-27  
+**Status:** Implemented, 25 tests passing
+
+Standalone Go MQTT ingestor service. Separate process from Node.js web server that handles MQTT packet ingestion + writes to shared SQLite DB.
+
+**Architecture:**
+- Single binary, no CGO (uses `modernc.org/sqlite` pure Go)
+- Reads same `config.json` (mqttSources array)
+- Shares SQLite DB with Node.js (WAL mode for concurrent access)
+- Format 1 (raw packet) MQTT only — companion bridge stays in Node.js
+- No HTTP/WebSocket — web layer stays in Node.js
+
+**Ported from decoder.js:**
+- Packet header/path/payloads, advert with flags/lat/lon/name
+- computeContentHash (SHA-256, path-independent)
+- db.js v3 schema (transmissions, observations, nodes, observers)
+- MQTT connection logic (multi-broker, reconnect, IATA filter)
+
+**Not Ported:** Companion bridge format, channel key decryption, WebSocket broadcast, in-memory packet store.
+
+---
+
+### Go Web Server (cmd/server/)
+**By:** Hicks (Backend Dev)  
+**Date:** 2026-03-27  
+**Status:** Implemented, 42 tests passing, `go vet` clean
+
+Standalone Go web server replacing Node.js server's READ side (REST API + WebSocket). Two-component rewrite: ingestor (MQTT writes), server (REST/WS reads).
+
+**Architecture Decisions:**
+1. **Direct SQLite queries** — No in-memory packet store; all reads via `packets_v` view (v3 schema)
+2. **Per-module go.mod** — Each `cmd/*` directory has own `go.mod`
+3. **gorilla/mux for routing** — Handles 35+ parameterized routes cleanly
+4. **SQLite polling for WebSocket** — Polls for new transmission IDs every 1s (decouples from MQTT)
+5. **Analytics stubs** — Topology, distance, hash-sizes, subpath return valid structural responses (empty data). RF/channels implemented via SQL.
+6. **Response shape compatibility** — All endpoints return JSON matching Node.js exactly (frontend works unchanged)
+
+**Files:**
+- `cmd/server/main.go` — Entry, HTTP, graceful shutdown
+- `cmd/server/db.go` — SQLite read queries
+- `cmd/server/routes.go` — 35+ REST API handlers
+- `cmd/server/websocket.go` — Hub + SQLite poller
+- `cmd/server/README.md` — Build/run docs
+
+**Future Work:** Full analytics via SQL, TTL response cache, shared `internal/db/` package, TLS, region-aware filtering.
+
+---
+
+### Go API Parity: Transmission-Centric Queries
+**By:** Hicks (Backend Dev)  
+**Date:** 2026-03-27  
+**Status:** Implemented, all 42+ tests pass
+
+Go server rewrote packet list queries from VIEW-based (slow, wrong shape) to **transmission-centric** with correlated subqueries. Schema version detection (`isV3` flag) handles both v2 and v3 schemas.
+
+**Performance Fix:** `/api/packets?groupByHash=true` — 8s → <100ms (query `transmissions` table 52K rows instead of `packets_v` 1.2M observations).
+
+**Field Parity:**
+- `totalNodes` now 7-day active window (was all-time)
+- Added `totalNodesAllTime` field
+- Role counts use 7-day filter (matches Node.js line 880-886)
+- `/api/nodes` counts use no time filter; `/api/stats` uses 7-day (separate methods avoid conflation)
+- `/api/packets/:id` now parses `path_json`, returns actual hop array
+- `/api/observers` — packetsLastHour, lat, lon, nodeRole computed from SQL
+- `/api/nodes/bulk-health` — Per-node stats computed (was returning zeros)
+- `/api/packets` — Multi-node filter support (`nodes` query param, comma-separated pubkeys)
+
+---
+
+### Go In-Memory Packet Store (cmd/server/store.go)
+**By:** Hicks (Backend Dev)  
+**Date:** 2026-03-26  
+**Status:** Implemented
+
+Port of `packet-store.js` with streaming load, 5 indexes, lean observation structs (only observation-specific fields). `QueryPackets` handles type, route, observer, hash, since, until, region, node. `IngestNewFromDB()` streams new transmissions from DB into memory.
+
+**Trade-offs:**
+- Memory: ~450 bytes/tx + ~100 bytes/obs (52K tx + 1.2M obs ≈ ~143MB)
+- Startup: One-time load adds few seconds (acceptable)
+- DB still used for: analytics, node/observer queries, role counts, region resolution
+
+---
+
+### Observation RAM Optimization
+**By:** Hicks (Backend Dev)  
+**Date:** 2026-03-27  
+**Status:** Implemented
+
+Observation objects in in-memory packet store now store only `transmission_id` reference instead of copying `hash`, `raw_hex`, `decoded_json`, `payload_type`, `route_type` from parent. API boundary methods (`getById`, `getSiblings`, `enrichObservations`) hydrate on demand. Load uses `.iterate()` instead of `.all()` to avoid materializing full JOIN.
+
+**Impact:** Eliminates ~1.17M redundant string copies, avoids 1.17M-row array during startup. 2.7GB RAM → acceptable levels with 185MB database.
+
+**Code Pattern:** Any code reading observation objects from `tx.observations` directly must use `pktStore.enrichObservations()` if it needs transmission fields. Internal iteration over observations for observer_id, snr, rssi, path_json works unchanged.
+
+---
+
+## Decision: E2E Playwright Performance Improvements
+
+**Author:** Kobayashi (Lead)  
+**Date:** 2026-03-26  
+**Status:** Proposed — awaiting user sign-off before implementation
+
+Playwright E2E tests (16 tests in `test-e2e-playwright.js`) are slow in CI. Analysis identified ~40-50% potential runtime reduction.
+
+### Recommendations (prioritized)
+
+#### HIGH impact (30%+ improvement)
+
+1. **Replace `waitUntil: 'networkidle'` with `'domcontentloaded'` + targeted waits** — used ~20 times; `networkidle` worst-case for SPAs with persistent WebSocket + Leaflet tile loading. Each navigation pays 500ms+ penalty.
+
+2. **Eliminate redundant navigations** — group tests by route; navigate once, run all assertions for that route.
+
+3. **Cache Playwright browser install in CI** — `npx playwright install chromium --with-deps` runs every frontend push. Self-hosted runner should retain browser between runs.
+
+#### MEDIUM impact (10-30%)
+
+4. **Replace hardcoded `waitForTimeout` with event-driven waits** — ~17s scattered. Replace with `waitForSelector`, `waitForFunction`, or `page.waitForResponse`.
+
+5. **Merge coverage collection into E2E run** — `collect-frontend-coverage.js` launches second browser. Extract `window.__coverage__` at E2E end instead.
+
+6. **Replace `sleep 5` server startup with health-check polling** — Start tests as soon as `/api/stats` responsive (~1-2s savings).
+
+#### LOW impact (<10%)
+
+7. **Block unnecessary resources for non-visual tests** — use `page.route()` to abort map tiles, fonts.
+
+8. **Reduce default timeout 15s → 10s** — sufficient for local CI.
+
+### Implementation notes
+
+- Items 1-2 are test-file-only (Bishop/Newt scope)
+- Items 3, 5-6 are CI pipeline (Hicks scope)
+- No architectural changes; all incremental
+- All assertions remain identical — only wait strategies change
+
+---
+
+### 2026-03-27T20:56:00Z — Protobuf API Contract (Merged)
+**By:** Kpa-clawbot (via Copilot)  
+**Decision:** 
+1. All frontend/backend interfaces get protobuf definitions as single source of truth
+2. Go generates structs with JSON tags from protos; Node stays unchanged — protos derived from Node's current JSON shapes
+3. Proto definitions MUST use inheritance and composition (no repeating field definitions)
+4. Data flow: SQLite → proto struct → JSON; JSON blobs from DB deserialize against proto structs for validation
+5. CI pipeline's proto fixture capture runs against prod (stable reference), not staging
+
+**Rationale:** Eliminates parity bugs between Node and Go. Compiler-enforced contract. Prod is known-good baseline.

.squad/identity/now.md

@@ -0,0 +1,9 @@
+---
+updated_at: 2026-03-26T04:11:47.138Z
+focus_area: Initial setup
+active_issues: []
+---
+
+# What We're Focused On
+
+Getting started. Updated by coordinator at session start.

.squad/identity/wisdom.md

@@ -0,0 +1,11 @@
+---
+last_updated: 2026-03-26T04:11:47.138Z
+---
+
+# Team Wisdom
+
+Reusable patterns and heuristics learned through work. NOT transcripts — each entry is a distilled, actionable insight.
+
+## Patterns
+
+<!-- Append entries below. Format: **Pattern:** description. **Context:** when it applies. -->

.squad/orchestration-log/scribe-2026-03-27-spawn-batch.md

@@ -0,0 +1,86 @@
+# Spawn Batch — Proto Validation & Typed API Contracts
+
+**Timestamp:** 2026-03-27T22:19:53Z  
+**Scribe:** Orchestration Log Entry  
+**Scope:** Go server proto validation, fixture capture, CI architecture
+
+---
+
+## Team Accomplishments (Spawn Manifest)
+
+### Hicks (Backend Dev)
+- **Fixed #163:** 15 API violations — type mismatches in route handlers
+- **Fixed #164:** 24 proto mismatches — shape inconsistencies between Node.js JSON and Go structs
+- **Delivered:** `types.go` — 80 typed Go structs replacing all `map[string]interface{}` in route handlers
+- **Impact:** Proto contract fully wired into Go server; compiler now enforces API response shapes
+
+### Bishop (Proto Validation)
+- **Validated:** All proto definitions (0 errors)
+- **Captured:** 33 Node.js API response fixtures from production
+- **Status:** Baseline fixture set ready for CI contract testing
+
+### Hudson (CI/DevOps)
+- **Implemented:** CI proto validation pipeline with all 33 fixtures
+- **Fixed:** Fixture capture source changed from staging → production
+- **Improved:** CI split into parallel tracks (backend tests, frontend tests, proto validation)
+- **Impact:** Proto contracts now validated against prod on every push
+
+### Coordinator
+- **Fixed:** Fixture capture source (staging → prod)
+- **Verified:** Data integrity of captured fixtures
+
+---
+
+## Key Milestone: Proto-Enforced API Contract
+
+**Status:** ✅ Complete
+
+Go server now has:
+1. Full type safety (80 structs replacing all `map[string]interface{}`)
+2. Proto definitions as single source of truth
+3. Compiler-enforced JSON field matching (no more mismatches)
+4. CI validation on every push (all 33 fixtures + 0 errors)
+
+**What Changed:**
+- All route handlers return typed structs (proto-derived)
+- Response shapes match Node.js JSON exactly
+- Any shape mismatch caught at compile time, not test time
+
+**Frontend Impact:** None — JSON shapes unchanged, frontend code continues unchanged.
+
+---
+
+## Decisions Merged
+
+**New inbox entries processed:**
+1. ✅ `copilot-directive-protobuf-contract.md` → decisions.md (1 decision)
+2. ✅ `copilot-directive-fixtures-from-prod.md` → decisions.md (1 directive)
+
+**Deduplication:** Both entries new (timestamps 2026-03-27T20:56:00Z, 2026-03-27T22:00:00Z). No duplicates detected.
+
+---
+
+## Decisions File Status
+
+**Location:** `.squad/decisions/decisions.md`  
+**Current Size:** ~380 lines  
+**Archival Threshold:** 20KB  
+**Status:** ✅ Well under threshold, no archival needed
+
+**Sections:**
+1. User Directives (6 decisions)
+2. Technical Fixes (7 issues)
+3. Infrastructure & Deployment (3 decisions)
+4. Go Rewrite — API & Storage (7 decisions, +2 proto entries)
+5. E2E Playwright Performance (1 proposed strategy)
+
+---
+
+## Summary
+
+**Inbox Merged:** 2 entries → decisions.md  
+**Orchestration Log:** 1 new entry (this file)  
+**Files Modified:** `.squad/decisions/decisions.md`  
+**Git Status:** Ready for commit
+
+**Next Action:** Git commit with explicit file list (no `-A` flag).

.squad/orchestration-log/scribe-2026-03-27.md

@@ -0,0 +1,178 @@
+# Scribe Orchestration Log
+
+## 2026-03-27 — Session Summary & Finalization
+
+**Agent:** Scribe (Logging)  
+**Date:** 2026-03-27  
+**Task:** Merge decision inbox, write session orchestration log entry, commit .squad/ changes
+
+### Inbox Merge Status
+
+**Decision Inbox Review:** `.squad/decisions/inbox/` directory scanned — **EMPTY** (no new decisions filed during this session).
+
+**Decisions.md Status:** Current file contains 9 decision categories:
+1. User Directives (6 decisions)
+2. Technical Fixes (4 issues: #126, #133 parts 1-2, #123, #130, #131, #129, #132)
+3. Infrastructure & Deployment (3 decisions: DB merge, Docker volumes, staging setup)
+4. Go Rewrite — API & Storage (4 decisions: MQTT ingestor, web server, API parity, observation RAM optimization)
+5. E2E Playwright Performance (proposed, not yet implemented)
+
+**No merges required** — all work captured in existing decision log categories.
+
+---
+
+## Session Orchestration Summary
+
+**Session Scope:** #151-160 issues + Go rewrite staging + database merge + E2E expansion
+
+### Agent Deliverables (28 issues closed)
+
+#### Hicks (Backend Dev)
+- **Issues Fixed:** #123 (channel hash), #126 (hop prefixes), #133 (phantom nodes × 3), #143 (perf dashboard), #154-#155 (Go server parity)
+- **Go Ingestor:** ~800 lines, 25 tests ✅ — MQTT ingestion, packet decode, DB writes
+- **Go Server:** ~2000 lines, 42 tests ✅ — REST API (35+ endpoints), WebSocket, SQLite polling
+- **API Parity:** All endpoints matching Node.js shape, transmission-centric queries, field fixes
+- **Performance:** 8s → <100ms on `/api/packets?groupByHash=true`
+- **Testing:** Backend coverage 85%+, all tests passing
+
+#### Newt (Frontend)
+- **Issues Fixed:** #130 (live map stale dimming), #131 (WS auto-update), #129 (observer comparison), #133 (live page pruning)
+- **Frontend Patterns:** WS cache reset (null + invalidateApiCache + re-fetch), detail pane CSS collapse, time-based eviction
+- **Observer Comparison:** New `#/compare` route, pure function `comparePacketSets()` exposed on window
+- **E2E:** Playwright tests verified all routes, live page behavior, observer analytics
+- **Cache Busters:** Bumped in same commit as code changes
+
+#### Bishop (Tester)
+- **PR Reviews:** Approved Hicks #6 + Newt #5 + Hudson DB merge plan with gap coverage
+- **Gap Coverage:** 14 phantom node tests, 5 WS handler tests added to backend suite
+- **E2E Expansion:** 16 → 42 Playwright tests covering 11 routes + new audio lab, channels, observers, traces, perf pages
+- **Coverage Validation:** Frontend 42%+, backend 85%+ (both on target)
+- **Outcome:** 526 backend tests + 42 E2E tests, all passing ✅
+
+#### Kobayashi (Lead)
+- **Root Cause Analysis:** Issue #133 phantom node creation traced to `autoLearnHopNodes()` with `hash_size=1`
+- **DB Merge Plan:** 6-phase strategy (pre-flight, backup, merge, deploy, validate, cleanup) with dedup logic
+- **Coordination:** Assigned fix owners, reviewed 6 PRs, approved DB merge execution
+- **Outcome:** 185MB staging DB → 51,723 transmissions + 1,237,186 observations merged successfully
+
+#### Hudson (DevOps)
+- **Database Merge:** Executed production merge (0 data loss, ~2 min downtime, 8,491ms load time)
+- **Docker Compose:** Unified volume paths, reconciled manage.sh ↔ docker-compose.yml (no version key, v2 compatible)
+- **Staging Setup:** Created `~/meshcore-staging-data/` with old problematic DB for debugging, separate MQTT/HTTP ports
+- **CI Pipeline:** Auto-check `docker compose` install, staging auto-deploy with health checks, manual production promotion
+- **Infrastructure:** Azure CLI user restoration, Docker group membership, backup retention (7 days)
+- **Outcome:** Production stable (860MiB RSS post-merge), staging ready for Go server deployment (port 82)
+
+#### Coordinator (Manual Triage)
+- **Issue Closure:** 9 issues closed manually (#134-#142, duplicates + resolved UI polish)
+- **New Issue:** #146 filed (unique node count bug — 6502 nodes caused by phantom cleanup audit gap)
+- **Outcome:** Backlog cleaned, new issue scoped for Hicks backend audit
+
+#### Ripley (Support)
+- **Onboarding:** Joined as Support Engineer mid-session
+- **Knowledge Transfer:** Explained staleness thresholds (24h companions/sensors, 72h infrastructure), 7-day active window, health calculations
+- **Documentation Reference:** Pointed to `roles.js` as authoritative source for health thresholds
+- **Outcome:** Support engineer ready for operational questions and user escalations
+
+---
+
+## Orchestration Log Entries Written
+
+All agent logs already present at session end:
+- `bishop-2026-03-27.md` (116 lines) — PR reviews, gap coverage, E2E expansion
+- `hicks-2026-03-27.md` (102 lines) — 6 fixes, Go ingestor/server, API parity, perf dashboard
+- `newt-2026-03-27.md` (56 lines) — 4 frontend fixes, WS patterns, observer comparison
+- `kobayashi-2026-03-27.md` (27 lines) — Root cause analysis, DB merge plan, coordination
+- `hudson-2026-03-27.md` (117 lines) — DB merge execution, Docker Compose migration, staging setup, CI pipeline
+- `ripley-2026-03-27.md` (30 lines) — Support onboarding, health threshold documentation
+
+**Entry Total:** 448 lines of orchestration logs covering 28 issues, 2 Go services, database merge, staging deployment, CI pipeline updates, 42 E2E tests, 19 backend fixes
+
+---
+
+## Decisions.md Review
+
+Current decisions.md (342 lines) contains authoritative log of all technical + infrastructure + deployment decisions made during #151-160 session. No archival needed (well under 20KB threshold). Organized by:
+1. User Directives (process decisions)
+2. Technical Fixes (bug fixes with rationale)
+3. Infrastructure & Deployment (ops decisions)
+4. Go Rewrite — API & Storage (architecture decisions)
+5. E2E Playwright Performance (performance optimization strategy)
+
+---
+
+## Git Status
+
+Scribe operations:
+- ✅ No inbox → decisions.md merges (inbox empty)
+- ✅ Orchestration logs written (6 agent logs, 448 lines)
+- ✅ Session summary complete
+- ✅ No modifications to non-.squad/ files
+- ✅ Ready for commit
+
+### .squad/ Directory Structure
+```
+.squad/
+├── agents/
+│   ├── bishop/
+│   ├── hicks/
+│   ├── kobayashi/
+│   ├── newt/
+│   ├── ripley/
+│   ├── hudson/
+│   └── coordinator/
+├── decisions/
+│   ├── decisions.md (342 lines, final)
+│   └── inbox/ (empty)
+├── orchestration-log/
+│   ├── bishop-2026-03-27.md
+│   ├── hicks-2026-03-27.md
+│   ├── newt-2026-03-27.md
+│   ├── kobayashi-2026-03-27.md
+│   ├── hudson-2026-03-27.md
+│   ├── ripley-2026-03-27.md
+│   └── scribe-2026-03-27.md ← NEW
+├── log/ (session artifacts)
+└── agents/scribe/charter.md
+```
+
+---
+
+## Session Impact Summary
+
+| Metric | Before | After | Status |
+|--------|--------|-------|--------|
+| **Issues Closed** | Open backlog | 28 closed | ✅ |
+| **Node Count** | 7,308 (phantom) | ~400 (7-day active) | ✅ Fixed |
+| **Heap Usage** | 2.7GB (OOM risk) | 860MB RSS | ✅ Fixed |
+| **Prod DB Size** | 21MB | 206MB (merged) | ✅ Complete |
+| **Transmissions** | 46K | 51,723 | ✅ Complete |
+| **Observations** | ~50K | 1,237,186 | ✅ Complete |
+| **Go MQTT Ingestor** | Non-existent | 25 tests ✅ | ✅ Delivered |
+| **Go Web Server** | Non-existent | 42 tests ✅ | ✅ Delivered |
+| **E2E Test Coverage** | 16 tests | 42 tests | ✅ Expanded |
+| **Backend Test Coverage** | 80%+ | 85%+ | ✅ Improved |
+| **Frontend Test Coverage** | 38%+ | 42%+ | ✅ Improved |
+| **Staging Environment** | Non-existent | Docker Compose + Go-ready | ✅ Delivered |
+| **API Parity** | Node.js only | Go server 100% match | ✅ Complete |
+| **Production Uptime** | Pre-merge | Post-merge stable | ✅ Restored |
+
+---
+
+## Outcome
+
+✅ **Session Complete**
+
+- All 28 issues closed
+- Go MQTT ingestor + web server deployed to staging (ready for Go runtime performance validation)
+- Database merge successful (0 data loss, minimal downtime)
+- Staging environment operational (Docker Compose, old DB for debugging)
+- E2E test coverage expanded (16 → 42 tests)
+- Backend test coverage target met (85%+)
+- Production restored to healthy state (860MB RSS, no phantom nodes)
+- CI pipeline auto-heals (Docker Compose v2 check)
+- All agent logs written to orchestration-log/
+- Decisions.md current and comprehensive
+- Ready for final git commit
+
+**Status:** 🟢 READY FOR COMMIT

.squad/routing.md

@@ -0,0 +1,60 @@
+# Work Routing
+
+How to decide who handles what.
+
+## Routing Table
+
+| Work Type | Route To | Examples |
+|-----------|----------|----------|
+| Architecture, scope, decisions | Kobayashi | Feature planning, trade-offs, scope decisions |
+| Code review, PR review | Kobayashi | Review PRs, check quality, approve/reject |
+| server.js, API routes, Express | Hicks | Add endpoints, fix API bugs, MQTT config |
+| decoder.js, packet parsing | Hicks | Protocol changes, parser bugs, new packet types |
+| packet-store.js, db.js, SQLite | Hicks | Storage bugs, query optimization, schema changes |
+| server-helpers.js, MQTT, WebSocket | Hicks | Helper functions, real-time data flow |
+| Performance optimization | Hicks | Caching, O(n) improvements, response times |
+| Docker, deployment, manage.sh | Hicks | Container config, deploy scripts |
+| MeshCore protocol/firmware | Hicks | Read firmware source, verify protocol behavior |
+| public/*.js (all frontend modules) | Newt | UI features, interactions, SPA routing |
+| Leaflet maps, live visualization | Newt | Map markers, VCR playback, animations |
+| CSS, theming, customize.js | Newt | Styles, CSS variables, theme customizer |
+| packet-filter.js (filter engine) | Newt | Filter syntax, parser, Wireshark-style queries |
+| index.html, cache busters | Newt | Script tags, version bumps |
+| Unit tests, test-*.js | Bishop | Write/fix tests, coverage improvements |
+| Playwright E2E tests | Bishop | Browser tests, UI verification |
+| Coverage, CI pipeline | Bishop | Coverage targets, CI config |
+| CI/CD pipeline, .github/workflows | Hudson | Pipeline config, step optimization, CI debugging |
+| Docker, Dockerfile, docker/ | Hudson | Container config, build optimization |
+| manage.sh, deployment scripts | Hudson | Deploy scripts, server management |
+| scripts/, coverage tooling | Hudson | Build scripts, coverage collector optimization |
+| Azure, VM, infrastructure | Hudson | az CLI, SSH, server provisioning, monitoring |
+| Production debugging, DB ops | Hudson | SQLite recovery, WAL issues, process diagnostics |
+| User questions, "why does X..." | Ripley | Community support, UI behavior explanations |
+| Bug report triage from users | Ripley | Analyze reports, reproduce, route to dev |
+| GitHub issue comments (support) | Ripley | Explain behavior, suggest workarounds |
+| README, docs/ | Kobayashi | Documentation updates |
+| Session logging | Scribe | Automatic — never needs routing |
+
+## Issue Routing
+
+| Label | Action | Who |
+|-------|--------|-----|
+| `squad` | Triage: analyze issue, assign `squad:{member}` label | Lead |
+| `squad:{name}` | Pick up issue and complete the work | Named member |
+
+### How Issue Assignment Works
+
+1. When a GitHub issue gets the `squad` label, the **Lead** triages it — analyzing content, assigning the right `squad:{member}` label, and commenting with triage notes.
+2. When a `squad:{member}` label is applied, that member picks up the issue in their next session.
+3. Members can reassign by removing their label and adding another member's label.
+4. The `squad` label is the "inbox" — untriaged issues waiting for Lead review.
+
+## Rules
+
+1. **Eager by default** — spawn all agents who could usefully start work, including anticipatory downstream work.
+2. **Scribe always runs** after substantial work, always as `mode: "background"`. Never blocks.
+3. **Quick facts → coordinator answers directly.** Don't spawn an agent for "what port does the server run on?"
+4. **When two agents could handle it**, pick the one whose domain is the primary concern.
+5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
+6. **Anticipate downstream work.** If a feature is being built, spawn the tester to write test cases from requirements simultaneously.
+7. **Issue-labeled work** — when a `squad:{member}` label is applied to an issue, route to that member. The Lead handles all `squad` (base label) triage.

.squad/team.md

@@ -0,0 +1,25 @@
+# Squad — CoreScope
+
+## Project Context
+
+**Project:** CoreScope — Real-time LoRa mesh packet analyzer
+**Stack:** Node.js 18+, Express 5, SQLite (better-sqlite3), vanilla JS frontend, Leaflet maps, WebSocket (ws), MQTT (mqtt)
+**User:** User
+**Description:** Self-hosted alternative to analyzer.letsmesh.net. Ingests MeshCore mesh network packets via MQTT, decodes with custom parser (decoder.js), stores in SQLite with in-memory indexing (packet-store.js), and serves a rich SPA with live visualization, packet analysis, node analytics, channel chat, observer health, and theme customizer. ~18K lines, 14 test files, 85%+ backend coverage. Production at v2.6.0.
+
+**Key files:** server.js (Express API + MQTT + WebSocket), decoder.js (packet parser), packet-store.js (in-memory store), db.js (SQLite), server-helpers.js (shared helpers), public/ (22 frontend modules)
+
+**Rules:** Read AGENTS.md before any work. No commit without tests. Cache busters always bumped. Plan before implementing. One commit per logical change. Explicit git add only.
+
+## Members
+
+| Name | Role | Model | Emoji |
+|------|------|-------|-------|
+| Kobayashi | Lead | auto | 🏗️ |
+| Hicks | Backend Dev | auto | 🔧 |
+| Newt | Frontend Dev | auto | ⚛️ |
+| Bishop | Tester | auto | 🧪 |
+| Hudson | DevOps Engineer | auto | ⚙️ |
+| Ripley | Support Engineer | auto | 🛟 |
+| Scribe | Session Logger | claude-haiku-4.5 | 📋 |
+| Ralph | Work Monitor | — | 🔄 |

.squad/templates/casting-history.json

@@ -0,0 +1,4 @@
+{
+  "universe_usage_history": [],
+  "assignment_cast_snapshots": {}
+}

.squad/templates/casting-policy.json

@@ -0,0 +1,37 @@
+{
+  "casting_policy_version": "1.1",
+  "allowlist_universes": [
+    "The Usual Suspects",
+    "Reservoir Dogs",
+    "Alien",
+    "Ocean's Eleven",
+    "Arrested Development",
+    "Star Wars",
+    "The Matrix",
+    "Firefly",
+    "The Goonies",
+    "The Simpsons",
+    "Breaking Bad",
+    "Lost",
+    "Marvel Cinematic Universe",
+    "DC Universe",
+    "Futurama"
+  ],
+  "universe_capacity": {
+    "The Usual Suspects": 6,
+    "Reservoir Dogs": 8,
+    "Alien": 8,
+    "Ocean's Eleven": 14,
+    "Arrested Development": 15,
+    "Star Wars": 12,
+    "The Matrix": 10,
+    "Firefly": 10,
+    "The Goonies": 8,
+    "The Simpsons": 20,
+    "Breaking Bad": 12,
+    "Lost": 18,
+    "Marvel Cinematic Universe": 25,
+    "DC Universe": 18,
+    "Futurama": 12
+  }
+}

.squad/templates/casting-reference.md

@@ -0,0 +1,104 @@
+# Casting Reference
+
+On-demand reference for Squad's casting system. Loaded during Init Mode or when adding team members.
+
+## Universe Table
+
+| Universe | Capacity | Shape Tags | Resonance Signals |
+|---|---|---|---|
+| The Usual Suspects | 6 | small, noir, ensemble | crime, heist, mystery, deception |
+| Reservoir Dogs | 8 | small, noir, ensemble | crime, heist, tension, loyalty |
+| Alien | 8 | small, sci-fi, survival | space, isolation, threat, engineering |
+| Ocean's Eleven | 14 | medium, heist, ensemble | planning, coordination, roles, charm |
+| Arrested Development | 15 | medium, comedy, ensemble | dysfunction, business, family, satire |
+| Star Wars | 12 | medium, sci-fi, epic | conflict, mentorship, legacy, rebellion |
+| The Matrix | 10 | medium, sci-fi, cyberpunk | systems, reality, hacking, philosophy |
+| Firefly | 10 | medium, sci-fi, western | frontier, crew, independence, smuggling |
+| The Goonies | 8 | small, adventure, ensemble | exploration, treasure, kids, teamwork |
+| The Simpsons | 20 | large, comedy, ensemble | satire, community, family, absurdity |
+| Breaking Bad | 12 | medium, drama, tension | chemistry, transformation, consequence, power |
+| Lost | 18 | large, mystery, ensemble | survival, mystery, groups, leadership |
+| Marvel Cinematic Universe | 25 | large, action, ensemble | heroism, teamwork, powers, scale |
+| DC Universe | 18 | large, action, ensemble | justice, duality, powers, mythology |
+| Futurama | 12 | medium, sci-fi, comedy | future, robots, space, absurdity |
+
+**Total: 15 universes** — capacity range 6–25.
+
+## Selection Algorithm
+
+Universe selection is deterministic. Score each universe and pick the highest:
+
+```
+score = size_fit + shape_fit + resonance_fit + LRU
+```
+
+| Factor | Description |
+|---|---|
+| `size_fit` | How well the universe capacity matches the team size. Prefer universes where capacity ≥ agent_count with minimal waste. |
+| `shape_fit` | Match universe shape tags against the assignment shape derived from the project description. |
+| `resonance_fit` | Match universe resonance signals against session and repo context signals. |
+| `LRU` | Least-recently-used bonus — prefer universes not used in recent assignments (from `history.json`). |
+
+Same inputs → same choice (unless LRU changes between assignments).
+
+## Casting State File Schemas
+
+### policy.json
+
+Source template: `.squad/templates/casting-policy.json`
+Runtime location: `.squad/casting/policy.json`
+
+```json
+{
+  "casting_policy_version": "1.1",
+  "allowlist_universes": ["Universe Name", "..."],
+  "universe_capacity": {
+    "Universe Name": 10
+  }
+}
+```
+
+### registry.json
+
+Source template: `.squad/templates/casting-registry.json`
+Runtime location: `.squad/casting/registry.json`
+
+```json
+{
+  "agents": {
+    "agent-role-id": {
+      "persistent_name": "CharacterName",
+      "universe": "Universe Name",
+      "created_at": "ISO-8601",
+      "legacy_named": false,
+      "status": "active"
+    }
+  }
+}
+```
+
+### history.json
+
+Source template: `.squad/templates/casting-history.json`
+Runtime location: `.squad/casting/history.json`
+
+```json
+{
+  "universe_usage_history": [
+    {
+      "universe": "Universe Name",
+      "assignment_id": "unique-id",
+      "used_at": "ISO-8601"
+    }
+  ],
+  "assignment_cast_snapshots": {
+    "assignment-id": {
+      "universe": "Universe Name",
+      "agents": {
+        "role-id": "CharacterName"
+      },
+      "created_at": "ISO-8601"
+    }
+  }
+}
+```

.squad/templates/casting-registry.json

@@ -0,0 +1,3 @@
+{
+  "agents": {}
+}

.squad/templates/casting/Futurama.json

@@ -0,0 +1,10 @@
+[
+    "Fry",
+    "Leela",
+    "Bender",
+    "Farnsworth",
+    "Zoidberg",
+    "Amy",
+    "Zapp",
+    "Kif"
+]

.squad/templates/ceremonies.md

@@ -0,0 +1,41 @@
+# Ceremonies
+
+> Team meetings that happen before or after work. Each squad configures their own.
+
+## Design Review
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | before |
+| **Condition** | multi-agent task involving 2+ agents modifying shared systems |
+| **Facilitator** | lead |
+| **Participants** | all-relevant |
+| **Time budget** | focused |
+| **Enabled** | ✅ yes |
+
+**Agenda:**
+1. Review the task and requirements
+2. Agree on interfaces and contracts between components
+3. Identify risks and edge cases
+4. Assign action items
+
+---
+
+## Retrospective
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto |
+| **When** | after |
+| **Condition** | build failure, test failure, or reviewer rejection |
+| **Facilitator** | lead |
+| **Participants** | all-involved |
+| **Time budget** | focused |
+| **Enabled** | ✅ yes |
+
+**Agenda:**
+1. What happened? (facts only)
+2. Root cause analysis
+3. What should change?
+4. Action items for next iteration

.squad/templates/charter.md

@@ -0,0 +1,53 @@
+# {Name} — {Role}
+
+> {One-line personality statement — what makes this person tick}
+
+## Identity
+
+- **Name:** {Name}
+- **Role:** {Role title}
+- **Expertise:** {2-3 specific skills relevant to the project}
+- **Style:** {How they communicate — direct? thorough? opinionated?}
+
+## What I Own
+
+- {Area of responsibility 1}
+- {Area of responsibility 2}
+- {Area of responsibility 3}
+
+## How I Work
+
+- {Key approach or principle 1}
+- {Key approach or principle 2}
+- {Pattern or convention I follow}
+
+## Boundaries
+
+**I handle:** {types of work this agent does}
+
+**I don't handle:** {types of work that belong to other team members}
+
+**When I'm unsure:** I say so and suggest who might know.
+
+**If I review others' work:** On rejection, I may require a different agent to revise (not the original author) or request a new specialist be spawned. The Coordinator enforces this.
+
+## Model
+
+- **Preferred:** auto
+- **Rationale:** Coordinator selects the best model based on task type — cost first unless writing code
+- **Fallback:** Standard chain — the coordinator handles fallback automatically
+
+## Collaboration
+
+Before starting work, run `git rev-parse --show-toplevel` to find the repo root, or use the `TEAM ROOT` provided in the spawn prompt. All `.squad/` paths must be resolved relative to this root — do not assume CWD is the repo root (you may be in a worktree or subdirectory).
+
+Before starting work, read `.squad/decisions.md` for team decisions that affect me.
+After making a decision others should know, write it to `.squad/decisions/inbox/{my-name}-{brief-slug}.md` — the Scribe will merge it.
+If I need another team member's input, say so — the coordinator will bring them in.
+
+## Voice
+
+{1-2 sentences describing personality. Not generic — specific. This agent has OPINIONS.
+They have preferences. They push back. They have a style that's distinctly theirs.
+Example: "Opinionated about test coverage. Will push back if tests are skipped.
+Prefers integration tests over mocks. Thinks 80% coverage is the floor, not the ceiling."}

.squad/templates/constraint-tracking.md

@@ -0,0 +1,38 @@
+# Constraint Budget Tracking
+
+When the user or system imposes constraints (question limits, revision limits, time budgets), maintain a visible counter in your responses and in the artifact.
+
+## Format
+
+```
+📊 Clarifying questions used: 2 / 3
+```
+
+## Rules
+
+- Update the counter each time the constraint is consumed
+- When a constraint is exhausted, state it: `📊 Question budget exhausted (3/3). Proceeding with current information.`
+- If no constraints are active, do not display counters
+- Include the final constraint status in multi-agent artifacts
+
+## Example Session
+
+```
+Coordinator: Spawning agents to analyze requirements...
+📊 Clarifying questions used: 0 / 3
+
+Agent asks clarification: "Should we support OAuth?"
+Coordinator: Checking with user...
+📊 Clarifying questions used: 1 / 3
+
+Agent asks clarification: "What's the rate limit?"
+Coordinator: Checking with user...
+📊 Clarifying questions used: 2 / 3
+
+Agent asks clarification: "Do we need RBAC?"
+Coordinator: Checking with user...
+📊 Clarifying questions used: 3 / 3
+
+Agent asks clarification: "Should we cache responses?"
+Coordinator: 📊 Question budget exhausted (3/3). Proceeding without clarification.
+```

.squad/templates/cooperative-rate-limiting.md

@@ -0,0 +1,229 @@
+# Cooperative Rate Limiting for Multi-Agent Deployments
+
+> Coordinate API quota across multiple Ralph instances to prevent cascading failures.
+
+## Problem
+
+The [circuit breaker template](ralph-circuit-breaker.md) handles single-instance rate limiting well. But when multiple Ralphs run across machines (or pods on K8s), each instance independently hits API limits:
+
+- **No coordination** — 5 Ralphs each think they have full API quota
+- **Thundering herd** — All Ralphs retry simultaneously after rate limit resets
+- **Priority inversion** — Low-priority work exhausts quota before critical work runs
+- **Reactive only** — Circuit opens AFTER 429, wasting the failed request
+
+## Solution: 6-Pattern Architecture
+
+These patterns layer on top of the existing circuit breaker. Each is independent — adopt one or all.
+
+### Pattern 1: Traffic Light (RAAS — Rate-Aware Agent Scheduling)
+
+Map GitHub API `X-RateLimit-Remaining` to traffic light states:
+
+| State | Remaining % | Behavior |
+|-------|------------|----------|
+| 🟢 GREEN | >20% | Normal operation |
+| 🟡 AMBER | 5–20% | Only P0 agents proceed |
+| 🔴 RED | <5% | Block all except emergency P0 |
+
+```typescript
+type TrafficLight = 'green' | 'amber' | 'red';
+
+function getTrafficLight(remaining: number, limit: number): TrafficLight {
+  const pct = remaining / limit;
+  if (pct > 0.20) return 'green';
+  if (pct > 0.05) return 'amber';
+  return 'red';
+}
+
+function shouldProceed(light: TrafficLight, agentPriority: number): boolean {
+  if (light === 'green') return true;
+  if (light === 'amber') return agentPriority === 0; // P0 only
+  return false; // RED — block all
+}
+```
+
+### Pattern 2: Cooperative Token Pool (CMARP)
+
+A shared JSON file (`~/.squad/rate-pool.json`) distributes API quota:
+
+```json
+{
+  "totalLimit": 5000,
+  "resetAt": "2026-03-22T20:00:00Z",
+  "allocations": {
+    "picard": { "priority": 0, "allocated": 2000, "used": 450, "leaseExpiry": "2026-03-22T19:55:00Z" },
+    "data": { "priority": 1, "allocated": 1750, "used": 200, "leaseExpiry": "2026-03-22T19:55:00Z" },
+    "ralph": { "priority": 2, "allocated": 1250, "used": 100, "leaseExpiry": "2026-03-22T19:55:00Z" }
+  }
+}
+```
+
+**Rules:**
+- P0 agents (Lead) get 40% of quota
+- P1 agents (specialists) get 35%
+- P2 agents (Ralph, Scribe) get 25%
+- Stale leases (>5 minutes without heartbeat) are auto-recovered
+- Each agent checks their remaining allocation before making API calls
+
+```typescript
+interface RatePoolAllocation {
+  priority: number;
+  allocated: number;
+  used: number;
+  leaseExpiry: string;
+}
+
+interface RatePool {
+  totalLimit: number;
+  resetAt: string;
+  allocations: Record<string, RatePoolAllocation>;
+}
+
+function canUseQuota(pool: RatePool, agentName: string): boolean {
+  const alloc = pool.allocations[agentName];
+  if (!alloc) return true; // Unknown agent — allow (graceful)
+  
+  // Reclaim stale leases from crashed agents
+  const now = new Date();
+  for (const [name, a] of Object.entries(pool.allocations)) {
+    if (new Date(a.leaseExpiry) < now && name !== agentName) {
+      a.allocated = 0; // Reclaim
+    }
+  }
+  
+  return alloc.used < alloc.allocated;
+}
+```
+
+### Pattern 3: Predictive Circuit Breaker (PCB)
+
+Opens the circuit BEFORE getting a 429 by predicting when quota will run out:
+
+```typescript
+interface RateSample {
+  timestamp: number;  // Date.now()
+  remaining: number;  // from X-RateLimit-Remaining header
+}
+
+class PredictiveCircuitBreaker {
+  private samples: RateSample[] = [];
+  private readonly maxSamples = 10;
+  private readonly warningThresholdSeconds = 120;
+
+  addSample(remaining: number): void {
+    this.samples.push({ timestamp: Date.now(), remaining });
+    if (this.samples.length > this.maxSamples) {
+      this.samples.shift();
+    }
+  }
+
+  /** Predict seconds until quota exhaustion using linear regression */
+  predictExhaustion(): number | null {
+    if (this.samples.length < 3) return null;
+
+    const n = this.samples.length;
+    const first = this.samples[0];
+    const last = this.samples[n - 1];
+    
+    const elapsedMs = last.timestamp - first.timestamp;
+    if (elapsedMs === 0) return null;
+    
+    const consumedPerMs = (first.remaining - last.remaining) / elapsedMs;
+    if (consumedPerMs <= 0) return null; // Not consuming — safe
+    
+    const msUntilExhausted = last.remaining / consumedPerMs;
+    return msUntilExhausted / 1000;
+  }
+
+  shouldOpen(): boolean {
+    const eta = this.predictExhaustion();
+    if (eta === null) return false;
+    return eta < this.warningThresholdSeconds;
+  }
+}
+```
+
+### Pattern 4: Priority Retry Windows (PWJG)
+
+Non-overlapping jitter windows prevent thundering herd:
+
+| Priority | Retry Window | Description |
+|----------|-------------|-------------|
+| P0 (Lead) | 500ms–5s | Recovers first |
+| P1 (Specialists) | 2s–30s | Moderate delay |
+| P2 (Ralph/Scribe) | 5s–60s | Most patient |
+
+```typescript
+function getRetryDelay(priority: number, attempt: number): number {
+  const windows: Record<number, [number, number]> = {
+    0: [500, 5000],     // P0: 500ms–5s
+    1: [2000, 30000],   // P1: 2s–30s
+    2: [5000, 60000],   // P2: 5s–60s
+  };
+  
+  const [min, max] = windows[priority] ?? windows[2];
+  const base = Math.min(min * Math.pow(2, attempt), max);
+  const jitter = Math.random() * base * 0.5;
+  return base + jitter;
+}
+```
+
+### Pattern 5: Resource Epoch Tracker (RET)
+
+Heartbeat-based lease system for multi-machine deployments:
+
+```typescript
+interface ResourceLease {
+  agent: string;
+  machine: string;
+  leaseStart: string;
+  leaseExpiry: string;  // Typically 5 minutes from now
+  allocated: number;
+}
+
+// Each agent renews its lease every 2 minutes
+// If lease expires (agent crashed), allocation is reclaimed
+```
+
+### Pattern 6: Cascade Dependency Detector (CDD)
+
+Track downstream failures and apply backpressure:
+
+```
+Agent A (rate limited) → Agent B (waiting for A) → Agent C (waiting for B)
+                         ↑ Backpressure signal: "don't start new work"
+```
+
+When a dependency is rate-limited, upstream agents should pause new work rather than queuing requests that will fail.
+
+## Kubernetes Integration
+
+On K8s, cooperative rate limiting can use KEDA to scale pods based on API quota:
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+spec:
+  scaleTargetRef:
+    name: ralph-deployment
+  triggers:
+  - type: external
+    metadata:
+      scalerAddress: keda-copilot-scaler:6000
+      # Scaler returns 0 when rate limited → pods scale to zero
+```
+
+See [keda-copilot-scaler](https://github.com/tamirdresher/keda-copilot-scaler) for a complete implementation.
+
+## Quick Start
+
+1. **Minimum viable:** Adopt Pattern 1 (Traffic Light) — read `X-RateLimit-Remaining` from API responses
+2. **Multi-machine:** Add Pattern 2 (Cooperative Pool) — shared `rate-pool.json`
+3. **Production:** Add Pattern 3 (Predictive CB) — prevent 429s entirely
+4. **Kubernetes:** Add KEDA scaler for automatic pod scaling
+
+## References
+
+- [Circuit Breaker Template](ralph-circuit-breaker.md) — Foundation patterns
+- [Squad on AKS](https://github.com/tamirdresher/squad-on-aks) — Production K8s deployment
+- [KEDA Copilot Scaler](https://github.com/tamirdresher/keda-copilot-scaler) — Custom KEDA external scaler

.squad/templates/copilot-instructions.md

@@ -0,0 +1,46 @@
+# Copilot Coding Agent — Squad Instructions
+
+You are working on a project that uses **Squad**, an AI team framework. When picking up issues autonomously, follow these guidelines.
+
+## Team Context
+
+Before starting work on any issue:
+
+1. Read `.squad/team.md` for the team roster, member roles, and your capability profile.
+2. Read `.squad/routing.md` for work routing rules.
+3. If the issue has a `squad:{member}` label, read that member's charter at `.squad/agents/{member}/charter.md` to understand their domain expertise and coding style — work in their voice.
+
+## Capability Self-Check
+
+Before starting work, check your capability profile in `.squad/team.md` under the **Coding Agent → Capabilities** section.
+
+- **🟢 Good fit** — proceed autonomously.
+- **🟡 Needs review** — proceed, but note in the PR description that a squad member should review.
+- **🔴 Not suitable** — do NOT start work. Instead, comment on the issue:
+  ```
+  🤖 This issue doesn't match my capability profile (reason: {why}). Suggesting reassignment to a squad member.
+  ```
+
+## Branch Naming
+
+Use the squad branch convention:
+```
+squad/{issue-number}-{kebab-case-slug}
+```
+Example: `squad/42-fix-login-validation`
+
+## PR Guidelines
+
+When opening a PR:
+- Reference the issue: `Closes #{issue-number}`
+- If the issue had a `squad:{member}` label, mention the member: `Working as {member} ({role})`
+- If this is a 🟡 needs-review task, add to the PR description: `⚠️ This task was flagged as "needs review" — please have a squad member review before merging.`
+- Follow any project conventions in `.squad/decisions.md`
+
+## Decisions
+
+If you make a decision that affects other team members, write it to:
+```
+.squad/decisions/inbox/copilot-{brief-slug}.md
+```
+The Scribe will merge it into the shared decisions file.

.squad/templates/history.md

@@ -0,0 +1,10 @@
+# Project Context
+
+- **Owner:** {user name}
+- **Project:** {project description}
+- **Stack:** {languages, frameworks, tools}
+- **Created:** {timestamp}
+
+## Learnings
+
+<!-- Append new learnings below. Each entry is something lasting about the project. -->

.squad/templates/identity/now.md

@@ -0,0 +1,9 @@
+---
+updated_at: {timestamp}
+focus_area: {brief description}
+active_issues: []
+---
+
+# What We're Focused On
+
+{Narrative description of current focus — 1-3 sentences. Updated by coordinator at session start.}

.squad/templates/identity/wisdom.md

@@ -0,0 +1,15 @@
+---
+last_updated: {timestamp}
+---
+
+# Team Wisdom
+
+Reusable patterns and heuristics learned through work. NOT transcripts — each entry is a distilled, actionable insight.
+
+## Patterns
+
+<!-- Append entries below. Format: **Pattern:** description. **Context:** when it applies. -->
+
+## Anti-Patterns
+
+<!-- Things we tried that didn't work. **Avoid:** description. **Why:** reason. -->

.squad/templates/issue-lifecycle.md

@@ -0,0 +1,412 @@
+# Issue Lifecycle — Repo Connection & PR Flow
+
+Reference for connecting Squad to a repository and managing the issue→branch→PR→merge lifecycle.
+
+## Repo Connection Format
+
+When connecting Squad to an issue tracker, store the connection in `.squad/team.md`:
+
+```markdown
+## Issue Source
+
+**Repository:** {owner}/{repo}  
+**Connected:** {date}  
+**Platform:** {GitHub | Azure DevOps | Planner}  
+**Filters:**
+- Labels: `{label-filter}`
+- Project: `{project-name}` (ADO/Planner only)
+- Plan: `{plan-id}` (Planner only)
+```
+
+**Detection triggers:**
+- User says "connect to {repo}"
+- User says "monitor {repo} for issues"
+- Ralph is activated without an issue source
+
+## Platform-Specific Issue States
+
+Each platform tracks issue lifecycle differently. Squad normalizes these into a common board state.
+
+### GitHub
+
+| GitHub State | GitHub API Fields | Squad Board State |
+|--------------|-------------------|-------------------|
+| Open, no assignee | `state: open`, `assignee: null` | `untriaged` |
+| Open, assigned, no branch | `state: open`, `assignee: @user`, no linked PR | `assigned` |
+| Open, branch exists | `state: open`, linked branch exists | `inProgress` |
+| Open, PR opened | `state: open`, PR exists, `reviewDecision: null` | `needsReview` |
+| Open, PR approved | `state: open`, PR `reviewDecision: APPROVED` | `readyToMerge` |
+| Open, changes requested | `state: open`, PR `reviewDecision: CHANGES_REQUESTED` | `changesRequested` |
+| Open, CI failure | `state: open`, PR `statusCheckRollup: FAILURE` | `ciFailure` |
+| Closed | `state: closed` | `done` |
+
+**Issue labels used by Squad:**
+- `squad` — Issue is in Squad backlog
+- `squad:{member}` — Assigned to specific agent
+- `squad:untriaged` — Needs triage
+- `go:needs-research` — Needs investigation before implementation
+- `priority:p{N}` — Priority level (0=critical, 1=high, 2=medium, 3=low)
+- `next-up` — Queued for next agent pickup
+
+**Branch naming convention:**
+```
+squad/{issue-number}-{kebab-case-slug}
+```
+Example: `squad/42-fix-login-validation`
+
+### Azure DevOps
+
+| ADO State | Squad Board State |
+|-----------|-------------------|
+| New | `untriaged` |
+| Active, no branch | `assigned` |
+| Active, branch exists | `inProgress` |
+| Active, PR opened | `needsReview` |
+| Active, PR approved | `readyToMerge` |
+| Resolved | `done` |
+| Closed | `done` |
+
+**Work item tags used by Squad:**
+- `squad` — Work item is in Squad backlog
+- `squad:{member}` — Assigned to specific agent
+
+**Branch naming convention:**
+```
+squad/{work-item-id}-{kebab-case-slug}
+```
+Example: `squad/1234-add-auth-module`
+
+### Microsoft Planner
+
+Planner does not have native Git integration. Squad uses Planner for task tracking and GitHub/ADO for code management.
+
+| Planner Status | Squad Board State |
+|----------------|-------------------|
+| Not Started | `untriaged` |
+| In Progress, no PR | `inProgress` |
+| In Progress, PR opened | `needsReview` |
+| Completed | `done` |
+
+**Planner→Git workflow:**
+1. Task created in Planner bucket
+2. Agent reads task from Planner
+3. Agent creates branch in GitHub/ADO repo
+4. Agent opens PR referencing Planner task ID in description
+5. Agent marks task as "Completed" when PR merges
+
+## Issue → Branch → PR → Merge Lifecycle
+
+### 1. Issue Assignment (Triage)
+
+**Trigger:** Ralph detects an untriaged issue or user manually assigns work.
+
+**Actions:**
+1. Read `.squad/routing.md` to determine which agent should handle the issue
+2. Apply `squad:{member}` label (GitHub) or tag (ADO)
+3. Transition issue to `assigned` state
+4. Optionally spawn agent immediately if issue is high-priority
+
+**Issue read command:**
+```bash
+# GitHub
+gh issue view {number} --json number,title,body,labels,assignees
+
+# Azure DevOps
+az boards work-item show --id {id} --output json
+```
+
+### 2. Branch Creation (Start Work)
+
+**Trigger:** Agent accepts issue assignment and begins work.
+
+**Actions:**
+1. Ensure working on latest base branch (usually `main` or `dev`)
+2. Create feature branch using Squad naming convention
+3. Transition issue to `inProgress` state
+
+**Branch creation commands:**
+
+**Standard (single-agent, no parallelism):**
+```bash
+git checkout main && git pull && git checkout -b squad/{issue-number}-{slug}
+```
+
+**Worktree (parallel multi-agent):**
+```bash
+git worktree add ../worktrees/{issue-number} -b squad/{issue-number}-{slug}
+cd ../worktrees/{issue-number}
+```
+
+> **Note:** Worktree support is in progress (#525). Current implementation uses standard checkout.
+
+### 3. Implementation & Commit
+
+**Actions:**
+1. Agent makes code changes
+2. Commits reference the issue number
+3. Pushes branch to remote
+
+**Commit message format:**
+```
+{type}({scope}): {description} (#{issue-number})
+
+{detailed explanation if needed}
+
+{breaking change notice if applicable}
+
+Closes #{issue-number}
+
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
+```
+
+**Commit types:** `feat`, `fix`, `docs`, `refactor`, `test`, `chore`, `perf`, `style`, `build`, `ci`
+
+**Push command:**
+```bash
+git push -u origin squad/{issue-number}-{slug}
+```
+
+### 4. PR Creation
+
+**Trigger:** Agent completes implementation and is ready for review.
+
+**Actions:**
+1. Open PR from feature branch to base branch
+2. Reference issue in PR description
+3. Apply labels if needed
+4. Transition issue to `needsReview` state
+
+**PR creation commands:**
+
+**GitHub:**
+```bash
+gh pr create --title "{title}" \
+  --body "Closes #{issue-number}\n\n{description}" \
+  --head squad/{issue-number}-{slug} \
+  --base main
+```
+
+**Azure DevOps:**
+```bash
+az repos pr create --title "{title}" \
+  --description "Closes #{work-item-id}\n\n{description}" \
+  --source-branch squad/{work-item-id}-{slug} \
+  --target-branch main
+```
+
+**PR description template:**
+```markdown
+Closes #{issue-number}
+
+## Summary
+{what changed}
+
+## Changes
+- {change 1}
+- {change 2}
+
+## Testing
+{how this was tested}
+
+{If working as a squad member:}
+Working as {member} ({role})
+
+{If needs human review:}
+⚠️ This task was flagged as "needs review" — please have a squad member review before merging.
+```
+
+### 5. PR Review & Updates
+
+**Review states:**
+- **Approved** → `readyToMerge`
+- **Changes requested** → `changesRequested`
+- **CI failure** → `ciFailure`
+
+**When changes are requested:**
+1. Agent addresses feedback
+2. Commits fixes to the same branch
+3. Pushes updates
+4. Requests re-review
+
+**Update workflow:**
+```bash
+# Make changes
+git add .
+git commit -m "fix: address review feedback"
+git push
+```
+
+**Re-request review (GitHub):**
+```bash
+gh pr ready {pr-number}
+```
+
+### 6. PR Merge
+
+**Trigger:** PR is approved and CI passes.
+
+**Merge strategies:**
+
+**GitHub (merge commit):**
+```bash
+gh pr merge {pr-number} --merge --delete-branch
+```
+
+**GitHub (squash):**
+```bash
+gh pr merge {pr-number} --squash --delete-branch
+```
+
+**Azure DevOps:**
+```bash
+az repos pr update --id {pr-id} --status completed --delete-source-branch true
+```
+
+**Post-merge actions:**
+1. Issue automatically closes (if "Closes #{number}" is in PR description)
+2. Feature branch is deleted
+3. Squad board state transitions to `done`
+4. Worktree cleanup (if worktree was used — #525)
+
+### 7. Cleanup
+
+**Standard workflow cleanup:**
+```bash
+git checkout main
+git pull
+git branch -d squad/{issue-number}-{slug}
+```
+
+**Worktree cleanup (future, #525):**
+```bash
+cd {original-cwd}
+git worktree remove ../worktrees/{issue-number}
+```
+
+## Spawn Prompt Additions for Issue Work
+
+When spawning an agent to work on an issue, include this context block:
+
+```markdown
+## ISSUE CONTEXT
+
+**Issue:** #{number} — {title}  
+**Platform:** {GitHub | Azure DevOps | Planner}  
+**Repository:** {owner}/{repo}  
+**Assigned to:** {member}
+
+**Description:**
+{issue body}
+
+**Labels/Tags:**
+{labels}
+
+**Acceptance Criteria:**
+{criteria if present in issue}
+
+**Branch:** `squad/{issue-number}-{slug}`
+
+**Your task:**
+{specific directive to the agent}
+
+**After completing work:**
+1. Commit with message referencing issue number
+2. Push branch
+3. Open PR using:
+   ```
+   gh pr create --title "{title}" --body "Closes #{number}\n\n{description}" --head squad/{issue-number}-{slug} --base {base-branch}
+   ```
+4. Report PR URL to coordinator
+```
+
+## Ralph's Role in Issue Lifecycle
+
+Ralph (the work monitor) continuously checks issue and PR state:
+
+1. **Triage:** Detects untriaged issues, assigns `squad:{member}` labels
+2. **Spawn:** Launches agents for assigned issues
+3. **Monitor:** Tracks PR state transitions (needsReview → changesRequested → readyToMerge)
+4. **Merge:** Automatically merges approved PRs
+5. **Cleanup:** Marks issues as done when PRs merge
+
+**Ralph's work-check cycle:**
+```
+Scan → Categorize → Dispatch → Watch → Report → Loop
+```
+
+See `.squad/templates/ralph-reference.md` for Ralph's full lifecycle.
+
+## PR Review Handling
+
+### Automated Approval (CI-only projects)
+
+If the project has no human reviewers configured:
+1. PR opens
+2. CI runs
+3. If CI passes, Ralph auto-merges
+4. Issue closes
+
+### Human Review Required
+
+If the project requires human approval:
+1. PR opens
+2. Human reviewer is notified (GitHub/ADO notifications)
+3. Reviewer approves or requests changes
+4. If approved + CI passes, Ralph merges
+5. If changes requested, agent addresses feedback
+
+### Squad Member Review
+
+If the issue was assigned to a squad member and they authored the PR:
+1. Another squad member reviews (conflict of interest avoidance)
+2. Original author is locked out from re-working rejected code (rejection lockout)
+3. Reviewer can approve edits or reject outright
+
+## Common Issue Lifecycle Patterns
+
+### Pattern 1: Quick Fix (Single Agent, No Review)
+```
+Issue created → Assigned to agent → Branch created → Code fixed → 
+PR opened → CI passes → Auto-merged → Issue closed
+```
+
+### Pattern 2: Feature Development (Human Review)
+```
+Issue created → Assigned to agent → Branch created → Feature implemented → 
+PR opened → Human reviews → Changes requested → Agent fixes → 
+Re-reviewed → Approved → Merged → Issue closed
+```
+
+### Pattern 3: Research-Then-Implement
+```
+Issue created → Labeled `go:needs-research` → Research agent spawned → 
+Research documented → Research PR merged → Implementation issue created → 
+Implementation agent spawned → Feature built → PR merged
+```
+
+### Pattern 4: Parallel Multi-Agent (Future, #525)
+```
+Epic issue created → Decomposed into sub-issues → Each sub-issue assigned → 
+Multiple agents work in parallel worktrees → PRs opened concurrently → 
+All PRs reviewed → All PRs merged → Epic closed
+```
+
+## Anti-Patterns
+
+- ❌ Creating branches without linking to an issue
+- ❌ Committing without issue reference in message
+- ❌ Opening PRs without "Closes #{number}" in description
+- ❌ Merging PRs before CI passes
+- ❌ Leaving feature branches undeleted after merge
+- ❌ Using `checkout -b` when parallel agents are active (causes working directory conflicts)
+- ❌ Manually transitioning issue states — let the platform and Squad automation handle it
+- ❌ Skipping the branch naming convention — breaks Ralph's tracking logic
+
+## Migration Notes
+
+**v0.8.x → v0.9.x (Worktree Support):**
+- `checkout -b` → `git worktree add` for parallel agents
+- Worktree cleanup added to post-merge flow
+- `TEAM_ROOT` passing to agents to support worktree-aware state resolution
+
+This template will be updated as worktree lifecycle support lands in #525.

.squad/templates/keda-scaler.md

@@ -0,0 +1,164 @@
+# KEDA External Scaler for GitHub Issue-Driven Agent Autoscaling
+
+> Scale agent pods to zero when idle, up when work arrives — driven by GitHub Issues.
+
+## Overview
+
+When running Squad on Kubernetes, agent pods sit idle when no work exists. [KEDA](https://keda.sh) (Kubernetes Event-Driven Autoscaler) solves this for queue-based workloads, but GitHub Issues isn't a native KEDA trigger.
+
+The `keda-copilot-scaler` is a KEDA External Scaler (gRPC) that bridges this gap:
+1. Polls GitHub API for issues matching specific labels (e.g., `squad:copilot`)
+2. Reports queue depth as a KEDA metric
+3. Handles rate limits gracefully (Retry-After, exponential backoff)
+4. Supports composite scaling decisions
+
+## Quick Start
+
+### Prerequisites
+- Kubernetes cluster with KEDA v2.x installed
+- GitHub personal access token (PAT) with `repo` scope
+- Helm 3.x
+
+### 1. Install the Scaler
+
+```bash
+helm install keda-copilot-scaler oci://ghcr.io/tamirdresher/keda-copilot-scaler \
+  --namespace squad-scaler --create-namespace \
+  --set github.owner=YOUR_ORG \
+  --set github.repo=YOUR_REPO \
+  --set github.token=YOUR_TOKEN
+```
+
+Or with Kustomize:
+```bash
+kubectl apply -k https://github.com/tamirdresher/keda-copilot-scaler/deploy/kustomize
+```
+
+### 2. Create a ScaledObject
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: ScaledObject
+metadata:
+  name: picard-scaler
+  namespace: squad
+spec:
+  scaleTargetRef:
+    name: picard-deployment
+  minReplicaCount: 0          # Scale to zero when idle
+  maxReplicaCount: 3
+  pollingInterval: 30         # Check every 30 seconds
+  cooldownPeriod: 300         # Wait 5 minutes before scaling down
+  triggers:
+  - type: external
+    metadata:
+      scalerAddress: keda-copilot-scaler.squad-scaler.svc.cluster.local:6000
+      owner: your-org
+      repo: your-repo
+      labels: squad:copilot    # Only count issues with this label
+      threshold: "1"           # Scale up when >= 1 issue exists
+```
+
+### 3. Verify
+
+```bash
+# Check the scaler is running
+kubectl get pods -n squad-scaler
+
+# Check ScaledObject status
+kubectl get scaledobject picard-scaler -n squad
+
+# Watch scaling events
+kubectl get events -n squad --watch
+```
+
+## Scaling Behavior
+
+| Open Issues | Target Replicas | Behavior |
+|------------|----------------|----------|
+| 0 | 0 | Scale to zero — save resources |
+| 1–3 | 1 | Single agent handles work |
+| 4–10 | 2 | Scale up for parallel processing |
+| 10+ | 3 (max) | Maximum parallelism |
+
+The threshold and max replicas are configurable per ScaledObject.
+
+## Rate Limit Awareness
+
+The scaler tracks GitHub API rate limits:
+- Reads `X-RateLimit-Remaining` from API responses
+- Backs off when quota is low (< 100 remaining)
+- Reports rate limit metrics as secondary KEDA triggers
+- Never exhausts API quota from polling
+
+## Integration with Squad
+
+### Machine Capabilities (#514)
+
+Combine with machine capability labels for intelligent scheduling:
+
+```yaml
+# Only scale pods on GPU-capable nodes
+spec:
+  template:
+    spec:
+      nodeSelector:
+        node.squad.dev/gpu: "true"
+  triggers:
+  - type: external
+    metadata:
+      labels: squad:copilot,needs:gpu
+```
+
+### Cooperative Rate Limiting (#515)
+
+The scaler exposes rate limit metrics that feed into the cooperative rate limiting system:
+- Current `X-RateLimit-Remaining` value
+- Predicted time to exhaustion (from predictive circuit breaker)
+- Can return 0 target replicas when rate limited → pods scale to zero
+
+## Architecture
+
+```
+GitHub API                    KEDA                    Kubernetes
+┌──────────┐              ┌──────────┐           ┌──────────────┐
+│  Issues   │◄── poll ──►│  Scaler   │──metrics─►│ HPA / KEDA   │
+│  (REST)   │             │  (gRPC)   │           │ Controller   │
+└──────────┘              └──────────┘           └──────┬───────┘
+                                                        │
+                                                  scale up/down
+                                                        │
+                                                 ┌──────▼───────┐
+                                                 │ Agent Pods    │
+                                                 │ (0–N replicas)│
+                                                 └──────────────┘
+```
+
+## Configuration Reference
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `github.owner` | — | Repository owner |
+| `github.repo` | — | Repository name |
+| `github.token` | — | GitHub PAT with `repo` scope |
+| `github.labels` | `squad:copilot` | Comma-separated label filter |
+| `scaler.port` | `6000` | gRPC server port |
+| `scaler.pollInterval` | `30s` | GitHub API polling interval |
+| `scaler.rateLimitThreshold` | `100` | Stop polling below this remaining |
+
+## Source & Contributing
+
+- **Repository:** [tamirdresher/keda-copilot-scaler](https://github.com/tamirdresher/keda-copilot-scaler)
+- **License:** MIT
+- **Language:** Go
+- **Tests:** 51 passing (unit + integration)
+- **CI:** GitHub Actions
+
+The scaler is maintained as a standalone project. PRs and issues welcome.
+
+## References
+
+- [KEDA External Scalers](https://keda.sh/docs/latest/concepts/external-scalers/) — KEDA documentation
+- [Squad on AKS](https://github.com/tamirdresher/squad-on-aks) — Full Kubernetes deployment example
+- [Machine Capabilities](machine-capabilities.md) — Capability-based routing (#514)
+- [Cooperative Rate Limiting](cooperative-rate-limiting.md) — Multi-agent rate management (#515)

.squad/templates/machine-capabilities.md

@@ -0,0 +1,75 @@
+# Machine Capability Discovery & Label-Based Routing
+
+> Enable Ralph to skip issues requiring capabilities the current machine lacks.
+
+## Overview
+
+When running Squad across multiple machines (laptops, DevBoxes, GPU servers, Kubernetes nodes), each machine has different tooling. The capability system lets you declare what each machine can do, and Ralph automatically routes work accordingly.
+
+## Setup
+
+### 1. Create a Capabilities Manifest
+
+Create `~/.squad/machine-capabilities.json` (user-wide) or `.squad/machine-capabilities.json` (project-local):
+
+```json
+{
+  "machine": "MY-LAPTOP",
+  "capabilities": ["browser", "personal-gh", "onedrive"],
+  "missing": ["gpu", "docker", "azure-speech"],
+  "lastUpdated": "2026-03-22T00:00:00Z"
+}
+```
+
+### 2. Label Issues with Requirements
+
+Add `needs:*` labels to issues that require specific capabilities:
+
+| Label | Meaning |
+|-------|---------|
+| `needs:browser` | Requires Playwright / browser automation |
+| `needs:gpu` | Requires NVIDIA GPU |
+| `needs:personal-gh` | Requires personal GitHub account |
+| `needs:emu-gh` | Requires Enterprise Managed User account |
+| `needs:azure-cli` | Requires authenticated Azure CLI |
+| `needs:docker` | Requires Docker daemon |
+| `needs:onedrive` | Requires OneDrive sync |
+| `needs:teams-mcp` | Requires Teams MCP tools |
+
+Custom capabilities are supported — any `needs:X` label works if `X` is in the machine's `capabilities` array.
+
+### 3. Run Ralph
+
+```bash
+squad watch --interval 5
+```
+
+Ralph will log skipped issues:
+```
+⏭️ Skipping #42 "Train ML model" — missing: gpu
+✓ Triaged #43 "Fix CSS layout" → Picard (routing-rule)
+```
+
+## How It Works
+
+1. Ralph loads `machine-capabilities.json` at startup
+2. For each open issue, Ralph extracts `needs:*` labels
+3. If any required capability is missing, the issue is skipped
+4. Issues without `needs:*` labels are always processed (opt-in system)
+
+## Kubernetes Integration
+
+On Kubernetes, machine capabilities map to node labels:
+
+```yaml
+# Node labels (set by capability DaemonSet or manually)
+node.squad.dev/gpu: "true"
+node.squad.dev/browser: "true"
+
+# Pod spec uses nodeSelector
+spec:
+  nodeSelector:
+    node.squad.dev/gpu: "true"
+```
+
+A DaemonSet can run capability discovery on each node and maintain labels automatically. See the [squad-on-aks](https://github.com/tamirdresher/squad-on-aks) project for a complete Kubernetes deployment example.

.squad/templates/mcp-config.md

@@ -0,0 +1,90 @@
+# MCP Integration — Configuration and Samples
+
+MCP (Model Context Protocol) servers extend Squad with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Squad discovers and uses them.
+
+> **Full patterns:** Read `.squad/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, and graceful degradation.
+
+## Config File Locations
+
+Users configure MCP servers at these locations (checked in priority order):
+1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
+3. **User-level:** `~/.copilot/mcp-config.json` (personal)
+4. **CLI override:** `--additional-mcp-config` flag (session-specific)
+
+## Sample Config — Trello
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "npx",
+      "args": ["-y", "@trello/mcp-server"],
+      "env": {
+        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
+        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — GitHub
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Azure
+
+```json
+{
+  "mcpServers": {
+    "azure": {
+      "command": "npx",
+      "args": ["-y", "@azure/mcp-server"],
+      "env": {
+        "AZURE_SUBSCRIPTION_ID": "${AZURE_SUBSCRIPTION_ID}",
+        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
+        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
+        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Aspire
+
+```json
+{
+  "mcpServers": {
+    "aspire": {
+      "command": "npx",
+      "args": ["-y", "@aspire/mcp-server"],
+      "env": {
+        "ASPIRE_DASHBOARD_URL": "${ASPIRE_DASHBOARD_URL}"
+      }
+    }
+  }
+}
+```
+
+## Authentication Notes
+
+- **GitHub MCP requires a separate token** from the `gh` CLI auth. Generate at https://github.com/settings/tokens
+- **Trello requires API key + token** from https://trello.com/power-ups/admin
+- **Azure requires service principal credentials** — see Azure docs for setup
+- **Aspire uses the dashboard URL** — typically `http://localhost:18888` during local dev
+
+Auth is a real blocker for some MCP servers. Users need separate tokens for GitHub MCP, Azure MCP, Trello MCP, etc. This is a documentation problem, not a code problem.

.squad/templates/multi-agent-format.md

@@ -0,0 +1,28 @@
+# Multi-Agent Artifact Format
+
+When multiple agents contribute to a final artifact (document, analysis, design), use this format. The assembled result must include:
+
+- Termination condition
+- Constraint budgets (if active)
+- Reviewer verdicts (if any)
+- Raw agent outputs appendix
+
+## Assembly Structure
+
+The assembled result goes at the top. Below it, include:
+
+```
+## APPENDIX: RAW AGENT OUTPUTS
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+```
+
+## Appendix Rules
+
+This appendix is for diagnostic integrity. Do not edit, summarize, or polish the raw outputs. The Coordinator may not rewrite raw agent outputs; it may only paste them verbatim and assemble the final artifact above.
+
+See `.squad/templates/run-output.md` for the complete output format template.

.squad/templates/orchestration-log.md

@@ -0,0 +1,27 @@
+# Orchestration Log Entry
+
+> One file per agent spawn. Saved to `.squad/orchestration-log/{timestamp}-{agent-name}.md`
+
+---
+
+### {timestamp} — {task summary}
+
+| Field | Value |
+|-------|-------|
+| **Agent routed** | {Name} ({Role}) |
+| **Why chosen** | {Routing rationale — what in the request matched this agent} |
+| **Mode** | {`background` / `sync`} |
+| **Why this mode** | {Brief reason — e.g., "No hard data dependencies" or "User needs to approve architecture"} |
+| **Files authorized to read** | {Exact file paths the agent was told to read} |
+| **File(s) agent must produce** | {Exact file paths the agent is expected to create or modify} |
+| **Outcome** | {Completed / Rejected by {Reviewer} / Escalated} |
+
+---
+
+## Rules
+
+1. **One file per agent spawn.** Named `{timestamp}-{agent-name}.md`.
+2. **Log BEFORE spawning.** The entry must exist before the agent runs.
+3. **Update outcome AFTER the agent completes.** Fill in the Outcome field.
+4. **Never delete or edit past entries.** Append-only.
+5. **If a reviewer rejects work,** log the rejection as a new entry with the revision agent.

.squad/templates/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

.squad/templates/plugin-marketplace.md

@@ -0,0 +1,49 @@
+# Plugin Marketplace
+
+Plugins are curated agent templates, skills, instructions, and prompts shared by the community via GitHub repositories (e.g., `github/awesome-copilot`, `anthropics/skills`). They provide ready-made expertise for common domains — cloud platforms, frameworks, testing strategies, etc.
+
+## Marketplace State
+
+Registered marketplace sources are stored in `.squad/plugins/marketplaces.json`:
+
+```json
+{
+  "marketplaces": [
+    {
+      "name": "awesome-copilot",
+      "source": "github/awesome-copilot",
+      "added_at": "2026-02-14T00:00:00Z"
+    }
+  ]
+}
+```
+
+## CLI Commands
+
+Users manage marketplaces via the CLI:
+- `squad plugin marketplace add {owner/repo}` — Register a GitHub repo as a marketplace source
+- `squad plugin marketplace remove {name}` — Remove a registered marketplace
+- `squad plugin marketplace list` — List registered marketplaces
+- `squad plugin marketplace browse {name}` — List available plugins in a marketplace
+
+## When to Browse
+
+During the **Adding Team Members** flow, AFTER allocating a name but BEFORE generating the charter:
+
+1. Read `.squad/plugins/marketplaces.json`. If the file doesn't exist or `marketplaces` is empty, skip silently.
+2. For each registered marketplace, search for plugins whose name or description matches the new member's role or domain keywords.
+3. Present matching plugins to the user: *"Found '{plugin-name}' in {marketplace} marketplace — want me to install it as a skill for {CastName}?"*
+4. If the user accepts, install the plugin (see below). If they decline or skip, proceed without it.
+
+## How to Install a Plugin
+
+1. Read the plugin content from the marketplace repository (the plugin's `SKILL.md` or equivalent).
+2. Copy it into the agent's skills directory: `.squad/skills/{plugin-name}/SKILL.md`
+3. If the plugin includes charter-level instructions (role boundaries, tool preferences), merge those into the agent's `charter.md`.
+4. Log the installation in the agent's `history.md`: *"📦 Plugin '{plugin-name}' installed from {marketplace}."*
+
+## Graceful Degradation
+
+- **No marketplaces configured:** Skip the marketplace check entirely. No warning, no prompt.
+- **Marketplace unreachable:** Warn the user (*"⚠ Couldn't reach {marketplace} — continuing without it"*) and proceed with team member creation normally.
+- **No matching plugins:** Inform the user (*"No matching plugins found in configured marketplaces"*) and proceed.

.squad/templates/ralph-circuit-breaker.md

@@ -0,0 +1,313 @@
+# Ralph Circuit Breaker — Model Rate Limit Fallback
+
+> Classic circuit breaker pattern (Hystrix / Polly / Resilience4j) applied to Copilot model selection.
+> When the preferred model hits rate limits, Ralph automatically degrades to free-tier models, then self-heals.
+
+## Problem
+
+When running multiple Ralph instances across repos, Copilot model rate limits cause cascading failures.
+All Ralphs fail simultaneously when the preferred model (e.g., `claude-sonnet-4.6`) hits quota.
+
+Premium models burn quota fast:
+| Model | Multiplier | Risk |
+|-------|-----------|------|
+| `claude-sonnet-4.6` | 1x | Moderate with many Ralphs |
+| `claude-opus-4.6` | 10x | High |
+| `gpt-5.4` | 50x | Very high |
+| `gpt-5.4-mini` | **0x** | **Free — unlimited** |
+| `gpt-5-mini` | **0x** | **Free — unlimited** |
+| `gpt-4.1` | **0x** | **Free — unlimited** |
+
+## Circuit Breaker States
+
+```
+┌─────────┐   rate limit error    ┌────────┐
+│ CLOSED  │ ───────────────────►  │  OPEN  │
+│ (normal)│                       │(fallback)│
+└────┬────┘   ◄──────────────── └────┬────┘
+     │        2 consecutive          │
+     │        successes              │ cooldown expires
+     │                               ▼
+     │                          ┌──────────┐
+     └───── success ◄────────  │HALF-OPEN │
+             (close)            │ (testing) │
+                                └──────────┘
+```
+
+### CLOSED (normal operation)
+- Use preferred model from config
+- Every successful response confirms circuit stays closed
+- On rate limit error → transition to OPEN
+
+### OPEN (rate limited — fallback active)
+- Fall back through the free-tier model chain:
+  1. `gpt-5.4-mini`
+  2. `gpt-5-mini`
+  3. `gpt-4.1`
+- Start cooldown timer (default: 10 minutes)
+- When cooldown expires → transition to HALF-OPEN
+
+### HALF-OPEN (testing recovery)
+- Try preferred model again
+- If 2 consecutive successes → transition to CLOSED
+- If rate limit error → back to OPEN, reset cooldown
+
+## State File: `.squad/ralph-circuit-breaker.json`
+
+```json
+{
+  "state": "closed",
+  "preferredModel": "claude-sonnet-4.6",
+  "fallbackChain": ["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"],
+  "currentFallbackIndex": 0,
+  "cooldownMinutes": 10,
+  "openedAt": null,
+  "halfOpenSuccesses": 0,
+  "consecutiveFailures": 0,
+  "metrics": {
+    "totalFallbacks": 0,
+    "totalRecoveries": 0,
+    "lastFallbackAt": null,
+    "lastRecoveryAt": null
+  }
+}
+```
+
+## PowerShell Functions
+
+Paste these into your `ralph-watch.ps1` or source them from a shared module.
+
+### `Get-CircuitBreakerState`
+
+```powershell
+function Get-CircuitBreakerState {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    if (-not (Test-Path $StateFile)) {
+        $default = @{
+            state              = "closed"
+            preferredModel     = "claude-sonnet-4.6"
+            fallbackChain      = @("gpt-5.4-mini", "gpt-5-mini", "gpt-4.1")
+            currentFallbackIndex = 0
+            cooldownMinutes    = 10
+            openedAt           = $null
+            halfOpenSuccesses  = 0
+            consecutiveFailures = 0
+            metrics            = @{
+                totalFallbacks  = 0
+                totalRecoveries = 0
+                lastFallbackAt  = $null
+                lastRecoveryAt  = $null
+            }
+        }
+        $default | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+        return $default
+    }
+
+    return (Get-Content $StateFile -Raw | ConvertFrom-Json)
+}
+```
+
+### `Save-CircuitBreakerState`
+
+```powershell
+function Save-CircuitBreakerState {
+    param(
+        [object]$State,
+        [string]$StateFile = ".squad/ralph-circuit-breaker.json"
+    )
+
+    $State | ConvertTo-Json -Depth 3 | Set-Content $StateFile
+}
+```
+
+### `Get-CurrentModel`
+
+Returns the model Ralph should use right now, based on circuit state.
+
+```powershell
+function Get-CurrentModel {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+
+    switch ($cb.state) {
+        "closed" {
+            return $cb.preferredModel
+        }
+        "open" {
+            # Check if cooldown has expired
+            if ($cb.openedAt) {
+                $opened = [DateTime]::Parse($cb.openedAt)
+                $elapsed = (Get-Date) - $opened
+                if ($elapsed.TotalMinutes -ge $cb.cooldownMinutes) {
+                    # Transition to half-open
+                    $cb.state = "half-open"
+                    $cb.halfOpenSuccesses = 0
+                    Save-CircuitBreakerState -State $cb -StateFile $StateFile
+                    Write-Host "  [circuit-breaker] Cooldown expired. Testing preferred model..." -ForegroundColor Yellow
+                    return $cb.preferredModel
+                }
+            }
+            # Still in cooldown — use fallback
+            $idx = [Math]::Min($cb.currentFallbackIndex, $cb.fallbackChain.Count - 1)
+            return $cb.fallbackChain[$idx]
+        }
+        "half-open" {
+            return $cb.preferredModel
+        }
+        default {
+            return $cb.preferredModel
+        }
+    }
+}
+```
+
+### `Update-CircuitBreakerOnSuccess`
+
+Call after every successful model response.
+
+```powershell
+function Update-CircuitBreakerOnSuccess {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures = 0
+
+    if ($cb.state -eq "half-open") {
+        $cb.halfOpenSuccesses++
+        if ($cb.halfOpenSuccesses -ge 2) {
+            # Recovery! Close the circuit
+            $cb.state = "closed"
+            $cb.openedAt = $null
+            $cb.halfOpenSuccesses = 0
+            $cb.currentFallbackIndex = 0
+            $cb.metrics.totalRecoveries++
+            $cb.metrics.lastRecoveryAt = (Get-Date).ToString("o")
+            Save-CircuitBreakerState -State $cb -StateFile $StateFile
+            Write-Host "  [circuit-breaker] RECOVERED — back to preferred model ($($cb.preferredModel))" -ForegroundColor Green
+            return
+        }
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+        Write-Host "  [circuit-breaker] Half-open success $($cb.halfOpenSuccesses)/2" -ForegroundColor Yellow
+        return
+    }
+
+    # closed state — nothing to do
+}
+```
+
+### `Update-CircuitBreakerOnRateLimit`
+
+Call when a model response indicates rate limiting (HTTP 429 or error message containing "rate limit").
+
+```powershell
+function Update-CircuitBreakerOnRateLimit {
+    param([string]$StateFile = ".squad/ralph-circuit-breaker.json")
+
+    $cb = Get-CircuitBreakerState -StateFile $StateFile
+    $cb.consecutiveFailures++
+
+    if ($cb.state -eq "closed" -or $cb.state -eq "half-open") {
+        # Open the circuit
+        $cb.state = "open"
+        $cb.openedAt = (Get-Date).ToString("o")
+        $cb.halfOpenSuccesses = 0
+        $cb.currentFallbackIndex = 0
+        $cb.metrics.totalFallbacks++
+        $cb.metrics.lastFallbackAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+
+        $fallbackModel = $cb.fallbackChain[0]
+        Write-Host "  [circuit-breaker] RATE LIMITED — falling back to $fallbackModel (cooldown: $($cb.cooldownMinutes)m)" -ForegroundColor Red
+        return
+    }
+
+    if ($cb.state -eq "open") {
+        # Already open — try next fallback in chain if current one also fails
+        if ($cb.currentFallbackIndex -lt ($cb.fallbackChain.Count - 1)) {
+            $cb.currentFallbackIndex++
+            $nextModel = $cb.fallbackChain[$cb.currentFallbackIndex]
+            Write-Host "  [circuit-breaker] Fallback also limited — trying $nextModel" -ForegroundColor Red
+        }
+        # Reset cooldown timer
+        $cb.openedAt = (Get-Date).ToString("o")
+        Save-CircuitBreakerState -State $cb -StateFile $StateFile
+    }
+}
+```
+
+## Integration with ralph-watch.ps1
+
+In your Ralph polling loop, wrap the model selection:
+
+```powershell
+# At the top of your polling loop
+$model = Get-CurrentModel
+
+# When invoking copilot CLI
+$result = copilot-cli --model $model ...
+
+# After the call
+if ($result -match "rate.?limit" -or $LASTEXITCODE -eq 429) {
+    Update-CircuitBreakerOnRateLimit
+} else {
+    Update-CircuitBreakerOnSuccess
+}
+```
+
+### Full integration example
+
+```powershell
+# Source the circuit breaker functions
+. .squad-templates/ralph-circuit-breaker-functions.ps1
+
+while ($true) {
+    $model = Get-CurrentModel
+    Write-Host "Polling with model: $model"
+
+    try {
+        # Your existing Ralph logic here, but pass $model
+        $response = Invoke-RalphCycle -Model $model
+
+        # Success path
+        Update-CircuitBreakerOnSuccess
+    }
+    catch {
+        if ($_.Exception.Message -match "rate.?limit|429|quota|Too Many Requests") {
+            Update-CircuitBreakerOnRateLimit
+            # Retry immediately with fallback model
+            continue
+        }
+        # Other errors — handle normally
+        throw
+    }
+
+    Start-Sleep -Seconds $pollInterval
+}
+```
+
+## Configuration
+
+Override defaults by editing `.squad/ralph-circuit-breaker.json`:
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `preferredModel` | `claude-sonnet-4.6` | Model to use when circuit is closed |
+| `fallbackChain` | `["gpt-5.4-mini", "gpt-5-mini", "gpt-4.1"]` | Ordered fallback models (all free-tier) |
+| `cooldownMinutes` | `10` | How long to wait before testing recovery |
+
+## Metrics
+
+The state file tracks operational metrics:
+
+- **totalFallbacks** — How many times the circuit opened
+- **totalRecoveries** — How many times it recovered to preferred model
+- **lastFallbackAt** — ISO timestamp of last rate limit event
+- **lastRecoveryAt** — ISO timestamp of last successful recovery
+
+Query metrics with:
+```powershell
+$cb = Get-Content .squad/ralph-circuit-breaker.json | ConvertFrom-Json
+Write-Host "Fallbacks: $($cb.metrics.totalFallbacks) | Recoveries: $($cb.metrics.totalRecoveries)"
+```

.squad/templates/ralph-triage.js

@@ -0,0 +1,543 @@
+#!/usr/bin/env node
+/**
+ * Ralph Triage Script — Standalone CJS implementation
+ *
+ * ⚠️ SYNC NOTICE: This file ports triage logic from the SDK source:
+ *   packages/squad-sdk/src/ralph/triage.ts
+ *
+ * Any changes to routing/triage logic MUST be applied to BOTH files.
+ * The SDK module is the canonical implementation; this script exists
+ * for zero-dependency use in GitHub Actions workflows.
+ *
+ * To verify parity: npm test -- test/ralph-triage.test.ts
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const https = require('node:https');
+const { execSync } = require('node:child_process');
+
+function parseArgs(argv) {
+  let squadDir = '.squad';
+  let output = 'triage-results.json';
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--squad-dir') {
+      squadDir = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === '--output') {
+      output = argv[i + 1];
+      i += 1;
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
+      printUsage();
+      process.exit(0);
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  if (!squadDir) throw new Error('--squad-dir requires a value');
+  if (!output) throw new Error('--output requires a value');
+
+  return { squadDir, output };
+}
+
+function printUsage() {
+  console.log('Usage: node .squad/templates/ralph-triage.js --squad-dir .squad --output triage-results.json');
+}
+
+function normalizeEol(content) {
+  return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+function parseRoutingRules(routingMd) {
+  const table = parseTableSection(routingMd, /^##\s*work\s*type\s*(?:→|->)\s*agent\b/i);
+  if (!table) return [];
+
+  const workTypeIndex = findColumnIndex(table.headers, ['work type', 'type']);
+  const agentIndex = findColumnIndex(table.headers, ['agent', 'route to', 'route']);
+  const examplesIndex = findColumnIndex(table.headers, ['examples', 'example']);
+
+  if (workTypeIndex < 0 || agentIndex < 0) return [];
+
+  const rules = [];
+  for (const row of table.rows) {
+    const workType = cleanCell(row[workTypeIndex] || '');
+    const agentName = cleanCell(row[agentIndex] || '');
+    const keywords = splitKeywords(examplesIndex >= 0 ? row[examplesIndex] : '');
+    if (!workType || !agentName) continue;
+    rules.push({ workType, agentName, keywords });
+  }
+
+  return rules;
+}
+
+function parseModuleOwnership(routingMd) {
+  const table = parseTableSection(routingMd, /^##\s*module\s*ownership\b/i);
+  if (!table) return [];
+
+  const moduleIndex = findColumnIndex(table.headers, ['module', 'path']);
+  const primaryIndex = findColumnIndex(table.headers, ['primary']);
+  const secondaryIndex = findColumnIndex(table.headers, ['secondary']);
+
+  if (moduleIndex < 0 || primaryIndex < 0) return [];
+
+  const modules = [];
+  for (const row of table.rows) {
+    const modulePath = normalizeModulePath(row[moduleIndex] || '');
+    const primary = cleanCell(row[primaryIndex] || '');
+    const secondaryRaw = cleanCell(secondaryIndex >= 0 ? row[secondaryIndex] || '' : '');
+    const secondary = normalizeOptionalOwner(secondaryRaw);
+
+    if (!modulePath || !primary) continue;
+    modules.push({ modulePath, primary, secondary });
+  }
+
+  return modules;
+}
+
+function parseRoster(teamMd) {
+  const table =
+    parseTableSection(teamMd, /^##\s*members\b/i) ||
+    parseTableSection(teamMd, /^##\s*team\s*roster\b/i);
+
+  if (!table) return [];
+
+  const nameIndex = findColumnIndex(table.headers, ['name']);
+  const roleIndex = findColumnIndex(table.headers, ['role']);
+  if (nameIndex < 0 || roleIndex < 0) return [];
+
+  const excluded = new Set(['scribe', 'ralph']);
+  const members = [];
+
+  for (const row of table.rows) {
+    const name = cleanCell(row[nameIndex] || '');
+    const role = cleanCell(row[roleIndex] || '');
+    if (!name || !role) continue;
+    if (excluded.has(name.toLowerCase())) continue;
+
+    members.push({
+      name,
+      role,
+      label: `squad:${name.toLowerCase()}`,
+    });
+  }
+
+  return members;
+}
+
+function triageIssue(issue, rules, modules, roster) {
+  const issueText = `${issue.title}\n${issue.body || ''}`.toLowerCase();
+  const normalizedIssueText = normalizeTextForPathMatch(issueText);
+
+  const bestModule = findBestModuleMatch(normalizedIssueText, modules);
+  if (bestModule) {
+    const primaryMember = findMember(bestModule.primary, roster);
+    if (primaryMember) {
+      return {
+        agent: primaryMember,
+        reason: `Matched module path "${bestModule.modulePath}" to primary owner "${bestModule.primary}"`,
+        source: 'module-ownership',
+        confidence: 'high',
+      };
+    }
+
+    if (bestModule.secondary) {
+      const secondaryMember = findMember(bestModule.secondary, roster);
+      if (secondaryMember) {
+        return {
+          agent: secondaryMember,
+          reason: `Matched module path "${bestModule.modulePath}" to secondary owner "${bestModule.secondary}"`,
+          source: 'module-ownership',
+          confidence: 'medium',
+        };
+      }
+    }
+  }
+
+  const bestRule = findBestRuleMatch(issueText, rules);
+  if (bestRule) {
+    const agent = findMember(bestRule.rule.agentName, roster);
+    if (agent) {
+      return {
+        agent,
+        reason: `Matched routing keyword(s): ${bestRule.matchedKeywords.join(', ')}`,
+        source: 'routing-rule',
+        confidence: bestRule.matchedKeywords.length >= 2 ? 'high' : 'medium',
+      };
+    }
+  }
+
+  const roleMatch = findRoleKeywordMatch(issueText, roster);
+  if (roleMatch) {
+    return {
+      agent: roleMatch.agent,
+      reason: roleMatch.reason,
+      source: 'role-keyword',
+      confidence: 'medium',
+    };
+  }
+
+  const lead = findLeadFallback(roster);
+  if (!lead) return null;
+
+  return {
+    agent: lead,
+    reason: 'No module, routing, or role keyword match — routed to Lead/Architect',
+    source: 'lead-fallback',
+    confidence: 'low',
+  };
+}
+
+function parseTableSection(markdown, sectionHeader) {
+  const lines = normalizeEol(markdown).split('\n');
+  let inSection = false;
+  const tableLines = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!inSection && sectionHeader.test(trimmed)) {
+      inSection = true;
+      continue;
+    }
+    if (inSection && /^##\s+/.test(trimmed)) break;
+    if (inSection && trimmed.startsWith('|')) tableLines.push(trimmed);
+  }
+
+  if (tableLines.length === 0) return null;
+
+  let headers = null;
+  const rows = [];
+
+  for (const line of tableLines) {
+    const cells = parseTableLine(line);
+    if (cells.length === 0) continue;
+    if (cells.every((cell) => /^:?-{2,}:?$/.test(cell))) continue;
+
+    if (!headers) {
+      headers = cells;
+      continue;
+    }
+
+    rows.push(cells);
+  }
+
+  if (!headers) return null;
+  return { headers, rows };
+}
+
+function parseTableLine(line) {
+  return line
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split('|')
+    .map((cell) => cell.trim());
+}
+
+function findColumnIndex(headers, candidates) {
+  const normalizedHeaders = headers.map((header) => cleanCell(header).toLowerCase());
+  for (const candidate of candidates) {
+    const index = normalizedHeaders.findIndex((header) => header.includes(candidate));
+    if (index >= 0) return index;
+  }
+  return -1;
+}
+
+function cleanCell(value) {
+  return value
+    .replace(/`/g, '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .trim();
+}
+
+function splitKeywords(examplesCell) {
+  if (!examplesCell) return [];
+  return examplesCell
+    .split(',')
+    .map((keyword) => cleanCell(keyword))
+    .filter((keyword) => keyword.length > 0);
+}
+
+function normalizeOptionalOwner(owner) {
+  if (!owner) return null;
+  if (/^[-—–]+$/.test(owner)) return null;
+  return owner;
+}
+
+function normalizeModulePath(modulePath) {
+  return cleanCell(modulePath).replace(/\\/g, '/').toLowerCase();
+}
+
+function normalizeTextForPathMatch(text) {
+  return text.replace(/\\/g, '/').replace(/`/g, '');
+}
+
+function normalizeName(value) {
+  return cleanCell(value)
+    .toLowerCase()
+    .replace(/[^\w@\s-]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function findMember(target, roster) {
+  const normalizedTarget = normalizeName(target);
+  if (!normalizedTarget) return null;
+
+  for (const member of roster) {
+    if (normalizeName(member.name) === normalizedTarget) return member;
+  }
+
+  for (const member of roster) {
+    if (normalizeName(member.role) === normalizedTarget) return member;
+  }
+
+  for (const member of roster) {
+    const memberName = normalizeName(member.name);
+    if (normalizedTarget.includes(memberName) || memberName.includes(normalizedTarget)) {
+      return member;
+    }
+  }
+
+  for (const member of roster) {
+    const memberRole = normalizeName(member.role);
+    if (normalizedTarget.includes(memberRole) || memberRole.includes(normalizedTarget)) {
+      return member;
+    }
+  }
+
+  return null;
+}
+
+function findBestModuleMatch(issueText, modules) {
+  let best = null;
+  let bestLength = -1;
+
+  for (const module of modules) {
+    const modulePath = normalizeModulePath(module.modulePath);
+    if (!modulePath) continue;
+    if (!issueText.includes(modulePath)) continue;
+
+    if (modulePath.length > bestLength) {
+      best = module;
+      bestLength = modulePath.length;
+    }
+  }
+
+  return best;
+}
+
+function findBestRuleMatch(issueText, rules) {
+  let best = null;
+  let bestScore = 0;
+
+  for (const rule of rules) {
+    const matchedKeywords = rule.keywords
+      .map((keyword) => keyword.toLowerCase())
+      .filter((keyword) => keyword.length > 0 && issueText.includes(keyword));
+
+    if (matchedKeywords.length === 0) continue;
+
+    const score =
+      matchedKeywords.length * 100 + matchedKeywords.reduce((sum, keyword) => sum + keyword.length, 0);
+    if (score > bestScore) {
+      best = { rule, matchedKeywords };
+      bestScore = score;
+    }
+  }
+
+  return best;
+}
+
+function findRoleKeywordMatch(issueText, roster) {
+  for (const member of roster) {
+    const role = member.role.toLowerCase();
+
+    if (
+      (role.includes('frontend') || role.includes('ui')) &&
+      (issueText.includes('ui') || issueText.includes('frontend') || issueText.includes('css'))
+    ) {
+      return { agent: member, reason: 'Matched frontend/UI role keywords' };
+    }
+
+    if (
+      (role.includes('backend') || role.includes('api') || role.includes('server')) &&
+      (issueText.includes('api') || issueText.includes('backend') || issueText.includes('database'))
+    ) {
+      return { agent: member, reason: 'Matched backend/API role keywords' };
+    }
+
+    if (
+      (role.includes('test') || role.includes('qa')) &&
+      (issueText.includes('test') || issueText.includes('bug') || issueText.includes('fix'))
+    ) {
+      return { agent: member, reason: 'Matched testing/QA role keywords' };
+    }
+  }
+
+  return null;
+}
+
+function findLeadFallback(roster) {
+  return (
+    roster.find((member) => {
+      const role = member.role.toLowerCase();
+      return role.includes('lead') || role.includes('architect');
+    }) || null
+  );
+}
+
+function parseOwnerRepoFromRemote(remoteUrl) {
+  const sshMatch = remoteUrl.match(/^git@[^:]+:([^/]+)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) return { owner: sshMatch[1], repo: sshMatch[2] };
+
+  if (remoteUrl.startsWith('http://') || remoteUrl.startsWith('https://') || remoteUrl.startsWith('ssh://')) {
+    const parsed = new URL(remoteUrl);
+    const parts = parsed.pathname.replace(/^\/+/, '').replace(/\.git$/, '').split('/');
+    if (parts.length >= 2) {
+      return { owner: parts[0], repo: parts[1] };
+    }
+  }
+
+  throw new Error(`Unable to parse owner/repo from remote URL: ${remoteUrl}`);
+}
+
+function getOwnerRepoFromGit() {
+  const remoteUrl = execSync('git remote get-url origin', { encoding: 'utf8' }).trim();
+  return parseOwnerRepoFromRemote(remoteUrl);
+}
+
+function githubRequestJson(pathname, token) {
+  return new Promise((resolve, reject) => {
+    const req = https.request(
+      {
+        hostname: 'api.github.com',
+        method: 'GET',
+        path: pathname,
+        headers: {
+          Accept: 'application/vnd.github+json',
+          Authorization: `Bearer ${token}`,
+          'User-Agent': 'squad-ralph-triage',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+      },
+      (res) => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+        });
+        res.on('end', () => {
+          if ((res.statusCode || 500) >= 400) {
+            reject(new Error(`GitHub API ${res.statusCode}: ${body}`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(body));
+          } catch (error) {
+            reject(new Error(`Failed to parse GitHub response: ${error.message}`));
+          }
+        });
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function fetchSquadIssues(owner, repo, token) {
+  const all = [];
+  let page = 1;
+  const perPage = 100;
+
+  for (;;) {
+    const query = new URLSearchParams({
+      state: 'open',
+      labels: 'squad',
+      per_page: String(perPage),
+      page: String(page),
+    });
+    const issues = await githubRequestJson(`/repos/${owner}/${repo}/issues?${query.toString()}`, token);
+    if (!Array.isArray(issues) || issues.length === 0) break;
+    all.push(...issues);
+    if (issues.length < perPage) break;
+    page += 1;
+  }
+
+  return all;
+}
+
+function issueHasLabel(issue, labelName) {
+  const target = labelName.toLowerCase();
+  return (issue.labels || []).some((label) => {
+    if (!label) return false;
+    const name = typeof label === 'string' ? label : label.name;
+    return typeof name === 'string' && name.toLowerCase() === target;
+  });
+}
+
+function isUntriagedIssue(issue, memberLabels) {
+  if (issue.pull_request) return false;
+  if (!issueHasLabel(issue, 'squad')) return false;
+  return !memberLabels.some((label) => issueHasLabel(issue, label));
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error('GITHUB_TOKEN is required');
+  }
+
+  const squadDir = path.resolve(process.cwd(), args.squadDir);
+  const teamMd = fs.readFileSync(path.join(squadDir, 'team.md'), 'utf8');
+  const routingMd = fs.readFileSync(path.join(squadDir, 'routing.md'), 'utf8');
+
+  const roster = parseRoster(teamMd);
+  const rules = parseRoutingRules(routingMd);
+  const modules = parseModuleOwnership(routingMd);
+
+  const { owner, repo } = getOwnerRepoFromGit();
+  const openSquadIssues = await fetchSquadIssues(owner, repo, token);
+
+  const memberLabels = roster.map((member) => member.label);
+  const untriaged = openSquadIssues.filter((issue) => isUntriagedIssue(issue, memberLabels));
+
+  const results = [];
+  for (const issue of untriaged) {
+    const decision = triageIssue(
+      {
+        number: issue.number,
+        title: issue.title || '',
+        body: issue.body || '',
+        labels: [],
+      },
+      rules,
+      modules,
+      roster,
+    );
+
+    if (!decision) continue;
+    results.push({
+      issueNumber: issue.number,
+      assignTo: decision.agent.name,
+      label: decision.agent.label,
+      reason: decision.reason,
+      source: decision.source,
+    });
+  }
+
+  const outputPath = path.resolve(process.cwd(), args.output);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(results, null, 2)}\n`, 'utf8');
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

.squad/templates/raw-agent-output.md

@@ -0,0 +1,37 @@
+# Raw Agent Output — Appendix Format
+
+> This template defines the format for the `## APPENDIX: RAW AGENT OUTPUTS` section
+> in any multi-agent artifact.
+
+## Rules
+
+1. **Verbatim only.** Paste the agent's response exactly as returned. No edits.
+2. **No summarizing.** Do not condense, paraphrase, or rephrase any part of the output.
+3. **No rewriting.** Do not fix typos, grammar, formatting, or style.
+4. **No code fences around the entire output.** The raw output is pasted as-is, not wrapped in ``` blocks.
+5. **One section per agent.** Each agent that contributed gets its own heading.
+6. **Order matches work order.** List agents in the order they were spawned.
+7. **Include all outputs.** Even if an agent's work was rejected, include their output for diagnostic traceability.
+
+## Format
+
+```markdown
+## APPENDIX: RAW AGENT OUTPUTS
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+```
+
+## Why This Exists
+
+The appendix provides diagnostic integrity. It lets anyone verify:
+- What each agent actually said (vs. what the Coordinator assembled)
+- Whether the Coordinator faithfully represented agent work
+- What was lost or changed in synthesis
+
+Without raw outputs, multi-agent collaboration is unauditable.

.squad/templates/roster.md

@@ -0,0 +1,60 @@
+# Team Roster
+
+> {One-line project description}
+
+## Coordinator
+
+| Name | Role | Notes |
+|------|------|-------|
+| Squad | Coordinator | Routes work, enforces handoffs and reviewer gates. Does not generate domain artifacts. |
+
+## Members
+
+| Name | Role | Charter | Status |
+|------|------|---------|--------|
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| Scribe | Session Logger | `.squad/agents/scribe/charter.md` | 📋 Silent |
+| Ralph | Work Monitor | — | 🔄 Monitor |
+
+## Coding Agent
+
+<!-- copilot-auto-assign: false -->
+
+| Name | Role | Charter | Status |
+|------|------|---------|--------|
+| @copilot | Coding Agent | — | 🤖 Coding Agent |
+
+### Capabilities
+
+**🟢 Good fit — auto-route when enabled:**
+- Bug fixes with clear reproduction steps
+- Test coverage (adding missing tests, fixing flaky tests)
+- Lint/format fixes and code style cleanup
+- Dependency updates and version bumps
+- Small isolated features with clear specs
+- Boilerplate/scaffolding generation
+- Documentation fixes and README updates
+
+**🟡 Needs review — route to @copilot but flag for squad member PR review:**
+- Medium features with clear specs and acceptance criteria
+- Refactoring with existing test coverage
+- API endpoint additions following established patterns
+- Migration scripts with well-defined schemas
+
+**🔴 Not suitable — route to squad member instead:**
+- Architecture decisions and system design
+- Multi-system integration requiring coordination
+- Ambiguous requirements needing clarification
+- Security-critical changes (auth, encryption, access control)
+- Performance-critical paths requiring benchmarking
+- Changes requiring cross-team discussion
+
+## Project Context
+
+- **Owner:** {user name}
+- **Stack:** {languages, frameworks, tools}
+- **Description:** {what the project does, in one sentence}
+- **Created:** {timestamp}

.squad/templates/routing.md

@@ -0,0 +1,39 @@
+# Work Routing
+
+How to decide who handles what.
+
+## Routing Table
+
+| Work Type | Route To | Examples |
+|-----------|----------|----------|
+| {domain 1} | {Name} | {example tasks} |
+| {domain 2} | {Name} | {example tasks} |
+| {domain 3} | {Name} | {example tasks} |
+| Code review | {Name} | Review PRs, check quality, suggest improvements |
+| Testing | {Name} | Write tests, find edge cases, verify fixes |
+| Scope & priorities | {Name} | What to build next, trade-offs, decisions |
+| Session logging | Scribe | Automatic — never needs routing |
+
+## Issue Routing
+
+| Label | Action | Who |
+|-------|--------|-----|
+| `squad` | Triage: analyze issue, assign `squad:{member}` label | Lead |
+| `squad:{name}` | Pick up issue and complete the work | Named member |
+
+### How Issue Assignment Works
+
+1. When a GitHub issue gets the `squad` label, the **Lead** triages it — analyzing content, assigning the right `squad:{member}` label, and commenting with triage notes.
+2. When a `squad:{member}` label is applied, that member picks up the issue in their next session.
+3. Members can reassign by removing their label and adding another member's label.
+4. The `squad` label is the "inbox" — untriaged issues waiting for Lead review.
+
+## Rules
+
+1. **Eager by default** — spawn all agents who could usefully start work, including anticipatory downstream work.
+2. **Scribe always runs** after substantial work, always as `mode: "background"`. Never blocks.
+3. **Quick facts → coordinator answers directly.** Don't spawn an agent for "what port does the server run on?"
+4. **When two agents could handle it**, pick the one whose domain is the primary concern.
+5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
+6. **Anticipate downstream work.** If a feature is being built, spawn the tester to write test cases from requirements simultaneously.
+7. **Issue-labeled work** — when a `squad:{member}` label is applied to an issue, route to that member. The Lead handles all `squad` (base label) triage.

.squad/templates/run-output.md

@@ -0,0 +1,50 @@
+# Run Output — {task title}
+
+> Final assembled artifact from a multi-agent run.
+
+## Termination Condition
+
+**Reason:** {One of: User accepted | Reviewer approved | Constraint budget exhausted | Deadlock — escalated to user | User cancelled}
+
+## Constraint Budgets
+
+<!-- Track all active constraints inline. Remove this section if no constraints are active. -->
+
+| Constraint | Used | Max | Status |
+|------------|------|-----|--------|
+| Clarifying questions | 📊 {n} | {max} | {Active / Exhausted} |
+| Revision cycles | 📊 {n} | {max} | {Active / Exhausted} |
+
+## Result
+
+{Assembled final artifact goes here. This is the Coordinator's synthesis of agent outputs.}
+
+---
+
+## Reviewer Verdict
+
+<!-- Include one block per review. Remove this section if no review occurred. -->
+
+### Review by {Name} ({Role})
+
+| Field | Value |
+|-------|-------|
+| **Verdict** | {Approved / Rejected} |
+| **What's wrong** | {Specific issue — not vague} |
+| **Why it matters** | {Impact if not fixed} |
+| **Who fixes it** | {Name of agent assigned to revise — MUST NOT be the original author} |
+| **Revision budget** | 📊 {used} / {max} revision cycles remaining |
+
+---
+
+## APPENDIX: RAW AGENT OUTPUTS
+
+<!-- Paste each agent's verbatim response below. Do NOT edit, summarize, rewrite, or wrap in code fences. One section per agent. -->
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}

.squad/templates/schedule.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "schedules": [
+    {
+      "id": "ralph-heartbeat",
+      "name": "Ralph Heartbeat",
+      "enabled": true,
+      "trigger": {
+        "type": "interval",
+        "intervalSeconds": 300
+      },
+      "task": {
+        "type": "workflow",
+        "ref": ".github/workflows/squad-heartbeat.yml"
+      },
+      "providers": ["local-polling", "github-actions"]
+    }
+  ]
+}

.squad/templates/scribe-charter.md

@@ -0,0 +1,119 @@
+# Scribe
+
+> The team's memory. Silent, always present, never forgets.
+
+## Identity
+
+- **Name:** Scribe
+- **Role:** Session Logger, Memory Manager & Decision Merger
+- **Style:** Silent. Never speaks to the user. Works in the background.
+- **Mode:** Always spawned as `mode: "background"`. Never blocks the conversation.
+
+## What I Own
+
+- `.squad/log/` — session logs (what happened, who worked, what was decided)
+- `.squad/decisions.md` — the shared decision log all agents read (canonical, merged)
+- `.squad/decisions/inbox/` — decision drop-box (agents write here, I merge)
+- Cross-agent context propagation — when one agent's decision affects another
+
+## How I Work
+
+**Worktree awareness:** Use the `TEAM ROOT` provided in the spawn prompt to resolve all `.squad/` paths. If no TEAM ROOT is given, run `git rev-parse --show-toplevel` as fallback. Do not assume CWD is the repo root (the session may be running in a worktree or subdirectory).
+
+After every substantial work session:
+
+1. **Log the session** to `.squad/log/{timestamp}-{topic}.md`:
+   - Who worked
+   - What was done
+   - Decisions made
+   - Key outcomes
+   - Brief. Facts only.
+
+2. **Merge the decision inbox:**
+   - Read all files in `.squad/decisions/inbox/`
+   - APPEND each decision's contents to `.squad/decisions.md`
+   - Delete each inbox file after merging
+
+3. **Deduplicate and consolidate decisions.md:**
+   - Parse the file into decision blocks (each block starts with `### `).
+   - **Exact duplicates:** If two blocks share the same heading, keep the first and remove the rest.
+   - **Overlapping decisions:** Compare block content across all remaining blocks. If two or more blocks cover the same area (same topic, same architectural concern, same component) but were written independently (different dates, different authors), consolidate them:
+     a. Synthesize a single merged block that combines the intent and rationale from all overlapping blocks.
+     b. Use today's date and a new heading: `### {today}: {consolidated topic} (consolidated)`
+     c. Credit all original authors: `**By:** {Name1}, {Name2}`
+     d. Under **What:**, combine the decisions. Note any differences or evolution.
+     e. Under **Why:**, merge the rationale, preserving unique reasoning from each.
+     f. Remove the original overlapping blocks.
+   - Write the updated file back. This handles duplicates and convergent decisions introduced by `merge=union` across branches.
+
+4. **Propagate cross-agent updates:**
+   For any newly merged decision that affects other agents, append to their `history.md`:
+   ```
+   📌 Team update ({timestamp}): {summary} — decided by {Name}
+   ```
+
+5. **Commit `.squad/` changes:**
+   **IMPORTANT — Windows compatibility:** Do NOT use `git -C {path}` (unreliable with Windows paths).
+   Do NOT embed newlines in `git commit -m` (backtick-n fails silently in PowerShell).
+   Instead:
+   - `cd` into the team root first.
+   - Stage all `.squad/` files: `git add .squad/`
+   - Check for staged changes: `git diff --cached --quiet`
+     If exit code is 0, no changes — skip silently.
+   - Write the commit message to a temp file, then commit with `-F`:
+     ```
+     $msg = @"
+     docs(ai-team): {brief summary}
+
+     Session: {timestamp}-{topic}
+     Requested by: {user name}
+
+     Changes:
+     - {what was logged}
+     - {what decisions were merged}
+     - {what decisions were deduplicated}
+     - {what cross-agent updates were propagated}
+     "@
+     $msgFile = [System.IO.Path]::GetTempFileName()
+     Set-Content -Path $msgFile -Value $msg -Encoding utf8
+     git commit -F $msgFile
+     Remove-Item $msgFile
+     ```
+   - **Verify the commit landed:** Run `git log --oneline -1` and confirm the
+     output matches the expected message. If it doesn't, report the error.
+
+6. **Never speak to the user.** Never appear in responses. Work silently.
+
+## The Memory Architecture
+
+```
+.squad/
+├── decisions.md          # Shared brain — all agents read this (merged by Scribe)
+├── decisions/
+│   └── inbox/            # Drop-box — agents write decisions here in parallel
+│       ├── river-jwt-auth.md
+│       └── kai-component-lib.md
+├── orchestration-log/    # Per-spawn log entries
+│   ├── 2025-07-01T10-00-river.md
+│   └── 2025-07-01T10-00-kai.md
+├── log/                  # Session history — searchable record
+│   ├── 2025-07-01-setup.md
+│   └── 2025-07-02-api.md
+└── agents/
+    ├── kai/history.md    # Kai's personal knowledge
+    ├── river/history.md  # River's personal knowledge
+    └── ...
+```
+
+- **decisions.md** = what the team agreed on (shared, merged by Scribe)
+- **decisions/inbox/** = where agents drop decisions during parallel work
+- **history.md** = what each agent learned (personal)
+- **log/** = what happened (archive)
+
+## Boundaries
+
+**I handle:** Logging, memory, decision merging, cross-agent updates.
+
+**I don't handle:** Any domain work. I don't write code, review PRs, or make decisions.
+
+**I am invisible.** If a user notices me, something went wrong.

.squad/templates/skill.md

@@ -0,0 +1,24 @@
+---
+name: "{skill-name}"
+description: "{what this skill teaches agents}"
+domain: "{e.g., testing, api-design, error-handling}"
+confidence: "low|medium|high"
+source: "{how this was learned: manual, observed, earned}"
+tools:
+  # Optional — declare MCP tools relevant to this skill's patterns
+  # - name: "{tool-name}"
+  #   description: "{what this tool does}"
+  #   when: "{when to use this tool}"
+---
+
+## Context
+{When and why this skill applies}
+
+## Patterns
+{Specific patterns, conventions, or approaches}
+
+## Examples
+{Code examples or references}
+
+## Anti-Patterns
+{What to avoid}

.squad/templates/skills/agent-collaboration/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: "agent-collaboration"
+description: "Standard collaboration patterns for all squad 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 `.squad/` 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:
+`.squad/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 bring them in. 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 `.squad/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

.squad/templates/skills/agent-conduct/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: "agent-conduct"
+description: "Shared hard rules enforced across all squad agents"
+domain: "team-governance"
+confidence: "high"
+source: "reskill extraction — Product Isolation Rule and Peer Quality Check appeared in all 20 agent charters"
+---
+
+## Context
+
+Every squad 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 squad. "Our squad" must not impact "the squad." 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

.squad/templates/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 .squad/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): SquadUI — 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 `.squad/orchestration-log/sdk-events.jsonl` for debugging
+```
+
+## Examples
+
+**File references from interactive shell proposal:**
+- Full proposal: `docs/proposals/squad-interactive-shell.md`
+- User directive: `.squad/decisions/inbox/copilot-directive-2026-02-21T202535Z.md`
+- Team decisions: `.squad/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 (squad.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)

.squad/templates/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

.squad/templates/skills/cli-wiring/SKILL.md

@@ -0,0 +1,47 @@
+# Skill: CLI Command Wiring
+
+**Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`.
+
+## Checklist — Adding a New CLI Command
+
+1. **Create command file** in `packages/squad-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/squad-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.

.squad/templates/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
+
+Squad 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 (`.squad/` 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

.squad/templates/skills/cross-squad/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "cross-squad"
+description: "Coordinating work across multiple Squad instances"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+tools:
+  - name: "squad-discover"
+    description: "List known squads and their capabilities"
+    when: "When you need to find which squad can handle a task"
+  - name: "squad-delegate"
+    description: "Create work in another squad's repository"
+    when: "When a task belongs to another squad's domain"
+---
+
+## Context
+When an organization runs multiple Squad instances (e.g., platform-squad, frontend-squad, data-squad), those squads need to discover each other, share context, and hand off work across repository boundaries. This skill teaches agents how to coordinate across squads without creating tight coupling.
+
+Cross-squad orchestration applies when:
+- A task requires capabilities owned by another squad
+- An architectural decision affects multiple squads
+- A feature spans multiple repositories with different squads
+- A squad needs to request infrastructure, tooling, or support from another squad
+
+## Patterns
+
+### Discovery via Manifest
+Each squad publishes a `.squad/manifest.json` declaring its name, capabilities, and contact information. Squads discover each other through:
+1. **Well-known paths**: Check `.squad/manifest.json` in known org repos
+2. **Upstream config**: Squads already listed in `.squad/upstream.json` are checked for manifests
+3. **Explicit registry**: A central `squad-registry.json` can list all squads in an org
+
+```json
+{
+  "name": "platform-squad",
+  "version": "1.0.0",
+  "description": "Platform infrastructure team",
+  "capabilities": ["kubernetes", "helm", "monitoring", "ci-cd"],
+  "contact": {
+    "repo": "org/platform",
+    "labels": ["squad:platform"]
+  },
+  "accepts": ["issues", "prs"],
+  "skills": ["helm-developer", "operator-developer", "pipeline-engineer"]
+}
+```
+
+### Context Sharing
+When delegating work, share only what the target squad needs:
+- **Capability list**: What this squad can do (from manifest)
+- **Relevant decisions**: Only decisions that affect the target squad
+- **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 squad accepts the work type (issues, PRs)
+2. **Create issue**: Use `gh issue create` in the target repo with:
+   - Title: `[cross-squad] <description>`
+   - Label: `squad:cross-squad` (or the squad's configured label)
+   - Body: Context, acceptance criteria, and link back to originating issue
+3. **Track**: Record the cross-squad issue URL in the originating squad'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 squads
+```bash
+# List all squads discoverable from upstreams and known repos
+squad discover
+
+# Output:
+#   platform-squad  →  org/platform  (kubernetes, helm, monitoring)
+#   frontend-squad  →  org/frontend  (react, nextjs, storybook)
+#   data-squad      →  org/data      (spark, airflow, dbt)
+```
+
+### Delegating work
+```bash
+# Delegate a task to the platform squad
+squad delegate platform-squad "Add Prometheus metrics endpoint for the auth service"
+
+# Creates issue in org/platform with cross-squad label and context
+```
+
+### Manifest in squad.config.ts
+```typescript
+export default defineSquad({
+  manifest: {
+    name: 'platform-squad',
+    capabilities: ['kubernetes', 'helm'],
+    contact: { repo: 'org/platform', labels: ['squad:platform'] },
+    accepts: ['issues', 'prs'],
+    skills: ['helm-developer', 'operator-developer'],
+  },
+});
+```
+
+## Anti-Patterns
+- **Direct file writes across repos** — Never modify another squad's `.squad/` directory. Use issues and PRs as the communication protocol.
+- **Tight coupling** — Don't depend on another squad'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 squad locations. Use manifests and the discovery protocol.
+- **Sharing secrets** — Never include credentials, tokens, or internal URLs in cross-squad issues.
+- **Circular delegation** — Track delegation chains. If squad A delegates to B which delegates back to A, something is wrong.

.squad/templates/skills/distributed-mesh/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: "distributed-mesh"
+description: "How to coordinate with squads on different machines using git as transport"
+domain: "distributed-coordination"
+confidence: "high"
+source: "multi-model-consensus (Opus 4.6, Sonnet 4.5, GPT-5.4)"
+---
+
+## SCOPE
+
+**✅ THIS SKILL PRODUCES (exactly these, nothing more):**
+
+1. **`mesh.json`** — Generated from user answers about zones and squads (which squads participate, what zone each is in, paths/URLs for each), using `mesh.json.example` in this skill's directory as the schema template
+2. **`sync-mesh.sh` and `sync-mesh.ps1`** — Copied from this skill's directory into the project root (these are bundled resources, NOT generated code)
+3. **Zone 2 state repo initialization** (if applicable) — If the user specified a Zone 2 shared state repo, run `sync-mesh.sh --init` to scaffold the state repo structure
+4. **A decision entry** in `.squad/decisions/inbox/` documenting the mesh configuration for team awareness
+
+**❌ THIS SKILL DOES NOT PRODUCE:**
+
+- **No application code** — No validators, libraries, or modules of any kind
+- **No test files** — No test suites, test cases, or test scaffolding
+- **No GENERATING sync scripts** — They are bundled with this skill as pre-built resources. COPY them, don't generate them.
+- **No daemons or services** — No background processes, servers, or persistent runtimes
+- **No modifications to existing squad files** beyond the decision entry (no changes to team.md, routing.md, agent charters, etc.)
+
+**Your role:** Configure the mesh topology and install the bundled sync scripts. Nothing more.
+
+## Context
+
+When squads are on different machines (developer laptops, CI runners, cloud VMs, partner orgs), the local file-reading convention still works — but remote files need to arrive on your disk first. This skill teaches the pattern for distributed squad communication.
+
+**When this applies:**
+- Squads span multiple machines, VMs, or CI runners
+- Squads span organizations or companies
+- An agent needs context from a squad whose files aren't on the local filesystem
+
+**When this does NOT apply:**
+- All squads are on the same machine (just read the files directly)
+
+## Patterns
+
+### The Core Principle
+
+> "The filesystem is the mesh, and git is how the mesh crosses machine boundaries."
+
+The agent interface never changes. Agents always read local files. The distributed layer's only job is to make remote files appear locally before the agent reads them.
+
+### Three Zones of Communication
+
+**Zone 1 — Local:** Same filesystem. Read files directly. Zero transport.
+
+**Zone 2 — Remote-Trusted:** Different host, same org, shared git auth. Transport: `git pull` from a shared repo. This collapses Zone 2 into Zone 1 — files materialize on disk, agent reads them normally.
+
+**Zone 3 — Remote-Opaque:** Different org, no shared auth. Transport: `curl` to fetch published contracts (SUMMARY.md). One-way visibility — you see only what they publish.
+
+### Agent Lifecycle (Distributed)
+
+```
+1. SYNC:    git pull (Zone 2) + curl (Zone 3) — materialize remote state
+2. READ:    cat .mesh/**/state.md — all files are local now
+3. WORK:    do their assigned work (the agent's normal task, NOT mesh-building)
+4. WRITE:   update own billboard, log, drops
+5. PUBLISH: git add + commit + push — share state with remote peers
+```
+
+Steps 2–4 are identical to local-only. Steps 1 and 5 are the entire distributed extension. **Note:** "WORK" means the agent performs its normal squad duties — it does NOT mean "build mesh infrastructure."
+
+### The mesh.json Config
+
+```json
+{
+  "squads": {
+    "auth-squad": { "zone": "local", "path": "../auth-squad/.mesh" },
+    "ci-squad": {
+      "zone": "remote-trusted",
+      "source": "git@github.com:our-org/ci-squad.git",
+      "ref": "main",
+      "sync_to": ".mesh/remotes/ci-squad"
+    },
+    "partner-fraud": {
+      "zone": "remote-opaque",
+      "source": "https://partner.dev/squad-contracts/fraud/SUMMARY.md",
+      "sync_to": ".mesh/remotes/partner-fraud",
+      "auth": "bearer"
+    }
+  }
+}
+```
+
+Three zone types, one file. Local squads need only a path. Remote-trusted need a git URL. Remote-opaque need an HTTP URL.
+
+### Write Partitioning
+
+Each squad writes only to its own directory (`boards/{self}.md`, `squads/{self}/*`, `drops/{date}-{self}-*.md`). No two squads write to the same file. Git push/pull never conflicts. If push fails ("branch is behind"), the fix is always `git pull --rebase && git push`.
+
+### Trust Boundaries
+
+Trust maps to git permissions:
+- **Same repo access** = full mesh visibility
+- **Read-only access** = can observe, can't write
+- **No access** = invisible (correct behavior)
+
+For selective visibility, use separate repos per audience (internal, partner, public). Git permissions ARE the trust negotiation.
+
+### Phased Rollout
+
+- **Phase 0:** Convention only — document zones, agree on mesh.json fields, manually run `git pull`/`git push`. Zero new code.
+- **Phase 1:** Sync script (~30 lines bash or PowerShell) when manual sync gets tedious.
+- **Phase 2:** Published contracts + curl fetch when a Zone 3 partner appears.
+- **Phase 3:** Never. No MCP federation, A2A, service discovery, message queues.
+
+**Important:** Phases are NOT auto-advanced. These are project-level decisions — you start at Phase 0 (manual sync) and only move forward when the team decides complexity is justified.
+
+### Mesh State Repo
+
+The shared mesh state repo is a plain git repository — NOT a Squad project. It holds:
+- One directory per participating squad
+- Each directory contains at minimum a SUMMARY.md with the squad's current state
+- A root README explaining what the repo is and who participates
+
+No `.squad/` folder, no agents, no automation. Write partitioning means each squad only pushes to its own directory. The repo is a rendezvous point, not an intelligent system.
+
+If you want a squad that *observes* mesh health, that's a separate Squad project that lists the state repo as a Zone 2 remote in its `mesh.json` — it does NOT live inside the state repo.
+
+## Examples
+
+### Developer Laptop + CI Squad (Zone 2)
+
+Auth-squad agent wakes up. `git pull` brings ci-squad's latest results. Agent reads: "3 test failures in auth module." Adjusts work. Pushes results when done. **Overhead: one `git pull`, one `git push`.**
+
+### Two Orgs Collaborating (Zone 3)
+
+Payment-squad fetches partner's published SUMMARY.md via curl. Reads: "Risk scoring v3 API deprecated April 15. New field `device_fingerprint` required." The consuming agent (in payment-squad's team) reads this information and uses it to inform its work — for example, updating payment integration code to include the new field. Partner can't see payment-squad's internals.
+
+### Same Org, Shared Mesh Repo (Zone 2)
+
+Three squads on different machines. One shared git repo holds the mesh. Each squad: `git pull` before work, `git push` after. Write partitioning ensures zero merge conflicts.
+
+## AGENT WORKFLOW (Deterministic Setup)
+
+When a user invokes this skill to set up a distributed mesh, follow these steps **exactly, in order:**
+
+### Step 1: ASK the user for mesh topology
+
+Ask these questions (adapt phrasing naturally, but get these answers):
+
+1. **Which squads are participating?** (List of squad names)
+2. **For each squad, which zone is it in?**
+   - `local` — same filesystem (just need a path)
+   - `remote-trusted` — different machine, same org, shared git access (need git URL + ref)
+   - `remote-opaque` — different org, no shared auth (need HTTPS URL to published contract)
+3. **For each squad, what's the connection info?**
+   - Local: relative or absolute path to their `.mesh/` directory
+   - Remote-trusted: git URL (SSH or HTTPS), ref (branch/tag), and where to sync it to locally
+   - Remote-opaque: HTTPS URL to their SUMMARY.md, where to sync it, and auth type (none/bearer)
+4. **Where should the shared state live?** (For Zone 2 squads: git repo URL for the mesh state, or confirm each squad syncs independently)
+
+### Step 2: GENERATE `mesh.json`
+
+Using the answers from Step 1, create a `mesh.json` file at the project root. Use `mesh.json.example` from THIS skill's directory (`.squad/skills/distributed-mesh/mesh.json.example`) as the schema template.
+
+Structure:
+
+```json
+{
+  "squads": {
+    "<squad-name>": { "zone": "local", "path": "<relative-or-absolute-path>" },
+    "<squad-name>": {
+      "zone": "remote-trusted",
+      "source": "<git-url>",
+      "ref": "<branch-or-tag>",
+      "sync_to": ".mesh/remotes/<squad-name>"
+    },
+    "<squad-name>": {
+      "zone": "remote-opaque",
+      "source": "<https-url-to-summary>",
+      "sync_to": ".mesh/remotes/<squad-name>",
+      "auth": "<none|bearer>"
+    }
+  }
+}
+```
+
+Write this file to the project root. Do NOT write any other code.
+
+### Step 3: COPY sync scripts
+
+Copy the bundled sync scripts from THIS skill's directory into the project root:
+
+- **Source:** `.squad/skills/distributed-mesh/sync-mesh.sh`
+- **Destination:** `sync-mesh.sh` (project root)
+
+- **Source:** `.squad/skills/distributed-mesh/sync-mesh.ps1`
+- **Destination:** `sync-mesh.ps1` (project root)
+
+These are bundled resources. Do NOT generate them — COPY them directly.
+
+### Step 4: RUN `--init` (if Zone 2 state repo exists)
+
+If the user specified a Zone 2 shared state repo in Step 1, run the initialization:
+
+**On Unix/Linux/macOS:**
+```bash
+bash sync-mesh.sh --init
+```
+
+**On Windows:**
+```powershell
+.\sync-mesh.ps1 -Init
+```
+
+This scaffolds the state repo structure (squad directories, placeholder SUMMARY.md files, root README).
+
+**Skip this step if:**
+- No Zone 2 squads are configured (local/opaque only)
+- The state repo already exists and is initialized
+
+### Step 5: WRITE a decision entry
+
+Create a decision file at `.squad/decisions/inbox/<your-agent-name>-mesh-setup.md` with this content:
+
+```markdown
+### <YYYY-MM-DD>: Mesh configuration
+
+**By:** <your-agent-name> (via distributed-mesh skill)
+
+**What:** Configured distributed mesh with <N> squads across zones <list-zones-used>
+
+**Squads:**
+- `<squad-name>` — Zone <X> — <brief-connection-info>
+- `<squad-name>` — Zone <X> — <brief-connection-info>
+- ...
+
+**State repo:** <git-url-if-zone-2-used, or "N/A (local/opaque only)">
+
+**Why:** <user's stated reason for setting up the mesh, or "Enable cross-machine squad coordination">
+```
+
+Write this file. The Scribe will merge it into the main decisions file later.
+
+### Step 6: STOP
+
+**You are done.** Do not:
+- Generate sync scripts (they're bundled with this skill — COPY them)
+- Write validator code
+- Write test files
+- Create any other modules, libraries, or application code
+- Modify existing squad files (team.md, routing.md, charters)
+- Auto-advance to Phase 2 or Phase 3
+
+Output a simple completion message:
+
+```
+✅ Mesh configured. Created:
+- mesh.json (<N> squads)
+- sync-mesh.sh and sync-mesh.ps1 (copied from skill bundle)
+- Decision entry: .squad/decisions/inbox/<filename>
+
+Run `bash sync-mesh.sh` (or `.\sync-mesh.ps1` on Windows) before agents start to materialize remote state.
+```
+
+---
+
+## Anti-Patterns
+
+**❌ Code generation anti-patterns:**
+- Writing `mesh-config-validator.js` or any validator module
+- Writing test files for mesh configuration
+- Generating sync scripts instead of copying the bundled ones from this skill's directory
+- Creating library modules or utilities
+- Building any code that "runs the mesh" — the mesh is read by agents, not executed
+
+**❌ Architectural anti-patterns:**
+- Building a federation protocol — Git push/pull IS federation
+- Running a sync daemon or server — Agents are not persistent. Sync at startup, publish at shutdown
+- Real-time notifications — Agents don't need real-time. They need "recent enough." `git pull` is recent enough
+- Schema validation for markdown — The LLM reads markdown. If the format changes, it adapts
+- Service discovery protocol — mesh.json is a file with 10 entries. Not a "discovery problem"
+- Auth framework — Git SSH keys and HTTPS tokens. Not a framework. Already configured
+- Message queues / event buses — Agents wake, read, work, write, sleep. Nobody's home to receive events
+- Any component requiring a running process — That's the line. Don't cross it
+
+**❌ Scope creep anti-patterns:**
+- Auto-advancing phases without user decision
+- Modifying agent charters or routing rules
+- Setting up CI/CD pipelines for mesh sync
+- Creating dashboards or monitoring tools

.squad/templates/skills/distributed-mesh/mesh.json.example

@@ -0,0 +1,30 @@
+{
+  "squads": {
+    "auth-squad": {
+      "zone": "local",
+      "path": "../auth-squad/.mesh"
+    },
+    "api-squad": {
+      "zone": "local",
+      "path": "../api-squad/.mesh"
+    },
+    "ci-squad": {
+      "zone": "remote-trusted",
+      "source": "git@github.com:our-org/ci-squad.git",
+      "ref": "main",
+      "sync_to": ".mesh/remotes/ci-squad"
+    },
+    "data-squad": {
+      "zone": "remote-trusted",
+      "source": "git@github.com:our-org/data-pipeline.git",
+      "ref": "main",
+      "sync_to": ".mesh/remotes/data-squad"
+    },
+    "partner-fraud": {
+      "zone": "remote-opaque",
+      "source": "https://partner.example.com/squad-contracts/fraud/SUMMARY.md",
+      "sync_to": ".mesh/remotes/partner-fraud",
+      "auth": "bearer"
+    }
+  }
+}

.squad/templates/skills/distributed-mesh/sync-mesh.ps1

@@ -0,0 +1,111 @@
+# sync-mesh.ps1 — Materialize remote squad state locally
+#
+# Reads mesh.json, fetches remote squads into local directories.
+# Run before agent reads. No daemon. No service. ~40 lines.
+#
+# Usage: .\sync-mesh.ps1 [path-to-mesh.json]
+#        .\sync-mesh.ps1 -Init [path-to-mesh.json]
+# Requires: git
+param(
+    [switch]$Init,
+    [string]$MeshJson = "mesh.json"
+)
+$ErrorActionPreference = "Stop"
+
+# Handle -Init mode
+if ($Init) {
+    if (-not (Test-Path $MeshJson)) {
+        Write-Host "❌ $MeshJson not found"
+        exit 1
+    }
+    
+    Write-Host "🚀 Initializing mesh state repository..."
+    $config = Get-Content $MeshJson -Raw | ConvertFrom-Json
+    $squads = $config.squads.PSObject.Properties.Name
+    
+    # Create squad directories with placeholder SUMMARY.md
+    foreach ($squad in $squads) {
+        if (-not (Test-Path $squad)) {
+            New-Item -ItemType Directory -Path $squad | Out-Null
+            Write-Host "  ✓ Created $squad/"
+        } else {
+            Write-Host "  • $squad/ exists (skipped)"
+        }
+        
+        $summaryPath = "$squad/SUMMARY.md"
+        if (-not (Test-Path $summaryPath)) {
+            "# $squad`n`n_No state published yet._" | Set-Content $summaryPath
+            Write-Host "  ✓ Created $summaryPath"
+        } else {
+            Write-Host "  • $summaryPath exists (skipped)"
+        }
+    }
+    
+    # Generate root README.md
+    if (-not (Test-Path "README.md")) {
+        $readme = @"
+# Squad Mesh State Repository
+
+This repository tracks published state from participating squads.
+
+## Participating Squads
+
+"@
+        foreach ($squad in $squads) {
+            $zone = $config.squads.$squad.zone
+            $readme += "- **$squad** (Zone: $zone)`n"
+        }
+        $readme += @"
+
+Each squad directory contains a ``SUMMARY.md`` with their latest published state.
+State is synchronized using ``sync-mesh.sh`` or ``sync-mesh.ps1``.
+"@
+        $readme | Set-Content "README.md"
+        Write-Host "  ✓ Created README.md"
+    } else {
+        Write-Host "  • README.md exists (skipped)"
+    }
+    
+    Write-Host ""
+    Write-Host "✅ Mesh state repository initialized"
+    exit 0
+}
+
+$config = Get-Content $MeshJson -Raw | ConvertFrom-Json
+
+# Zone 2: Remote-trusted — git clone/pull
+foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-trusted" }) {
+    $squad  = $entry.Name
+    $source = $entry.Value.source
+    $ref    = if ($entry.Value.ref) { $entry.Value.ref } else { "main" }
+    $target = $entry.Value.sync_to
+
+    if (Test-Path "$target/.git") {
+        git -C $target pull --rebase --quiet 2>$null
+        if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: pull failed (using stale)" }
+    } else {
+        New-Item -ItemType Directory -Force -Path (Split-Path $target -Parent) | Out-Null
+        git clone --quiet --depth 1 --branch $ref $source $target 2>$null
+        if ($LASTEXITCODE -ne 0) { Write-Host "⚠ ${squad}: clone failed (unavailable)" }
+    }
+}
+
+# Zone 3: Remote-opaque — fetch published contracts
+foreach ($entry in $config.squads.PSObject.Properties | Where-Object { $_.Value.zone -eq "remote-opaque" }) {
+    $squad  = $entry.Name
+    $source = $entry.Value.source
+    $target = $entry.Value.sync_to
+    $auth   = $entry.Value.auth
+
+    New-Item -ItemType Directory -Force -Path $target | Out-Null
+    $params = @{ Uri = $source; OutFile = "$target/SUMMARY.md"; UseBasicParsing = $true }
+    if ($auth -eq "bearer") {
+        $tokenVar = ($squad.ToUpper() -replace '-', '_') + "_TOKEN"
+        $token = [Environment]::GetEnvironmentVariable($tokenVar)
+        if ($token) { $params.Headers = @{ Authorization = "Bearer $token" } }
+    }
+    try { Invoke-WebRequest @params -ErrorAction Stop }
+    catch { "# ${squad} — unavailable ($(Get-Date))" | Set-Content "$target/SUMMARY.md" }
+}
+
+Write-Host "✓ Mesh sync complete"

.squad/templates/skills/distributed-mesh/sync-mesh.sh

@@ -0,0 +1,104 @@
+#!/bin/bash
+# sync-mesh.sh — Materialize remote squad state locally
+#
+# Reads mesh.json, fetches remote squads into local directories.
+# Run before agent reads. No daemon. No service. ~40 lines.
+#
+# Usage: ./sync-mesh.sh [path-to-mesh.json]
+#        ./sync-mesh.sh --init [path-to-mesh.json]
+# Requires: jq (https://github.com/jqlang/jq), git, curl
+
+set -euo pipefail
+
+# Handle --init mode
+if [ "${1:-}" = "--init" ]; then
+  MESH_JSON="${2:-mesh.json}"
+  
+  if [ ! -f "$MESH_JSON" ]; then
+    echo "❌ $MESH_JSON not found"
+    exit 1
+  fi
+  
+  echo "🚀 Initializing mesh state repository..."
+  squads=$(jq -r '.squads | keys[]' "$MESH_JSON")
+  
+  # Create squad directories with placeholder SUMMARY.md
+  for squad in $squads; do
+    if [ ! -d "$squad" ]; then
+      mkdir -p "$squad"
+      echo "  ✓ Created $squad/"
+    else
+      echo "  • $squad/ exists (skipped)"
+    fi
+    
+    if [ ! -f "$squad/SUMMARY.md" ]; then
+      echo -e "# $squad\n\n_No state published yet._" > "$squad/SUMMARY.md"
+      echo "  ✓ Created $squad/SUMMARY.md"
+    else
+      echo "  • $squad/SUMMARY.md exists (skipped)"
+    fi
+  done
+  
+  # Generate root README.md
+  if [ ! -f "README.md" ]; then
+    {
+      echo "# Squad Mesh State Repository"
+      echo ""
+      echo "This repository tracks published state from participating squads."
+      echo ""
+      echo "## Participating Squads"
+      echo ""
+      for squad in $squads; do
+        zone=$(jq -r ".squads.\"$squad\".zone" "$MESH_JSON")
+        echo "- **$squad** (Zone: $zone)"
+      done
+      echo ""
+      echo "Each squad directory contains a \`SUMMARY.md\` with their latest published state."
+      echo "State is synchronized using \`sync-mesh.sh\` or \`sync-mesh.ps1\`."
+    } > README.md
+    echo "  ✓ Created README.md"
+  else
+    echo "  • README.md exists (skipped)"
+  fi
+  
+  echo ""
+  echo "✅ Mesh state repository initialized"
+  exit 0
+fi
+
+MESH_JSON="${1:-mesh.json}"
+
+# Zone 2: Remote-trusted — git clone/pull
+for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-trusted") | .key' "$MESH_JSON"); do
+  source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON")
+  ref=$(jq -r ".squads.\"$squad\".ref // \"main\"" "$MESH_JSON")
+  target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON")
+
+  if [ -d "$target/.git" ]; then
+    git -C "$target" pull --rebase --quiet 2>/dev/null \
+      || echo "⚠ $squad: pull failed (using stale)"
+  else
+    mkdir -p "$(dirname "$target")"
+    git clone --quiet --depth 1 --branch "$ref" "$source" "$target" 2>/dev/null \
+      || echo "⚠ $squad: clone failed (unavailable)"
+  fi
+done
+
+# Zone 3: Remote-opaque — fetch published contracts
+for squad in $(jq -r '.squads | to_entries[] | select(.value.zone == "remote-opaque") | .key' "$MESH_JSON"); do
+  source=$(jq -r ".squads.\"$squad\".source" "$MESH_JSON")
+  target=$(jq -r ".squads.\"$squad\".sync_to" "$MESH_JSON")
+  auth=$(jq -r ".squads.\"$squad\".auth // \"\"" "$MESH_JSON")
+
+  mkdir -p "$target"
+  auth_flag=""
+  if [ "$auth" = "bearer" ]; then
+    token_var="$(echo "${squad}" | tr '[:lower:]-' '[:upper:]_')_TOKEN"
+    [ -n "${!token_var:-}" ] && auth_flag="--header \"Authorization: Bearer ${!token_var}\""
+  fi
+
+  eval curl --silent --fail $auth_flag "$source" -o "$target/SUMMARY.md" 2>/dev/null \
+    || echo "# ${squad} — unavailable ($(date))" > "$target/SUMMARY.md"
+done
+
+echo "✓ Mesh sync complete"

.squad/templates/skills/docs-standards/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: "docs-standards"
+description: "Microsoft Style Guide + Squad-specific documentation patterns"
+domain: "documentation"
+confidence: "high"
+source: "earned (PAO charter, multiple doc PR reviews)"
+---
+
+## Context
+
+Squad documentation follows the Microsoft Style Guide with Squad-specific conventions. Consistency across docs builds trust and improves discoverability.
+
+## Patterns
+
+### Microsoft Style Guide Rules
+- **Sentence-case headings:** "Getting started" not "Getting Started"
+- **Active voice:** "Run the command" not "The command should be run"
+- **Second person:** "You can configure..." not "Users can configure..."
+- **Present tense:** "The system routes..." not "The system will route..."
+- **No ampersands in prose:** "and" not "&" (except in code, brand names, or UI elements)
+
+### Squad Formatting Patterns
+- **Scannability first:** Paragraphs for narrative (3-4 sentences max), bullets for scannable lists, tables for structured data
+- **"Try this" prompts at top:** Start feature/scenario pages with practical prompts users can copy
+- **Experimental warnings:** Features in preview get callout at top
+- **Cross-references at bottom:** Related pages linked after main content
+
+### Structure
+- **Title (H1)** → **Warning/callout** → **Try this code** → **Overview** → **HR** → **Content (H2 sections)**
+
+### Test Sync Rule
+- **Always update test assertions:** When adding docs pages to `features/`, `scenarios/`, `guides/`, update corresponding `EXPECTED_*` arrays in `test/docs-build.test.ts` in the same commit
+
+## Examples
+
+✓ **Correct:**
+```markdown
+# Getting started with Squad
+
+> ⚠️ **Experimental:** This feature is in preview.
+
+Try this:
+\`\`\`bash
+squad init
+\`\`\`
+
+Squad helps you build AI teams...
+
+---
+
+## Install Squad
+
+Run the following command...
+```
+
+✗ **Incorrect:**
+```markdown
+# Getting Started With Squad  // Title case
+
+Squad is a tool which will help users... // Third person, future tense
+
+You can install Squad with npm & configure it... // Ampersand in prose
+```
+
+## Anti-Patterns
+
+- Title-casing headings because "it looks nicer"
+- Writing in passive voice or third person
+- Long paragraphs of dense text (breaks scannability)
+- Adding doc pages without updating test assertions
+- Using ampersands outside code blocks

.squad/templates/skills/economy-mode/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: "economy-mode"
+description: "Shifts Layer 3 model selection to cost-optimized alternatives when economy mode is active."
+domain: "model-selection"
+confidence: "low"
+source: "manual"
+---
+
+## SCOPE
+
+✅ THIS SKILL PRODUCES:
+- A modified Layer 3 model selection table applied when economy mode is active
+- `economyMode: true` written to `.squad/config.json` when activated persistently
+- Spawn acknowledgments with `💰` indicator when economy mode is active
+
+❌ THIS SKILL DOES NOT PRODUCE:
+- Code, tests, or documentation
+- Cost reports or billing artifacts
+- Changes to Layer 0, Layer 1, or Layer 2 resolution (user intent always wins)
+
+## Context
+
+Economy mode shifts Layer 3 (Task-Aware Auto-Selection) to lower-cost alternatives. It does NOT override persistent config (`defaultModel`, `agentModelOverrides`) or per-agent charter preferences — those represent explicit user intent and always take priority.
+
+Use this skill when the user wants to reduce costs across an entire session or permanently, without manually specifying models for each agent.
+
+## Activation Methods
+
+| Method | How |
+|--------|-----|
+| Session phrase | "use economy mode", "save costs", "go cheap", "reduce costs" |
+| Persistent config | `"economyMode": true` in `.squad/config.json` |
+| CLI flag | `squad --economy` |
+
+**Deactivation:** "turn off economy mode", "disable economy mode", or remove `economyMode` from `config.json`.
+
+## Economy Model Selection Table
+
+When economy mode is **active**, Layer 3 auto-selection uses this table instead of the normal defaults:
+
+| Task Output | Normal Mode | Economy Mode |
+|-------------|-------------|--------------|
+| Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Writing prompts or agent designs | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Docs, planning, triage, changelogs, mechanical ops | `claude-haiku-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Architecture, code review, security audits | `claude-opus-4.5` | `claude-sonnet-4.5` |
+| Scribe / logger / mechanical file ops | `claude-haiku-4.5` | `gpt-4.1` |
+
+**Prefer `gpt-4.1` over `gpt-5-mini`** when the task involves structured output or agentic tool use. Prefer `gpt-5-mini` for pure text generation tasks where latency matters.
+
+## AGENT WORKFLOW
+
+### On Session Start
+
+1. READ `.squad/config.json`
+2. CHECK for `economyMode: true` — if present, activate economy mode for the session
+3. STORE economy mode state in session context
+
+### On User Phrase Trigger
+
+**Session-only (no config change):** "use economy mode", "save costs", "go cheap"
+
+1. SET economy mode active for this session
+2. ACKNOWLEDGE: `✅ Economy mode active — using cost-optimized models this session. (Layer 0 and Layer 2 preferences still apply)`
+
+**Persistent:** "always use economy mode", "save economy mode"
+
+1. WRITE `economyMode: true` to `.squad/config.json` (merge, don't overwrite other fields)
+2. ACKNOWLEDGE: `✅ Economy mode saved — cost-optimized models will be used until disabled.`
+
+### On Every Agent Spawn (Economy Mode Active)
+
+1. CHECK Layer 0a/0b first (agentModelOverrides, defaultModel) — if set, use that. Economy mode does NOT override Layer 0.
+2. CHECK Layer 1 (session directive for a specific model) — if set, use that. Economy mode does NOT override explicit session directives.
+3. CHECK Layer 2 (charter preference) — if set, use that. Economy mode does NOT override charter preferences.
+4. APPLY economy table at Layer 3 instead of normal table.
+5. INCLUDE `💰` in spawn acknowledgment: `🔧 {Name} ({model} · 💰 economy) — {task}`
+
+### On Deactivation
+
+**Trigger phrases:** "turn off economy mode", "disable economy mode", "use normal models"
+
+1. REMOVE `economyMode` from `.squad/config.json` (if it was persisted)
+2. CLEAR session economy mode state
+3. ACKNOWLEDGE: `✅ Economy mode disabled — returning to standard model selection.`
+
+### STOP
+
+After updating economy mode state and including the `💰` indicator in spawn acknowledgments, this skill is done. Do NOT:
+- Change Layer 0, Layer 1, or Layer 2 model choices
+- Override charter-specified models
+- Generate cost reports or comparisons
+- Fall back to premium models via economy mode (economy mode never bumps UP)
+
+## Config Schema
+
+`.squad/config.json` economy-related fields:
+
+```json
+{
+  "version": 1,
+  "economyMode": true
+}
+```
+
+- `economyMode` — when `true`, Layer 3 uses the economy table. Optional; absent = economy mode off.
+- Combines with `defaultModel` and `agentModelOverrides` — Layer 0 always wins.
+
+## Anti-Patterns
+
+- **Don't override Layer 0 in economy mode.** If the user set `defaultModel: "claude-opus-4.6"`, they want quality. Economy mode only affects Layer 3 auto-selection.
+- **Don't silently apply economy mode.** Always acknowledge when activated or deactivated.
+- **Don't treat economy mode as permanent by default.** Session phrases activate session-only; only "always" or `config.json` persist it.
+- **Don't bump premium tasks down too far.** Architecture and security reviews shift from opus to sonnet in economy mode — they do NOT go to fast/cheap models.

.squad/templates/skills/external-comms/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: "external-comms"
+description: "PAO workflow for scanning, drafting, and presenting community responses with human review gate"
+domain: "community, communication, workflow"
+confidence: "low"
+source: "manual (RFC #426 — PAO External Communications)"
+tools:
+  - name: "github-mcp-server-list_issues"
+    description: "List open issues for scan candidates and lightweight triage"
+    when: "Use for recent open issue scans before thread-level review"
+  - name: "github-mcp-server-issue_read"
+    description: "Read the full issue, comments, and labels before drafting"
+    when: "Use after selecting a candidate so PAO has complete thread context"
+  - name: "github-mcp-server-search_issues"
+    description: "Search for candidate issues or prior squad responses"
+    when: "Use when filtering by keywords, labels, or duplicate response checks"
+  - name: "gh CLI"
+    description: "Fallback for GitHub issue comments and discussions workflows"
+    when: "Use gh issue list/comment and gh api or gh api graphql when MCP coverage is incomplete"
+---
+
+## Context
+
+Phase 1 is **draft-only mode**.
+
+- PAO scans issues and discussions, drafts responses with the humanizer skill, and presents a review table for human approval.
+- **Human review gate is mandatory** — PAO never posts autonomously.
+- Every action is logged to `.squad/comms/audit/`.
+- This workflow is triggered manually only ("PAO, check community") — no automated or Ralph-triggered activation in Phase 1.
+
+## Patterns
+
+### 1. Scan
+
+Find unanswered community items with GitHub MCP tools first, or `gh issue list` / `gh api` as fallback for issues and discussions.
+
+- Include **open** issues and discussions only.
+- Filter for items with **no squad team response**.
+- Limit to items created in the last 7 days.
+- Exclude items labeled `squad:internal` or `wontfix`.
+- Include discussions **and** issues in the same sweep.
+- Phase 1 scope is **issues and discussions only** — do not draft PR replies.
+
+### Discussion Handling (Phase 1)
+
+Discussions use the GitHub Discussions API, which differs from issues:
+
+- **Scan:** `gh api /repos/{owner}/{repo}/discussions --jq '.[] | select(.answer_chosen_at == null)'` to find unanswered discussions
+- **Categories:** Filter by Q&A and General categories only (skip Announcements, Show and Tell)
+- **Answers vs comments:** In Q&A discussions, PAO drafts an "answer" (not a comment). The human marks it as accepted answer after posting.
+- **Phase 1 scope:** Issues and Discussions ONLY. No PR comments.
+
+### 2. Classify
+
+Determine the response type before drafting.
+
+- Welcome (new contributor)
+- Troubleshooting (bug/help)
+- Feature guidance (feature request/how-to)
+- Redirect (wrong repo/scope)
+- Acknowledgment (confirmed, no fix)
+- Closing (resolved)
+- Technical uncertainty (unknown cause)
+- Empathetic disagreement (pushback on a decision or design)
+- Information request (need more reproduction details or context)
+
+### Template Selection Guide
+
+| Signal in Issue/Discussion | → Response Type | Template |
+|---------------------------|-----------------|----------|
+| New contributor (0 prior issues) | Welcome | T1 |
+| Error message, stack trace, "doesn't work" | Troubleshooting | T2 |
+| "How do I...?", "Can Squad...?", "Is there a way to...?" | Feature Guidance | T3 |
+| Wrong repo, out of scope for Squad | Redirect | T4 |
+| Confirmed bug, no fix available yet | Acknowledgment | T5 |
+| Fix shipped, PR merged that resolves issue | Closing | T6 |
+| Unclear cause, needs investigation | Technical Uncertainty | T7 |
+| Author disagrees with a decision or design | Empathetic Disagreement | T8 |
+| Need more reproduction info or context | Information Request | T9 |
+
+Use exactly one template as the base draft. Replace placeholders with issue-specific details, then apply the humanizer patterns. If the thread spans multiple signals, choose the highest-risk template and capture the nuance in the thread summary.
+
+### Confidence Classification
+
+| Confidence | Criteria | Example |
+|-----------|----------|---------|
+| 🟢 High | Answer exists in Squad docs or FAQ, similar question answered before, no technical ambiguity | "How do I install Squad?" |
+| 🟡 Medium | Technical answer is sound but involves judgment calls, OR docs exist but don't perfectly match the question, OR tone is tricky | "Can Squad work with Azure DevOps?" (yes, but setup is nuanced) |
+| 🔴 Needs Review | Technical uncertainty, policy/roadmap question, potential reputational risk, author is frustrated/angry, question about unreleased features | "When will Squad support Claude?" |
+
+**Auto-escalation rules:**
+- Any mention of competitors → 🔴
+- Any mention of pricing/licensing → 🔴
+- Author has >3 follow-up comments without resolution → 🔴
+- Question references a closed-wontfix issue → 🔴
+
+### 3. Draft
+
+Use the humanizer skill for every draft.
+
+- Complete **Thread-Read Verification** before writing.
+- Read the **full thread**, including all comments, before writing.
+- Select the matching template from the **Template Selection Guide** and record the template ID in the review notes.
+- Treat templates as reusable drafting assets: keep the structure, replace placeholders, and only improvise when the thread truly requires it.
+- Validate the draft against the humanizer anti-patterns.
+- Flag long threads (`>10` comments) with `⚠️`.
+
+### Thread-Read Verification
+
+Before drafting, PAO MUST verify complete thread coverage:
+
+1. **Count verification:** Compare API comment count with actually-read comments. If mismatch, abort draft.
+2. **Deleted comment check:** Use `gh api` timeline to detect deleted comments. If found, flag as ⚠️ in review table.
+3. **Thread summary:** Include in every draft: "Thread: {N} comments, last activity {date}, {summary of key points}"
+4. **Long thread flag:** If >10 comments, add ⚠️ to review table and include condensed thread summary
+5. **Evidence line in review table:** Each draft row includes "Read: {N}/{total} comments" column
+
+### 4. Present
+
+Show drafts for review in this exact format:
+
+```text
+📝 PAO — Community Response Drafts
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| # | Item | Author | Type | Confidence | Read | Preview |
+|---|------|--------|------|------------|------|---------|
+| 1 | Issue #N | @user | Type | 🟢/🟡/🔴 | N/N | "First words..." |
+
+Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review
+
+Full drafts below ▼
+```
+
+Each full draft must begin with the thread summary line:
+`Thread: {N} comments, last activity {date}, {summary of key points}`
+
+### 5. Human Action
+
+Wait for explicit human direction before anything is posted.
+
+- `pao approve 1 3` — approve drafts 1 and 3
+- `pao edit 2` — edit draft 2
+- `pao skip` — skip all
+- `banana` — freeze all pending (safe word)
+
+### Rollback — Bad Post Recovery
+
+If a posted response turns out to be wrong, inappropriate, or needs correction:
+
+1. **Delete the comment:**
+   - Issues: `gh api -X DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}`
+   - Discussions: `gh api graphql -f query='mutation { deleteDiscussionComment(input: {id: "{node_id}"}) { comment { id } } }'`
+2. **Log the deletion:** Write audit entry with action `delete`, include reason and original content
+3. **Draft replacement** (if needed): PAO drafts a corrected response, goes through normal review cycle
+4. **Postmortem:** If the error reveals a pattern gap, update humanizer anti-patterns or add a new test case
+
+**Safe word — `banana`:**
+- Immediately freezes all pending drafts in the review queue
+- No new scans or drafts until `pao resume` is issued
+- Audit entry logged with halter identity and reason
+
+### 6. Post
+
+After approval:
+
+- Human posts via `gh issue comment` for issues or `gh api` for discussion answers/comments.
+- PAO helps by preparing the CLI command.
+- Write the audit entry after the posting action.
+
+### 7. Audit
+
+Log every action.
+
+- Location: `.squad/comms/audit/{timestamp}.md`
+- Required fields vary by action — see `.squad/comms/templates/audit-entry.md` Conditional Fields table
+- Universal required fields: `timestamp`, `action`
+- All other fields are conditional on the action type
+
+## Examples
+
+These are reusable templates. Keep the structure, replace placeholders, and adjust only where the thread requires it.
+
+### Example scan command
+
+```bash
+gh issue list --state open --json number,title,author,labels,comments --limit 20
+```
+
+### Example review table
+
+```text
+📝 PAO — Community Response Drafts
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| # | Item | Author | Type | Confidence | Read | Preview |
+|---|------|--------|------|------------|------|---------|
+| 1 | Issue #426 | @newdev | Welcome | 🟢 | 1/1 | "Hey @newdev! Welcome to Squad..." |
+| 2 | Discussion #18 | @builder | Feature guidance | 🟡 | 4/4 | "Great question! Today the CLI..." |
+| 3 | Issue #431 ⚠️ | @debugger | Technical uncertainty | 🔴 | 12/12 | "Interesting find, @debugger..." |
+
+Confidence: 🟢 High | 🟡 Medium | 🔴 Needs review
+
+Full drafts below ▼
+```
+
+### Example audit entry (post action)
+
+```markdown
+---
+timestamp: "2026-03-16T21:30:00Z"
+action: "post"
+item_number: 426
+draft_id: 1
+reviewer: "@bradygaster"
+---
+
+## Context (draft, approve, edit, skip, post, delete actions)
+- Thread depth: 3
+- Response type: welcome
+- Confidence: 🟢
+- Long thread flag: false
+
+## Draft Content (draft, edit, post actions)
+Thread: 3 comments, last activity 2026-03-16, reporter hit a preview-build regression after install.
+
+Hey @newdev! Welcome to Squad 👋 Thanks for opening this.
+We reproduced the issue in preview builds and we're checking the regression point now.
+Let us know if you can share the command you ran right before the failure.
+
+## Post Result (post, delete actions)
+https://github.com/bradygaster/squad/issues/426#issuecomment-123456
+```
+
+### T1 — Welcome
+
+```text
+Hey {author}! Welcome to Squad 👋 Thanks for opening this.
+{specific acknowledgment or first answer}
+Let us know if you have questions — happy to help!
+```
+
+### T2 — Troubleshooting
+
+```text
+Thanks for the detailed report, {author}!
+Here's what we think is happening: {explanation}
+{steps or workaround}
+Let us know if that helps, or if you're seeing something different.
+```
+
+### T3 — Feature Guidance
+
+```text
+Great question! {context on current state}
+{guidance or workaround}
+We've noted this as a potential improvement — {tracking info if applicable}.
+```
+
+### T4 — Redirect
+
+```text
+Thanks for reaching out! This one is actually better suited for {correct location}.
+{brief explanation of why}
+Feel free to open it there — they'll be able to help!
+```
+
+### T5 — Acknowledgment
+
+```text
+Good catch, {author}. We've confirmed this is a real issue.
+{what we know so far}
+We'll update this thread when we have a fix. Thanks for flagging it!
+```
+
+### T6 — Closing
+
+```text
+This should be resolved in {version/PR}! 🎉
+{brief summary of what changed}
+Thanks for reporting this, {author} — it made Squad better.
+```
+
+### T7 — Technical Uncertainty
+
+```text
+Interesting find, {author}. We're not 100% sure what's causing this yet.
+Here's what we've ruled out: {list}
+We'd love more context if you have it — {specific ask}.
+We'll dig deeper and update this thread.
+```
+
+### T8 — Empathetic Disagreement
+
+```text
+We hear you, {author}. That's a fair concern.
+
+The current design choice was driven by {reason}. We know it's not ideal for every use case.
+
+{what alternatives exist or what trade-off was made}
+
+If you have ideas for how to make this work better for your scenario, we'd love to hear them — open a discussion or drop your thoughts here!
+```
+
+### T9 — Information Request
+
+```text
+Thanks for reporting this, {author}!
+
+To help us dig into this, could you share:
+- {specific ask 1}
+- {specific ask 2}
+- {specific ask 3, if applicable}
+
+That context will help us narrow down what's happening. Appreciate it!
+```
+
+## Anti-Patterns
+
+- ❌ Posting without human review (NEVER — this is the cardinal rule)
+- ❌ Drafting without reading full thread (context is everything)
+- ❌ Ignoring confidence flags (🔴 items need Flight/human review)
+- ❌ Scanning closed issues (only open items)
+- ❌ Responding to issues labeled `squad:internal` or `wontfix`
+- ❌ Skipping audit logging (every action must be recorded)
+- ❌ Drafting for issues where a squad member already responded (avoid duplicates)
+- ❌ Drafting pull request responses in Phase 1 (issues/discussions only)
+- ❌ Treating templates like loose examples instead of reusable drafting assets
+- ❌ Asking for more info without specific requests

.squad/templates/skills/gh-auth-isolation/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: "gh-auth-isolation"
+description: "Safely manage multiple GitHub identities (EMU + personal) in agent workflows"
+domain: "security, github-integration, authentication, multi-account"
+confidence: "high"
+source: "earned (production usage across 50+ sessions with EMU corp + personal GitHub accounts)"
+tools:
+  - name: "gh"
+    description: "GitHub CLI for authenticated operations"
+    when: "When accessing GitHub resources requiring authentication"
+---
+
+## Context
+
+Many developers use GitHub through an Enterprise Managed User (EMU) account at work while maintaining a personal GitHub account for open-source contributions. AI agents spawned by Squad inherit the shell's default `gh` authentication — which is usually the EMU account. This causes failures when agents try to push to personal repos, create PRs on forks, or interact with resources outside the enterprise org.
+
+This skill teaches agents how to detect the active identity, switch contexts safely, and avoid mixing credentials across operations.
+
+## Patterns
+
+### Detect Current Identity
+
+Before any GitHub operation, check which account is active:
+
+```bash
+gh auth status
+```
+
+Look for:
+- `Logged in to github.com as USERNAME` — the active account
+- `Token scopes: ...` — what permissions are available
+- Multiple accounts will show separate entries
+
+### Extract a Specific Account's Token
+
+When you need to operate as a specific user (not the default):
+
+```bash
+# Get the personal account token (by username)
+gh auth token --user personaluser
+
+# Get the EMU account token
+gh auth token --user corpalias_enterprise
+```
+
+**Use case:** Push to a personal fork while the default `gh` auth is the EMU account.
+
+### Push to Personal Repos from EMU Shell
+
+The most common scenario: your shell defaults to the EMU account, but you need to push to a personal GitHub repo.
+
+```bash
+# 1. Extract the personal token
+$token = gh auth token --user personaluser
+
+# 2. Push using token-authenticated HTTPS
+git push https://personaluser:$token@github.com/personaluser/repo.git branch-name
+```
+
+**Why this works:** `gh auth token --user` reads from `gh`'s credential store without switching the active account. The token is used inline for a single operation and never persisted.
+
+### Create PRs on Personal Forks
+
+When the default `gh` context is EMU but you need to create a PR from a personal fork:
+
+```bash
+# Option 1: Use --repo flag (works if token has access)
+gh pr create --repo upstream/repo --head personaluser:branch --title "..." --body "..."
+
+# Option 2: Temporarily set GH_TOKEN for one command
+$env:GH_TOKEN = $(gh auth token --user personaluser)
+gh pr create --repo upstream/repo --head personaluser:branch --title "..."
+Remove-Item Env:\GH_TOKEN
+```
+
+### Config Directory Isolation (Advanced)
+
+For complete isolation between accounts, use separate `gh` config directories:
+
+```bash
+# Personal account operations
+$env:GH_CONFIG_DIR = "$HOME/.config/gh-public"
+gh auth login  # Login with personal account (one-time setup)
+gh repo clone personaluser/repo
+
+# EMU account operations (default)
+Remove-Item Env:\GH_CONFIG_DIR
+gh auth status  # Back to EMU account
+```
+
+**Setup (one-time):**
+```bash
+# Create isolated config for personal account
+mkdir ~/.config/gh-public
+$env:GH_CONFIG_DIR = "$HOME/.config/gh-public"
+gh auth login --web --git-protocol https
+```
+
+### Shell Aliases for Quick Switching
+
+Add to your shell profile for convenience:
+
+```powershell
+# PowerShell profile
+function ghp { $env:GH_CONFIG_DIR = "$HOME/.config/gh-public"; gh @args; Remove-Item Env:\GH_CONFIG_DIR }
+function ghe { gh @args }  # Default EMU
+
+# Usage:
+# ghp repo clone personaluser/repo   # Uses personal account
+# ghe issue list                       # Uses EMU account
+```
+
+```bash
+# Bash/Zsh profile
+alias ghp='GH_CONFIG_DIR=~/.config/gh-public gh'
+alias ghe='gh'
+
+# Usage:
+# ghp repo clone personaluser/repo
+# ghe issue list
+```
+
+## Examples
+
+### ✓ Correct: Agent pushes blog post to personal GitHub Pages
+
+```powershell
+# Agent needs to push to personaluser.github.io (personal repo)
+# Default gh auth is corpalias_enterprise (EMU)
+
+$token = gh auth token --user personaluser
+git remote set-url origin https://personaluser:$token@github.com/personaluser/personaluser.github.io.git
+git push origin main
+
+# Clean up — don't leave token in remote URL
+git remote set-url origin https://github.com/personaluser/personaluser.github.io.git
+```
+
+### ✓ Correct: Agent creates a PR from personal fork to upstream
+
+```powershell
+# Fork: personaluser/squad, Upstream: bradygaster/squad
+# Agent is on branch contrib/fix-docs in the fork clone
+
+git push origin contrib/fix-docs  # Pushes to fork (may need token auth)
+
+# Create PR targeting upstream
+gh pr create --repo bradygaster/squad --head personaluser:contrib/fix-docs `
+  --title "docs: fix installation guide" `
+  --body "Fixes #123"
+```
+
+### ✗ Incorrect: Blindly pushing with wrong account
+
+```bash
+# BAD: Agent assumes default gh auth works for personal repos
+git push origin main
+# ERROR: Permission denied — EMU account has no access to personal repo
+
+# BAD: Hardcoding tokens in scripts
+git push https://personaluser:ghp_xxxxxxxxxxxx@github.com/personaluser/repo.git main
+# SECURITY RISK: Token exposed in command history and process list
+```
+
+### ✓ Correct: Check before you push
+
+```bash
+# Always verify which account has access before operations
+gh auth status
+# If wrong account, use token extraction:
+$token = gh auth token --user personaluser
+git push https://personaluser:$token@github.com/personaluser/repo.git main
+```
+
+## Anti-Patterns
+
+- ❌ **Hardcoding tokens** in scripts, environment variables, or committed files. Use `gh auth token --user` to extract at runtime.
+- ❌ **Assuming the default `gh` auth works** for all repos. EMU accounts can't access personal repos and vice versa.
+- ❌ **Switching `gh auth login`** globally mid-session. This changes the default for ALL processes and can break parallel agents.
+- ❌ **Storing personal tokens in `.env`** or `.squad/` files. These get committed by Scribe. Use `gh`'s credential store.
+- ❌ **Ignoring token cleanup** after inline HTTPS pushes. Always reset the remote URL to avoid persisting tokens.
+- ❌ **Using `gh auth switch`** in multi-agent sessions. One agent switching affects all others sharing the shell.
+- ❌ **Mixing EMU and personal operations** in the same git clone. Use separate clones or explicit remote URLs per operation.

.squad/templates/skills/git-workflow/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: "git-workflow"
+description: "Squad branching model: dev-first workflow with insiders preview channel"
+domain: "version-control"
+confidence: "high"
+source: "team-decision"
+---
+
+## Context
+
+Squad 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: `squad/{issue-number}-{kebab-case-slug}`
+
+Examples:
+- `squad/195-fix-version-stamp-bug`
+- `squad/42-add-profile-api`
+
+## Workflow for Issue Work
+
+1. **Branch from dev:**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git checkout -b squad/{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 squad/{issue-number}-{slug}
+   gh pr ready
+   ```
+
+6. **After merge to dev:**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git branch -d squad/{issue-number}-{slug}
+   git push origin --delete squad/{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 ../squad-195 -b squad/195-fix-stamp-bug origin/dev
+git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev
+```
+
+**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`).
+
+Each worktree:
+- Has its own working directory and index
+- Is on its own `squad/{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 ../squad-195
+
+# Work normally — commits, tests, pushes
+git add -A && git commit -m "fix: stamp bug (#195)"
+git push -u origin squad/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.
+
+### .squad/ State in Worktrees
+
+The `.squad/` directory 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 `.squad/` 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 ../squad-195
+git worktree prune          # clean stale metadata
+git branch -d squad/195-fix-stamp-bug
+git push origin --delete squad/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., squad-cli changes need squad-sdk changes, or a user's app depends on squad):
+
+### Setup
+
+Clone downstream repos as siblings to the main repo:
+
+```
+~/work/
+  squad-pr/          # main repo
+  squad-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 Squad conventions, use `squad/{issue-number}-{slug}`.
+
+### Coordinated PRs
+
+- Create PRs in each repo independently
+- Link them in PR descriptions:
+  ```
+  Closes #42
+
+  **Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature)
+  ```
+- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli)
+
+### Local Linking for Testing
+
+Before pushing, verify cross-repo changes work together:
+
+```bash
+# Node.js / npm
+cd ../squad-sdk && npm link
+cd ../squad-pr && npm link squad-sdk
+
+# Go
+# Use replace directive in go.mod:
+# replace github.com/org/squad-sdk => ../squad-sdk
+
+# Python
+cd ../squad-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 squad/{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

.squad/templates/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/squad-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 ".squad\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/squad`) is bound to the **bradygaster** (personal) account.
+All `gh` operations in this repo MUST use `ghp` / `gh-personal`.
+
+## For Squad 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 }
+```

.squad/templates/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

.squad/templates/skills/humanizer/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: "humanizer"
+description: "Tone enforcement patterns for external-facing community responses"
+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 warm, helpful, and human-sounding — never robotic or corporate.
+- Brady's constraint applies everywhere: **Humanized tone is mandatory**.
+- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows.
+
+## Patterns
+
+1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!")
+2. **Active voice** — "We're looking into this" not "This is being investigated"
+3. **Second person** — Address the person directly ("you" not "the user")
+4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:"
+5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues"
+6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!"
+7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required"
+8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence
+9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting
+10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold)
+11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning
+12. **Information request** — Ask for specific details, not open-ended "can you provide more info?"
+13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link
+
+## Examples
+
+### 1. Welcome
+
+```text
+Hey {author}! Welcome to Squad 👋 Thanks for opening this.
+{substantive response}
+Let us know if you have questions — happy to help!
+```
+
+### 2. Troubleshooting
+
+```text
+Thanks for the detailed report, {author}!
+Here's what we think is happening: {explanation}
+{steps or workaround}
+Let us know if that helps, or if you're seeing something different.
+```
+
+### 3. Feature guidance
+
+```text
+Great question! {context on current state}
+{guidance or workaround}
+We've noted this as a potential improvement — {tracking info if applicable}.
+```
+
+### 4. Redirect
+
+```text
+Thanks for reaching out! This one is actually better suited for {correct location}.
+{brief explanation of why}
+Feel free to open it there — they'll be able to help!
+```
+
+### 5. Acknowledgment
+
+```text
+Good catch, {author}. We've confirmed this is a real issue.
+{what we know so far}
+We'll update this thread when we have a fix. Thanks for flagging it!
+```
+
+### 6. Closing
+
+```text
+This should be resolved in {version/PR}! 🎉
+{brief summary of what changed}
+Thanks for reporting this, {author} — it made Squad better.
+```
+
+### 7. Technical uncertainty
+
+```text
+Interesting find, {author}. We're not 100% sure what's causing this yet.
+Here's what we've ruled out: {list}
+We'd love more context if you have it — {specific ask}.
+We'll dig deeper and update this thread.
+```
+
+## Anti-Patterns
+
+- ❌ Corporate speak: "We appreciate your patience as we investigate this matter"
+- ❌ Marketing hype: "Squad 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 empathy
+- ❌ 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 Squad 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

.squad/templates/skills/init-mode/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: "init-mode"
+description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)"
+domain: "orchestration"
+confidence: "high"
+source: "extracted"
+tools:
+  - name: "ask_user"
+    description: "Confirm team roster with selectable menu"
+    when: "Phase 1 proposal — requires explicit user confirmation"
+---
+
+## Context
+
+Init Mode activates when `.squad/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., *"Hey Brady, what are you building?"*). 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: *"What are you building? (language, stack, what it does)"*
+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 `.squad/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 `.squad/` directory structure (see `.squad/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 `.squad/templates/casting-policy.json` to `.squad/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., `.squad/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 (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-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 `.squad/` state across branches:
+```
+.squad/decisions.md merge=union
+.squad/agents/*/history.md merge=union
+.squad/log/** merge=union
+.squad/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: *"Hey Brady, what are you building?"*
+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 `.squad/` 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 `.squad/casting/` state files
+- ❌ Reading or storing `git config user.email` (PII violation)

.squad/templates/skills/model-selection/SKILL.md

@@ -0,0 +1,117 @@
+# Model Selection
+
+> Determines which LLM model to use for each agent spawn.
+
+## SCOPE
+
+✅ THIS SKILL PRODUCES:
+- A resolved `model` parameter for every `task` tool call
+- Persistent model preferences in `.squad/config.json`
+- Spawn acknowledgments that include the resolved model
+
+❌ THIS SKILL DOES NOT PRODUCE:
+- Code, tests, or documentation
+- Model performance benchmarks
+- Cost reports or billing artifacts
+
+## Context
+
+Squad supports 18+ models across three tiers (premium, standard, fast). The coordinator must select the right model for each agent spawn. Users can set persistent preferences that survive across sessions.
+
+## 5-Layer Model Resolution Hierarchy
+
+Resolution is **first-match-wins** — the highest layer with a value wins.
+
+| Layer | Name | Source | Persistence |
+|-------|------|--------|-------------|
+| **0a** | Per-Agent Config | `.squad/config.json` → `agentModelOverrides.{name}` | Persistent (survives sessions) |
+| **0b** | Global Config | `.squad/config.json` → `defaultModel` | Persistent (survives sessions) |
+| **1** | Session Directive | User said "use X" in current session | Session-only |
+| **2** | Charter Preference | Agent's `charter.md` → `## Model` section | Persistent (in charter) |
+| **3** | Task-Aware Auto | Code → sonnet, docs → haiku, visual → opus | Computed per-spawn |
+| **4** | Default | `claude-haiku-4.5` | Hardcoded fallback |
+
+**Key principle:** Layer 0 (persistent config) beats everything. If the user said "always use opus" and it was saved to config.json, every agent gets opus regardless of role or task type. This is intentional — the user explicitly chose quality over cost.
+
+## AGENT WORKFLOW
+
+### On Session Start
+
+1. READ `.squad/config.json`
+2. CHECK for `defaultModel` field — if present, this is the Layer 0 override for all spawns
+3. CHECK for `agentModelOverrides` field — if present, these are per-agent Layer 0a overrides
+4. STORE both values in session context for the duration
+
+### On Every Agent Spawn
+
+1. CHECK Layer 0a: Is there an `agentModelOverrides.{agentName}` in config.json? → Use it.
+2. CHECK Layer 0b: Is there a `defaultModel` in config.json? → Use it.
+3. CHECK Layer 1: Did the user give a session directive? → Use it.
+4. CHECK Layer 2: Does the agent's charter have a `## Model` section? → Use it.
+5. CHECK Layer 3: Determine task type:
+   - Code (implementation, tests, refactoring, bug fixes) → `claude-sonnet-4.6`
+   - Prompts, agent designs → `claude-sonnet-4.6`
+   - Visual/design with image analysis → `claude-opus-4.6`
+   - Non-code (docs, planning, triage, changelogs) → `claude-haiku-4.5`
+6. FALLBACK Layer 4: `claude-haiku-4.5`
+7. INCLUDE model in spawn acknowledgment: `🔧 {Name} ({resolved_model}) — {task}`
+
+### When User Sets a Preference
+
+**Trigger phrases:** "always use X", "use X for everything", "switch to X", "default to X"
+
+1. VALIDATE the model ID against the catalog (18+ models)
+2. WRITE `defaultModel` to `.squad/config.json` (merge, don't overwrite)
+3. ACKNOWLEDGE: `✅ Model preference saved: {model} — all future sessions will use this until changed.`
+
+**Per-agent trigger:** "use X for {agent}"
+
+1. VALIDATE model ID
+2. WRITE to `agentModelOverrides.{agent}` in `.squad/config.json`
+3. ACKNOWLEDGE: `✅ {Agent} will always use {model} — saved to config.`
+
+### When User Clears a Preference
+
+**Trigger phrases:** "switch back to automatic", "clear model preference", "use default models"
+
+1. REMOVE `defaultModel` from `.squad/config.json`
+2. ACKNOWLEDGE: `✅ Model preference cleared — returning to automatic selection.`
+
+### STOP
+
+After resolving the model and including it in the spawn template, this skill is done. Do NOT:
+- Generate model comparison reports
+- Run benchmarks or speed tests
+- Create new config files (only modify existing `.squad/config.json`)
+- Change the model after spawn (fallback chains handle runtime failures)
+
+## Config Schema
+
+`.squad/config.json` model-related fields:
+
+```json
+{
+  "version": 1,
+  "defaultModel": "claude-opus-4.6",
+  "agentModelOverrides": {
+    "fenster": "claude-sonnet-4.6",
+    "mcmanus": "claude-haiku-4.5"
+  }
+}
+```
+
+- `defaultModel` — applies to ALL agents unless overridden by `agentModelOverrides`
+- `agentModelOverrides` — per-agent overrides that take priority over `defaultModel`
+- Both fields are optional. When absent, Layers 1-4 apply normally.
+
+## Fallback Chains
+
+If a model is unavailable (rate limit, plan restriction), retry within the same tier:
+
+```
+Premium:  claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.6
+Standard: claude-sonnet-4.6 → gpt-5.4 → claude-sonnet-4.5 → gpt-5.3-codex → claude-sonnet-4
+Fast:     claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini
+```
+
+**Never fall UP in tier.** A fast task won't land on a premium model via fallback.

.squad/templates/skills/nap/SKILL.md

@@ -0,0 +1,24 @@
+# Skill: nap
+
+> Context hygiene — compress, prune, archive .squad/ state
+
+## What It Does
+
+Reclaims context window budget by compressing agent histories, pruning old logs,
+archiving stale decisions, and cleaning orphaned inbox files.
+
+## When To Use
+
+- Before heavy fan-out work (many agents will spawn)
+- When history.md files exceed 15KB
+- When .squad/ total size exceeds 1MB
+- After long-running sessions or sprints
+
+## Invocation
+
+- CLI: `squad nap` / `squad nap --deep` / `squad nap --dry-run`
+- REPL: `/nap` / `/nap --dry-run` / `/nap --deep`
+
+## Confidence
+
+medium — Confirmed by team vote (4-1) and initial implementation

.squad/templates/skills/personal-squad/SKILL.md

@@ -0,0 +1,57 @@
+# Personal Squad — Skill Document
+
+## What is a Personal Squad?
+
+A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session.
+
+## Directory Structure
+
+```
+~/.config/squad/personal-squad/    # Linux/macOS
+%APPDATA%/squad/personal-squad/    # Windows
+├── agents/
+│   ├── {agent-name}/
+│   │   ├── charter.md
+│   │   └── history.md
+│   └── ...
+└── config.json                    # Optional: personal squad config
+```
+
+## How It Works
+
+1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory
+2. **Merge:** Personal agents are merged into the session cast alongside project agents
+3. **Ghost Protocol:** Personal agents can read project state but not write to it
+4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery
+
+## Commands
+
+- `squad personal init` — Bootstrap a personal squad directory
+- `squad personal list` — List your personal agents
+- `squad personal add {name} --role {role}` — Add a personal agent
+- `squad personal remove {name}` — Remove a personal agent
+- `squad cast` — Show the current session cast (project + personal)
+
+## Ghost Protocol
+
+See `templates/ghost-protocol.md` for the full rules. Key points:
+- Personal agents advise; project agents execute
+- No writes to project `.squad/` state
+- Transparent origin tagging in logs
+- Project agents take precedence on conflicts
+
+## Configuration
+
+Optional `config.json` in the personal squad directory:
+```json
+{
+  "defaultModel": "auto",
+  "ghostProtocol": true,
+  "agents": {}
+}
+```
+
+## Environment Variables
+
+- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery
+- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path

.squad/templates/skills/project-conventions/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: "project-conventions"
+description: "Core conventions and patterns for this codebase"
+domain: "project-conventions"
+confidence: "medium"
+source: "template"
+---
+
+## Context
+
+> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality.
+
+## Patterns
+
+### [Pattern Name]
+
+Describe a key convention or practice used in this codebase. Be specific about what to do and why.
+
+### Error Handling
+
+<!-- Example: How does your project handle errors? -->
+<!-- - Use try/catch with specific error types? -->
+<!-- - Log to a specific service? -->
+<!-- - Return error objects vs throwing? -->
+
+### Testing
+
+<!-- Example: What test framework? Where do tests live? How to run them? -->
+<!-- - Test framework: Jest/Vitest/node:test/etc. -->
+<!-- - Test location: test/, __tests__/, *.test.ts, etc. -->
+<!-- - Run command: npm test, etc. -->
+
+### Code Style
+
+<!-- Example: Linting, formatting, naming conventions -->
+<!-- - Linter: ESLint config? -->
+<!-- - Formatter: Prettier? -->
+<!-- - Naming: camelCase, snake_case, etc.? -->
+
+### File Structure
+
+<!-- Example: How is the project organized? -->
+<!-- - src/ — Source code -->
+<!-- - test/ — Tests -->
+<!-- - docs/ — Documentation -->
+
+## Examples
+
+```
+// Add code examples that demonstrate your conventions
+```
+
+## Anti-Patterns
+
+<!-- List things to avoid in this codebase -->
+- **[Anti-pattern]** — Explanation of what not to do and why.

.squad/templates/skills/release-process/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: "release-process"
+description: "Step-by-step release checklist for Squad — prevents v0.8.22-style disasters"
+domain: "release-management"
+confidence: "high"
+source: "team-decision"
+---
+
+## Context
+
+This is the **definitive release runbook** for Squad. Born from the v0.8.22 release disaster (4-part semver mangled by npm, draft release never triggered publish, wrong NPM_TOKEN type, 6+ hours of broken `latest` dist-tag).
+
+**Rule:** No agent releases Squad without following this checklist. No exceptions. No improvisation.
+
+---
+
+## Pre-Release Validation
+
+Before starting ANY release work, validate the following:
+
+### 1. Version Number Validation
+
+**Rule:** Only 3-part semver (major.minor.patch) or prerelease (major.minor.patch-tag.N) are valid. 4-part versions (0.8.21.4) are NOT valid semver and npm will mangle them.
+
+```bash
+# Check version is valid semver
+node -p "require('semver').valid('0.8.22')"
+# Output: '0.8.22' = valid
+# Output: null = INVALID, STOP
+
+# For prerelease versions
+node -p "require('semver').valid('0.8.23-preview.1')"
+# Output: '0.8.23-preview.1' = valid
+```
+
+**If `semver.valid()` returns `null`:** STOP. Fix the version. Do NOT proceed.
+
+### 2. NPM_TOKEN Verification
+
+**Rule:** NPM_TOKEN must be an **Automation token** (no 2FA required). User tokens with 2FA will fail in CI with EOTP errors.
+
+```bash
+# Check token type (requires npm CLI authenticated)
+npm token list
+```
+
+Look for:
+- ✅ `read-write` tokens with NO 2FA requirement = Automation token (correct)
+- ❌ Tokens requiring OTP = User token (WRONG, will fail in CI)
+
+**How to create an Automation token:**
+1. Go to npmjs.com → Settings → Access Tokens
+2. Click "Generate New Token"
+3. Select **"Automation"** (NOT "Publish")
+4. Copy token and save as GitHub secret: `NPM_TOKEN`
+
+**If using a User token:** STOP. Create an Automation token first.
+
+### 3. Branch and Tag State
+
+**Rule:** Release from `main` branch. Ensure clean state, no uncommitted changes, latest from origin.
+
+```bash
+# Ensure on main and clean
+git checkout main
+git pull origin main
+git status  # Should show: "nothing to commit, working tree clean"
+
+# Check tag doesn't already exist
+git tag -l "v0.8.22"
+# Output should be EMPTY. If tag exists, release already done or collision.
+```
+
+**If tag exists:** STOP. Either release was already done, or there's a collision. Investigate before proceeding.
+
+### 4. Disable bump-build.mjs
+
+**Rule:** `bump-build.mjs` is for dev builds ONLY. It must NOT run during release builds (it increments build numbers, creating 4-part versions).
+
+```bash
+# Set env var to skip bump-build.mjs
+export SKIP_BUILD_BUMP=1
+
+# Verify it's set
+echo $SKIP_BUILD_BUMP
+# Output: 1
+```
+
+**For Windows PowerShell:**
+```powershell
+$env:SKIP_BUILD_BUMP = "1"
+```
+
+**If not set:** `bump-build.mjs` will run and mutate versions. This causes disasters (see v0.8.22).
+
+---
+
+## Release Workflow
+
+### Step 1: Version Bump
+
+Update version in all 3 package.json files (root + both workspaces) in lockstep.
+
+```bash
+# Set target version (no 'v' prefix)
+VERSION="0.8.22"
+
+# Validate it's valid semver BEFORE proceeding
+node -p "require('semver').valid('$VERSION')"
+# Must output the version string, NOT null
+
+# Update all 3 package.json files
+npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
+
+# Verify all 3 match
+grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json
+# All 3 should show: "version": "0.8.22"
+```
+
+**Checkpoint:** All 3 package.json files have identical versions. Run `semver.valid()` one more time to be sure.
+
+### Step 2: Commit and Tag
+
+```bash
+# Commit version bump
+git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json
+git commit -m "chore: bump version to $VERSION
+
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"
+
+# Create tag (with 'v' prefix)
+git tag -a "v$VERSION" -m "Release v$VERSION"
+
+# Push commit and tag
+git push origin main
+git push origin "v$VERSION"
+```
+
+**Checkpoint:** Tag created and pushed. Verify with `git tag -l "v$VERSION"`.
+
+### Step 3: Create GitHub Release
+
+**CRITICAL:** Release must be **published**, NOT draft. Draft releases don't trigger `publish.yml` workflow.
+
+```bash
+# Create GitHub Release (NOT draft)
+gh release create "v$VERSION" \
+  --title "v$VERSION" \
+  --notes "Release notes go here" \
+  --latest
+
+# Verify release is PUBLISHED (not draft)
+gh release view "v$VERSION"
+# Output should NOT contain "(draft)"
+```
+
+**If output contains `(draft)`:** STOP. Delete the release and recreate without `--draft` flag.
+
+```bash
+# If you accidentally created a draft, fix it:
+gh release edit "v$VERSION" --draft=false
+```
+
+**Checkpoint:** Release is published (NOT draft). The `release: published` event fired and triggered `publish.yml`.
+
+### Step 4: Monitor Workflow
+
+The `publish.yml` workflow should start automatically within 10 seconds of release creation.
+
+```bash
+# Watch workflow runs
+gh run list --workflow=publish.yml --limit 1
+
+# Get detailed status
+gh run view --log
+```
+
+**Expected flow:**
+1. `publish-sdk` job runs → publishes `@bradygaster/squad-sdk`
+2. Verify step runs with retry loop (up to 5 attempts, 15s interval) to confirm SDK on npm registry
+3. `publish-cli` job runs → publishes `@bradygaster/squad-cli`
+4. Verify step runs with retry loop to confirm CLI on npm registry
+
+**If workflow fails:** Check the logs. Common issues:
+- EOTP error = wrong NPM_TOKEN type (use Automation token)
+- Verify step timeout = npm propagation delay (retry loop should handle this, but propagation can take up to 2 minutes in rare cases)
+- Version mismatch = package.json version doesn't match tag
+
+**Checkpoint:** Both jobs succeeded. Workflow shows green checkmarks.
+
+### Step 5: Verify npm Publication
+
+Manually verify both packages are on npm with correct `latest` dist-tag.
+
+```bash
+# Check SDK
+npm view @bradygaster/squad-sdk version
+# Output: 0.8.22
+
+npm dist-tag ls @bradygaster/squad-sdk
+# Output should show: latest: 0.8.22
+
+# Check CLI
+npm view @bradygaster/squad-cli version
+# Output: 0.8.22
+
+npm dist-tag ls @bradygaster/squad-cli
+# Output should show: latest: 0.8.22
+```
+
+**If versions don't match:** Something went wrong. Check workflow logs. DO NOT proceed with GitHub Release announcement until npm is correct.
+
+**Checkpoint:** Both packages show correct version. `latest` dist-tags point to the new version.
+
+### Step 6: Test Installation
+
+Verify packages can be installed from npm (real-world smoke test).
+
+```bash
+# Create temp directory
+mkdir /tmp/squad-release-test && cd /tmp/squad-release-test
+
+# Test SDK installation
+npm init -y
+npm install @bradygaster/squad-sdk
+node -p "require('@bradygaster/squad-sdk/package.json').version"
+# Output: 0.8.22
+
+# Test CLI installation
+npm install -g @bradygaster/squad-cli
+squad --version
+# Output: 0.8.22
+
+# Cleanup
+cd -
+rm -rf /tmp/squad-release-test
+```
+
+**If installation fails:** npm registry issue or package metadata corruption. DO NOT announce release until this works.
+
+**Checkpoint:** Both packages install cleanly. Versions match.
+
+### Step 7: Sync dev to Next Preview
+
+After main release, sync dev to the next preview version.
+
+```bash
+# Checkout dev
+git checkout dev
+git pull origin dev
+
+# Bump to next preview version (e.g., 0.8.23-preview.1)
+NEXT_VERSION="0.8.23-preview.1"
+
+# Validate semver
+node -p "require('semver').valid('$NEXT_VERSION')"
+# Must output the version string, NOT null
+
+# Update all 3 package.json files
+npm version $NEXT_VERSION --workspaces --include-workspace-root --no-git-tag-version
+
+# Commit
+git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json
+git commit -m "chore: bump dev to $NEXT_VERSION
+
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"
+
+# Push
+git push origin dev
+```
+
+**Checkpoint:** dev branch now shows next preview version. Future dev builds will publish to `@preview` dist-tag.
+
+---
+
+## Manual Publish (Fallback)
+
+If `publish.yml` workflow fails or needs to be bypassed, use `workflow_dispatch` to manually trigger publish.
+
+```bash
+# Trigger manual publish
+gh workflow run publish.yml -f version="0.8.22"
+
+# Monitor the run
+gh run watch
+```
+
+**Rule:** Only use this if automated publish failed. Always investigate why automation failed and fix it for next release.
+
+---
+
+## Rollback Procedure
+
+If a release is broken and needs to be rolled back:
+
+### 1. Unpublish from npm (Nuclear Option)
+
+**WARNING:** npm unpublish is time-limited (24 hours) and leaves the version slot burned. Only use if version is critically broken.
+
+```bash
+# Unpublish (requires npm owner privileges)
+npm unpublish @bradygaster/squad-sdk@0.8.22
+npm unpublish @bradygaster/squad-cli@0.8.22
+```
+
+### 2. Deprecate on npm (Preferred)
+
+**Preferred approach:** Mark version as deprecated, publish a hotfix.
+
+```bash
+# Deprecate broken version
+npm deprecate @bradygaster/squad-sdk@0.8.22 "Broken release, use 0.8.22.1 instead"
+npm deprecate @bradygaster/squad-cli@0.8.22 "Broken release, use 0.8.22.1 instead"
+
+# Publish hotfix version
+# (Follow this runbook with version 0.8.22.1)
+```
+
+### 3. Delete GitHub Release and Tag
+
+```bash
+# Delete GitHub Release
+gh release delete "v0.8.22" --yes
+
+# Delete tag locally and remotely
+git tag -d "v0.8.22"
+git push origin --delete "v0.8.22"
+```
+
+### 4. Revert Commit on main
+
+```bash
+# Revert version bump commit
+git checkout main
+git revert HEAD
+git push origin main
+```
+
+**Checkpoint:** Tag and release deleted. main branch reverted. npm packages deprecated or unpublished.
+
+---
+
+## Common Failure Modes
+
+### EOTP Error (npm OTP Required)
+
+**Symptom:** Workflow fails with `EOTP` error.  
+**Root cause:** NPM_TOKEN is a User token with 2FA enabled. CI can't provide OTP.  
+**Fix:** Replace NPM_TOKEN with an Automation token (no 2FA). See "NPM_TOKEN Verification" above.
+
+### Verify Step 404 (npm Propagation Delay)
+
+**Symptom:** Verify step fails with 404 even though publish succeeded.  
+**Root cause:** npm registry propagation delay (5-30 seconds).  
+**Fix:** Verify step now has retry loop (5 attempts, 15s interval). Should auto-resolve. If not, wait 2 minutes and re-run workflow.
+
+### Version Mismatch (package.json ≠ tag)
+
+**Symptom:** Verify step fails with "Package version (X) does not match target version (Y)".  
+**Root cause:** package.json version doesn't match the tag version.  
+**Fix:** Ensure all 3 package.json files were updated in Step 1. Re-run `npm version` if needed.
+
+### 4-Part Version Mangled by npm
+
+**Symptom:** Published version on npm doesn't match package.json (e.g., 0.8.21.4 became 0.8.2-1.4).  
+**Root cause:** 4-part versions are NOT valid semver. npm's parser misinterprets them.  
+**Fix:** NEVER use 4-part versions. Only 3-part (0.8.22) or prerelease (0.8.23-preview.1). Run `semver.valid()` before ANY commit.
+
+### Draft Release Didn't Trigger Workflow
+
+**Symptom:** Release created but `publish.yml` never ran.  
+**Root cause:** Release was created as a draft. Draft releases don't emit `release: published` event.  
+**Fix:** Edit release and change to published: `gh release edit "v$VERSION" --draft=false`. Workflow should trigger immediately.
+
+---
+
+## Validation Checklist
+
+Before starting ANY release, confirm:
+
+- [ ] Version is valid semver: `node -p "require('semver').valid('VERSION')"` returns the version string (NOT null)
+- [ ] NPM_TOKEN is an Automation token (no 2FA): `npm token list` shows `read-write` without OTP requirement
+- [ ] Branch is clean: `git status` shows "nothing to commit, working tree clean"
+- [ ] Tag doesn't exist: `git tag -l "vVERSION"` returns empty
+- [ ] `SKIP_BUILD_BUMP=1` is set: `echo $SKIP_BUILD_BUMP` returns `1`
+
+Before creating GitHub Release:
+
+- [ ] All 3 package.json files have matching versions: `grep '"version"' package.json packages/*/package.json`
+- [ ] Commit is pushed: `git log origin/main..main` returns empty
+- [ ] Tag is pushed: `git ls-remote --tags origin vVERSION` returns the tag SHA
+
+After GitHub Release:
+
+- [ ] Release is published (NOT draft): `gh release view "vVERSION"` output doesn't contain "(draft)"
+- [ ] Workflow is running: `gh run list --workflow=publish.yml --limit 1` shows "in_progress"
+
+After workflow completes:
+
+- [ ] Both jobs succeeded: Workflow shows green checkmarks
+- [ ] SDK on npm: `npm view @bradygaster/squad-sdk version` returns correct version
+- [ ] CLI on npm: `npm view @bradygaster/squad-cli version` returns correct version
+- [ ] `latest` tags correct: `npm dist-tag ls @bradygaster/squad-sdk` shows `latest: VERSION`
+- [ ] Packages install: `npm install @bradygaster/squad-cli` succeeds
+
+After dev sync:
+
+- [ ] dev branch has next preview version: `git show dev:package.json | grep version` shows next preview
+
+---
+
+## Post-Mortem Reference
+
+This skill was created after the v0.8.22 release disaster. Full retrospective: `.squad/decisions/inbox/keaton-v0822-retrospective.md`
+
+**Key learnings:**
+1. No release without a runbook = improvisation = disaster
+2. Semver validation is mandatory — 4-part versions break npm
+3. NPM_TOKEN type matters — User tokens with 2FA fail in CI
+4. Draft releases are a footgun — they don't trigger automation
+5. Retry logic is essential — npm propagation takes time
+
+**Never again.**

.squad/templates/skills/reskill/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: "reskill"
+description: "Team-wide charter and history optimization through skill extraction"
+domain: "team-optimization"
+confidence: "high"
+source: "manual — Brady directive to reduce per-agent context overhead"
+---
+
+## Context
+
+When the coordinator hears "team, reskill" (or similar: "optimize context", "slim down charters"), trigger a team-wide optimization pass. The goal: reduce per-agent context consumption by extracting shared patterns from charters and histories into reusable skills.
+
+This is a periodic maintenance activity. Run whenever charter/history bloat is suspected.
+
+## Process
+
+### Step 1: Audit
+Read all agent charters and histories. Measure byte sizes. Identify:
+
+- **Boilerplate** — sections repeated across ≥3 charters with <10% variation (collaboration, model, boundaries template)
+- **Shared knowledge** — domain knowledge duplicated in 2+ charters (incident postmortems, technical patterns)
+- **Mature learnings** — history entries appearing 3+ times across agents that should be promoted to skills
+
+### Step 2: Extract
+For each identified pattern:
+1. Create or update a skill at `.squad/skills/{skill-name}/SKILL.md`
+2. Follow the skill template format (frontmatter + Context + Patterns + Examples + Anti-Patterns)
+3. Set confidence: low (first observation), medium (2+ agents), high (team-wide)
+
+### Step 3: Trim
+**Charters** — target ≤1.5KB per agent:
+- Remove Collaboration section entirely (spawn prompt + agent-collaboration skill covers it)
+- Remove Voice section (tagline blockquote at top of charter already captures it)
+- Trim Model section to single line: `Preferred: {model}`
+- Remove "When I'm unsure" boilerplate from Boundaries
+- Remove domain knowledge now covered by a skill — add skill reference comment if helpful
+- Keep: Identity, What I Own, unique How I Work patterns, Boundaries (domain list only)
+
+**Histories** — target ≤8KB per agent:
+- Apply history-hygiene skill to any history >12KB
+- Promote recurring patterns (3+ occurrences across agents) to skills
+- Summarize old entries into `## Core Context` section
+- Remove session-specific metadata (dates, branch names, requester names)
+
+### Step 4: Report
+Output a savings table:
+
+| Agent | Charter Before | Charter After | History Before | History After | Saved |
+|-------|---------------|---------------|----------------|---------------|-------|
+
+Include totals and percentage reduction.
+
+## Patterns
+
+### Minimal Charter Template (target format after reskill)
+
+```
+# {Name} — {Role}
+
+> {Tagline — one sentence capturing voice and philosophy}
+
+## Identity
+- **Name:** {Name}
+- **Role:** {Role}
+- **Expertise:** {comma-separated list}
+
+## What I Own
+- {bullet list of owned artifacts/domains}
+
+## How I Work
+- {unique patterns and principles — NOT boilerplate}
+
+## Boundaries
+**I handle:** {domain list}
+**I don't handle:** {explicit exclusions}
+
+## Model
+Preferred: {model}
+```
+
+### Skill Extraction Threshold
+- **1 charter** → leave in charter (unique to that agent)
+- **2 charters** → consider extracting if >500 bytes of overlap
+- **3+ charters** → always extract to a shared skill
+
+## Anti-Patterns
+- Don't delete unique per-agent identity or domain-specific knowledge
+- Don't create skills for content only one agent uses
+- Don't merge unrelated patterns into a single mega-skill
+- Don't remove Model preference line (coordinator needs it for model selection)
+- Don't touch `.squad/decisions.md` during reskill
+- Don't remove the tagline blockquote — it's the charter's soul in one line

.squad/templates/skills/reviewer-protocol/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: "reviewer-protocol"
+description: "Reviewer rejection workflow and strict lockout semantics"
+domain: "orchestration"
+confidence: "high"
+source: "extracted"
+---
+
+## Context
+
+When a team member has a **Reviewer** role (e.g., Tester, Code Reviewer, Lead), they may approve or reject work from other agents. On rejection, the coordinator enforces strict lockout rules to ensure the original author does NOT self-revise. This prevents defensive feedback loops and ensures independent review.
+
+## Patterns
+
+### Reviewer Rejection Protocol
+
+When a team member has a **Reviewer** role:
+
+- Reviewers may **approve** or **reject** work from other agents.
+- On **rejection**, the Reviewer may choose ONE of:
+  1. **Reassign:** Require a *different* agent to do the revision (not the original author).
+  2. **Escalate:** Require a *new* agent be spawned with specific expertise.
+- The Coordinator MUST enforce this. If the Reviewer says "someone else should fix this," the original agent does NOT get to self-revise.
+- If the Reviewer approves, work proceeds normally.
+
+### Strict Lockout Semantics
+
+When an artifact is **rejected** by a Reviewer:
+
+1. **The original author is locked out.** They may NOT produce the next version of that artifact. No exceptions.
+2. **A different agent MUST own the revision.** The Coordinator selects the revision author based on the Reviewer's recommendation (reassign or escalate).
+3. **The Coordinator enforces this mechanically.** Before spawning a revision agent, the Coordinator MUST verify that the selected agent is NOT the original author. If the Reviewer names the original author as the fix agent, the Coordinator MUST refuse and ask the Reviewer to name a different agent.
+4. **The locked-out author may NOT contribute to the revision** in any form — not as a co-author, advisor, or pair. The revision must be independently produced.
+5. **Lockout scope:** The lockout applies to the specific artifact that was rejected. The original author may still work on other unrelated artifacts.
+6. **Lockout duration:** The lockout persists for that revision cycle. If the revision is also rejected, the same rule applies again — the revision author is now also locked out, and a third agent must revise.
+7. **Deadlock handling:** If all eligible agents have been locked out of an artifact, the Coordinator MUST escalate to the user rather than re-admitting a locked-out author.
+
+## Examples
+
+**Example 1: Reassign after rejection**
+1. Fenster writes authentication module
+2. Hockney (Tester) reviews → rejects: "Error handling is missing. Verbal should fix this."
+3. Coordinator: Fenster is now locked out of this artifact
+4. Coordinator spawns Verbal to revise the authentication module
+5. Verbal produces v2
+6. Hockney reviews v2 → approves
+7. Lockout clears for next artifact
+
+**Example 2: Escalate for expertise**
+1. Edie writes TypeScript config
+2. Keaton (Lead) reviews → rejects: "Need someone with deeper TS knowledge. Escalate."
+3. Coordinator: Edie is now locked out
+4. Coordinator spawns new agent (or existing TS expert) to revise
+5. New agent produces v2
+6. Keaton reviews v2
+
+**Example 3: Deadlock handling**
+1. Fenster writes module → rejected
+2. Verbal revises → rejected
+3. Hockney revises → rejected
+4. All 3 eligible agents are now locked out
+5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]"
+
+**Example 4: Reviewer accidentally names original author**
+1. Fenster writes module → rejected
+2. Hockney says: "Fenster should fix the error handling"
+3. Coordinator: "Fenster is locked out as the original author. Please name a different agent."
+4. Hockney: "Verbal, then"
+5. Coordinator spawns Verbal
+
+## Anti-Patterns
+
+- ❌ Allowing the original author to self-revise after rejection
+- ❌ Treating the locked-out author as an "advisor" or "co-author" on the revision
+- ❌ Re-admitting a locked-out author when deadlock occurs (must escalate to user)
+- ❌ Applying lockout across unrelated artifacts (scope is per-artifact)
+- ❌ Accepting the Reviewer's assignment when they name the original author (must refuse and ask for a different agent)
+- ❌ Clearing lockout before the revision is approved (lockout persists through revision cycle)
+- ❌ Skipping verification that the revision agent is not the original author

.squad/templates/skills/secret-handling/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: secret-handling
+description: Never read .env files or write secrets to .squad/ committed files
+domain: security, file-operations, team-collaboration
+confidence: high
+source: earned (issue #267 — credential leak incident)
+---
+
+## Context
+
+Spawned agents have read access to the entire repository, including `.env` files containing live credentials. If an agent reads secrets and writes them to `.squad/` files (decisions, logs, history), Scribe auto-commits them to git, exposing them in remote history. This skill codifies absolute prohibitions and safe alternatives.
+
+## Patterns
+
+### Prohibited File Reads
+
+**NEVER read these files:**
+- `.env` (production secrets)
+- `.env.local` (local dev secrets)
+- `.env.production` (production environment)
+- `.env.development` (development environment)
+- `.env.staging` (staging environment)
+- `.env.test` (test environment with real credentials)
+- Any file matching `.env.*` UNLESS explicitly allowed (see below)
+
+**Allowed alternatives:**
+- `.env.example` (safe — contains placeholder values, no real secrets)
+- `.env.sample` (safe — documentation template)
+- `.env.template` (safe — schema/structure reference)
+
+**If you need config info:**
+1. **Ask the user directly** — "What's the database connection string?"
+2. **Read `.env.example`** — shows structure without exposing secrets
+3. **Read documentation** — check `README.md`, `docs/`, config guides
+
+**NEVER assume you can "just peek at .env to understand the schema."** Use `.env.example` or ask.
+
+### Prohibited Output Patterns
+
+**NEVER write these to `.squad/` files:**
+
+| Pattern Type | Examples | Regex Pattern (for scanning) |
+|--------------|----------|-------------------------------|
+| API Keys | `OPENAI_API_KEY=sk-proj-...`, `GITHUB_TOKEN=ghp_...` | `[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+` |
+| Passwords | `DB_PASSWORD=super_secret_123`, `password: "..."` | `(?:PASSWORD|PASS|PWD)[:=]\s*["']?[^\s"']+` |
+| Connection Strings | `postgres://user:pass@host:5432/db`, `Server=...;Password=...` | `(?:postgres|mysql|mongodb)://[^@]+@|(?:Server|Host)=.*(?:Password|Pwd)=` |
+| JWT Tokens | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` | `eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+` |
+| Private Keys | `-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` | `-----BEGIN [A-Z ]+PRIVATE KEY-----` |
+| AWS Credentials | `AKIA...`, `aws_secret_access_key=...` | `AKIA[0-9A-Z]{16}|aws_secret_access_key=[^\s]+` |
+| Email Addresses | `user@example.com` (PII violation per team decision) | `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` |
+
+**What to write instead:**
+- Placeholder values: `DATABASE_URL=<set in .env>`
+- Redacted references: `API key configured (see .env.example)`
+- Architecture notes: "App uses JWT auth — token stored in session"
+- Schema documentation: "Requires OPENAI_API_KEY, GITHUB_TOKEN (see .env.example for format)"
+
+### Scribe Pre-Commit Validation
+
+**Before committing `.squad/` changes, Scribe MUST:**
+
+1. **Scan all staged files** for secret patterns (use regex table above)
+2. **Check for prohibited file names** (don't commit `.env` even if manually staged)
+3. **If secrets detected:**
+   - STOP the commit (do NOT proceed)
+   - Remove the file from staging: `git reset HEAD <file>`
+   - Report to user:
+     ```
+     🚨 SECRET DETECTED — commit blocked
+     
+     File: .squad/decisions/inbox/river-db-config.md
+     Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod
+     
+     This file contains credentials and MUST NOT be committed.
+     Please remove the secret, replace with placeholder, and try again.
+     ```
+   - Exit with error (never silently skip)
+
+4. **If no secrets detected:**
+   - Proceed with commit as normal
+
+**Implementation note for Scribe:**
+- Run validation AFTER staging files, BEFORE calling `git commit`
+- Use PowerShell `Select-String` or `git diff --cached` to scan staged content
+- Fail loud — secret leaks are unacceptable, blocking the commit is correct behavior
+
+### Remediation — If a Secret Was Already Committed
+
+**If you discover a secret in git history:**
+
+1. **STOP immediately** — do not make more commits
+2. **Alert the user:**
+   ```
+   🚨 CREDENTIAL LEAK DETECTED
+   
+   A secret was found in git history:
+   Commit: abc1234
+   File: .squad/decisions/inbox/agent-config.md
+   Pattern: API_KEY=sk-proj-...
+   
+   This requires immediate remediation:
+   1. Revoke the exposed credential (regenerate API key, rotate password)
+   2. Remove from git history (git filter-repo or BFG)
+   3. Force-push the cleaned history
+   
+   Do NOT proceed with new work until this is resolved.
+   ```
+3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools
+4. **Wait for user confirmation** before resuming work
+
+## Examples
+
+### ✓ Correct: Reading Config Schema
+
+**Agent needs to know what environment variables are required:**
+
+```
+Agent: "What environment variables does this app need?"
+→ Reads `.env.example`:
+    OPENAI_API_KEY=sk-...
+    DATABASE_URL=postgres://user:pass@localhost:5432/db
+    REDIS_URL=redis://localhost:6379
+
+→ Writes to .squad/decisions/inbox/river-env-setup.md:
+    "App requires three environment variables:
+    - OPENAI_API_KEY (OpenAI API key, format: sk-...)
+    - DATABASE_URL (Postgres connection string)
+    - REDIS_URL (Redis connection string)
+    See .env.example for full schema."
+```
+
+### ✗ Incorrect: Reading Live Credentials
+
+**Agent needs to know database schema:**
+
+```
+Agent: (reads .env)
+    DATABASE_URL=postgres://admin:super_secret_pw@prod.example.com:5432/appdb
+
+→ Writes to .squad/decisions/inbox/river-db-schema.md:
+    "Database connection: postgres://admin:super_secret_pw@prod.example.com:5432/appdb"
+    
+🚨 VIOLATION: Live credential written to committed file
+```
+
+**Correct approach:**
+```
+Agent: (reads .env.example OR asks user)
+User: "It's a Postgres database, schema is in migrations/"
+
+→ Writes to .squad/decisions/inbox/river-db-schema.md:
+    "Database: Postgres (connection configured in .env). Schema defined in db/migrations/."
+```
+
+### ✓ Correct: Scribe Pre-Commit Validation
+
+**Scribe is about to commit:**
+
+```powershell
+# Stage files
+git add .squad/
+
+# Scan staged content for secrets
+$stagedContent = git diff --cached
+$secretPatterns = @(
+    '[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+',
+    '(?:PASSWORD|PASS|PWD)[:=]\s*["'']?[^\s"'']+',
+    'eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+'
+)
+
+$detected = $false
+foreach ($pattern in $secretPatterns) {
+    if ($stagedContent -match $pattern) {
+        $detected = $true
+        Write-Host "🚨 SECRET DETECTED: $($matches[0])"
+        break
+    }
+}
+
+if ($detected) {
+    # Remove from staging, report, exit
+    git reset HEAD .squad/
+    Write-Error "Commit blocked — secret detected in staged files"
+    exit 1
+}
+
+# Safe to commit
+git commit -F $msgFile
+```
+
+## Anti-Patterns
+
+- ❌ Reading `.env` "just to check the schema" — use `.env.example` instead
+- ❌ Writing "sanitized" connection strings that still contain credentials
+- ❌ Assuming "it's just a dev environment" makes secrets safe to commit
+- ❌ Committing first, scanning later — validation MUST happen before commit
+- ❌ Silently skipping secret detection — fail loud, never silent
+- ❌ Trusting agents to "know better" — enforce at multiple layers (prompt, hook, architecture)
+- ❌ Writing secrets to "temporary" files in `.squad/` — Scribe commits ALL `.squad/` changes
+- ❌ Extracting "just the host" from a connection string — still leaks infrastructure topology

.squad/templates/skills/session-recovery/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: "session-recovery"
+description: "Find and resume interrupted Copilot CLI sessions using session_store queries"
+domain: "workflow-recovery"
+confidence: "high"
+source: "earned"
+tools:
+  - name: "sql"
+    description: "Query session_store database for past session history"
+    when: "Always — session_store is the source of truth for session history"
+---
+
+## Context
+
+Squad agents run in Copilot CLI sessions that can be interrupted — terminal crashes, network drops, machine restarts, or accidental window closes. When this happens, in-progress work may be left in a partially-completed state: branches with uncommitted changes, issues marked in-progress with no active agent, or checkpoints that were never finalized.
+
+Copilot CLI stores session history in a SQLite database called `session_store` (read-only, accessed via the `sql` tool with `database: "session_store"`). This skill teaches agents how to query that store to detect interrupted sessions and resume work.
+
+## Patterns
+
+### 1. Find Recent Sessions
+
+Query the `sessions` table filtered by time window. Include the last checkpoint to understand where the session stopped:
+
+```sql
+SELECT
+  s.id,
+  s.summary,
+  s.cwd,
+  s.branch,
+  s.updated_at,
+  (SELECT title FROM checkpoints
+   WHERE session_id = s.id
+   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
+FROM sessions s
+WHERE s.updated_at >= datetime('now', '-24 hours')
+ORDER BY s.updated_at DESC;
+```
+
+### 2. Filter Out Automated Sessions
+
+Automated agents (monitors, keep-alive, heartbeat) create high-volume sessions that obscure human-initiated work. Exclude them:
+
+```sql
+SELECT s.id, s.summary, s.cwd, s.updated_at,
+  (SELECT title FROM checkpoints
+   WHERE session_id = s.id
+   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
+FROM sessions s
+WHERE s.updated_at >= datetime('now', '-24 hours')
+  AND s.id NOT IN (
+    SELECT DISTINCT t.session_id FROM turns t
+    WHERE t.turn_index = 0
+      AND (LOWER(t.user_message) LIKE '%keep-alive%'
+           OR LOWER(t.user_message) LIKE '%heartbeat%')
+  )
+ORDER BY s.updated_at DESC;
+```
+
+### 3. Search by Topic (FTS5)
+
+Use the `search_index` FTS5 table for keyword search. Expand queries with synonyms since this is keyword-based, not semantic:
+
+```sql
+SELECT DISTINCT s.id, s.summary, s.cwd, s.updated_at
+FROM search_index si
+JOIN sessions s ON si.session_id = s.id
+WHERE search_index MATCH 'auth OR login OR token OR JWT'
+  AND s.updated_at >= datetime('now', '-48 hours')
+ORDER BY s.updated_at DESC
+LIMIT 10;
+```
+
+### 4. Search by Working Directory
+
+```sql
+SELECT s.id, s.summary, s.updated_at,
+  (SELECT title FROM checkpoints
+   WHERE session_id = s.id
+   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
+FROM sessions s
+WHERE s.cwd LIKE '%my-project%'
+  AND s.updated_at >= datetime('now', '-48 hours')
+ORDER BY s.updated_at DESC;
+```
+
+### 5. Get Full Session Context Before Resuming
+
+Before resuming, inspect what the session was doing:
+
+```sql
+-- Conversation turns
+SELECT turn_index, substr(user_message, 1, 200) AS ask, timestamp
+FROM turns WHERE session_id = 'SESSION_ID' ORDER BY turn_index;
+
+-- Checkpoint progress
+SELECT checkpoint_number, title, overview
+FROM checkpoints WHERE session_id = 'SESSION_ID' ORDER BY checkpoint_number;
+
+-- Files touched
+SELECT file_path, tool_name
+FROM session_files WHERE session_id = 'SESSION_ID';
+
+-- Linked PRs/issues/commits
+SELECT ref_type, ref_value
+FROM session_refs WHERE session_id = 'SESSION_ID';
+```
+
+### 6. Detect Orphaned Issue Work
+
+Find sessions that were working on issues but may not have completed:
+
+```sql
+SELECT DISTINCT s.id, s.branch, s.summary, s.updated_at,
+  sr.ref_type, sr.ref_value
+FROM sessions s
+JOIN session_refs sr ON s.id = sr.session_id
+WHERE sr.ref_type = 'issue'
+  AND s.updated_at >= datetime('now', '-48 hours')
+ORDER BY s.updated_at DESC;
+```
+
+Cross-reference with `gh issue list --label "status:in-progress"` to find issues that are marked in-progress but have no active session.
+
+### 7. Resume a Session
+
+Once you have the session ID:
+
+```bash
+# Resume directly
+copilot --resume SESSION_ID
+```
+
+## Examples
+
+**Recovering from a crash during PR creation:**
+1. Query recent sessions filtered by branch name
+2. Find the session that was working on the PR
+3. Check its last checkpoint — was the code committed? Was the PR created?
+4. Resume or manually complete the remaining steps
+
+**Finding yesterday's work on a feature:**
+1. Use FTS5 search with feature keywords
+2. Filter to the relevant working directory
+3. Review checkpoint progress to see how far the session got
+4. Resume if work remains, or start fresh with the context
+
+## Anti-Patterns
+
+- ❌ Searching by partial session IDs — always use full UUIDs
+- ❌ Resuming sessions that completed successfully — they have no pending work
+- ❌ Using `MATCH` with special characters without escaping — wrap paths in double quotes
+- ❌ Skipping the automated-session filter — high-volume automated sessions will flood results
+- ❌ Assuming FTS5 is semantic search — it's keyword-based; always expand queries with synonyms
+- ❌ Ignoring checkpoint data — checkpoints show exactly where the session stopped

.squad/templates/skills/squad-conventions/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: "squad-conventions"
+description: "Core conventions and patterns used in the Squad codebase"
+domain: "project-conventions"
+confidence: "high"
+source: "manual"
+---
+
+## Context
+These conventions apply to all work on the Squad CLI tool (`create-squad`). Squad is a zero-dependency Node.js package that adds AI agent teams to any project. Understanding these patterns is essential before modifying any Squad source code.
+
+## Patterns
+
+### Zero Dependencies
+Squad 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
+- `.squad/` — Team state (user-owned, never overwritten by upgrades)
+- `.squad/templates/` — Template files copied from `templates/` (Squad-owned, overwritten on upgrade)
+- `.github/agents/squad.agent.md` — Coordinator prompt (Squad-owned, overwritten on upgrade)
+- `templates/` — Source templates shipped with the npm package
+- `.squad/skills/` — Team skills in SKILL.md format (user-owned)
+- `.squad/decisions/inbox/` — Drop-box for parallel decision writes
+
+### Windows Compatibility
+Always use `path.join()` for file paths — never hardcode `/` or `\` separators. Squad 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 Squad-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', 'squad.agent.md');
+
+// Skip-if-exists pattern
+if (!fs.existsSync(ceremoniesDest)) {
+  fs.copyFileSync(ceremoniesSrc, ceremoniesDest);
+  console.log(`${GREEN}✓${RESET} .squad/ceremonies.md`);
+} else {
+  console.log(`${DIM}ceremonies.md already exists — skipping${RESET}`);
+}
+```
+
+## Anti-Patterns
+- **Adding npm dependencies** — Squad 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 Squad-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`).

.squad/templates/skills/test-discipline/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: "test-discipline"
+description: "Update tests when changing APIs — no exceptions"
+domain: "quality"
+confidence: "high"
+source: "earned (Fenster/Hockney incident, test assertion sync violations)"
+---
+
+## Context
+
+When APIs or public interfaces change, tests must be updated in the same commit. When test assertions reference file counts or expected arrays, they must be kept in sync with disk reality. Stale tests block CI for other contributors.
+
+## Patterns
+
+- **API changes → test updates (same commit):** If you change a function signature, public interface, or exported API, update the corresponding tests before committing
+- **Test assertions → disk reality:** When test files contain expected counts (e.g., `EXPECTED_FEATURES`, `EXPECTED_SCENARIOS`), they must match the actual files on disk
+- **Add files → update assertions:** When adding docs pages, features, or any counted resource, update the test assertion array in the same commit
+- **CI failures → check assertions first:** Before debugging complex failures, verify test assertion arrays match filesystem state
+
+## Examples
+
+✓ **Correct:**
+- Changed auth API signature → updated auth.test.ts in same commit
+- Added `distributed-mesh.md` to features/ → added `'distributed-mesh'` to EXPECTED_FEATURES array
+- Deleted two scenario files → removed entries from EXPECTED_SCENARIOS
+
+✗ **Incorrect:**
+- Changed spawn parameters → committed without updating casting.test.ts (CI breaks for next person)
+- Added `built-in-roles.md` → left EXPECTED_FEATURES at old count (PR blocked)
+- Test says "expected 7 files" but disk has 25 (assertion staleness)
+
+## Anti-Patterns
+
+- Committing API changes without test updates ("I'll fix tests later")
+- Treating test assertion arrays as static (they evolve with content)
+- Assuming CI passing means coverage is correct (stale assertions can pass while being wrong)
+- Leaving gaps for other agents to discover