bradygaster · bradygaster · Mar 23, 2026 · Mar 22, 2026 · Mar 22, 2026 · Mar 22, 2026
@@ -29,6 +29,10 @@
 | `.ai-team/` directory | `.squad/` directory |
 | v0.5.4 (beta) | v0.8.x (latest) |
 
+> **Distribution changed at v0.8.0**
+>
+> Versions before v0.8.0 were distributed exclusively through GitHub (`npx github:bradygaster/squad`). Starting with v0.8.0, Squad moved to npm under two packages: `@bradygaster/squad-cli` (CLI) and `@bradygaster/squad-sdk` (SDK). The `npx github:` path no longer works for any version. If you see it referenced in older docs or blog posts for versions before v0.8.0, that was historically accurate — but you can't use it today. For v0.8.0 and later, use `npm install -g @bradygaster/squad-cli`.
+
 ---
 
 ## Scenario 1: Brand New User
@@ -212,7 +216,7 @@ The `squad` command works the same way. Your `.squad/` directory does not need t
 
 ## Scenario 5: Was Using npx github: Distribution
 
-The GitHub-native distribution (`npx github:bradygaster/squad`) has been removed. Squad is now distributed exclusively through npm.
+The GitHub-native distribution (`npx github:bradygaster/squad`) has been removed. Squad is now distributed exclusively through npm. This change happened at v0.8.0 — versions before v0.8.0 only ever existed on GitHub, so if you were on a pre-0.8.0 version, v0.8.0 is where the npm packages began.
 
 ### Switch
 

@@ -17,19 +17,21 @@ The Insider Program gives you continuous access to development builds of Squad.
 
 ## How to Install and Upgrade
 
-### Install Insider Build
+### Install insider build
 
 ```bash
-npx github:bradygaster/squad#insider
+npm install -g @bradygaster/squad-cli@insider
 ```
 
-### Upgrade Existing Repo to Insider
+### Upgrade to latest insider build
+
+Run the same install command — npm handles the upgrade:
 
 ```bash
-npx github:bradygaster/squad#insider upgrade
+npm install -g @bradygaster/squad-cli@insider
 ```
 
-This updates Squad-owned files (`squad.agent.md`, workflows, templates) to the latest insider build. Your `.squad/` team state (agents, decisions, casting, history) is always preserved.
+This updates your CLI to the latest insider build. Your `.squad/` team state (agents, decisions, casting, history) is always preserved.
 
 ---
 
@@ -75,7 +77,7 @@ You'll see this in your `squad.agent.md` HTML version comment:
 **Pin a specific tagged version:**
 
 ```bash
-npx github:bradygaster/squad#v0.5.2-insider+<sha>
+npm install -g @bradygaster/squad-cli@<version>
 ```
 
 ---
@@ -102,7 +104,7 @@ Version: v0.4.2-insider+abc1234f
 Environment: CLI on macOS 14.1, Node 20.11.0
 
 Steps:
-1. npx github:bradygaster/squad#insider
+1. npm install -g @bradygaster/squad-cli@insider
 2. Follow quick start
 3. Error in squad.agent.md...
 ```
@@ -114,10 +116,10 @@ Steps:
 Want to go back to stable releases?
 
 ```bash
-npx github:bradygaster/squad
+npm install -g @bradygaster/squad-cli
 ```
 
-This installs the latest stable version. Your `.ai-team/` state is safe — it'll work with any version.
+This installs the latest stable version. Your `.squad/` state is safe — it'll work with any version.
 
 ---
 
@@ -129,23 +131,22 @@ This installs the latest stable version. Your `.ai-team/` state is safe — it'l
 
 ### Q: Can I switch between insider and stable builds?
 
-**A:** Yes. Insider builds are backward compatible with stable installs. Your `.ai-team/` directory works with any version.
+**A:** Yes. Insider builds are backward compatible with stable installs. Your `.squad/` directory works with any version.
 
 ### Q: How often do insider builds update?
 
 **A:** As often as commits land on the `insider` branch. Could be daily, could be weekly — depends on the dev cycle. Run the install command again to fetch the latest.
 
 ### Q: Will my team state be preserved?
 
-**A:** Yes. `.ai-team/` is never overwritten on upgrade. All your agents, decisions, and histories are safe.
+**A:** Yes. `.squad/` is never overwritten on upgrade. All your agents, decisions, and histories are safe.
 
 ### Q: What if an insider build has a bad bug?
 
 **A:** Roll back immediately:
 
 ```bash
