docs: session model, known limitations, repo anatomy, and FAQ

docs/src/content/docs/concepts/repo-anatomy.md

@@ -0,0 +1,134 @@
+# Repo Anatomy
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+Every Squad-enabled repository has a `.squad/` directory at the root. This page explains what each file and folder does, how they relate to each other, and which ones you should edit vs. leave to the agents.
+
+---
+
+## Try This
+
+```
+What's in our .squad directory?
+```
+
+```
+Show me the team's current decisions
+```
+
+```
+Which skills has the team learned?
+```
+
+---
+
+## Directory Structure
+
+After running `squad init`, your repo looks like this:
+
+```
+.squad/
+├── team.md                    # Team roster and member profiles
+├── routing.md                 # Work routing rules
+├── charter.md                 # Team charter and mission
+├── decisions.md               # Shared decision log (all agents read this)
+├── decisions-archive.md       # Archived decisions
+├── history.md                 # Team-wide session history
+├── roster.md                  # Member list with roles
+├── ceremonies.md              # Team rituals (standup, retro, etc.)
+├── config.json                # Local configuration
+├── agents/
+│   └── {name}/
+│       ├── charter.md         # Agent's role, domain, and voice
+│       └── history.md         # Agent's personal memory
+├── skills/
+│   └── {name}/
+│       └── SKILL.md           # Learned patterns and tool usage
+├── decisions/
+│   └── inbox/                 # Pending decision drafts (gitignored)
+├── sessions/                  # Session logs (gitignored)
+├── templates/                 # File templates for new squads
+└── identity/                  # Team identity and wisdom docs
+```
+
+---
+
+## What Each File Does
+
+### Files You Should Know
+
+| File | Purpose | Who writes it | You edit? |
+|------|---------|---------------|-----------|
+| `team.md` | Roster of all agents with roles and capabilities | `squad init` and Scribe | Rarely — add human members here |
+| `routing.md` | Rules for which agent handles what | You or Scribe | Yes — tune routing as your team evolves |
+| `decisions.md` | Shared rules every agent reads at session start | Scribe (merges from inbox) | Yes — this is your team's law |
+| `charter.md` | Team mission and operating principles | `squad init` | Occasionally — when team direction changes |
+
+### Per-Agent Files
+
+| File | Purpose | Who writes it |
+|------|---------|---------------|
+| `agents/{name}/charter.md` | Defines the agent's role, domain expertise, voice, and boundaries | `squad init` or casting |
+| `agents/{name}/history.md` | Personal memory — only this agent reads its own | The agent itself |
+
+Charters are your primary lever for shaping agent behavior. Edit a charter to change how an agent thinks, what it prioritizes, and how it communicates.
+
+### Skills
+
+| File | Purpose | Who writes it |
+|------|---------|---------------|
+| `skills/{name}/SKILL.md` | Reusable pattern with tools, examples, and anti-patterns | Agents (typically Procedures or the agent that learned it) |
+
+Skills are portable. You can copy a skill from one repo to another, and any Squad team can use it. They follow a standard template with Context, Patterns, Examples, and Anti-Patterns sections.
+
+---
+
+## The Decision Lifecycle
+
+Decisions flow through a specific path:
+
+```
+Agent drafts note → .squad/decisions/inbox/{agent}-{slug}.md
+       ↓
+Scribe reviews and merges → .squad/decisions.md
+       ↓
+All agents read decisions.md at session start
+       ↓
+Old decisions archived → .squad/decisions-archive.md
+```
+
+The `inbox/` directory is gitignored — it's a staging area for drafts that haven't been reviewed yet. Once Scribe merges a decision, it becomes team law.
+
+---
+
+## What Gets Checked In vs. Gitignored
+
+| Checked in | Gitignored |
+|------------|------------|
+| `team.md`, `routing.md`, `charter.md` | `decisions/inbox/` (draft staging) |
+| `decisions.md`, `decisions-archive.md` | `sessions/` (session logs) |
+| `agents/{name}/charter.md` and `history.md` | `config.json` (local machine paths) |
+| `skills/{name}/SKILL.md` | `*.local.json` (local secrets and config) |
+| `ceremonies.md`, `templates/` | `orchestration-log/`, `log/` |
+
+**Rule of thumb:** If it shapes agent behavior, check it in. If it contains local paths, secrets, or transient state, gitignore it.
+
+---
+
+## Relationship to Other Config
+
+Squad also uses files outside `.squad/`:
+
+| File | Purpose |
+|------|---------|
+| `squad.config.ts` | SDK configuration (when using `squad init --sdk`) |
+| `.github/agents/squad.agent.md` | GitHub Copilot Coding Agent coordinator prompt |
+| `.github/copilot-instructions.md` | Global Copilot instructions (Squad adds team context here) |
+
+---
+
+## Next Steps
+
+- [Team Setup](../features/team-setup) — configure your team roster
+- [Memory and Knowledge](memory-and-knowledge) — how the three memory layers interact
+- [Skills](../features/skills) — how to create and manage skills

