@proflandrigan/shards 1.1.0

package/src/docs/04-ui/sessions.md

@@ -0,0 +1,81 @@
+# Sessions Panel
+
+The Sessions panel in the activity bar is a durable history of every Shards chat
+recorded under `.shards/sessions/INDEX.json`. Unlike the **Session Activity**
+timeline (which renders live in-memory state for sessions still spawned in the
+current UI process), the Sessions panel survives server restarts, browser
+closes, and CLI exits — anything that ever opened a chat shows up here.
+
+## Where it lives
+
+Activity bar → the loopback arrow icon ("Sessions — resume past chats"). The
+panel sits alongside Explorer, Git, Session Files, Session Activity, and
+Bookmarks.
+
+## What you see
+
+Each row shows:
+
+- **Agent dot + name** — colored by the agent type
+- **Status pill** — `live`, `ended`, or `abandoned` (active sessions that haven't
+  reported activity in 24h are reclassified as abandoned at server startup)
+- **Phase chip** — the last gate phase the session reached, when known
+- **Last user prompt** — a short preview of what you said most recently
+- **Relative time** — when activity last touched this session
+
+Rows are grouped by project directory (e.g. `analysis/q2_churn`) so you can
+scan past work on a particular topic quickly.
+
+## Filtering
+
+Three quick filter buttons sit above the list: **Live**, **Ended**,
+**Abandoned**. Click one to filter; click again to clear. This is just a view
+filter — the underlying index file isn't modified.
+
+## Resuming a session
+
+Click any row. If the session is still live in the current UI process, you'll
+be switched to its chat tab. Otherwise a confirmation dialog appears summarizing
+the session (agent, project, phase, last prompt). Confirm and a fresh chat
+spawns with `--resume <sessionId>`, bringing the Claude Code transcript back
+and dropping you into the same project context.
+
+A few constraints worth knowing:
+
+- Resume only works for `ended` and `abandoned` sessions. Trying to resume a
+  live session that's already attached elsewhere returns a 409 from the server.
+- The new session gets a new `sessionId`. The `resumedFrom` field on the new
+  entry points back at the original — useful for tracing chains of resumes.
+- Project state (the on-disk `project-specs.md`, `.shards/gates/state.json`,
+  etc.) is shared across resumes since it lives in the project dir, not the
+  session. A resumed session sees the same gate state and phase progression
+  the original left behind.
+
+## Ending a session
+
+The header has an **End Chat** button next to **+ New Chat**. It calls
+`POST /chat/end` for the active session — flushes the transcript, marks the
+INDEX entry as `ended`, snapshots any open gate into `gateOpenAtEnd`, and
+stops the Claude CLI process. The button is disabled when there is no active
+session.
+
+Gate state itself is **not** modified — gates belong to the project, not the
+session. If the chat ended mid-phase with a gate open, resuming will land back
+at the same gate awaiting the same confirmation.
+
+## CLI parity
+
+The same data is reachable outside the UI. See the
+[Slash Command Reference](../05-commands/reference.md) for `/resume` and
+`/end`, and run `shards-sessions help` from any project root for the full bin.
+
+## Where the data lives
+
+- `.shards/sessions/INDEX.json` — the durable index this panel reads
+- `.shards/sessions/<sessionId>-transcript.json` — per-session transcript dump
+- `.shards/sessions/<sessionId>.json` — short-lived in-flight metadata
+  (removed when the process exits)
+
+The disk index uses atomic writes (`INDEX.json.tmp` → rename) so concurrent
+reads never observe a torn file. The server also runs an abandonment sweep
+on startup that reclassifies stale `active` rows past the 24h window.

package/src/docs/04-ui/settings-permissions.md

