docs: FAQ and CLI guidance improvements (#398)

.squad/agents/fido/history.md

@@ -31,6 +31,32 @@
 Both PRs show CI build failures (missing SDK exports: listRoles, searchRoles, getCategories, getRoleById, generateCharterFromRole). Investigation confirmed this is a **pre-existing issue on dev branch** (CI runs #23109355116, #23108671446 also fail). Local builds succeed. Not introduced by either PR.
 
 **Lesson reinforced:** When reviewing PRs with CI failures, always check if dev branch has the same failures. Don't block PRs for pre-existing platform issues.
+### PR #380 Quality Gate Review — FAIL (Test Assertion Sync Violation) (2026-03-14T03:35:00Z)
+
+**TEST FAILURE:** `test/docs-build.test.ts > features directory contains all expected markdown files` — Expected 33 files, found 34.
+
+**ROOT CAUSE:** PR #380 added `distributed-mesh.md` (new feature) and correctly added `distributed-mesh` to EXPECTED_FEATURES array. However, the base branch (dev @ dea678b) already contains `built-in-roles.md` (added in commit 83fd050, PR #368 on 2026-03-12), which was NOT in the test's expected list. The PR author updated the array to add their new feature but failed to notice the pre-existing gap.
+
+**BASELINE COMPARISON:**
+- Dev branch: 15 failures (docs-build, init tests [12 failures, missing skill templates], aspire-integration, cli-packaging-smoke)
+- PR branch (before sync): Same 15 failures
+- PR branch (after sync script): **3 failures** — aspire-integration (Docker), cli-packaging-smoke (npm install), and **1 NEW FAILURE in docs-build.test.ts**
+
+**POSITIVE FINDINGS:**
+- ✅ PR FIXED 12 test failures in test/init.test.ts by introducing `scripts/sync-skill-templates.mjs` and integrating it into prebuild
+- ✅ Sync script works correctly (syncs 15 skills from .squad/skills/ to package templates)
+- ✅ Build succeeds cleanly with sync script
+- ✅ No regression in existing test coverage (4142 tests passing vs 4084 on baseline)
+- ✅ `distributed-mesh.md` documentation file properly added to features directory
+- ✅ No new dependencies in package.json (only build script changes)
+
+**REQUIRED FIX:** Add `'built-in-roles'` to EXPECTED_FEATURES array in test/docs-build.test.ts. Array should be 34 items total (33 existing features + distributed-mesh).
+
+**COVERAGE GAP:** No unit tests for the distributed mesh feature itself. PR is templates + docs only, which aligns with the stated "no code changes" design decision. Future work should add tests for mesh sync logic when implemented.
+
+**VERDICT:** FAIL — Cannot merge until test assertion is corrected. The sync script is a major quality improvement (fixes 12 tests), but the test count mismatch must be resolved.
+
+**Test counts:** 4113 passed, 1 failed, 34 skipped, 46 todo (PR branch with 3 suites failing: aspire [pre-existing], cli-packaging [pre-existing], docs-build [NEW]).
 
 ### Name-Agnostic Testing Pattern
 Tests reading live .squad/ files (team.md, routing.md) must assert structure/behavior, not specific agent names. Names change during team rebirths. Two classes of tests: (1) live-file tests — must survive rebirths, use property checks, (2) inline-fixture tests — self-contained, can hardcode names. See ralph-triage.test.ts for the canonical pattern.

.squad/agents/flight/history.md

@@ -27,3 +27,10 @@ Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic
 
 📌 Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern — decided by Procedures, PAO, Flight, Network
 
+---
+
+## Sprint Prioritization Pattern
+
+**Backlog triage methodology (47-issue analysis):**  
+Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA release, (3) high-ROI features unblocking downstream work. Current sprint Top 10 identifies 3 bugs (WSL crash, SDK init regression, VS Code crash), 3 quality gates (SDK feature parity testing), and 4 governance/architecture decisions (opt-in roles, ADR archive, docs gaps, upstream sync). This pattern scales: categorize all open issues by type → sort each category by impact/urgency → interleave across sprint capacity to balance stability (bugs/quality) with velocity (features). Squad GA is gated by quality #340, #341, #347 and user-facing regressions #363, #337 — these must ship in parallel next sprint.
+

.squad/decisions-archive.md

@@ -4244,3 +4244,47 @@ Created two deliverables:
 **By:** Brady (via Copilot)
 **What:** DO NOT merge PR #547 (Squad Remote Control). Do not touch #547 at all.
 **Why:** User request — captured for team memory
+
+# Decision: CLI sessions use approve-all permission handler
+
+**Date:** 2025-07-14
+**Author:** Fenster (Core Dev)
+**Issue:** #651
+
+## Context
+
+The Copilot SDK requires an onPermissionRequest handler when creating sessions. This handler was defined in our adapter types (SquadSessionConfig) but was never wired in the CLI shell's 4 createSession() calls. External users hit a raw SDK error with no guidance.
+
+## Decision
+
+All CLI shell session creation calls now pass onPermissionRequest: approveAllPermissions, a handler that returns { kind: 'approved' } for every request. The CLI runs locally with user trust — there is no interactive permission prompt.
+
+SDK consumers (programmatic API users) still control their own handler. The SDK's createSession in dapter/client.ts now catches the raw permission error and wraps it with a clear message explaining how to fix it.
+
+## Impact
+
+- **CLI users:** Error is gone. All permissions auto-approved (matches existing CLI trust model).
+- **SDK consumers:** Better error message if they forget to pass onPermissionRequest.
+- **Types:** SquadPermissionHandler, SquadPermissionRequest, SquadPermissionRequestResult are now exported from @bradygaster/squad-sdk/client for reuse.
+### 2025-07-24: Multi-Squad Global Config Layout
+**By:** Fenster (Core Dev)  
+**Issue:** #652  
+**PR:** #691  
+
+## What
+
+Squad now supports a global squads.json registry at the platform config root (%APPDATA%/squad/ on Windows, ~/.config/squad/ on Linux/macOS). Each named squad is registered with a name, path, and creation timestamp. Resolution follows a 5-step chain: explicit name → SQUAD_NAME env var → active in squads.json → "default" → legacy ~/.squad fallback.
+
+## Why
+
+Users need to manage multiple squads (personal, work, experiments) without conflicts. A global registry decouples squad identity from the current working directory and enables future CLI commands (squad list, squad switch, etc.) in Phase 2.
+
+## Migration Strategy
+
+Migration is **non-destructive and registration-only**. When esolveSquadPath() detects a legacy ~/.squad layout without an existing squads.json, it registers that path as the "default" squad. No files are moved, copied, or renamed. This eliminates data loss risk on first upgrade.
+
+## Impact
+
+- All future squad path resolution should go through esolveSquadPath() from multi-squad.ts
+- Existing esolveSquad() and esolveSquadPaths() in esolution.ts remain unchanged (project-local .squad/ walk-up)
+- Phase 2 CLI commands will consume these SDK functions directly

.squad/decisions.md

@@ -942,53 +942,6 @@ esolveSquadForProject()
 ## Why
 
 Duplicated separator logic was found in 3 files (App.tsx, AgentPanel.tsx, MessageStream.tsx). Consolidation to a single component prevents drift and makes it trivial to change separator style globally. The info hierarchy and whitespace conventions ensure visual consistency as new components are added.
-
-# Decision: CLI sessions use approve-all permission handler
-
-**Date:** 2025-07-14
-**Author:** Fenster (Core Dev)
-**Issue:** #651
-
-## Context
-
-The Copilot SDK requires an `onPermissionRequest` handler when creating sessions. This handler was defined in our adapter types (`SquadSessionConfig`) but was never wired in the CLI shell's 4 `createSession()` calls. External users hit a raw SDK error with no guidance.
-
-## Decision
-
-All CLI shell session creation calls now pass `onPermissionRequest: approveAllPermissions`, a handler that returns `{ kind: 'approved' }` for every request. The CLI runs locally with user trust — there is no interactive permission prompt.
-
-SDK consumers (programmatic API users) still control their own handler. The SDK's `createSession` in `adapter/client.ts` now catches the raw permission error and wraps it with a clear message explaining how to fix it.
-
-## Impact
-
-- **CLI users:** Error is gone. All permissions auto-approved (matches existing CLI trust model).
-- **SDK consumers:** Better error message if they forget to pass `onPermissionRequest`.
-- **Types:** `SquadPermissionHandler`, `SquadPermissionRequest`, `SquadPermissionRequestResult` are now exported from `@bradygaster/squad-sdk/client` for reuse.
-
-### 2026-03-01: Multi-Squad Global Config Layout
-**By:** Fenster (Core Dev)  
-**Date:** 2025-07-24  
-**Issue:** #652  
-**PR:** #691  
-
-## What
-
-Squad now supports a global `squads.json` registry at the platform config root (`%APPDATA%/squad/` on Windows, `~/.config/squad/` on Linux/macOS). Each named squad is registered with a name, path, and creation timestamp. Resolution follows a 5-step chain: explicit name → `SQUAD_NAME` env var → active in squads.json → "default" → legacy `~/.squad` fallback.
-
-## Why
-
-Users need to manage multiple squads (personal, work, experiments) without conflicts. A global registry decouples squad identity from the current working directory and enables future CLI commands (`squad list`, `squad switch`, etc.) in Phase 2.
-
-## Migration Strategy
-
-Migration is **non-destructive and registration-only**. When `resolveSquadPath()` detects a legacy `~/.squad` layout without an existing `squads.json`, it registers that path as the "default" squad. No files are moved, copied, or renamed. This eliminates data loss risk on first upgrade.
-
-## Impact
-
-- All future squad path resolution should go through `resolveSquadPath()` from `multi-squad.ts`
-- Existing `resolveSquad()` and `resolveSquadPaths()` in `resolution.ts` remain unchanged (project-local `.squad/` walk-up)
-- Phase 2 CLI commands will consume these SDK functions directly
-
 ### 2026-03-01: PR #547 Remote Control Feature — Architectural Review
 **By:** Fenster  
 **Date:** 2026-03-01  
@@ -5559,3 +5512,4 @@ The feature page provides practical setup steps and respects the tone ceiling 
 
 
 ---
+

docs/src/content/docs/features/copilot-coding-agent.md

@@ -33,8 +33,11 @@ gh secret set COPILOT_ASSIGN_TOKEN
 git add .github/ .squad/ && git commit -m "feat: add copilot to squad" && git push
 
 # 5. Test — label any issue with squad:copilot
+gh issue edit <number> --add-label "squad:copilot"
 ```
 
+> **Why can't I use `gh issue edit --add-assignee "@copilot"`?** Bot accounts cannot be assigned via the GitHub CLI the same way as human users. Use label-based assignment instead. See [FAQ: Why doesn't gh issue edit --add-assignee "@copilot" work?](../guide/faq.md#why-doesnt-gh-issue-edit---add-assignee-copilot-work) for details.
+
 ---
 
 ## Enabling @copilot

docs/src/content/docs/guide.md

@@ -8,12 +8,37 @@ It is not a chatbot wearing hats. Each team member is spawned as a real sub-agen
 
 ---
 
+## Which CLI should I use?
+
+**Use GitHub Copilot CLI for day-to-day work.** It's the recommended interface for interacting with your Squad — full agent spawning, model selection, and conversational access to all features.
+
+**Use Squad CLI for setup and operations:**
+- Initial setup: `squad init`
+- Diagnostics: `squad doctor`
+- Continuous triage: `squad triage --interval 10`
+- Aspire dashboard: `squad aspire`
+- Export/import: `squad export` and `squad import`
+
+**Common workflow:**
+```bash
+# Terminal 1: Run continuous triage (Squad CLI)
+squad triage --interval 10
+
+# Terminal 2: Work with your team (GitHub Copilot CLI)
+gh copilot
+> @squad what issues are ready to work?
+```
+
+Both CLIs read and write the same `.squad/` directory, so state stays synchronized. For more details, see [FAQ: Which CLI should I use?](guide/faq.md#which-cli-should-i-use) and [Client Compatibility Matrix](scenarios/client-compatibility.md).
+
+---
+
 ## Supported Platforms
 
 Squad is designed for **GitHub Copilot CLI** and ships with full support. **VS Code is now fully supported with zero code changes** — agents work identically on both platforms.
 
 **Current state:**
-- ✅ **GitHub Copilot CLI** — fully supported. This is the primary platform. Uses the stable `task` tool for sub-agent spawning, per-spawn model selection, and background mode.
+- ✅ **GitHub Copilot CLI** — fully supported. This is the recommended interface for day-to-day work. Uses the stable `task` tool for sub-agent spawning, per-spawn model selection, and background mode.
 - ✅ **VS Code Copilot** — fully supported (v0.4.0+). VS Code uses `runSubagent` for parallel execution and supports full `.ai-team/` read/write. See [Client Compatibility Matrix](scenarios/client-compatibility.md) for details.
 - ❌ **Other platforms** — JetBrains IDEs and other runtimes are untested. GitHub.com web-based Copilot is untested.