@@ -95,7 +95,8 @@ These community members shaped Squad through issues, discussions, and feedback.
 | Contributor | Contributions |
 |-------------|---------------|
 | [@dfberry](https://github.com/dfberry) | #241 (Squad member for docs), #157 (CFO/account member) — docs and team composition ideas |
-| [@diberry](https://github.com/diberry) | #211 (Squad management paradigms) — management approaches |
+| [@IEvangelist](https://github.com/IEvangelist) | PR #293 (Astro docs rewrite) — complete documentation site rebuild with Astro, Tailwind CSS, Pagefind search, responsive design. Massive contribution. |
+| [@diberry](https://github.com/diberry) | #211 (Squad management paradigms), PR #286 (Quick Start validation), PR #288 (installation decision tree), PR #290 (.squad/ directory explainer), PR #292 (doc-impact review process) — management approaches, documentation improvements across multiple PRs |
 | [@HemSoft](https://github.com/HemSoft) | #148 (GitHub Agent Workflows) — GAW concept |
 | [@sturlath](https://github.com/sturlath) | #156 (Team learning from others' work) — cross-agent learning |
 | [@tomasherceg](https://github.com/tomasherceg) | #184 (Multi-PR commit isolation), #237 (CLI wiring bug) — worktree improvements and bug reports |
 
@@ -70,4 +70,10 @@ const base = import.meta.env.BASE_URL;
   }
 
   overlay?.addEventListener('click', closeSidebar);
+
+  // Scroll the active TOC link into view on page load
+  const activeLink = sidebar?.querySelector('.sidebar-link.active');
+  if (activeLink && sidebar) {
+    activeLink.scrollIntoView({ block: 'center', behavior: 'instant' });
+  }
 </script>
@@ -0,0 +1,99 @@
+---
+title: "New Docs Site: Built by the Community"
+date: 2026-03-10
+author: "PAO (DevRel)"
+wave: 7
+tags: [squad, docs, community, astro, contributions]
+status: published
+hero: "Squad's documentation gets a complete rebuild — powered by Astro, Tailwind CSS, and community contributors."
+---
+
+# New Docs Site: Built by the Community
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+> _Squad's documentation site has been completely rebuilt from the ground up. A full Astro-powered docs experience with search, responsive design, and content contributed by multiple community members._
+
+---
+
+## What Shipped
+
+### Complete Astro Docs Rewrite
+
+[@IEvangelist](https://github.com/IEvangelist) (David Pine) delivered a **complete documentation site rebuild** in PR #293. This isn't a reskin — it's a ground-up rewrite:
+
+- **Astro 5.7** — Static site generation with component islands
+- **Tailwind CSS 4.1** — Modern utility-first styling with responsive design
+- **Pagefind** — Client-side full-text search across all docs
+- **Structured content** — Markdown content collections with frontmatter validation
+- **Blog system** — All existing blog posts migrated into the new architecture
+- **Custom components** — Sidebar with scroll-to-active, syntax-highlighted code blocks, callout boxes
+
+The site ships as a static build under `docs/` with its own `package.json`. Dev server: `npm run dev`. Production build: `astro build && pagefind`.
+
+### Community Content from @diberry
+
+[@diberry](https://github.com/diberry) (Dina Berry) submitted **four pull requests** improving the getting-started experience:
+
+- **PR #286** — Added validation steps to the Quick Start README
+- **PR #288** — "Which method should I use?" decision tree for the installation page — CLI, VS Code, or SDK, with clear guidance on when to use each
+- **PR #290** — ".squad/ directory explainer" for the first-session guide — a table showing every file and directory in `.squad/` with its purpose, plus ownership guidance
+- **PR #292** — Doc-impact review process added to team workflows
+
+All four contributions have been merged or ported into the new Astro docs structure.
+
+---
+
+## What Changed for Users
+
+### Better Navigation
+
+The sidebar now scrolls to your current position when a page loads. If you're deep in the table of contents, it stays where you are instead of jumping back to the top.
+
+### Copilot CLI Callouts
+
+Key pages now include callouts directing users to the **GitHub Copilot CLI** as the recommended interface:
+
+```
+💡 The recommended way to use Squad is through GitHub Copilot CLI:
+copilot --agent squad
+```
+
+### CI/CD Safety Warnings
+
+The CI/CD integration page now ships with the cron schedule **commented out by default** and a warning about GitHub Actions minutes consumption when enabling heartbeats and scheduled runs.
+
+---
+
+## Community Impact
+
+This release represents a milestone for Squad's community. Two external contributors shaped the docs you'll use:
+
+| Contributor | Impact |
+|-------------|--------|
+| [@IEvangelist](https://github.com/IEvangelist) | Complete Astro docs site architecture and build |
+| [@diberry](https://github.com/diberry) | Four PRs improving installation, getting-started, and team workflow docs |
+
+Both contributors are now credited in [CONTRIBUTORS.md](https://github.com/bradygaster/squad/blob/main/CONTRIBUTORS.md).
+
+---
+
+## Try It
+
+Visit the docs at [bradygaster.github.io/squad](https://bradygaster.github.io/squad/) or run them locally:
+
+```bash
+cd docs
+npm install
+npm run dev
+```
+
+Open [localhost:4321/squad/](http://localhost:4321/squad/) and explore.
+
+---
+
+## What's Next
+
+- Search refinements and indexing improvements
+- More scenario guides from community feedback
+- Continued content contributions welcome — see [CONTRIBUTING.md](https://github.com/bradygaster/squad/blob/main/CONTRIBUTING.md)
@@ -86,7 +86,25 @@ Say "yes" or skip straight to a task (which is implicit confirmation):
 > Yes. Dallas, set up the Express server with basic routing.
 ```
 
-Squad creates the `.squad/` directory structure — team roster, routing rules, casting state, ceremony config, agent charters, and histories — all seeded with your project context. Then it spawns Dallas:
+Squad creates the `.squad/` directory structure — team roster, routing rules, casting state, ceremony config, agent charters, and histories — all seeded with your project context.
+
+### What's inside .squad/?
+
+| File/Directory | Purpose |
+|---|---|
+| `team.md` | Team roster, roles, and member info |
+| `routing.md` | Work routing rules (which agent handles what) |
+| `decisions.md` | Team decisions — all agents read this before working |
+| `agents/` | Each agent's charter and history (their memory) |
+| `ceremonies.md` | Ceremony schedule (retrospectives, reviews, etc.) |
+| `casting/` | Team formation history and casting state |
+| `skills/` | Reusable capabilities agents can learn |
+
+**You own these files.** Edit them anytime — change roles, add routing rules, fix decisions. Squad reads them before every spawn.
+
+**Commit `.squad/` to version control.** It's your team's brain. Anyone who clones the repo gets the team with all their knowledge.
+
+Then it spawns Dallas:
 
 ```
 🔧 Dallas — setting up Express server with routing
 
@@ -59,6 +59,21 @@ npm install -g @bradygaster/squad-cli@latest
 
 ---
 
+## Which method should I use?
+
+Pick based on what you're doing:
+
+| **You want to...** | **Use** | **Why** |
+|--------------------|---------|---------|
+| Try Squad quickly | **CLI** with `npx` | No install needed. Run `npx @bradygaster/squad-cli init` and you're testing it. |
+| Use Squad across all projects | **CLI** with `--global` | One install. Works everywhere. Run `squad` from any terminal. |
+| Work inside VS Code | **VS Code** (just open your project) | Already using Copilot? Squad just works. Same `.squad/` directory as CLI. |
+| Build tools on top of Squad | **SDK** | Typed APIs, routing config, agent lifecycle hooks. Programmatic access to everything. |
+
+Can't decide? → Start with **CLI**. You can always add VS Code or the SDK later. Your `.squad/` directory works identically everywhere.
+
+---
+
 ## 2. VS Code
 
 Squad works in VS Code through GitHub Copilot. Your `.squad/` directory works identically in both CLI and VS Code — same agents, same decisions, same memory.
 
@@ -2,7 +2,9 @@
 
 > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
 
-The Squad interactive shell gives you a persistent connection to your team. Instead of spawning short-lived CLI invocations, the shell maintains a real-time session where you can talk to agents, issue commands, and watch work happen.
+> 💡 **Recommended: Use GitHub Copilot CLI** — The best way to interact with Squad today is through the [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli). Run `copilot --agent squad` to start a session with your team. The Copilot CLI provides the richest agent experience, including tool use, parallel execution, and full MCP integration.
+
+The Squad interactive shell gives you a persistent connection to your team.Instead of spawning short-lived CLI invocations, the shell maintains a real-time session where you can talk to agents, issue commands, and watch work happen.
 
 ---
 
 
@@ -49,7 +49,7 @@ squad init
 | `squad aspire` | Launch Aspire dashboard for observability | No |
 | `squad aspire --docker` | Force Docker mode for Aspire | No |
 | `squad upstream add\|remove\|list\|sync` | Manage upstream Squad sources | Yes |
-| `squad shell` | Launch interactive shell explicitly | No |
+| `copilot --agent squad` | Launch interactive shell explicitly | No |
 | `squad nap` | Context hygiene (compress, prune, archive .squad/ state) | Yes |
 | `squad nap --deep` | Thorough cleanup with recursive descent | Yes |
 | `squad nap --dry-run` | Preview cleanup actions without changes | Yes |
 
@@ -28,8 +28,8 @@ The workflow is in `.github/workflows/squad-heartbeat.yml` and runs every 6 hour
 ```yaml
 name: Ralph Heartbeat
 on:
-  schedule:
-    - cron: '0 */6 * * *'  # Every 6 hours
+  # schedule:
+  #   - cron: '0 */6 * * *'  # Every 6 hours
   workflow_dispatch:
 
 jobs:
@@ -41,6 +41,8 @@ jobs:
         run: squad heartbeat
 ```
 
+> ⚡ **Cron is commented out by default.** The heartbeat schedule is disabled when Squad installs the workflow — it only runs via manual `workflow_dispatch` until you uncomment the `schedule` block. Be aware: enabling scheduled heartbeats will consume GitHub Actions minutes on every run. A 6-hour cron burns ~120 runs/month. Adjust the frequency to match your budget, or leave it manual and trigger heartbeats from the CLI with `squad heartbeat`.
+
 Ralph reads `.squad/routing.md`, looks at open issues, and applies labels:
 
 ```
 
@@ -266,7 +266,7 @@ const base = import.meta.env.BASE_URL;
           <div class="inline-flex items-center justify-center w-12 h-12 rounded-2xl bg-squad-600 text-white font-bold text-lg mb-5 shadow-lg shadow-squad-600/25">3</div>
           <h3 class="font-semibold text-surface-900 dark:text-white mb-2">Ship</h3>
           <p class="text-sm text-surface-600 dark:text-surface-400 mb-4 flex-1">Talk to your team — they build, test, and land PRs.</p>
-          <code class="text-sm font-mono bg-surface-100 dark:bg-surface-800 text-surface-700 dark:text-green-400 px-3 py-1.5 rounded-lg border border-surface-200 dark:border-transparent">squad shell</code>
+          <code class="text-sm font-mono bg-surface-100 dark:bg-surface-800 text-surface-700 dark:text-green-400 px-3 py-1.5 rounded-lg border border-surface-200 dark:border-transparent">copilot --agent squad</code>
         </div>
       </div>
     </div>