@@ -0,0 +1,56 @@
+# Settings & Permissions
+
+User-facing configuration. Open with `Cmd+,` or from the command palette.
+
+## Sections
+
+### Appearance
+
+- Theme: light / dark.
+- Editor font family + size.
+- Chat font family + size.
+- Line wrapping toggle.
+
+### Editor
+
+- Tab size (default 2).
+- Autosave (off / on focus change / on timeout).
+- Show minimap.
+- Show line numbers.
+
+### Chat
+
+- Render markdown (on by default).
+- Collapse tool calls by default.
+- Show gate blocks inline (on by default).
+- Search scope: current session only vs. all sessions.
+
+### Code Intel
+
+- Enable ctags (auto-detects).
+- Regex fallback (on if ctags missing).
+- Reindex on save vs. debounced.
+
+### Permissions
+
+The permission model for Claude Code tool use. Presets:
+
+- **plan** — Claude must present a plan before modifying files. Safest.
+- **acceptEdits** — file edits auto-approved; other tools still prompt.
+- **default** — every tool use prompts.
+- **bypassPermissions** — *dangerous*. All tools auto-approved. Only for trusted, sandboxed contexts.
+
+Cycle the active mode with `Shift+Tab` from the chat input.
+
+Permission state is held per-session and displayed in the HUD.
+
+## Where settings live
+
+- UI-only settings (theme, fonts, editor prefs) → `localStorage`.
+- Permission modes → per-session state, driven by Claude Code.
+- `.claude/settings.json` — project-level settings (hooks, permissions allowlist). Edited directly, not from the UI.
+
+## See also
+
+- [Keybindings](keybindings.md)
+- [Chat Pane — permission modes](chat-pane.md)

package/src/docs/05-commands/reference.md

@@ -0,0 +1,59 @@
+# Slash Command Reference
+
+Every installed slash command and what it does.
+
+## Orchestration
+
+| Command | Agent / Mode | When to use |
+|---|---|---|
+| `/shards` | Syn — triage | Default entry point. You describe the problem; Syn delegates. |
+| `/brainstorm` | Syn — brainstorm | Multi-agent ideation session. |
+| `/knowledge` | Syn — knowledge | Seed, browse, and manage the Knowledge Ledger. |
+| `/review-pr` | Syn — PR review | Threaded review of an open PR. |
+
+## Specialists
+
+| Command | Agent | Typical output |
+|---|---|---|
+| `/data-analyst` | Data Analyst | `analysis/<project>/` |
+| `/data-scientist` | Data Scientist | `studies/<project>/` |
+| `/data-engineer` | Data Engineer | `models/<project>/` |
+| `/data-modeller` | Data Modeller | `data_models/<project>/` |
+| `/analytics-engineer` | Analytics Engineer | `data_models/<project>/` |
+| `/ml-engineer` | ML Engineer | `models/<project>/` or existing service dir |
+| `/ai-engineer` | AI Engineer | `services/<project>/` |
+| `/applied-ml-scientist` | Applied ML Scientist | `research/<project>/` |
+| `/deep-learning-engineer` | Deep Learning Engineer | `services/<project>/` |
+| `/mlops-engineer` | MLOps Engineer | `services/<project>/` |
+| `/bi-engineer` | BI Engineer | `dashboards/<project>/` |
+| `/backend-engineer` | Backend Engineer | review only — no files |
+| `/researcher` | Researcher | review only — no files |
+| `/academic` | Academic | review, or `research/<project>/` in report mode |
+
+## UI
+
+| Command | Action |
+|---|---|
+| `/shards-ui` | Start the UI server and open the browser |
+| `/shards-guide` | Open the Developer Guide panel in the UI |
+
+## How commands work
+
+Each command file at `src/commands/<name>.md` is ~30 lines and does three things:
+
+1. Sets the agent persona.
+2. References the agent file at `.claude/agents/<name>.md`.
+3. Provides startup instructions — usually "read the agent file and begin Phase 0".
+
+At install time, commands are copied to `.claude/commands/` in the target project. Claude Code discovers them automatically.
+
+## Adding a new command
+
+1. Create `src/commands/<name>.md` with YAML frontmatter.
+2. Re-run `node tools/install.js` in the target project.
+3. Confirm it appears in Claude Code's `/` autocomplete.
+
+## See also
+
+- [Agents Overview](../02-agents/overview.md)
+- [Install & Setup](../01-getting-started/install.md)

