docs: add docs quality CI — markdown lint, spell check, link validation

.github/workflows/squad-ci.yml

@@ -11,6 +11,24 @@ permissions:
   contents: read
 
 jobs:
+  docs-quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install docs tools
+        run: npm install --no-save markdownlint-cli2 cspell
+
+      - name: Lint docs markdown
+        run: npx markdownlint-cli2
+
+      - name: Spell check docs
+        run: npx cspell --no-progress --dot "docs/src/content/**/*.md" "README.md"
+
   test:
     runs-on: ubuntu-latest
     steps:

.github/workflows/squad-docs-links.yml

@@ -0,0 +1,37 @@
+name: Docs — Weekly Link Check
+
+on:
+  schedule:
+    - cron: '0 9 * * 1'  # Monday 9am UTC
+  workflow_dispatch:
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check external links
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: >-
+            --verbose
+            --no-progress
+            --exclude-mail
+            --timeout 30
+            --max-retries 3
+            --accept 200..=299,403,429
+            'docs/src/content/**/*.md'
+            'README.md'
+          fail: false
+
+      - name: Create issue on broken links
+        if: steps.lychee.outputs.exit_code != 0
+        uses: peter-evans/create-issue-from-file@v5
+        with:
+          title: '🔗 Broken external links detected'
+          content-filepath: ./lychee/out.md
+          labels: docs, automated

.lycheeignore

@@ -0,0 +1,12 @@
+# Rate-limited or auth-gated URLs
+https://github.com/.*/edit/.*
+https://dev.azure.com/.*
+https://.*\.visualstudio\.com/.*
+# Localhost references in examples
+localhost
+127\.0\.0\.1
+# Template/placeholder URLs
+https://example\.com
+https://your-.*
+# npm registry (rate limits)
+https://www.npmjs.com/package/.*

.markdownlint-cli2.jsonc

@@ -0,0 +1,28 @@
+{
+  "config": {
+    "default": true,
+    "MD013": false,           // Line length — docs are prose, not code
+    "MD033": false,           // Inline HTML — Astro components use HTML in markdown
+    "MD041": false,           // First line heading — some docs don't start with heading
+    "MD024": false,           // Duplicate headings — OK in long docs
+    "MD025": { "front_matter_title": "" }, // Single H1
+    "MD009": false,           // Trailing spaces — can conflict with intentional formatting
+    "MD012": false,           // Multiple blank lines — common in docs for readability
+    "MD028": false,           // Blank line inside blockquote — blog frontmatter
+    "MD060": false,           // Table column style — existing blog tables
+    "MD049": false,           // Emphasis style — existing blog content uses mixed styles
+    "MD032": false,           // Lists surrounded by blank lines — existing docs
+    "MD031": false,           // Fenced code blocks surrounded by blank lines
+    "MD040": false,           // Fenced code language — not all code blocks need lang
+    "MD022": false,           // Headings surrounded by blank lines — blog posts
+    "MD029": false,           // Ordered list item prefix — intentional restarts
+    "MD036": false,           // Emphasis as heading — blog/guide formatting
+    "MD014": false,           // Dollar signs before commands — code examples
+    "MD034": false,           // Bare URLs — many existing bare URLs in docs
+    "MD004": false,           // Unordered list style — mixed styles in docs
+    "MD026": false,           // Trailing punctuation in heading — existing style
+    "MD051": false            // Link fragments — will be caught by link validation test
+  },
+  "globs": ["docs/src/content/**/*.md", "README.md"],
+  "ignores": ["node_modules", "docs/dist", "docs/node_modules", ".squad"]
+}

cspell.json

@@ -0,0 +1,42 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "files": ["docs/src/content/**/*.md", "README.md"],
+  "ignorePaths": ["node_modules", "docs/dist", "*.json", "*.ts", "*.js", ".squad"],
+  "words": [
+    "squad", "bradygaster", "astro", "pagefind", "starlight",
+    "copilot", "subagent", "subagents", "MCP", "REPL", "CLI", "DevRel",
+    "monorepo", "codespace", "codespaces", "worktree", "worktrees", "frontmatter",
+    "ralph", "scribe", "pao", "fido", "eecom", "capcom",
+    "retro", "inco", "guido", "booster", "gnc", "dsky", "vox",
+    "sims", "telemetry", "handbook",
+    "WIQL", "webhook", "webhooks", "dedup", "deduplicate",
+    "triage", "triaging", "untriaged", "kanban", "lifecycle",
+    "PRD", "SDK", "ADO", "RBAC", "OAuth", "JWT",
+    "Aspire", "Bicep", "Terraform", "Kubernetes",
+    "orchestrator", "orchestration", "runSubagent",
+    "Kujan", "kobayashi", "Kobayashi", "squadify",
+    "amolchanov", "Shayne", "spboyer", "mcmanus", "csharpfritz",
+    "anthropics", "dnoriegagoodwin", "unconfigured", "upgraders",
+    "Tamir", "Dresher", "Tetris", "tamirdresher", "tetris",
+    "Riker", "riker", "Troi", "Geordi", "Worf",
+    "recompiles", "edie", "Edie", "myorg", "myproject", "myrepo",
+    "WDATP", "wiisaacs", "Trejo", "Drucker", "dfberry", "diberry",
+    "unstarted", "ZUAER", "glab", "mlops", "Baer",
+    "devtunnel", "Devtunnel", "mysecret", "pyproject",
+    "Emmitt", "jsturtevant", "Sturtevant", "aadnesd", "Sardo",
+    "digitaldrummerj", "danielscholl", "llms", "dkirby", "lbouriez",
+    "vanartsdalen", "Artsdalen", "craigb", "tomasherceg", "Tomáš", "Herceg",
+    "uvirk", "Uday", "Eirik", "Haughom", "tihomir", "Tihomir",
+    "fboucher", "Pruthviraj", "cobey", "wbreza", "Breza",
+    "jbruce", "frankhaugen", "Haugen", "chrislomonico",
+    "johnwc", "swnger", "sturlath", "Fredo",
+    "Pomodoro", "pomodoro", "WASD", "Blazor", "narratively",
+    "MSMQ", "permadeath", "Permadeath", "CRDT", "httpx",
+    "Pydantic", "sdkgen", "ttft", "Strausz", "mycompany",
+    "slugified", "simplejwt", "pytest", "Luca", "Clemenza",
+    "Tessio", "Triaging", "Futurama", "mklink", "slnx", "jqlang"
+  ],
+  "dictionaries": ["en_US", "typescript", "node", "npm", "bash"],
+  "allowCompoundWords": true
+}

docs/src/content/docs/scenarios/client-compatibility.md

@@ -267,4 +267,4 @@ This document is based on active research spikes (#32, #33, #34) conducted in Fe
 - [Model Selection](../features/model-selection.md) — Cost-first routing across agents
 - [Parallel Execution](../features/parallel-execution.md) — Background and sync patterns
 - [Worktrees](../features/worktrees.md) — Multi-branch isolation
-- [FAQ](../guide.md#troubleshooting) — Common questions and answers
+- [Troubleshooting](./troubleshooting.md) — Common questions and answers