docs/src/content/docs/concepts/session-model.md

@@ -0,0 +1,115 @@
+# Session Model
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+Squad sessions are the container for everything you do with your team. Understanding the session model helps you work confidently across tools, recover from interruptions, and know exactly where your context lives.
+
+---
+
+## Try This
+
+```
+What did we work on last session?
+```
+
+```
+Can you pick up where we left off?
+```
+
+```
+Show me the decisions from today's sessions
+```
+
+---
+
+## What Is a Session?
+
+A session starts when you open a conversation with Squad (CLI, VS Code, or Copilot Chat) and ends when you close it. During that time:
+
+- **Agents remember context** — your current task, decisions made, files changed
+- **Memory accumulates** — skills learned, conventions captured, decisions recorded
+- **Work products persist** — commits, branches, PRs, and `.squad/` file changes survive the session
+
+The session itself is ephemeral. The work it produces is permanent.
+
+---
+
+## Session Boundaries
+
+| Surface | Session starts | Session ends |
+|---------|---------------|--------------|
+| CLI (`copilot` or `squad`) | You run the command | You exit (Ctrl+C or `/exit`) |
+| VS Code Copilot Chat | You open a chat thread | You close the thread or window |
+| Copilot Coding Agent | An issue is assigned | The PR is opened |
+
+Each surface creates an independent session. Switching from CLI to VS Code starts a **new** session — the agents don't automatically carry over mid-conversation context.
+
+---
+
+## What Survives Between Sessions
+
+Memory in Squad is layered. Some things persist automatically, others need explicit action:
+
+| Layer | Persists? | Where |
+|-------|-----------|-------|
+| **Skills** (learned patterns) | ✅ Always | `.squad/skills/{name}/SKILL.md` |
+| **Decisions** (team rules) | ✅ Always | `.squad/decisions.md` |
+| **Agent history** (per-agent memory) | ✅ Always | `.squad/agents/{name}/history.md` |
+| **Conversation context** | ❌ Session-only | Lives in the chat thread |
+| **Uncommitted file changes** | ⚠️ If saved | Local working tree |
+
+**Key insight:** If an agent learns something important mid-session, it writes it to a skill or decision file. That's what makes it permanent. Conversation context alone doesn't persist.
+
+---
+
+## Resuming Work
+
+When you start a new session and want to continue previous work:
+
+```
+Pick up where we left off on the auth refactor
+```
+
+Squad reads the persisted layers (skills, decisions, history) and reconstructs context. The more your team has written to these layers, the smoother the resume.
+
+For long-running projects, consider asking your team to checkpoint progress:
+
+```
+Scribe, log what we've done today before I close out
+```
+
+---
+
+## Crashes and Restarts
+
+During preview, session crashes and restarts are **expected behavior**. This is normal and not a sign of misconfiguration. When it happens:
+
+1. Your persisted memory (skills, decisions, history) is safe — it lives in files
+2. Uncommitted code changes are safe — they're in your working tree
+3. Conversation context is lost — you'll need to re-establish what you were doing
+
+A quick restart prompt works well:
+
+```
+I just restarted. We were working on [topic]. What's the current state?
+```
+
+---
+
+## Sessions Across Surfaces
+
+You can use different surfaces throughout the day without conflict:
+
+- **Morning:** CLI session for focused coding
+- **Midday:** VS Code chat for quick questions
+- **Evening:** CLI session to review the day's work
+
+Each reads the same `.squad/` directory, so decisions and skills are shared. The only thing that doesn't transfer is the live conversation thread.
+
+---
+
+## Next Steps
+
+- [Memory and Knowledge](memory-and-knowledge) — how the three memory layers work
+- [Your First Session](../get-started/first-session) — guided walkthrough
+- [Tips and Tricks](../guide/tips-and-tricks) — productivity patterns