package/src/docs/06-outputs/directory-map.md

@@ -0,0 +1,116 @@
+# Output Directory Map
+
+Where each shard writes. The installer creates these at install time; each project lands under its own named subdirectory.
+
+## Tree
+
+```
+<project root>/
+├── analysis/                 # Data Analyst — adhoc work
+│   └── <project>/
+│       ├── project-specs.md
+│       ├── query.sql
+│       └── findings.md
+│
+├── studies/                  # Data Scientist — deep studies
+│   └── <project>/
+│       ├── project-specs.md
+│       ├── notebooks/
+│       ├── sql/
+│       └── report.md
+│
+├── models/                   # Data Engineer + ML Engineer (greenfield)
+│   └── <project>/
+│       ├── project-specs.md
+│       ├── dbt/              # DE
+│       ├── training/         # MLE
+│       └── eval/             # MLE
+│
+├── data_models/              # Data Modeller + Analytics Engineer
+│   └── <project>/
+│       ├── project-specs.md
+│       ├── staging/
+│       ├── intermediate/
+│       └── marts/
+│
+├── services/                 # AI Engineer + DL Engineer + MLOps Engineer
+│   └── <project>/
+│       ├── project-specs.md
+│       ├── src/
+│       ├── eval/
+│       └── deploy/
+│
+├── research/                 # Applied ML Scientist
+│   └── <project>/
+│       ├── project-specs.md
+│       ├── framework/
+│       ├── experiments/
+│       └── report.md
+│
+├── dashboards/               # BI Engineer
+│   └── <project>/
+│       ├── project-specs.md
+│       └── app.py
+│
+├── brainstorm/               # Syn brainstorm sessions
+│   ├── brainstorm_<session>.md         # living doc — context, specialist input, synthesis, outcome
+│   ├── brainstorm_<session>.state.json # live state for the UI brainstorm panel
+│   └── workstreams.json                # optional — multi-workstream escalation
+│
+├── fixes/                    # Syn Fixer mode
+│   └── <project>/
+│       └── fix-notes.md
+│
+├── presentations/            # Syn Slides Mode decks
+│   └── <deck>/
+│       ├── presentation-spec.md
+│       ├── slides-url.txt
+│       └── iterations.md     # optional, after revisions
+│
+└── .shards/                  # runtime state, knowledge, UI, hooks
+    ├── knowledge/            # Knowledge Ledger — preserved across uninstalls
+    │   ├── INDEX.md
+    │   ├── entities/
+    │   ├── infrastructure/
+    │   ├── patterns/
+    │   └── features/
+    ├── sessions/             # per-session chat + panel state
+    ├── gates/                # gate-hook state
+    ├── hooks/                # installed hook scripts
+    ├── ui/                   # UI server assets
+    │   └── docs/             # this guide, served at runtime
+    └── event-queue.jsonl     # hook → UI relay buffer
+```
+
+## Per-specialist quick reference
+
+| Specialist | Dir | Central file |
+|---|---|---|
+| Data Analyst | `analysis/<p>/` | `project-specs.md` + `findings.md` |
+| Data Scientist | `studies/<p>/` | `project-specs.md` + `report.md` |
+| Data Engineer | `models/<p>/` | `project-specs.md` + dbt models |
+| Data Modeller | `data_models/<p>/` | `project-specs.md` + ERD |
+| Analytics Engineer | `data_models/<p>/` | `project-specs.md` + marts |
+| ML Engineer | `models/<p>/` or service | `project-specs.md` + `model-card.md` |
+| AI Engineer | `services/<p>/` | `project-specs.md` + evals |
+| Applied ML Scientist | `research/<p>/` | `project-specs.md` + `report.md` |
+| Deep Learning Engineer | `services/<p>/` | `project-specs.md` + `model-card.md` |
+| MLOps Engineer | `services/<p>/` | `project-specs.md` + deploy config |
+| BI Engineer | `dashboards/<p>/` | `project-specs.md` + app code |
+| Backend Engineer | — | review only |
+| Researcher / Academic | — | review only (Academic has report mode) |
+| Syn Fixer | `fixes/<p>/` | `fix-notes.md` |
+| Syn Slides Mode | `presentations/<deck>/` | `presentation-spec.md` + `slides-url.txt` |
+
+## Plain-markdown guide location
+
+The installer also copies the guide to `docs/shards-guide/` at the project root — readable in any editor or on GitHub without the UI.
+
+## Preservation on uninstall
+
+`.shards/knowledge/` is explicitly preserved on uninstall. Everything else under `.shards/` is removed, along with the `.claude/agents/`, `.claude/commands/`, and `templates/` that the installer added.
+
+## See also
+
+- [Install & Setup](../01-getting-started/install.md)
+- [Knowledge Ledger](../03-protocols/knowledge-ledger.md)