-npx github:bradygaster/squad                  # Back to stable
-npx github:bradygaster/squad upgrade          # Apply stable version
+npm install -g @bradygaster/squad-cli         # Back to stable
 ```
 
 Then [report the issue](https://github.com/bradygaster/squad/issues).

@@ -14,8 +14,8 @@ Squad runs on multiple Copilot surfaces — each with its own agent spawning mec
 | **Background/async execution** | ✅ `mode: "background"` (fire-and-forget) | ⚠️ Sync only (parallel concurrent) | ? | ? |
 | **Parallel fan-out** | ✅ Background tasks + `read_agent` | ✅ Multiple subagents in one turn | ? | ? |
 | **File discovery (.github/agents/)** | ✅ Automatic | ✅ Automatic | ? | ? |
-| **`.ai-team/` file access (read)** | ✅ Full | ✅ Full (workspace-scoped) | ? | ? |
-| **`.ai-team/` file access (write)** | ✅ Full | ✅ Full (with approval prompt) | ? | ? |
+| **`.squad/` file access (read)** | ✅ Full | ✅ Full (workspace-scoped) | ? | ? |
+| **`.squad/` file access (write)** | ✅ Full | ✅ Full (with approval prompt) | ? | ? |
 | **SQL tool** | ✅ Available | ❌ Not available | ❌ Not available | ❌ Not available |
 | **MCP server access** | ✅ Full | ✅ Full (inherited) | ⚠️ Limited | ⚠️ Limited |
 
@@ -69,7 +69,7 @@ Squad's **primary platform**. All features are fully supported.
 ### File Discovery & Access
 
 - **Auto-discovery:** `.github/agents/squad.agent.md` is discovered automatically
-- **`.ai-team/` access:** Unrestricted (full filesystem)
+- **`.squad/` access:** Unrestricted (full filesystem)
 - **Parallel reads:** Multiple file operations in one turn supported
 - **Parallel writes:** Multiple file creates/edits in one turn supported
 
@@ -123,8 +123,8 @@ Squad runs on VS Code with **conditional support**. Key differences from CLI:
 
 - **Auto-discovery:** `.github/agents/squad.agent.md` auto-discovered from workspace on load (file watchers enabled — no restart needed on changes)
 - **Scope:** Workspace-scoped (cannot access outside workspace directory)
-- **`.ai-team/` read:** ✅ Full access via `readFile` tool
-- **`.ai-team/` write:** ✅ Full access via `createFile` / `editFiles` tools
+- **`.squad/` read:** ✅ Full access via `readFile` tool
+- **`.squad/` write:** ✅ Full access via `createFile` / `editFiles` tools
 - **First-time approval:** VS Code may prompt for file modification approval on first write (security feature)
   - **User experience:** "Always allow in this workspace" option available
   - Subsequent writes in same workspace are automatic
@@ -160,7 +160,7 @@ Squad runs on VS Code with **conditional support**. Key differences from CLI:
 ### Questions to Answer
 
 - Does JetBrains Copilot support agent spawning via a tool equivalent to `task` or `runSubagent`?
-- Can agents access workspace files and `.ai-team/` directories?
+- Can agents access workspace files and `.squad/` directories?
 - What model selection mechanisms exist?
 - Is there a background/async mode?
 
@@ -179,7 +179,7 @@ Squad runs on VS Code with **conditional support**. Key differences from CLI:
 ### Questions to Answer
 
 - Can GitHub Copilot spawn agents for background work?
-- Can agents read `.ai-team/` files from the repository?
+- Can agents read `.squad/` files from the repository?
 - Is there a GitHub-specific command protocol for delegation?
 
 ---
@@ -203,7 +203,7 @@ Squad runs on VS Code with **conditional support**. Key differences from CLI:
 **Using Both:**
 - CLI is recommended for initial Squad setup and learning
 - VS Code works for day-to-day development once Squad is established
-- They share the same `.ai-team/` state — both can read/write the same team files
+- They share the same `.squad/` state — both can read/write the same team files
 - Team state is portable — init in CLI, use in VS Code, export/import across repos
 
 ### For Squad Developers
@@ -252,7 +252,7 @@ This document is based on active research spikes (#32, #33, #34) conducted in Fe
 
 - **Proposal 032a** (Strausz): `runSubagent` API research — agent spawning mechanics on VS Code
 - **Proposal 032b** (Kujan): CLI spawn parity analysis — all 5 Squad spawn patterns mapped
-- **Proposal 033a** (Strausz): VS Code file discovery — `.ai-team/` access and workspace scoping
+- **Proposal 033a** (Strausz): VS Code file discovery — `.squad/` access and workspace scoping
 - **Proposal 034a** (Kujan): Model selection & background mode — per-agent model routing and async execution
 
 **Next steps:**

@@ -2,7 +2,7 @@
 
 **Try this to recover from data loss:**
 ```
