chore: trim npm package — exclude docs and contributor files (#48)

* chore: unignore .ai-team/ for dev branches, update contributing guide

- Removed .ai-team/ from .gitignore so team files can be committed on dev/feature branches
- Updated CONTRIBUTING.md to reflect guard workflow as enforcement (not .gitignore)
- Updated guard workflow error message in both live and template copies
- .npmignore still excludes .ai-team/ from the published package

* chore: trim npm package — exclude docs, CONTRIBUTING.md, .gitignore

- Removed docs/ from package.json files allowlist (read on GitHub, not runtime)
- Added CONTRIBUTING.md, .gitignore, docs/ to .npmignore (belt-and-suspenders)
- Package: 82 files / 205.7kB -> 30 files / 75.1kB (63% smaller)

---------

Co-authored-by: bradygaster <bradygaster@users.noreply.github.com>

Author: bradygaster

.github/workflows/squad-main-guard.yml

@@ -81,8 +81,9 @@ jobs:
               'git push',
               '```',
               '',
-              '> ⚠️ `.ai-team/` is in `.gitignore` but files previously force-added with `git add -f`',
-              '> remain tracked. `git rm --cached` untracks them without deleting your local copies.',
+              '> ⚠️ `.ai-team/` is committed on `dev` and feature branches by design.',
+              '> The guard workflow is the enforcement mechanism that keeps these files off `main` and `preview`.',
+              '> `git rm --cached` untracks them from this PR without deleting your local copies.',
             ];
 
             core.setFailed(lines.join('\n'));

.gitignore

@@ -10,11 +10,10 @@ Thumbs.db
 # Node (if we add tooling later)
 node_modules/
 
-# Squad team state (created at runtime, never committed)
-# ⚠️ NEVER force-add these files (git add -f .ai-team/).
-# Previously force-added files remain tracked even with this rule.
-# If tracked files leak in, remove them: git rm --cached -r .ai-team/
-.ai-team/
+# Squad team state — committed on dev and feature branches,
+# blocked from main/preview by squad-main-guard.yml workflow.
+# ⚠️ NEVER merge .ai-team/ into main or preview.
+# The guard workflow will fail the PR if you try.
 
 # Squad Squad templates (internal, not distributed)
 .ai-team-templates/

.npmignore

@@ -1,6 +1,6 @@
 # Squad Squad — team state and development files
 # These are excluded from the distributed package.
-# The product ships: index.js, templates/, docs/, CHANGELOG.md, .github/agents/squad.agent.md
+# The product ships: index.js, templates/, CHANGELOG.md, .github/agents/squad.agent.md
 # (also enforced by package.json "files" field)
 
 # Squad Squad (the AI team that builds Squad)
@@ -10,13 +10,20 @@
 # Internal team docs (proposals, sprint plans — never shipped)
 team-docs/
 
+# Public docs (read on GitHub, not needed at runtime)
+docs/
+
 # Tests
 test/
 
 # Git/repo config not needed at runtime
+.gitignore
 .gitattributes
 .github/workflows/
 
+# Repo contributor docs (not needed by users)
+CONTRIBUTING.md
+
 # Editor / OS
 .vscode/
 .DS_Store

CONTRIBUTING.md

@@ -62,8 +62,8 @@ Squad uses a three-tier branch structure to protect production and staging while
 
 | Branch | Purpose | Protection | Files Allowed |
 |--------|---------|------------|---------------|