package/src/docs/07-workflows/ai-eval-first.md

@@ -0,0 +1,57 @@
+# Workflow: AI Engineering — Eval-First
+
+The AI Engineer's default posture. Before building the prompt chain or the RAG pipeline, build the evaluation. Every subsequent change is measured against it.
+
+## Flow
+
+```
+/ai-engineer
+  ├─ Phase 0: triage (is this actually an AI problem, or a regex?)
+  ├─ Phase 1: knowledge retrieval + problem framing
+  ├─ Phase 2: eval dataset + metric definition
+  │   └─ Researcher consult — statistical rigor of metric
+  ├─ Phase 3: baseline (the simplest possible approach)
+  │   └─ Record metric on baseline
+  ├─ Phase 4: candidate approach(es)
+  │   └─ Optional: DIVERGE into parallel branches
+  │   └─ Optional: [AR] mode for budget-bounded refinement
+  ├─ Phase 5: winner selection + human review
+  ├─ Phase 6: productionization (ML Engineer consult for infra)
+  ├─ Phase 7: monitoring spec (MLOps consult)
+  └─ Phase 8: Syn final review
+```
+
+Output: `services/<project>/` with eval dataset, prompts, evaluation runs, and deployment notes.
+
+## The "could this be a regex?" check
+
+The AI Engineer's Phase 0 explicitly asks whether the problem actually needs an LLM. Many apparent AI tasks:
+
+- Classification with clear rules → rules engine.
+- Extraction from structured text → regex or parser.
+- Deterministic transformation → code.
+
+If regex-able, the AI Engineer refuses and redirects. This saves both inference cost and the operational surface area of an LLM in production.
+
+## Prompt Lab mode (`[PL]`)
+
+For iterative prompt design, the AI Engineer's `[PL]` mode pushes a `prompt-lab` UI panel:
+
+- Prompt editor on the left.
+- Eval dataset on the right.
+- Run button triggers evaluation; results appear side-by-side.
+- Version history lets you compare prompt variants.
+
+## AR mode (`[AR]`)
+
+Budget-bounded autonomous loop. The AI Engineer adapts hypotheses, re-runs evals, auto-keeps or auto-reverts based on metric direction. User can steer mid-loop by editing `research_brief.md`.
+
+## DIVERGE
+
+When the approach space itself is unclear (e.g., "RAG vs. fine-tune vs. pure prompt"), fork parallel branches. Each branch runs independently; Syn Arbiter compares.
+
+## See also
+
+- [AI Engineer](../02-agents/ai-engineer.md)
+- [Autonomous Research](../03-protocols/autonomous-research.md)
+- [DIVERGE](../03-protocols/diverge.md)