-My .ai-team/ directory was deleted — help me recover the team state
+My .squad/ directory was deleted — help me recover the team state
 ```
 
 **Try this to revert bad code:**
@@ -15,33 +15,33 @@ An agent wrote bad code — how do I revert it?
 The squad is confused — reset their context
 ```
 
-Recovery procedures for deleted `.ai-team/`, bad agent code, confused squads, and upgrade issues. Most problems are fixable with Git or re-init.
+Recovery procedures for deleted `.squad/`, bad agent code, confused squads, and upgrade issues. Most problems are fixable with Git or re-init.
 
 ---
 
-## 1. "I accidentally deleted `.ai-team/`"
+## 1. "I accidentally deleted `.squad/`"
 
-Recovery scenarios: deleted `.ai-team/`, bad agent code, confused squad, upgrade issues.
+Recovery scenarios: deleted `.squad/`, bad agent code, confused squad, upgrade issues.
 
 **Solution:** It's in Git. Restore it.
 
 ```bash
-git checkout .ai-team/
+git checkout .squad/
 ```
 
-If you haven't committed `.ai-team/` yet, it's gone. Rebuild:
+If you haven't committed `.squad/` yet, it's gone. Rebuild:
 
 ```bash
-npx github:bradygaster/squad
+npx @bradygaster/squad-cli
 ```
 
 Start from scratch. If you exported your squad before, import the export:
 
 ```bash
-npx github:bradygaster/squad import squad-export-2025-07-15.zip
+npx @bradygaster/squad-cli import squad-export-2025-07-15.zip
 ```
 
-**Prevention:** Commit `.ai-team/` early. Don't let it stay uncommitted for long.
+**Prevention:** Commit `.squad/` early. Don't let it stay uncommitted for long.
 
 ---
 
@@ -85,7 +85,7 @@ Sonny reads the code, fixes the issue, commits.
 
 ## 3. "An agent made a wrong decision"
 
-**What happened:** Neo decided to use REST when GraphQL was the better choice. The decision is logged in `.ai-team/decisions.md`.
+**What happened:** Neo decided to use REST when GraphQL was the better choice. The decision is logged in `.squad/decisions.md`.
 
 **Solution:** Add a directive to override it.
 
@@ -125,7 +125,7 @@ Agents now read the new decision and build accordingly.
 ```
 📋 Scribe — archiving recent session histories
 
-Moved to .ai-team/history-archive/:
+Moved to .squad/history-archive/:
   - Neo's session from 2025-07-14
   - Morpheus's session from 2025-07-14
   - Trinity's session from 2025-07-14
@@ -141,11 +141,11 @@ Agents **forget** the bad session. They still have their long-term skills and de
 
 ## 5. "I want to start over completely"
 
-**Solution:** Delete `.ai-team/` and reinstall.
+**Solution:** Delete `.squad/` and reinstall.
 
 ```bash
