@proflandrigan/shards 1.1.0

package/src/docs/08-integrations/claude-code-auto-mode.md

@@ -0,0 +1,191 @@
+# Claude Code Auto Mode
+
+Claude Code's auto mode auto-approves tool calls via a server-side classifier instead of prompting per action. It composes well with Shards: gates remain as workflow checkpoints, and auto mode eliminates the per-command friction between them.
+
+**You do not need auto mode to get a smooth Shards experience.** The Shards installer ships narrow `permissions.allow` rules that pre-approve common specialist operations (`dbt build`, `pytest`, `jupyter nbconvert --execute`, file writes scoped to output directories, etc.) — these work in every permission mode and cover most of the friction auto mode would remove. If you're on a plan that supports auto mode it's a useful additional polish; if you're not, skip to [Without auto mode](#without-auto-mode) below and you'll have nearly the same experience.
+
+This page documents the recommended configuration, the composition with Shards gates, and the limitations.
+
+## What it is
+
+Auto mode is one of Claude Code's permission modes (alongside `default`, `acceptEdits`, `plan`, `dontAsk`, `bypassPermissions`). When active, every tool call is evaluated by a classifier that auto-approves working-directory-bound operations and routes anything that looks risky (external network requests, production deploys, force pushes, irreversible destruction) back through a permission prompt. The classifier reads your `CLAUDE.md` and your `autoMode.*` settings to understand what "trusted" means for your environment.
+
+It also nudges Claude to keep working without stopping for clarifying questions, which composes naturally with how Shards specialists run multi-step phases.
+
+For the full reference see [Claude Code's permission modes docs](https://code.claude.com/docs/en/permission-modes) and [Configure auto mode](https://code.claude.com/docs/en/auto-mode-config).
+
+## Why it pairs well with Shards
+
+Two systems doing different jobs:
+
+| Concern | Handled by |
+|---------|------------|
+| Should this individual tool call execute? | Claude Code's permission system + (when active) auto mode classifier |
+| Should the agent advance from Phase N to Phase N+1? | Shards `::GATE::` hook |
+
+Auto mode collapses the per-tool-call approval noise between gates. The gates themselves stay human-confirmed — the user reviews each phase's plan or output before the specialist proceeds.
+
+A representative mid-session sequence under auto mode might look like:
+
+1. User runs `/ml-engineer build a churn classifier`
+2. Specialist completes Phase 1 (problem framing) — emits gate fence — **pauses for user review** ⚠️
+3. User confirms
+4. Specialist executes Phase 2 (data exploration) — runs `bq query --dry_run`, reads schemas, writes preliminary notebook — **no prompts**
+5. Specialist emits Phase 2 gate fence — **pauses for user review** ⚠️
+6. User confirms
+7. Specialist executes Phase 3 (modelling) — trains baseline, runs `pytest`, writes model card — **no prompts**
+8. ...
+
+The classifier handles the safety floor (would refuse to run, say, a `terraform apply` against production even if the specialist tried). The Shards installer pre-approves common specialist Bash and Edit patterns so the classifier doesn't even see them.
+
+## Plan and account requirements
+
+Anthropic gates auto mode by plan:
+
+- **Plan**: Max, Team, Enterprise, or API. **Not available on Pro.**
+- **Model**: Claude Sonnet 4.6, Opus 4.6, or Opus 4.7
+- **Provider**: Anthropic API only. Not available on Bedrock, Vertex, or Foundry.
+- **Admin**: on Team and Enterprise, an admin must enable it in Claude Code admin settings
+
+This is an Anthropic product decision, not a Shards limitation. The classifier is a second model call per tool use (cost) and the safety surface is broader when no one is watching each action. If you're on a plan that doesn't qualify, the [Without auto mode](#without-auto-mode) path below gives you nearly the same experience using `acceptEdits` mode plus the allow rules Shards ships.
+
+## Recommended setup
+
+### `~/.claude/settings.json`
+
+⚠️ **Important:** `permissions.defaultMode: "auto"` only works in your **user-level** settings file (`~/.claude/settings.json`). Setting it in the project's `.claude/settings.json` is silently ignored — the project cannot grant itself auto mode.
+
+```json
+{
+  "permissions": {
+    "defaultMode": "auto"
+  },
+  "autoMode": {
+    "environment": [
+      "$defaults",
+      "Shards workspaces: any project containing a `.shards/` directory uses the Shards agent framework. Reads from and writes to project subdirectories (analysis/, studies/, models/, services/, data_models/, dashboards/, research/, presentations/, panels/, fixes/, brainstorm/) and `.shards/` are routine specialist work.",
+      "Warehouse access: dbt commands (run, build, test, show, ls, compile), bq read-only queries, and SELECT-only psql/snowsql/duckdb invocations against developer-configured (non-production) warehouses are routine validation operations.",
+      "Notebook execution: `jupyter nbconvert --execute` on notebooks under analysis/, studies/, models/, research/, services/ is routine validation work."
+    ]
+  }
+}
+```
+
+The `"$defaults"` token splices in the built-in environment entries (trusted working directory and configured git remotes). Without it, your custom entries replace the defaults entirely.
+
+### The project-level pieces (already in place)
+
+The Shards installer ships these so you don't have to configure them:
+
+1. **Narrow allow rules** in `.claude/settings.json`. The installed allowlist uses narrow `Bash(<cmd>:*)` and `Edit(<dir>/**)` patterns that survive auto mode's pruning of broad rules. Anything matching these rules bypasses the classifier entirely — fastest possible path.
+2. **A deny floor** that blocks force pushes, pushes to `main`/`master`, `sh -c`/`bash -c` evil-script execution, and `rm -rf --no-preserve-root`. Deny rules beat auto mode classifier approvals.
+3. **`ask` rules** for production-target dbt invocations that force a prompt even under auto mode.
+4. **A tool-call conventions section in `CLAUDE.md`** that primes the classifier on what counts as routine Shards work (file write scopes, routine commands, gate semantics).
+
+Re-running `node tools/install.js` (or `npx github:proflandrigan/shards install` from a fresh project) backfills any of these that are missing without removing your customizations.
+
+## What auto mode blocks even under Shards
+
+The classifier still blocks the following by default — Shards conventions do not override these:
+
+- **Production deploys and migrations** — `dbt run --target prod`, `terraform apply`, `kubectl apply`, and similar
+- **Force push, or push to `main`/`master`** — also blocked by Shards' deny rules
+- **Mass deletion on cloud storage**
+- **Granting IAM or repo permissions**
+- **Downloading and executing code** (`curl ... | bash`)
+- **Sending sensitive data to external endpoints**
+- **Modifying shared infrastructure**
+
+If the classifier blocks something routine for your environment that isn't covered by the default trusted list, add it to `autoMode.environment` in your user settings. Run `claude auto-mode config` to inspect the effective rules.
+
+## Footguns
+
+### Boundaries you state in conversation persist until lifted
+
+If you tell Shards "don't push to remote until I approve," the classifier picks that up from the transcript and enforces it even when the default rules would allow a push. Useful for tightening behavior mid-session. But if context compaction removes the message that stated the boundary, the boundary is lost. For a hard guarantee, add a `deny` rule to your settings instead.
+
+### Broad allow rules get dropped
+
+On entering auto mode, Claude Code drops `Bash(*)`, `PowerShell(*)`, wildcarded interpreters like `Bash(python*)`, package-manager run commands, and `Agent` allow rules. Narrow rules like `Bash(npm test)` carry over. The Shards installer only uses narrow rules, so this doesn't affect a stock install — but if you've added your own broad rules, they'll disappear in auto mode.
+
+### Subagent task descriptions are read by the classifier
+
+A full Shards session is a depth-2 Task chain: Syn spawns a specialist; the specialist spawns Syn for final review. The classifier evaluates each Task spawn against the parent's transcript. Ambiguous task descriptions ("clean up the data") may trigger a prompt; specific ones ("Build a churn classifier under `studies/churn_v2/` using the customers and events tables") usually don't. Syn's spawn prompts to specialists already reference Shards conventions explicitly.
+
+### Production target invocations always pause
+
+`dbt run --target prod*`, `dbt build --target prod*`, `dbt seed --target prod*`, and `dbt snapshot --target prod*` are in the Shards `ask` list — they force a prompt under every mode, including auto. This is intentional. To override, remove the ask rule from your project's `.claude/settings.json` (not recommended).
+
+### The 3-of-3 / 20-total fallback
+
+If the classifier blocks an action 3 times in a row or 20 times total in one session, auto mode pauses and prompts resume. These thresholds aren't configurable. The signal usually means the classifier is missing context about your infrastructure — add the destination to `autoMode.environment` and re-run `claude auto-mode config` to confirm.
+
+## Composition matrix
+
+What you see for a representative sequence (Read → `Bash(dbt show)` → `Bash(pytest)` → `Write studies/.../results.md` → `NotebookEdit studies/.../nb.ipynb`):
+
+| Mode | Read | `dbt show` | `pytest` | `Write` | `NotebookEdit` | Phase gates |
+|------|------|------------|----------|---------|----------------|-------------|
+| `default` | auto-allowed | pre-approved | pre-approved* | pre-approved* | pre-approved* | pause for confirm |
+| `acceptEdits` | auto-allowed | pre-approved | pre-approved* | pre-approved* | pre-approved* | pause for confirm |
+| `auto` (Max/Team/Enterprise/API) | auto-allowed | pre-approved | pre-approved* | pre-approved* | pre-approved* | pause for confirm |
+
+\* via Shards' shipped allow rules (`tools/install.js` `BASE_ALLOW`). Without them, `pytest`/`Write`/`NotebookEdit` would prompt under `default` mode and hit the classifier round-trip under `auto`.
+
+Phase gates pause in every mode because the gate hook is its own enforcement layer, independent of CC's permission system.
+
+## Without auto mode
+
+If you're on Pro, Bedrock, Vertex, or otherwise can't enable auto mode, the Shards-shipped allow rules already do most of the work. Two adjustments give you a session that's effectively indistinguishable from auto mode for routine specialist work:
+
+### 1. Switch to `acceptEdits` mode
+
+Press `Shift+Tab` once from default mode (the status bar shows `⏵⏵ accept edits on`). This auto-approves:
+
+- All file edits and writes in your working directory
+- Common filesystem commands (`mkdir`, `touch`, `mv`, `cp`)
+
+Combined with the Shards installer's narrow allow rules — which already pre-approve `dbt build/run/test/seed/snapshot`, `pytest`, `jupyter nbconvert --execute <output-dirs>`, scoped `mkdir`, and `Edit(<output-dir>/**)` — the only things that still prompt are genuinely novel operations the installer doesn't anticipate. That's the same end state auto mode gives you, just via deterministic rules instead of a classifier.
+
+To make it persistent, set in your user-level `~/.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "defaultMode": "acceptEdits"
+  }
+}
+```
+
+### 2. Use Auto-Verify Mode for bulk validation stretches
+
+[Auto-Verify Mode](../03-protocols/auto-verify.md) is Shards' native mechanism for bracketing read-only verification work with a marker pair (`::AUTO-VERIFY:: ... ::ENDAUTO::`). Specialists emit these around bulk validation stretches (grain checks, fan-out validation, sample inspections) so the gate hook auto-approves dozens of nearly-identical reads. Scope-bounded by tool budget and TTL; you can halt at any time with a "stop" message.
+
+Specialists already emit these markers at the right moments — you don't need to do anything; just let the workflow run.
+
+### 3. Add project-specific allow rules as needed
+
+If your project uses a tool not in the default allowlist (a specific warehouse CLI, an internal build script, etc.), add narrow entries to `.claude/settings.json` `permissions.allow`. The `/permissions` slash command in Claude Code lists what's been pre-approved and lets you add rules interactively.
+
+### The friction comparison
+
+| Operation | Default mode | `acceptEdits` + Shards rules | Auto mode + Shards rules |
+|-----------|--------------|------------------------------|---------------------------|
+| `Read studies/proj/notebook.ipynb` | none | none | none |
+| `Bash(dbt show -m model_x)` | none (pre-approved) | none | none |
+| `Bash(pytest tests/)` | **prompt** | none (pre-approved) | none |
+| `Bash(dbt build -m model_x)` | **prompt** | none (pre-approved) | none |
+| `Write studies/proj/results.md` | **prompt** | none | none |
+| `NotebookEdit studies/proj/nb.ipynb` | **prompt** | none | none |
+| `Bash(unknown novel command)` | **prompt** | **prompt** | classifier evaluates |
+| Phase gate | **pause for confirm** | **pause for confirm** | **pause for confirm** |
+
+The only meaningful difference between rows 2 and 3: auto mode classifier-evaluates the genuinely novel cases (and usually approves working-directory-bound operations), while `acceptEdits` prompts. For most Shards sessions where specialists stick to the predictable command patterns the installer covers, this difference is rarely felt.
+
+## See also
+
+- [Auto-Verify Mode](../03-protocols/auto-verify.md) — Shards' scope-bounded auto-approval for read-only verification
+- [The Gate Pattern](../03-protocols/gate-pattern.md) — Shards' phase boundary enforcement
+- [Configure auto mode (Claude Code docs)](https://code.claude.com/docs/en/auto-mode-config)
+- [Permission modes (Claude Code docs)](https://code.claude.com/docs/en/permission-modes)
+- [Configure permissions (Claude Code docs)](https://code.claude.com/docs/en/permissions)

package/src/docs/08-integrations/google-slides.md

@@ -0,0 +1,175 @@
+# Google Slides (Syn Slides Mode)
+
+Syn's `[SL]` Slides Mode builds Google Slides decks directly. It's a Syn-native
+mode (no specialist handoff) that drafts a slide-by-slide outline, polls the
+relevant specialists for content gut-checks at two checkpoints, and uses a
+Google Slides MCP to create and iterate on the deck.
+
+This is the first **Integrations** page — a section reserved for Shards modes
+that depend on external MCP servers.
+
+---
+
+## What it does
+
+Slides Mode is for readout-style decks: exec briefings, study findings,
+post-project demos, technical peer reviews. It is not for training material
+or book-length presentations (slides over 40 hard-escalate; over 25 soft-warn).
+
+Eight steps in the mode body, two gates:
+
+1. **Intake** — audience, purpose, source material, scope, tone, MCP availability
+2. **Outline draft** — Syn writes slide-by-slide outline directly into the spec doc
+3. **Outline review** — parallel Task calls to relevant specialists (BI Engineer, Data Analyst, ML Engineer, etc., depending on source material), each returning GOOD / CAUTION / TOO COMPLEX
+4. **Plan & gate** — show user the revised outline + verdicts; gate before any MCP write
+5. **Build** — call the MCP's `create_presentation` and `batch_update_presentation` tools
+6. **Build review** — second polling round; BI Engineer always, plus the Step 3 specialist for fidelity check
+7. **Iterate (optional)** — if Step 6 flagged issues, gate before applying revisions
+8. **Wrap** — finalize spec doc, optionally append a `## Presentation` block to the source project's `project-specs.md`
+
+Each polling round is a single message with multiple parallel `Task` blocks,
+mirroring Brainstorm Mode's pattern. Each specialist response is appended
+verbatim to the spec doc as it returns.
+
+The mode is **MCP-agnostic** — Syn detects available Slides tools by suffix
+(`create_presentation`, `batch_update_presentation`, `get_presentation`)
+regardless of which server's namespace they live under.
+
+---
+
+## Setup
+
+Slides Mode requires a Google Slides MCP configured in your **user-level**
+`~/.claude/settings.json`, not the project-level `.claude/settings.json`.
+Shards manages project settings for hooks and permissions; MCPs are a
+per-user concern.
+
+### Recommended servers
+
+| Server | Notes |
+|---|---|
+| **Google's official Workspace MCP** | First-party, most durable choice. Supports Slides, Docs, Sheets, Drive, Gmail, Calendar in one server. |
+| `taylorwilsdon/google_workspace_mcp` | Comprehensive community MCP covering all of Workspace. |
+| `matteoantoci/google-slides-mcp` | Slides-only, leaner footprint. |
+| Composio / StackOne | Hosted options that handle OAuth and token refresh for you. |
+
+Slides Mode does not care which one you pick — it discovers tools at runtime.
+Pick whichever fits your auth posture and breadth needs.
+
+### Example configuration
+
+Add an `mcpServers` block to `~/.claude/settings.json` (substitute the
+command, args, and env for your chosen server's docs):
+
+```json
+{
+  "mcpServers": {
+    "google_workspace": {
+      "command": "uvx",
+      "args": ["google-workspace-mcp"],
+      "env": {
+        "GOOGLE_OAUTH_CLIENT_ID": "...",
+        "GOOGLE_OAUTH_CLIENT_SECRET": "..."
+      }
+    }
+  }
+}
+```
+
+First-time use will trigger a Google OAuth flow in your browser. Slides Mode
+detects auth-not-authenticated errors and surfaces the auth flow URL clearly
+rather than failing silently.
+
+---
+
+## Specialist polling routing
+
+Step 3 (outline review) routes to specialists based on source material:
+
+| Source / topic | Always poll | Add when |
+|---|---|---|
+| ML model / training run | ml-engineer, data-scientist | + academic if user-facing |
+| Data analysis / EDA | data-analyst, researcher | + data-scientist if includes modelling claims |
+| Dashboard / BI tool | bi-engineer, data-analyst | — |
+| Pipeline / infra / mart | data-engineer or analytics-engineer, mlops-engineer | + data-modeller if grain/schema in scope |
+| LLM / RAG / agent system | ai-engineer | + academic for ethics; + researcher for eval methodology |
+| DL architecture / novel framework | deep-learning-engineer, applied-ml-scientist | — |
+| **Always optionally poll** | **academic** | for cognitive load, audience fit, message clarity |
+
+The academic shard is worth pulling in any time the audience is non-technical
+or external — it specializes in cognitive load and message clarity.
+
+Step 6 (build review) is lighter: BI Engineer always (visual layout, density),
+plus the Step 3 domain specialist for a fidelity check.
+
+### Trivial-deck exception
+
+≤5 slides AND internal status / agenda format → both polling rounds skip.
+Syn announces "Light enough I don't need a domain gut-check — going straight
+to build" and proceeds directly to the gate.
+
+---
+
+## Output
+
+Each deck lives in `presentations/<deck_slug>/`:
+
+| File | Contents |
+|---|---|
+| `presentation-spec.md` | The single decision document — intake, outline v1, review round 1, approved outline, build log, review round 2, wrap. Gate-bearing artifact. |
+| `slides-url.txt` | Plain text URL of the created deck (one line, easy re-open). |
+| `iterations.md` | Optional. Created on the first Step 7 revision pass. Each `## Pass N — <date>` block lists what changed and which feedback drove it. |
+
+`<deck_slug>` is slug-cased from the deck purpose (e.g., `q1-churn-readout`,
+`rag-prototype-demo`).
+
+If the deck originated from an existing Shards project, Step 8 offers to
+append a `## Presentation` block to that project's `project-specs.md` with
+the slides URL and date — closes the loop between specialist work and
+stakeholder readout.
+
+---
+
+## Limitations (v1)
+
+- **No image / chart insertion.** Where the outline references a chart, Syn
+  inserts `[CHART: <description>]` placeholder text. Build Log lists the slide
+  numbers that need manual chart drops. Most Slides MCPs support text but
+  image-insert APIs vary; v2 may add screenshot-based chart embedding.
+- **No theme / template selection beyond defaults.** Syn does not currently
+  pick brand templates. v2 candidate.
+- **Slide count cap.** >40 slides hard-escalates (split into multiple decks);
+  >25 slides soft-warns. Slides Mode is for readout decks, not training
+  material.
+
+---
+
+## Troubleshooting
+
+**"I don't see a Google Slides MCP configured"** — Slides Mode could not find
+a tool with `create_presentation` in its name. Confirm your MCP is in
+`~/.claude/settings.json` (not the project-level settings.json), and restart
+Claude Code so it picks up the new server. If still missing, run a `/mcp`
+diagnostic to see what's loaded.
+
+**OAuth flow loops** — most MCPs cache auth tokens locally. If the OAuth flow
+keeps prompting, delete the local token cache (path varies per server) and
+retry.
+
+**Quota errors** — Google Slides API has per-project quotas. If you hit a
+quota mid-build, Slides Mode logs partial state to `iterations.md` and asks
+how to proceed.
+
+**Tool name mismatch** — Slides Mode matches by suffix. If your MCP exposes
+something nonstandard like `mcp__foo__createSlidesDeck` instead of
+`create_presentation`, you may need to use the official MCP or a server that
+follows the standard naming. Open an issue if you hit this with a major
+server.
+
+---
+
+## How to invoke
+
+From a `/shards` session, type `SL` to enter Slides Mode. There is no
+separate `/slides` command — Syn-native modes (Fixer, PM, Slides) are
+accessed via the menu, consistent with the rest of the suite.

package/src/docs/README.md

@@ -0,0 +1,30 @@
+# Shards Developer Guide
+
+Shards is a suite of data, ML, and AI engineering agents built on top of Claude Code. Each agent is a "shard of Syn's brain" — a specialist fragment with a distinct persona, a phased workflow, and a gate-based documentation pattern that produces an auditable decision trail for every project.
+
+This guide is the canonical reference for everything Shards does: every agent, every mode, every protocol, every UI feature.
+
+## How to read this guide
+
+- **New to Shards?** Start with [Install & Setup](01-getting-started/install.md), then [Your First Session](01-getting-started/first-session.md), then [Core Concepts](01-getting-started/concepts.md).
+- **Picking an agent?** See [Agent Taxonomy](02-agents/overview.md).
+- **Curious about a specific feature?** Jump straight to the relevant page from the left sidebar.
+- **Reading offline?** The full guide is installed as plain markdown at `docs/shards-guide/` in your project after `npx github:proflandrigan/shards install`. Every page here renders correctly in GitHub and any markdown viewer.
+
+## What's inside
+
+- **[Getting Started](01-getting-started/install.md)** — install, first session, core concepts.
+- **[Agents](02-agents/overview.md)** — one page per agent, covering persona, menu options, phases, consultants, and where output lands.
+- **[Shared Protocols](03-protocols/gate-pattern.md)** — the gate pattern, DIVERGE parallel exploration, Autonomous Research, the Knowledge Ledger, and more.
+- **[Shards UI](04-ui/overview.md)** — every panel, keybinding, and feature in the browser UI.
+- **[Commands](05-commands/reference.md)** — every slash command at a glance.
+- **[Outputs](06-outputs/directory-map.md)** — where each agent writes files.
+- **[Workflows](07-workflows/quick-analysis.md)** — end-to-end examples of real projects.
+
+## Where this content lives
+
+- **Source of truth:** `src/docs/` in the Shards repo.
+- **Installed location (UI):** `.shards/ui/docs/` — served by the in-UI guide panel.
+- **Installed location (markdown):** `docs/shards-guide/` in your project — for reading in an editor or on GitHub.
+
+Both installed copies are kept in sync by `tools/install.js`. Edits should be made in `src/docs/` and reinstalled.

package/src/docs/manifest.json

@@ -0,0 +1,108 @@
+{
+  "version": 1,
+  "title": "Shards Developer Guide",
+  "sections": [
+    {
+      "id": "getting-started",
+      "title": "Getting Started",
+      "pages": [
+        { "id": "intro", "title": "What Is Shards?", "file": "README.md" },
+        { "id": "install", "title": "Install & Setup", "file": "01-getting-started/install.md" },
+        { "id": "first-session", "title": "Your First Session", "file": "01-getting-started/first-session.md" },
+        { "id": "concepts", "title": "Core Concepts", "file": "01-getting-started/concepts.md" }
+      ]
+    },
+    {
+      "id": "agents",
+      "title": "Agents",
+      "pages": [
+        { "id": "overview", "title": "Agent Taxonomy", "file": "02-agents/overview.md" },
+        { "id": "syn", "title": "Syn — Orchestrator", "file": "02-agents/syn.md" },
+        { "id": "data-analyst", "title": "Data Analyst", "file": "02-agents/data-analyst.md" },
+        { "id": "data-scientist", "title": "Data Scientist", "file": "02-agents/data-scientist.md" },
+        { "id": "ml-engineer", "title": "ML Engineer", "file": "02-agents/ml-engineer.md" },
+        { "id": "ai-engineer", "title": "AI Engineer", "file": "02-agents/ai-engineer.md" },
+        { "id": "data-engineer", "title": "Data Engineer", "file": "02-agents/data-engineer.md" },
+        { "id": "data-modeller", "title": "Data Modeller", "file": "02-agents/data-modeller.md" },
+        { "id": "analytics-engineer", "title": "Analytics Engineer", "file": "02-agents/analytics-engineer.md" },
+        { "id": "bi-engineer", "title": "BI Engineer", "file": "02-agents/bi-engineer.md" },
+        { "id": "applied-ml-scientist", "title": "Applied ML Scientist", "file": "02-agents/applied-ml-scientist.md" },
+        { "id": "deep-learning-engineer", "title": "Deep Learning Engineer", "file": "02-agents/deep-learning-engineer.md" },
+        { "id": "mlops-engineer", "title": "MLOps Engineer", "file": "02-agents/mlops-engineer.md" },
+        { "id": "backend-engineer", "title": "Backend Engineer", "file": "02-agents/backend-engineer.md" },
+        { "id": "researcher", "title": "Researcher", "file": "02-agents/researcher.md" },
+        { "id": "academic", "title": "Academic", "file": "02-agents/academic.md" }
+      ]
+    },
+    {
+      "id": "protocols",
+      "title": "Shared Protocols",
+      "pages": [
+        { "id": "gate-pattern", "title": "The Gate Pattern", "file": "03-protocols/gate-pattern.md" },
+        { "id": "behavioral-rules", "title": "Behavioral Rules", "file": "03-protocols/behavioral-rules.md" },
+        { "id": "engineering-guidelines", "title": "Engineering Guidelines", "file": "03-protocols/engineering-guidelines.md" },
+        { "id": "reviewer-verdicts", "title": "Reviewer Verdicts", "file": "03-protocols/reviewer-verdicts.md" },
+        { "id": "validation", "title": "Validation Protocol", "file": "03-protocols/validation.md" },
+        { "id": "diverge", "title": "DIVERGE (Time-Travel Branches)", "file": "03-protocols/diverge.md" },
+        { "id": "swarm", "title": "Decompose & Swarm", "file": "03-protocols/swarm.md" },
+        { "id": "autonomous-research", "title": "Autonomous Research", "file": "03-protocols/autonomous-research.md" },
+        { "id": "experiment-versioning", "title": "Experiment Versioning", "file": "03-protocols/experiment-versioning.md" },
+        { "id": "knowledge-ledger", "title": "Knowledge Ledger", "file": "03-protocols/knowledge-ledger.md" },
+        { "id": "join-path", "title": "Join-Path Protocol", "file": "03-protocols/join-path.md" },
+        { "id": "incremental-testing", "title": "Incremental Testing", "file": "03-protocols/incremental-testing.md" },
+        { "id": "auto-verify", "title": "Auto-Verify Mode", "file": "03-protocols/auto-verify.md" }
+      ]
+    },
+    {
+      "id": "ui",
+      "title": "Shards UI",
+      "pages": [
+        { "id": "overview", "title": "UI Overview", "file": "04-ui/overview.md" },
+        { "id": "activity-bar", "title": "Activity Bar", "file": "04-ui/activity-bar.md" },
+        { "id": "chat-pane", "title": "Chat Pane", "file": "04-ui/chat-pane.md" },
+        { "id": "file-editing", "title": "File Editing", "file": "04-ui/file-editing.md" },
+        { "id": "panels", "title": "Agent-Pushed Panels", "file": "04-ui/panels.md" },
+        { "id": "pinboard-selection", "title": "Pinboard & Selection", "file": "04-ui/pinboard-selection.md" },
+        { "id": "git", "title": "Git & PR Review", "file": "04-ui/git.md" },
+        { "id": "code-intel", "title": "Code Intelligence", "file": "04-ui/code-intel.md" },
+        { "id": "quick-open-palette", "title": "Quick Open & Command Palette", "file": "04-ui/quick-open-palette.md" },
+        { "id": "knowledge-map", "title": "Knowledge Map", "file": "04-ui/knowledge-map.md" },
+        { "id": "sessions", "title": "Sessions Panel", "file": "04-ui/sessions.md" },
+        { "id": "settings-permissions", "title": "Settings & Permissions", "file": "04-ui/settings-permissions.md" },
+        { "id": "keybindings", "title": "Keybindings Reference", "file": "04-ui/keybindings.md" }
+      ]
+    },
+    {
+      "id": "commands",
+      "title": "Commands",
+      "pages": [
+        { "id": "reference", "title": "Slash Command Reference", "file": "05-commands/reference.md" }
+      ]
+    },
+    {
+      "id": "outputs",
+      "title": "Outputs",
+      "pages": [
+        { "id": "directory-map", "title": "Output Directory Map", "file": "06-outputs/directory-map.md" }
+      ]
+    },
+    {
+      "id": "workflows",
+      "title": "Example Workflows",
+      "pages": [
+        { "id": "quick-analysis", "title": "Quick Analysis", "file": "07-workflows/quick-analysis.md" },
+        { "id": "deep-study-to-production", "title": "Study → Production ML", "file": "07-workflows/deep-study-to-production.md" },
+        { "id": "ai-eval-first", "title": "AI Eval-First", "file": "07-workflows/ai-eval-first.md" },
+        { "id": "diverge-exploration", "title": "Parallel Exploration (DIVERGE)", "file": "07-workflows/diverge-exploration.md" }
+      ]
+    },
+    {
+      "id": "integrations",
+      "title": "Integrations",
+      "pages": [
+        { "id": "google-slides", "title": "Google Slides (Syn Slides Mode)", "file": "08-integrations/google-slides.md" },
+        { "id": "claude-code-auto-mode", "title": "Claude Code Auto Mode", "file": "08-integrations/claude-code-auto-mode.md" }
+      ]
+    }
+  ]
+}

package/src/templates/analysis-template.md

@@ -0,0 +1,20 @@
+# Analysis: {{ANALYSIS_NAME}}
+- **Created:** {{DATE}}
+- **Analyst:** Data Analyst Shard
+- **Status:** In Progress
+
+---
+
+<!--
+  Adhoc analysis output file. The Data Analyst shard populates this as it
+  works through its phases.
+
+  Phases:
+    0. Triage
+    1. Data Clarification (with Data Modeller review)
+    2. Analysis Plan (with Data Scientist review)
+    3. Execute
+    4. Final Review (with Syn review)
+
+  Queries are written to: queries/*.sql
+-->

package/src/templates/branch-report.md

@@ -0,0 +1,46 @@
+# Branch Report: {{BRANCH_NAME}}
+
+- **Specialist:** {{SPECIALIST_AGENT}}
+- **Approach:** {{APPROACH_SUMMARY}}
+- **Branch directory:** {{BRANCH_DIR}}
+- **Date:** {{DATE}}
+
+---
+
+## Approach Description
+
+{{APPROACH_DESCRIPTION}}
+
+---
+
+## Implementation
+
+| File | Description |
+|------|-------------|
+| `{{FILE}}` | {{DESCRIPTION}} |
+
+---
+
+## Metrics
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| **{{PRIMARY_METRIC}}** | **{{VALUE}}** | {{NOTES}} |
+
+---
+
+## Strengths
+
+{{STRENGTHS}}
+
+---
+
+## Weaknesses
+
+{{WEAKNESSES}}
+
+---
+
+## Artifacts Summary
+
+{{ARTIFACTS_LIST}}

package/src/templates/diff-report.md

@@ -0,0 +1,88 @@
+# Cross-Project Diff: {{PROJECT_A_NAME}} vs. {{PROJECT_B_NAME}}
+
+- **Date:** {{DATE}}
+- **Analyst:** Syn (Diff Mode)
+- **Directory A:** {{DIR_A}}
+- **Directory B:** {{DIR_B}}
+- **Focus:** {{FOCUS}}
+
+---
+
+## Overview
+
+| Dimension | {{PROJECT_A_NAME}} | {{PROJECT_B_NAME}} |
+|-----------|------------|------------|
+| Specialist | {{SPECIALIST_A}} | {{SPECIALIST_B}} |
+| Track | {{TRACK_A}} | {{TRACK_B}} |
+| Status | {{STATUS_A}} | {{STATUS_B}} |
+| Created | {{DATE_A}} | {{DATE_B}} |
+| Directory | `{{DIR_A}}` | `{{DIR_B}}` |
+
+---
+
+## Methodology Divergence
+
+| Decision | {{PROJECT_A_NAME}} | {{PROJECT_B_NAME}} |
+|----------|------------|------------|
+| {{DECISION_POINT}} | {{CHOICE_A}} | {{CHOICE_B}} |
+
+{{METHODOLOGY_ANALYSIS}}
+
+---
+
+## Performance Delta
+
+| Metric | {{PROJECT_A_NAME}} | {{PROJECT_B_NAME}} | Delta | Leader |
+|--------|------------|------------|-------|--------|
+| {{METRIC}} | {{VALUE_A}} | {{VALUE_B}} | {{DELTA}} | {{LEADER}} |
+
+{{VERSIONING_NOTES}}
+
+---
+
+## Hyperparameters & Configuration
+
+| Parameter | {{PROJECT_A_NAME}} | {{PROJECT_B_NAME}} |
+|-----------|------------|------------|
+| {{PARAM}} | {{VALUE_A}} | {{VALUE_B}} |
+
+---
+
+## Data Sources
+
+| Source | {{PROJECT_A_NAME}} | {{PROJECT_B_NAME}} |
+|--------|------------|------------|
+| {{SOURCE}} | {{USED_A}} | {{USED_B}} |
+
+---
+
+## Implementation Differences
+
+| File Type | {{PROJECT_A_NAME}} | {{PROJECT_B_NAME}} | Key Difference |
+|-----------|------------|------------|----------------|
+| {{FILE_TYPE}} | `{{FILE_A}}` | `{{FILE_B}}` | {{DIFFERENCE}} |
+
+---
+
+## Artifact Inventory
+
+| Artifact | {{PROJECT_A_NAME}} | {{PROJECT_B_NAME}} |
+|----------|------------|------------|
+| project-specs.md | {{HAS_SPECS_A}} | {{HAS_SPECS_B}} |
+| experiments/ | {{EXP_COUNT_A}} | {{EXP_COUNT_B}} |
+| notebooks/ | {{NB_COUNT_A}} | {{NB_COUNT_B}} |
+| queries/ | {{Q_COUNT_A}} | {{Q_COUNT_B}} |
+| prompts/ | {{P_COUNT_A}} | {{P_COUNT_B}} |
+| configs/ | {{C_COUNT_A}} | {{C_COUNT_B}} |
+
+---
+
+## Syn's Analysis
+
+{{ANALYSIS}}
+
+---
+
+## Recommendation
+
+{{RECOMMENDATION}}