package/src/docs/07-workflows/deep-study-to-production.md

@@ -0,0 +1,76 @@
+# Workflow: Deep Study → Production Model
+
+When an analytical question evolves into a deployed ML service. Touches Data Scientist → ML Engineer → MLOps Engineer, with reviewer consults along the way.
+
+## Flow
+
+```
+/shards
+  └─ Data Scientist (studies/<p>/)
+     ├─ EDA
+     ├─ Feature engineering
+     ├─ Modeling (Researcher consult for methodology)
+     ├─ Report
+     └─ Handoff brief → ML Engineer
+          │
+          └─ ML Engineer (models/<p>/ or services/<p>/)
+             ├─ Production data pipeline
+             ├─ Training loop + eval
+             ├─ Applied ML Scientist consult (if non-standard)
+             ├─ Deep Learning Engineer consult (if DL)
+             ├─ Model card
+             └─ Handoff → MLOps Engineer
+                  │
+                  └─ MLOps Engineer (services/<p>/)
+                     ├─ Serving (BentoML / Triton / SageMaker / Vertex)
+                     ├─ Monitoring + drift detection
+                     └─ Retraining pipeline
+```
+
+## Key handoffs
+
+### DS → MLE
+
+The Data Scientist's `ml_engineer_handoff.md` variant produces a structured brief:
+
+- Final feature set + sources.
+- Modeling methodology + metric definitions.
+- Known limitations, assumptions, and data quality caveats.
+- Suggested production infrastructure constraints.
+
+The ML Engineer's incoming-handoff instructions read this brief at Phase 1.
+
+### MLE → MLOps
+
+After the ML Engineer ships a trained model with eval + model card, the MLOps Engineer picks up:
+
+- Serving target (batch / real-time / streaming).
+- Latency budget.
+- Model registry + versioning strategy.
+- Retraining cadence and trigger conditions.
+- Monitoring alerts.
+
+## Reviewer layers
+
+Throughout this chain, reviewers consult via Task:
+
+- **Researcher** — statistical methodology at modeling phase.
+- **Data Modeller** — feature source grain before pipeline build.
+- **Data Analyst** — feature interpretability if high explainability required.
+- **Applied ML Scientist** — methodology review if non-standard.
+- **Deep Learning Engineer** — architecture review if DL.
+- **Syn** — final review at each specialist's last phase.
+
+## Knowledge ledger contributions
+
+Typical harvest points:
+
+- DS phase → entity quirks discovered during EDA.
+- MLE phase → verified ML features land in `features/`.
+- MLOps phase → infrastructure notes (serving latency, retraining cost).
+
+## See also
+
+- [Data Scientist](../02-agents/data-scientist.md)
+- [ML Engineer](../02-agents/ml-engineer.md)
+- [MLOps Engineer](../02-agents/mlops-engineer.md)

package/src/docs/07-workflows/diverge-exploration.md