-rm -rf .ai-team/
-npx github:bradygaster/squad
+rm -rf .squad/
+npx @bradygaster/squad-cli
 ```
 
 ```
@@ -162,11 +162,11 @@ You're back to day one. Clean slate.
 
 **What happened:** You upgraded Squad to a new version, and now something doesn't work.
 
-**Solution:** Squad upgrades **never touch** `.ai-team/`. The issue is likely in:
+**Solution:** Squad upgrades **never touch** `.squad/`. The issue is likely in:
 
-1. **Workflow templates** — check `.ai-team-templates/`
+1. **Workflow templates** — check `.squad-templates/`
 2. **Squad agent definition** — check `.github/agents/squad.agent.md`
-3. **Model configuration** — check `.ai-team/model-config.json`
+3. **Model configuration** — check `.squad/model-config.json`
 
 Roll back the Squad agent definition:
 
@@ -177,10 +177,10 @@ git checkout HEAD^ .github/agents/squad.agent.md
 Or reinstall the previous version:
 
 ```bash
-npx github:bradygaster/squad@0.1.5
+npx @bradygaster/squad-cli@0.1.5
 ```
 
-**Your team's knowledge is safe.** `.ai-team/` is untouched.
+**Your team's knowledge is safe.** `.squad/` is untouched.
 
 **Prevention:** Check the CHANGELOG before upgrading. If the upgrade is major, test in a branch first.
 
@@ -211,17 +211,17 @@ Or just close the Copilot session (Ctrl+C) and start a new one.
 
 ## 8. "Skills are outdated or wrong"
 
-**What happened:** A skill file in `.ai-team/skills/` contains outdated information. Agents are following bad advice.
+**What happened:** A skill file in `.squad/skills/` contains outdated information. Agents are following bad advice.
 
 **Solution:** Edit or delete the skill file.
 
 ```bash
 # Edit the skill
-code .ai-team/skills/auth-rate-limiting.md
+code .squad/skills/auth-rate-limiting.md
 
 # Or delete it
-rm .ai-team/skills/auth-rate-limiting.md
-git add .ai-team/skills/
+rm .squad/skills/auth-rate-limiting.md
+git add .squad/skills/
 git commit -m "Remove outdated auth rate limiting skill"
 ```
 
@@ -231,13 +231,13 @@ git commit -m "Remove outdated auth rate limiting skill"
 
 ## 9. "Decisions.md is a mess"
 
-**What happened:** `.ai-team/decisions.md` has 200 entries and it's hard to find anything.
+**What happened:** `.squad/decisions.md` has 200 entries and it's hard to find anything.
 
 **Solution:** Archive old decisions.
 
 ```
 > Scribe, archive decisions older than 3 months. Move them to
-> .ai-team/decisions-archive.md.
+> .squad/decisions-archive.md.
 ```
 
 ```
@@ -284,10 +284,10 @@ Each agent logs what they did in their `history.md`.
 
 ## Tips
 
-- **`.ai-team/` is in Git.** If you delete it, restore from Git. If it's uncommitted, it's gone.
+- **`.squad/` is in Git.** If you delete it, restore from Git. If it's uncommitted, it's gone.
 - **Code review catches bad agent code.** Use the Lead to review before merging.
 - **Override bad decisions with directives.** If an agent made the wrong call, tell the team the correct one.
 - **Archive confused histories.** If a session went badly, archive the learnings so agents forget.
-- **Upgrades don't touch `.ai-team/`.** Your team's knowledge is safe across upgrades.
+- **Upgrades don't touch `.squad/`.** Your team's knowledge is safe across upgrades.
 - **Edit skill files directly.** They're just markdown. If a skill is wrong, fix it or delete it.
 - **Agent histories are the audit log.** Check them to see what each agent did.