docs: consolidated docs quality, reduction, and dedup

.squad/agents/pao/charter.md

@@ -26,6 +26,8 @@
 - **DOCS-TEST SYNC (hard rule):** When adding new docs pages (guides, blog posts), update the corresponding test assertions in test/docs-build.test.ts in the SAME commit. Stale test assertions that block CI are a docs team failure.
 - **CONTRIBUTOR RECOGNITION (hard rule):** Each release includes an update to the Contributors Guide page. No contribution goes unappreciated.
 - **DOC-IMPACT REVIEW (hard rule):** Review every PR for documentation impact. If a change affects user-facing behavior, ensure corresponding docs are updated or flag the gap.
+- **CONTENT DISCIPLINE (hard rule):** Before writing new content, search existing docs for coverage of the same topic. Link to the canonical page instead of duplicating setup steps, config blocks, or explanations. Each concept should live in exactly one place — other pages reference it. When reviewing docs, flag duplication and unnecessary growth.
+- **DEEP LINKING (hard rule):** When linking between docs pages, use the most specific anchor available (e.g., `guides/mcp/#authentication-errors`) rather than just the page URL. If a heading or section anchor exists for the target content, link to it.
 
 ## Boundaries
 

.squad/agents/pao/history.md

@@ -54,4 +54,6 @@ Added distributed-mesh.md to features/ — covers the three zones (local, remote
 Added "Skill scope" section to distributed-mesh.md to document zero-code skill boundaries. Pattern: explicitly state what the skill produces (config files, decision entries, pointers to templates) and what it does NOT produce (code, tests, custom scripts). Rationale: deterministic skills prevent agents from generating unnecessary implementations when pre-built templates exist. This documentation pattern should apply to other zero-code skills — helps agents understand when to copy templates vs. generate code. Position: after technical comparison sections, before "What We're NOT Building" or closing content.
 
 📌 Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern — decided by Procedures, PAO, Flight, Network
+### Teams MCP Documentation Audit (v0.8.26)
+Audited Teams MCP integration documentation per #258. Key findings: (1) All path references used placeholder `path/to/*.js` without clarifying these require actual MCP server implementations; (2) Link to `microsoft/IF-MCP-Server-for-Microsoft-Teams` was misleading — that repo is actually a Court Listener demo, not a general Teams server; (3) No example code exists in Squad codebase; (4) Community member benleane83 published working reference implementation at https://gist.github.com/benleane83/f37b5bc1ed3d00e320ba48886109b82a. Fixes applied: replaced placeholder paths with `/absolute/path/to/*.js` format, removed broken Microsoft Teams MCP reference, added link to community gist, clarified users must download/create MCP servers, updated all MCP config examples in notifications.md, mcp.md, and portability.md. Pattern reinforced: external tool integrations require explicit "where to get it" guidance, not assumptions about bundled code.
 

README.md

@@ -37,7 +37,7 @@ squad init
 
 **✓ Validate:** Check that `.squad/team.md` was created in your project.
 
-**Or use npx (no install):** `npx @bradygaster/squad-cli` — see [Migration Guide](docs/get-started/migration.md) if upgrading from an older version.
+**Or use npx (no install):** `npx @bradygaster/squad-cli` — see [Migration Guide](https://bradygaster.github.io/squad/docs/get-started/migration/) if upgrading from an older version.
 
 ### 3. Authenticate with GitHub (for Issues, PRs, and Ralph)
 
@@ -49,16 +49,13 @@ gh auth login
 
 ### 4. Open Copilot and go
 
-**Recommended:** start Copilot with `--yolo`.
-
 ```
-copilot --yolo
+copilot --agent squad --yolo
 ```
 
-> **Why use `--yolo`?** Squad makes many tool calls in a typical session. Without it, Copilot will prompt you to approve each one.
+> **Why `--yolo`?** Squad makes many tool calls in a typical session. Without it, Copilot will prompt you to approve each one.
 
-**In the GitHub Copilot CLI**, type `/agent` and select **Squad**.
-**In VS Code**, type `/agents` and select **Squad**.
+**In VS Code**, open Copilot Chat and select the **Squad** agent.
 
 Then:
 
@@ -245,7 +242,7 @@ export default defineSquad({
 });
 ```
 
-Run `squad build` to generate all the markdown. See the [SDK-First Mode Guide](docs/sdk-first-mode.md) for full documentation.
+Run `squad build` to generate all the markdown. See the [SDK-First Mode Guide](docs/src/content/docs/sdk-first-mode.md) for full documentation.
 
 ---
 

docs/src/content/docs/concepts/github-workflow.md

@@ -175,18 +175,7 @@ Board sync runs on label changes, issue close, PR merge, and a 30-minute schedul
 
 Your squad pings you when they need input, hit an error, or finish work. Squad uses MCP-based notification servers — you bring your own delivery channel.
 
-The flow:
-1. **Skill** (`human-notification`) tells agents when to ping
-2. **Agent** invokes your configured MCP server
-3. **MCP server** (Teams, Discord, iMessage, webhook) delivers the message
-
-| Trigger | Example |
-|---------|---------|
-| Blocked on input | "Keaton needs your decision on the API approach" |
-| Error hit | "McManus got an auth error — needs credentials" |
-| Work complete | "Fenster finished the test suite — 142 tests passing" |
-
-Configure in `.vscode/mcp.json` or `.copilot/mcp-config.json`. See the [MCP setup section in Portability & Extensions](portability.md) for configuration details.
+See the [Notifications Guide](../features/notifications.md) for [platform setup](../features/notifications.md#quick-start-teams-simplest-path) (Teams, Discord, iMessage, webhooks), [trigger configuration](../features/notifications.md#what-triggers-a-notification), and [sample MCP configs](../features/notifications.md#sample-mcp-configs).
 
 ---
 

docs/src/content/docs/concepts/memory-and-knowledge.md

@@ -210,6 +210,27 @@ Skills export and import with your team. Move a trained team to a new repo, and
 
 ---
 
+## Knowledge persistence
+
+Not all knowledge in `.squad/` lasts forever. When files grow large, Squad compacts them to keep performance fast. Here's what persists and what gets summarized:
+
+| What | File | Compacted? | Where old content goes | Who reads it |
+|------|------|-----------|----------------------|-------------|
+| Personal history | `history.md` | Yes, at ~12 KB | `history-archive.md` (preserved, read-only) | Owning agent |
+| Shared decisions | `decisions.md` | Yes, when large | `decisions-archive.md` (preserved, not loaded) | All agents |
+| Skills | `skills/{name}/SKILL.md` | Never | Grows indefinitely | All agents |
+| Directives | In `decisions.md` | With decisions | Archived with decisions | All agents |
+| Wisdom | `identity/wisdom.md` | Never | Permanent | All agents |
+| Casting registry | `casting/registry.json` | Never | Permanent | Coordinator |
+| Session logs | `log/*.md` | Never edited | Append-only archive | Read-only |
+| Orchestration logs | `orchestration-log/*.md` | Never edited | Append-only archive | Read-only |
+
+Knowledge that needs to survive compaction belongs in **skills**. Reusable patterns, code conventions, and technical techniques live here because they grow without limits. Team rules and preferences go in directives (stored in `decisions.md`) — they persist through compaction cycles because directives are preserved when decisions get summarized.
+
+> 💡 **Where to store permanent knowledge:** Put reusable patterns and techniques in `.squad/skills/`. Put team rules and preferences in directives (they persist in `decisions.md`). For org-wide knowledge that multiple teams need, use [upstream inheritance](/features/upstream-inheritance) to share a skills library.
+
+---
+
 ## Tips
 
 - **Commit `.squad/`** — anyone who clones the repo gets the team with all their accumulated knowledge.

docs/src/content/docs/concepts/portability.md

@@ -236,7 +236,7 @@ MCP (Model Context Protocol) servers extend Squad with external services. Agents
   "mcpServers": {
     "github": {
       "command": "node",
-      "args": ["/path/to/github-mcp.js"],
+      "args": ["/absolute/path/to/github-mcp.js"],
       "env": {
         "GITHUB_TOKEN": "$GITHUB_TOKEN"
       }

docs/src/content/docs/features/enterprise-platforms.md

@@ -102,18 +102,7 @@ All fields are optional. Omitted fields use the defaults shown above.
 
 Squad uses the Azure CLI for ADO authentication — **no Personal Access Tokens (PATs) needed.** Run `az login` once, and Squad agents use your authenticated session for all operations.
 
-Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. Add it to `.copilot/mcp-config.json`:
-
-```json
-{
-  "mcpServers": {
-    "azure-devops": {
-      "command": "npx",
-      "args": ["-y", "@azure/devops-mcp-server"]
-    }
-  }
-}
-```
+Alternatively, if the Azure DevOps MCP server is configured in your environment, Squad will use it automatically for richer API access. See [MCP Setup Guide](./mcp.md#mcp-configuration-files) for configuration instructions.
 
 Squad prefers MCP tools when available, falling back to `az` CLI when not.
 

docs/src/content/docs/features/mcp.md

@@ -19,13 +19,7 @@ MCP (Model Context Protocol) servers extend Squad with external services — Git
 
 ## What MCP Means for Squad
 
-**MCP (Model Context Protocol) servers extend your Squad environment.** Agents use MCP tools to send notifications, query GitHub, monitor deployments, integrate with Trello, and more. This guide walks you through configuring MCP services step-by-step.
-
----
-
-## What MCP Means for Squad
-
-MCP bridges Squad agents and external services. When your agents work, they can call any MCP-exposed tool — send notifications, check project status, update boards, or fetch live data. You define which services are available; agents discover and use them automatically.
+MCP bridges Squad agents and external services. Agents use MCP tools to send notifications, query GitHub, monitor deployments, integrate with Trello, and more. You define which services are available; agents discover and use them automatically.
 
 ---
 
@@ -72,7 +66,7 @@ Paste this base structure:
   "mcpServers": {
     "github": {
       "command": "node",
-      "args": ["path/to/github-mcp.js"],
+      "args": ["/absolute/path/to/github-mcp.js"],
       "env": {
         "GITHUB_TOKEN": "your-github-token-here"
       }
@@ -81,7 +75,7 @@ Paste this base structure:
 }
 ```
 
-Replace `path/to/github-mcp.js` with the actual path to your MCP server script. The `env` object passes environment variables to the server.
+Replace `/absolute/path/to/github-mcp.js` with the actual path to your MCP server script. The `env` object passes environment variables to the server.
 
 ### Step 3: Add your GitHub token
 
@@ -145,15 +139,15 @@ Click **"Edit in settings.json"** to see the raw configuration:
 "copilot.mcp.servers": {
   "github": {
     "command": "node",
-    "args": ["path/to/github-mcp.js"],
+    "args": ["/absolute/path/to/github-mcp.js"],
     "env": {
       "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
     }
   }
 }
 ```
 
-The `${env:GITHUB_TOKEN}` syntax reads from your shell environment.
+The `${env:GITHUB_TOKEN}` syntax reads from your shell environment. Replace `/absolute/path/to/github-mcp.js` with the actual path to your MCP server script.
 
 ### Step 4: Add environment variables
 
@@ -182,7 +176,7 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li
   "mcpServers": {
     "github": {
       "command": "node",
-      "args": ["/path/to/github-mcp.js"],
+      "args": ["/absolute/path/to/github-mcp.js"],
       "env": {
         "GITHUB_TOKEN": "$GITHUB_TOKEN"
       }
@@ -191,14 +185,16 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li
 }
 ```
 
+Replace `/absolute/path/to/github-mcp.js` with the actual path to your GitHub MCP server script.
+
 ### VS Code: `.vscode/settings.json`
 
 ```json
 {
   "copilot.mcp.servers": {
     "github": {
       "command": "node",
-      "args": ["/path/to/github-mcp.js"],
+      "args": ["/absolute/path/to/github-mcp.js"],
       "env": {
         "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
       }
@@ -207,14 +203,14 @@ Most Squad installs come with GitHub MCP pre-configured. Here's what it looks li
 }
 ```
 
+Replace `/absolute/path/to/github-mcp.js` with the actual path to your GitHub MCP server script.
+
 **What it does:**
-- List issues, PRs, and branches in your repo
+- List issues, PRs, and branches
 - Create, update, and search issues
-- Fetch commit history and diff info
+- Fetch commit history and diffs
 - Post and edit PR comments
 
-Agents automatically discover these tools and use them during work.
-
 ---
 
 ## Example: Trello MCP
@@ -228,14 +224,23 @@ Trello MCP lets agents interact with your Trello boards — create cards, move t
 3. Click "Tokens" and generate a new token (grant read/write permissions)
 4. Copy the **Token**
 
-### Step 2: Add to `.copilot/mcp-config.json`
+### Step 2: Add to your MCP config
 
+Add the Trello server configuration (see [MCP Configuration Files](#mcp-configuration-files) for CLI vs VS Code):
+
+| Variable | How to Get It |
+|----------|---------------|
+| `TRELLO_API_KEY` | Visit https://trello.com/app-key |
+| `TRELLO_TOKEN` | Click "Tokens" on the API key page, generate with read/write permissions |
+| `TRELLO_BOARD_ID` | Open any card, get ID from URL: `trello.com/c/{{CARD_ID}}/{{BOARD_ID}}/` |
+
+**Config template:**
 ```json
 {
   "mcpServers": {
     "trello": {
       "command": "node",
-      "args": ["/path/to/trello-mcp.js"],
+      "args": ["/absolute/path/to/trello-mcp.js"],
       "env": {
         "TRELLO_API_KEY": "your-api-key",
         "TRELLO_TOKEN": "your-token",
@@ -246,6 +251,8 @@ Trello MCP lets agents interact with your Trello boards — create cards, move t
 }
 ```
 
+Replace `/absolute/path/to/trello-mcp.js` with the actual path to your Trello MCP server script.
+
 Find your **board ID** by opening any card on Trello and looking at the URL: `trello.com/c/{{CARD_ID}}/{{BOARD_ID}}/`.
 
 ### Step 3: Test it
@@ -262,20 +269,15 @@ Agents will now automatically propose Trello tasks for tracking work items.
 
 ## Example: Aspire Dashboard MCP (Deployment Monitoring)
 
-For projects using .NET Aspire, the Aspire Dashboard MCP lets agents monitor deployments, check service health, and log errors.
-
-### Step 1: Start Aspire Dashboard
-
-Your project should have a dashboard running (usually `http://localhost:18888`).
-
-### Step 2: Configure MCP
+For .NET Aspire projects, configure the Aspire Dashboard MCP for deployment monitoring:
 
+**Config template:**
 ```json
 {
   "mcpServers": {
     "aspire": {
       "command": "node",
-      "args": ["/path/to/aspire-mcp.js"],
+      "args": ["/absolute/path/to/aspire-mcp.js"],
       "env": {
         "ASPIRE_URL": "http://localhost:18888",
         "ASPIRE_API_KEY": "optional-api-key"
@@ -285,6 +287,8 @@ Your project should have a dashboard running (usually `http://localhost:18888`).
 }
 ```
 
+Replace `/absolute/path/to/aspire-mcp.js` with the actual path to your Aspire MCP server script.
+
 ### Step 3: Use it
 
 Agents can now ask:
@@ -320,9 +324,9 @@ Agents don't need special setup to discover tools. Here's the flow:
 
 1. **Verify the command path:**
    ```bash
-   ls -la /path/to/mcp-server.js
+   ls -la /absolute/path/to/mcp-server.js
    ```
-   The file must exist and be executable.
+   The file must exist and be executable. Replace `/absolute/path/to/mcp-server.js` with your actual MCP server path.
 
 2. **Verify Node.js is installed:**
    ```bash
@@ -366,9 +370,9 @@ Agents don't need special setup to discover tools. Here's the flow:
 
 3. **Test the MCP server directly:**
    ```bash
-   node /path/to/mcp-server.js
+   node /absolute/path/to/mcp-server.js
    ```
-   It should start without errors. If it crashes, there's a server-side issue.
+   It should start without errors. If it crashes, there's a server-side issue. Replace `/absolute/path/to/mcp-server.js` with your actual MCP server path.
 
 ### Authentication Errors
 
@@ -414,13 +418,13 @@ Agents don't need special setup to discover tools. Here's the flow:
      "mcpServers": {
        "github": {
          "command": "node",
-        "args": ["/path/to/github-mcp.js"],
+        "args": ["/absolute/path/to/github-mcp.js"],
         "lazy": true
       }
     }
   }
    ```
-   This starts the server only when its first tool is called.
+   This starts the server only when its first tool is called. Replace `/absolute/path/to/github-mcp.js` with your actual MCP server path.
 
 ---