@@ -0,0 +1,77 @@
+# Workflow: DIVERGE Exploration
+
+When the approach is unclear and a single specialist guessing is likely wrong, fork parallel branches. Each branch runs to completion independently; Syn Arbiter compares them; the user picks a winner.
+
+## Flow
+
+```
+Specialist identifies branching point
+  └─ Proposes DIVERGE to Syn
+     └─ Syn approves fork
+        ├─ Branch A (Task: specialist in isolation)
+        ├─ Branch B (Task: specialist in isolation)
+        └─ Branch C (Task: specialist in isolation)
+           │   │   │
+           ▼   ▼   ▼
+        Each branch produces branch-report.md
+           │
+        Syn Arbiter reads all reports
+           │
+        Leaderboard + trade-off analysis
+           │
+        User selects winner
+           │
+        Promote winning branch to main project dir
+```
+
+## When to use
+
+- Competing architectural choices (e.g., vector DB vs. keyword search).
+- Competing modeling approaches (e.g., gradient boosting vs. transformer).
+- Unclear whether a feature is even worth building.
+- You have budget for parallel work and want evidence, not opinion.
+
+## When not to use
+
+- The answer is constrained by known infrastructure.
+- The differences between branches are cosmetic.
+- You're under time pressure and need any working answer now.
+
+## Branch isolation
+
+Each branch runs as an isolated Task. Branches cannot see each other's state — they can only compete on the branch report they emit. This prevents cross-contamination and ensures fair comparison.
+
+## Branch report
+
+Every branch emits a `branch-report.md` following the template at `src/templates/branch-report.md`:
+
+- Approach summary.
+- Results / metrics.
+- Trade-offs.
+- Estimated cost (compute, latency, engineering effort).
+- Confidence in recommendation.
+
+## Syn Arbiter
+
+After branches complete, Syn enters Arbiter mode:
+
+- Reads every branch report.
+- Builds a side-by-side leaderboard.
+- Calls out metrics where branches diverge.
+- Provides an advisory recommendation.
+
+The user makes the final call — Arbiter does not unilaterally promote.
+
+## Promotion
+
+After user selection, the winning branch's artifacts are promoted to the main project directory. Other branches are archived (not deleted) under `<project>/branches/<branch-id>/` for reference.
+
+## Composition with AR
+
+AR fan-out composes DIVERGE with Autonomous Research: each branch runs its own AR loop. When finished, Arbiter compares the best candidate from each branch's loop. Covered in section H of the AR protocol.
+
+## See also
+
+- [DIVERGE protocol](../03-protocols/diverge.md)
+- [Autonomous Research](../03-protocols/autonomous-research.md)
+- [Syn](../02-agents/syn.md)

package/src/docs/07-workflows/quick-analysis.md

@@ -0,0 +1,45 @@
+# Workflow: Quick Adhoc Analysis
+
+The shortest productive path through Shards. Use when you have a specific question answerable in a handful of SQL queries.
+
+## Flow
+
+```
+/shards
+  └─ Syn triages → Data Analyst
+     ├─ Phase 0: understand the question
+     ├─ Phase 1: check Knowledge Ledger, consult Data Modeller for schema
+     ├─ Phase 2: write query (join-path check)
+     ├─ Phase 3: execute, inspect
+     ├─ Phase 4: findings + chart (BI Engineer review if visual)
+     └─ Phase 5: Syn final review + knowledge harvest
+```
+
+Output: `analysis/<project>/` with `project-specs.md`, `query.sql`, and `findings.md`.
+
+## Example session
+
+**You:**
+> /shards
+> What is the weekly conversion rate by cohort for Q3?
+
+**Syn (triage):** Confirms scope, creates `analysis/q3_conversion_by_cohort/`, hands off to Data Analyst.
+
+**Data Analyst:**
+- Phase 1 gate — lists known tables (`users`, `signups`, `conversions`), notes grain of each, flags that `conversions` has one row per event (not per user).
+- Phase 2 gate — join path documented (left join `signups` → `conversions`, aggregated to weekly grain).
+- Phase 3 — runs query, notes one cohort is suspicious (unusually high rate).
+- Phase 4 — findings written, chart spec handed to BI Engineer for review.
+- Phase 5 — Syn reviews, knowledge-harvest suggests adding an entry about the suspicious cohort's data quality issue.
+
+## When to escalate
+
+- If answering the question requires modeling, feature engineering, or more than ~3 queries → escalate to `/data-scientist`.
+- If the question is actually about infrastructure (missing tables, broken pipeline) → escalate to `/data-engineer`.
+- If the chart is the real deliverable → consider running `/bi-engineer` directly.
+
+## See also
+
+- [Data Analyst](../02-agents/data-analyst.md)
+- [Join Path Protocol](../03-protocols/join-path.md)
+- [Gate Pattern](../03-protocols/gate-pattern.md)