-| **`dev`** | Development & integration | None | ✅ Everything |
-| **`feature/squad/{issue}-{slug}`** | Feature work | None — merge to dev | ✅ Everything |
+| **`dev`** | Development & integration | None | ✅ Everything (including `.ai-team/`) |
+| **`feature/squad/{issue}-{slug}`** | Feature work | None — merge to dev | ✅ Everything (including `.ai-team/`) |
 | **`preview`** | Staging & release candidate | Guard checks for `.ai-team/`, `team-docs/` (except blog/) | ✅ Most files — see [Protected Files](#whats-protected) |
 | **`main`** | Production & releases | Guard checks for `.ai-team/`, `team-docs/` (except blog/) | ✅ Most files — see [Protected Files](#whats-protected) |
 
@@ -97,15 +97,15 @@ git push origin squad/42-auth-refresh
 
 ### 🚫 CRITICAL: Files Blocked from `main` and `preview`
 
-These files are **runtime team state** and belong on development branches only:
+These files are **runtime team state** and live on `dev` and feature branches. They are committed to git and flow freely between `dev` and feature branches, but the **guard workflow** (`squad-main-guard.yml`) blocks them from reaching `main` or `preview`:
 
-| Path | Reason | Merged to main? |
-|------|--------|-----------------|
-| **`.ai-team/**`** | Agent charters, routing, decisions, history, casting registry | ❌ NEVER |
-| **`team-docs/` (except `team-docs/blog/`** | Internal team documentation, sprint plans, notes | ❌ NEVER |
-| **`team-docs/blog/**`** | Public blog content | ✅ YES — blog posts are public |
+| Path | Reason | Committed to `dev`? | Merged to `main`/`preview`? |
+|------|--------|---------------------|---------------------------|
+| **`.ai-team/**`** | Agent charters, routing, decisions, history, casting registry | ✅ YES | ❌ NEVER — guard blocks |
+| **`team-docs/` (except `team-docs/blog/`** | Internal team documentation, sprint plans, notes | ✅ YES | ❌ NEVER — guard blocks |
+| **`team-docs/blog/**`** | Public blog content | ✅ YES | ✅ YES |
 
-**Why?** `.ai-team/` contains persistent agent knowledge, routing rules, and decision history. It's internal infrastructure. If it leaks to `main`, you're shipping developer metadata as product. `team-docs/` is working notes — only blog content is publication-ready.
+**Why?** `.ai-team/` contains persistent agent knowledge, routing rules, and decision history. It's internal infrastructure that belongs on development branches — not in production. The guard workflow is the enforcement mechanism, not `.gitignore`. `.ai-team/` is NOT in `.gitignore` — it's a normal part of the `dev` branch. The `.npmignore` file ensures it's excluded from the published npm package.
 
 ### ✅ Files That Flow Freely
 
@@ -171,7 +171,7 @@ If you accidentally (or intentionally) target `preview` or `main`, the **guard w
 If the guard blocks your PR because it contains `.ai-team/` or `team-docs/` files:
 
 ```bash
-# Remove .ai-team/ from git (keeps local copies safe)
+# Remove .ai-team/ from this PR (keeps local copies and dev branch copies safe)
 git rm --cached -r .ai-team/
 
 # Remove team-docs/ except blog/
@@ -183,7 +183,7 @@ git commit -m "chore: remove internal team files from PR"
 git push
 ```
 
-The workflow will re-run and pass. Your local `.ai-team/` and `team-docs/` files remain untouched.
+The workflow will re-run and pass. Your local `.ai-team/` and `team-docs/` files remain untouched, and they continue to exist on `dev` normally.
 
 ---
 
@@ -289,18 +289,18 @@ You don't need to add these yourself — the Lead will triage and label issues.
 
 ```
 squad/
-├── .ai-team/                  🚫 BLOCKED from main/preview
-│   ├── agents/
-│   │   ├── {name}/charter.md  🚫 BLOCKED
-│   │   └── {name}/history.md  🚫 BLOCKED
-│   ├── team.md                🚫 BLOCKED
-│   ├── routing.md             🚫 BLOCKED
-│   ├── decisions.md           🚫 BLOCKED
+├── .ai-team/                  ✅ Committed on dev & feature branches
+│   ├── agents/                🚫 Guard blocks from main/preview
+│   │   ├── {name}/charter.md  🚫 Guard blocks from main/preview
+│   │   └── {name}/history.md  🚫 Guard blocks from main/preview
+│   ├── team.md                🚫 Guard blocks from main/preview
+│   ├── routing.md             🚫 Guard blocks from main/preview
+│   ├── decisions.md           🚫 Guard blocks from main/preview
 │   └── ...
 │
-├── team-docs/                 🚫 BLOCKED (except blog/)
-│   ├── sprint-plan.md         🚫 BLOCKED
-│   ├── roadmap.md             🚫 BLOCKED
+├── team-docs/                 🚫 Guard blocks from main/preview (except blog/)
+│   ├── sprint-plan.md         🚫 Guard blocks from main/preview
+│   ├── roadmap.md             🚫 Guard blocks from main/preview
 │   └── blog/                  ✅ ALLOWED (public content)
 │       └── 001-launch.md      ✅ ALLOWED
 │
@@ -342,20 +342,22 @@ When you open a PR to `main` or `preview`, the workflow `.github/workflows/squad
    - ✅ **Pass:** "No forbidden paths found" — you're good to merge
    - ❌ **Fail:** Lists forbidden files and shows `git rm --cached` fix
 
-The guard is **not a suggestion** — it's a hard stop. But it's easy to fix if it blocks you (see [Fixing a Blocked PR](#fixing-a-blocked-pr)).
+The guard is **not a suggestion** — it's a hard stop. This is the primary enforcement mechanism that keeps `.ai-team/` and internal `team-docs/` off `main` and `preview`. But it's easy to fix if it blocks you (see [Fixing a Blocked PR](#fixing-a-blocked-pr)).
 
 ---
 
 ## FAQ
 
 ### Q: I accidentally committed `.ai-team/` to my feature branch. Do I have to delete it?
 
-**A:** No! `.ai-team/` is in `.gitignore`, so it won't push to GitHub unless you force-add it. Just keep your feature branch clean:
+**A:** Nope — `.ai-team/` files are **supposed** to be committed on `dev` and feature branches! They're part of the normal development workflow. The guard workflow (`squad-main-guard.yml`) prevents them from reaching `main` or `preview`. Just don't PR them to those branches.
+
+If you're creating a PR to `main` or `preview` and the guard blocks it, remove the files from that PR only:
 
 ```bash
-git rm --cached -r .ai-team/  # Untrack if force-added
-git checkout dev              # Switch back to dev
-# Your local .ai-team/ remains untouched
+git rm --cached -r .ai-team/  # Untrack from this PR
+git commit -m "chore: remove .ai-team/ from release PR"
+git push
 ```
 
 ### Q: Can I PR to `main` directly?
@@ -364,7 +366,7 @@ git checkout dev              # Switch back to dev
 
 ### Q: The guard blocked my PR. What now?
 
-**A:** Your PR contains `.ai-team/` or `team-docs/` files that shouldn't be in `main`/`preview`. Follow [Fixing a Blocked PR](#fixing-a-blocked-pr) — it's three `git rm --cached` commands and a push. The workflow will re-run and pass.
+**A:** Your PR targets `main` or `preview` and contains `.ai-team/` or `team-docs/` files. These files live on `dev` and feature branches but must not reach production. Follow [Fixing a Blocked PR](#fixing-a-blocked-pr) — it's three `git rm --cached` commands and a push. The workflow will re-run and pass.
 
 ### Q: I want to commit `team-docs/sprint-plan.md` — can I do that?
 
@@ -389,9 +391,9 @@ Welcome aboard. Make Squad better. 🚀
 ## Summary: What You Need to Know
 
 1. **Clone from `dev`, create `squad/{issue}-{slug}` branch, PR back to `dev`**
-2. **Never commit `.ai-team/` or internal `team-docs/` to `main` or `preview` — the guard will block it**
+2. **`.ai-team/` files are committed on `dev` and feature branches — the guard workflow blocks them from `main`/`preview`**
 3. **Run `npm test` before pushing**
 4. **Follow conventional commits (feat:, fix:, docs:, etc.)**
-5. **If the guard blocks your PR, run `git rm --cached` and push again**
+5. **If the guard blocks your PR to `main`/`preview`, run `git rm --cached` and push again**
 
 That's it. Happy contributing.

package.json

@@ -9,7 +9,6 @@
     "index.js",
     ".github/agents/squad.agent.md",
     "templates/**/*",
-    "docs/**/*",
     "CHANGELOG.md"
   ],
   "scripts": {

templates/workflows/squad-main-guard.yml

@@ -81,8 +81,9 @@ jobs:
               'git push',
               '```',
               '',
-              '> ⚠️ `.ai-team/` is in `.gitignore` but files previously force-added with `git add -f`',
-              '> remain tracked. `git rm --cached` untracks them without deleting your local copies.',
+              '> ⚠️ `.ai-team/` is committed on `dev` and feature branches by design.',
+              '> The guard workflow is the enforcement mechanism that keeps these files off `main` and `preview`.',
+              '> `git rm --cached` untracks them from this PR without deleting your local copies.',
             ];
 
             core.setFailed(lines.join('\n'));