docs/src/content/docs/get-started/known-limitations.md

@@ -0,0 +1,92 @@
+# Known Limitations
+
+> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.
+
+Squad is in active preview. This page documents current limitations and expected behaviors so you can work confidently and know what to expect.
+
+---
+
+## Stability
+
+### Session crashes are normal
+
+During preview, sessions may crash and restart. This is expected behavior — not a sign of misconfiguration. Your work is safe:
+
+- ✅ Files you've saved are in your working tree
+- ✅ Skills, decisions, and history persist in `.squad/`
+- ✅ Commits and branches are in Git
+- ❌ Conversation context is lost — restart with a brief summary of what you were doing
+
+### Long sessions may degrade
+
+Very long sessions (many hours, hundreds of tool calls) can experience slowdowns or context overflow. Consider:
+
+- Asking Scribe to checkpoint progress before ending a long session
+- Starting fresh sessions for new topics
+- Keeping per-session scope focused
+
+---
+
+## Tool Approval
+
+### Copilot requires tool call approval by default
+
+Without `--yolo` mode, Copilot prompts for approval on every tool call (file reads, git operations, agent spawns). Squad sessions involve many tool calls, so this creates significant friction.
+
+**Recommendation:** Use `--yolo` mode for Squad sessions:
+
+```bash
+copilot --yolo
+```
+
+This is the single most impactful change for Squad usability. See [Quick Start](five-minute-start) for setup.
+
+---
+
+## Context and Memory
+
+### Conversation context doesn't persist across sessions
+
+When you close a session and start a new one, the live conversation is gone. Agents retain what they wrote to skills, decisions, and history files — but not the conversational back-and-forth. See [Session Model](../concepts/session-model) for details.
+
+### Agent memory has limits per session
+
+Each agent reads from its own history file at session start. Very large history files may exceed context limits. The team periodically compacts history during ceremonies.
+
+---
+
+## Multi-Surface
+
+### Switching tools creates new sessions
+
+Moving from CLI to VS Code (or vice versa) starts a fresh session. The persisted `.squad/` state is shared, but conversation context does not transfer. This is by design — each surface is independent.
+
+### VS Code Copilot Chat has shorter context
+
+VS Code chat threads have a smaller context window than CLI sessions. Complex multi-agent work is more reliable in the CLI.
+
+---
+
+## Platform
+
+### Path handling differs across operating systems
+
+Squad generates paths in agent output. On Windows, some paths may use forward slashes or Unix-style `~/.squad/` notation. The runtime handles this correctly, but log output may look inconsistent.
+
+### Git operations require a clean repo root
+
+Running `squad init` inside a subdirectory of an existing Git repo can cause agents to be invisible or misconfigured. Always initialize at the Git repository root.
+
+---
+
+## What's Improving
+
+These limitations are actively being addressed. Check [What's New](../whatsnew) for the latest fixes, or watch the [GitHub repo](https://github.com/bradygaster/squad) for releases.
+
+---
+
+## Next Steps
+
+- [Quick Start](five-minute-start) — get set up with recommended defaults
+- [Troubleshooting](../scenarios/troubleshooting) — common problems and fixes
+- [Session Model](../concepts/session-model) — understand session boundaries