@proflandrigan/shards 1.1.0

package/src/docs/04-ui/chat-pane.md

@@ -0,0 +1,80 @@
+# Chat Pane
+
+The center column. Live conversation with whichever shard is active.
+
+## Anatomy
+
+```
+┌──────────────────────────────┐
+│ Agent picker                 │  ← dropdown of all shards
+├──────────────────────────────┤
+│ Messages                     │
+│  · user prompts              │
+│  · agent responses           │
+│  · tool calls (collapsible)  │
+│  · gate blocks               │
+├──────────────────────────────┤
+│ Selection / pinboard         │
+├──────────────────────────────┤
+│ Input [Shift+Tab = mode]     │
+└──────────────────────────────┘
+```
+
+## Agent picker
+
+- Dropdown at the top of the chat pane lists every installed shard.
+- Picking an agent inserts the corresponding slash command into the input (`/data-analyst`, `/ml-engineer`, etc.).
+- The picker shows the agent's short description on hover.
+
+## Messages
+
+- User prompts render as plain text with light styling.
+- Agent responses render as markdown via `renderMarkdown()` (marked.js v4, GFM, code highlighting).
+- Tool calls render collapsed by default; click to expand arguments and results.
+- `::GATE::…::ENDGATE::` blocks render as highlighted gate cards — visually distinct, harder to miss.
+
+## Search
+
+- `Cmd+F` focuses the chat search bar.
+- Navigates matches with up/down arrows.
+- Match count shown inline.
+
+## Permission modes
+
+The current permission mode is shown in the HUD. Cycle with `Shift+Tab`:
+
+- **plan** — Claude must present an exit-plan-mode before editing.
+- **acceptEdits** — auto-approve file edits.
+- **default** — prompt for every tool use.
+
+## Input box
+
+- Multiline supported. `Enter` sends; `Shift+Enter` inserts a newline.
+- Slash commands autocomplete as you type.
+- File mentions: `@path/to/file` gets expanded inline.
+- Drag-and-drop a file from the Explorer onto the input to attach it.
+
+## Pinboard + selection context
+
+Immediately above the input:
+
+- **Pinboard** — files, snippets, and notes you've pinned for this chat.
+- **Selection context** — last text/code you selected in the editor is offered as context.
+
+See [Pinboard & Selection](pinboard-selection.md).
+
+## Hook-driven live updates
+
+The chat pane is fed by hook events:
+
+- `UserPromptSubmit` → new user bubble.
+- `PostToolUse` → new tool-call card.
+- `Stop` → completes the current agent turn.
+
+Events flow through `.shards/event-queue.jsonl` and SSE — the browser does not poll.
+
+## See also
+
+- [Overview](overview.md)
+- [Pinboard](pinboard-selection.md)
+- [Keybindings](keybindings.md)

package/src/docs/04-ui/code-intel.md

@@ -0,0 +1,62 @@
+# Code Intel
+
+Symbol indexing, Go-to-Definition, and find-references across the project.
+
+## Under the hood
+
+`src/ui/symbol-index.js` runs on the UI server. On startup it:
+
+1. Tries `ctags` — if available, runs `ctags -R` across the repo.
+2. Falls back to a regex-based scanner if ctags is missing.
+3. Watches the working tree (`chokidar`) and re-indexes changed files incrementally.
+
+The index is kept in memory; no sidecar file is written.
+
+## What gets indexed
+
+- Functions, classes, methods.
+- Top-level variables and constants.
+- TypeScript / Python type definitions.
+- SQL models (dbt model names) when ctags is configured for `.sql`.
+
+## Symbol search
+
+- `Cmd+T` opens the symbol picker.
+- Type to filter across the whole project.
+- Enter jumps to the symbol; `Cmd+Enter` opens in a new tab.
+- Results show symbol kind (function / class / var) and containing file.
+
+## Go-to-Definition
+
+- `F12` (or right-click → "Go to Definition") on an identifier.
+- If a single definition is found, jumps directly.
+- Multiple matches open a peek panel listing them.
+
+## Find references
+
+- `Shift+F12` on an identifier.
+- Opens a references panel listing each match with file + line + surrounding snippet.
+- Click any result to jump.
+
+## Installing ctags
+
+For best results install universal-ctags:
+
+```bash
+# macOS
+brew install universal-ctags
+
+# Ubuntu/Debian
+apt install universal-ctags
+```
+
+Without ctags, the regex fallback still provides workable symbol search and Go-to-Definition for Python, JavaScript, TypeScript, and Go — but with lower precision.
+
+## Symbol pins
+
+Code Intel feeds into the pinboard: searching a symbol and pinning it stores a reference that expands to the symbol's definition at prompt time. See [Pinboard](pinboard-selection.md).
+
+## See also
+
+- [File Editing](file-editing.md)
+- [Quick Open & Palette](quick-open-palette.md)

package/src/docs/04-ui/file-editing.md

@@ -0,0 +1,61 @@
+# File Editing
+
+The right pane is a Monaco-based editor with specialized renderers for non-code formats.
+
+## Supported formats
+
+| Format | Renderer | Features |
+|---|---|---|
+| Source code (`.py`, `.js`, `.ts`, `.sql`, …) | Monaco | Syntax highlighting, IntelliSense, Go-to-Definition |
+| Markdown (`.md`) | Split view (Monaco + preview) | Live preview, TOC |
+| Jupyter notebooks (`.ipynb`) | Cell-based renderer | Per-cell code + output, image rendering |
+| CSV / Parquet | Tabular viewer | Sortable/filterable table, schema panel |
+| JSON | Tree view + raw | Expand/collapse, copy path |
+| Images (`.png`, `.jpg`, `.svg`) | Image viewer | Zoom, pan |
+| PDFs | Embedded viewer | Page navigation |
+
+## Editing
+
+- Unsaved changes show a dot on the tab.
+- `Cmd+S` saves; autosave can be enabled in settings.
+- Multi-cursor: `Cmd+D` adds next occurrence, `Option+click` for additional cursors.
+- Find & replace: `Cmd+F` / `Cmd+Option+F`.
+
+## Tabs
+
+- Tabs live above the editor. Drag to reorder.
+- `Cmd+W` closes current tab.
+- `Cmd+Shift+T` reopens the last closed tab.
+- "Close All" and "Split" buttons in the tab bar actions.
+
+## Split view
+
+- `Cmd+\` toggles horizontal split.
+- Each split maintains its own tab set.
+- Drag a tab between splits to move it.
+
+## Notebook renderer
+
+- Cell types: code, markdown, raw.
+- Outputs rendered: stdout, images, HTML, Plotly, Altair.
+- Cells are not executable from the UI — editing-only.
+- Notebooks produced by Data Scientist / ML Engineer / AI Engineer land here automatically.
+
+## Tabular renderer
+
+- Previews CSV / Parquet / Arrow.
+- Column types inferred.
+- Filter per column; sort by clicking header.
+- Status bar shows row count, column count, memory footprint.
+
+## Markdown preview
+
+- Split-pane live preview with scroll-sync.
+- Renders via `renderMarkdown()` — same engine as chat messages.
+- Tables, code blocks, mermaid-style diagrams all supported.
+
+## See also
+
+- [Code Intel](code-intel.md)
+- [Quick Open & Palette](quick-open-palette.md)
+- [Panels](panels.md)

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

@@ -0,0 +1,54 @@
+# Git
+
+Git integration in the Shards UI: status, diffs, and PR review.
+
+## Source Control sidebar
+
+Click the branch icon in the activity bar (or `Cmd+Shift+G`). Shows:
+
+- Current branch + upstream tracking state.
+- List of changed files grouped by status: Modified / Added / Deleted / Untracked.
+- A badge on the activity-bar button shows the change count when the sidebar is collapsed.
+- Multi-repo projects: a repo picker at the top switches which repo the view shows.
+
+## Diff view
+
+Click any changed file → opens a split-pane diff in the right workspace.
+
+- Left: the committed version. Right: the working copy.
+- Hunks are navigable (up/down arrows in the diff toolbar).
+- Line numbers are preserved.
+
+## Commit / push
+
+Commits are not performed from the UI — it is intentionally read-only for git state changes. Use Claude Code directly or your shell. This is a deliberate choice: commits often interact with hooks, signing, and pre-commit checks better handled in the terminal.
+
+## PR review
+
+When the working tree is on a branch with an open PR (detected via `gh`):
+
+- "PR" tab appears in the source-control view.
+- PR title + description at the top.
+- File tree shows files changed vs. the base branch.
+- Inline comment threads appear in the diff.
+- Syn's PR Review mode (`Syn → [PR]`) can populate threaded review drafts into this view.
+
+See `src/agents/specific_instructions/syn/pr_review.md` for how Syn participates.
+
+## HUD integration
+
+The HUD strip above the sidebar shows:
+
+- Current branch.
+- Pending PR comment count (if reviewing a PR).
+- Pin count.
+
+## Troubleshooting
+
+- If the UI shows "no git repo detected": check that you launched `shards-ui` from inside a git working tree.
+- If PR info is missing: verify `gh auth status` works from your shell.
+
+## See also
+
+- [Activity Bar](activity-bar.md)
+- [Syn PR Review](../02-agents/syn.md)

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

@@ -0,0 +1,79 @@
+# Keybindings Reference
+
+All keybindings registered by the Shards UI. On macOS use `Cmd`; on Linux/Windows use `Ctrl`.
+
+## Global
+
+| Keybinding | Action |
+|---|---|
+| `Cmd+P` | Quick Open (files) |
+| `Cmd+T` | Symbol search (project-wide) |
+| `Cmd+K` | Command Palette |
+| `Cmd+,` | Open Settings |
+| `Cmd+B` | Toggle sidebar |
+| `Cmd+\` | Toggle split view |
+| `Cmd+S` | Save current file |
+| `Cmd+W` | Close current tab |
+| `Cmd+Shift+T` | Reopen last-closed tab |
+| `Cmd+F` | Find in current view (editor or chat) |
+| `Cmd+Option+F` | Find & Replace in editor |
+| `Shift+Tab` | Cycle permission mode |
+
+## Sidebar focus
+
+| Keybinding | Action |
+|---|---|
+| `Cmd+Shift+E` | Focus Explorer |
+| `Cmd+Shift+G` | Focus Source Control |
+| `Cmd+Shift+B` | Focus Bookmarks |
+
+## Workspace
+
+| Keybinding | Action |
+|---|---|
+| `Cmd+1` | Focus Chat pane |
+| `Cmd+2` | Focus Editor pane |
+| `Cmd+3` | Focus secondary split pane |
+
+## Editor (Monaco)
+
+| Keybinding | Action |
+|---|---|
+| `F12` | Go to Definition |
+| `Shift+F12` | Find References |
+| `Cmd+D` | Add next occurrence to selection |
+| `Option+click` | Add cursor |
+| `Cmd+/` | Toggle line comment |
+| `Cmd+Shift+K` | Delete line |
+| `Option+↑ / ↓` | Move line up/down |
+
+## Chat
+
+| Keybinding | Action |
+|---|---|
+| `Enter` | Send message |
+| `Shift+Enter` | Newline in input |
+| `Cmd+F` | Focus chat search bar |
+| `↑ / ↓` (in search) | Navigate matches |
+
+## Pinboard
+
+| Keybinding | Action |
+|---|---|
+| `Cmd+Shift+P` | Pin current selection |
+| `Cmd+D` | Bookmark current file/line |
+
+## Quick Open modifiers
+
+In the `Cmd+P` input:
+
+| Prefix | Behavior |
+|---|---|
+| `@` | Symbol search within current file |
+| `#` | Symbol search across project |
+| `:42` | Jump to line 42 in current file |
+
+## See also
+
+- [Quick Open & Palette](quick-open-palette.md)
+- [Settings](settings-permissions.md)

package/src/docs/04-ui/knowledge-map.md

@@ -0,0 +1,76 @@
+# Knowledge Map
+
+Browser for the [Knowledge Ledger](../03-protocols/knowledge-ledger.md). Card and graph views over `.shards/knowledge/`.
+
+## Opening
+
+- Click the brain icon in the activity bar.
+- Or command palette: "Open Knowledge Map".
+
+## Views
+
+### Card view
+
+One card per ledger entry. Shows:
+
+- Title.
+- Type badge (entity / infrastructure / pattern / feature).
+- Confidence indicator (high / medium / low).
+- Tags.
+- Contributed-by agent + date.
+
+Click a card to open the raw markdown in the editor.
+
+### Graph view
+
+Entries are nodes; edges come from shared tags and cross-references. Tight clusters indicate domains of related knowledge.
+
+- Drag nodes to rearrange.
+- Click a node to open its card.
+- Double-click a node to open the raw markdown.
+
+## Filtering
+
+Shared across both views:
+
+- By **type**: entity / infrastructure / pattern / feature.
+- By **confidence**: high / medium / low.
+- By **tag** (multi-select).
+- By **contributor** (which agent harvested it).
+- Full-text search across title + body.
+
+## Editing
+
+- Click the pencil icon on a card → inline edit of frontmatter + body.
+- Saves directly to the underlying `.md` file.
+- `INDEX.md` is regenerated after any save.
+
+## Adding entries
+
+Two paths:
+
+1. **From the UI**: "New Entry" button on the Knowledge Map toolbar. Opens a templated form.
+2. **Via Syn**: `/knowledge` slash command → Syn's Knowledge mode. Syn can seed, browse, and manage entries conversationally.
+
+## Frontmatter format
+
+```yaml
+---
+title: teacher_activity grain surprise
+domain: education
+type: entity
+confidence: high
+contributed_by: data-analyst
+date: 2025-09-12
+tags: [teacher_activity, grain, daily]
+---
+```
+
+## How entries get harvested
+
+After a specialist completes a project, the knowledge-harvest protocol runs: the specialist proposes candidate entries, the user confirms, and confirmed entries are written to the ledger. See [Knowledge Ledger](../03-protocols/knowledge-ledger.md).
+
+## See also
+
+- [Knowledge Ledger protocol](../03-protocols/knowledge-ledger.md)
+- [Activity Bar](activity-bar.md)

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

@@ -0,0 +1,93 @@
+# Shards UI — Overview
+
+A browser-based workspace that sits alongside Claude Code. Provides live chat with any shard, a file editor, agent-pushed panels, git integration, knowledge-map browsing, and the guide you are reading.
+
+## Launching
+
+```bash
+shards-ui
+```
+
+Or from Claude Code:
+
+```
+/shards-ui
+```
+
+The server binds to `127.0.0.1` on the first available port in `7842-7845`. Auth tokens are per-process (randomly generated UUIDs, not persisted). The port file at `.shards/ui.port` stores the port and token for the browser.
+
+## Layout
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│  Header: session bar · theme toggle · connection status       │
+├──┬────────────────────────────────────────────────────────────┤
+│  │  Workspace                                                 │
+│A │  ┌─────────────────────┬──────────────────────────────────┐│
+│c │  │  Chat pane          │  File / Panel pane               ││
+│t │  │  (agent picker,     │  (Monaco editor, tables,         ││
+│i │  │   messages,         │   panels, diagrams, etc.)        ││
+│v │  │   pinboard,         │                                  ││
+│i │  │   input)            │                                  ││
+│t │  │                     │                                  ││
+│y │  └─────────────────────┴──────────────────────────────────┘│
+│  │                                                            │
+│B │  HUD: git branch · pin count · PR comments · context       │
+│a │                                                            │
+│r │                                                            │
+├──┴────────────────────────────────────────────────────────────┤
+│  Sidebar (Explorer / Session Files / Bookmarks / Git / KM /   │
+│           Guide)                                              │
+└───────────────────────────────────────────────────────────────┘
+```
+
+## Top-level features
+
+| Feature | Where | Page |
+|---|---|---|
+| Activity bar (sidebar nav) | Left edge | [Activity Bar](activity-bar.md) |
+| Chat with any shard | Center pane | [Chat Pane](chat-pane.md) |
+| File editing | Right pane | [File Editing](file-editing.md) |
+| Agent-pushed panels | Right pane | [Panels](panels.md) |
+| Pinboard & selection context | Above chat input | [Pinboard](pinboard-selection.md) |
+| Git status + diffs + PR review | Sidebar + HUD | [Git](git.md) |
+| Symbol search, Go-to-Definition | Editor | [Code Intel](code-intel.md) |
+| Quick Open (Cmd+P) · Command Palette (Cmd+K) | Overlays | [Quick Open](quick-open-palette.md) |
+| Knowledge Map | Sidebar button | [Knowledge Map](knowledge-map.md) |
+| Settings & permissions | Cmd+, | [Settings](settings-permissions.md) |
+| Guide (this doc) | Book icon | See [Activity Bar](activity-bar.md) |
+
+## Keybindings at a glance
+
+See the full [Keybindings Reference](keybindings.md).
+
+Quick reference:
+
+- `Cmd+P` — Quick Open
+- `Cmd+K` — Command Palette
+- `Cmd+,` — Settings
+- `Cmd+B` — Toggle Explorer
+- `Cmd+\` — Toggle split view
+- `Cmd+1/2/3` — Switch between chat / file tabs
+- `Shift+Tab` — Cycle permission mode (acceptEdits ↔ plan)
+
+## Themes
+
+Light and dark. Toggle in the header (moon/sun icon) or via settings. Theme persists in `localStorage`.
+
+## Hooks
+
+The UI integrates with Claude Code via four hooks configured in `.claude/settings.json`:
+
+- `UserPromptSubmit` — relays user prompts to the UI.
+- `Stop` — notifies the UI when the model stops.
+- `PostToolUse` — pushes tool call results.
+- `PreToolUse` (Bash) — captures Bash invocations.
+
+Hook events flow through `src/ui/relay.js` → `.shards/event-queue.jsonl` → server SSE → browser.
+
+## See also
+
+- [Install & Setup](../01-getting-started/install.md)
+- [Panels](panels.md)
+- [Keybindings](keybindings.md)

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

@@ -0,0 +1,49 @@
+# Panels
+
+Panels are rich, structured renderings that agents push to the right pane. Unlike file tabs, panels are ephemeral — they come from a running agent, not the filesystem.
+
+## How panels arrive
+
+An agent invokes UI mode (via the agent's `[UI]` menu option or a dedicated mode file like `research_ui_mode.md`). UI-mode variants emit structured JSON via a hook; `src/ui/js/panels.js` dispatches on `panel.panel` (the panel type) and calls the right renderer.
+
+## Panel types
+
+| Panel | Who pushes it | What it shows |
+|---|---|---|
+| `data-viewer` | Data Analyst, Analytics Engineer | Query results table, schema, row count |
+| `chart` | BI Engineer, Data Analyst | Plotly / Altair / Vega-Lite visualizations |
+| `diagram` / `dag` | Analytics Engineer, Data Engineer | DAG of transformations, entity diagrams |
+| `experiment-dashboard` | ML Engineer, AI Engineer, Data Scientist (`[EX]` / `[AR]` modes) | Runs table, metric trends, config comparison. AR mode adds auto-decision coloring, cost strip, convergence badge |
+| `prompt-lab` | AI Engineer (`[PL]` mode) | Prompt editor, eval dataset, side-by-side outputs, version history |
+| `eval-dashboard` | AI Engineer, ML Engineer | Evaluation metrics per variant, confusion matrices |
+| `model-card` | ML Engineer, Deep Learning Engineer, Applied ML Scientist | Model card rendered from `model-card.md` template |
+| `knowledge-map` | Syn (Knowledge mode) | Ledger entries card/graph view |
+| `pr-review` | Syn (PR Review mode) | PR file tree, diff view, threaded comments |
+| `brainstorm` | Syn (`[B]` / `/brainstorm`) | Live multi-specialist fan-out: problem + context, specialist cards (queued → thinking → responded with headlines), synthesis buckets, facilitation log, outcome |
+| `guide` | Guide activity-bar button | This developer guide |
+
+## Registering a new panel type
+
+Two files:
+
+1. **Renderer** — add a branch in `src/ui/js/panels.js`:
+   ```js
+   case p.panel === 'my-panel':
+     renderMyPanel(container, panel);
+     break;
+   ```
+2. **Push-side** — the agent's `ui_mode.md` or equivalent variant emits the structured payload via the `push` helper.
+
+See `src/ui/js/experiment-dashboard.js`, `prompt-lab.js`, and `knowledge-map.js` as reference implementations.
+
+## Panel persistence
+
+- Panel payloads are logged to the session JSON under `.shards/sessions/<id>/`.
+- Re-opening a session re-renders its most recent panels.
+- Panels are not saved as files — if you want a permanent artifact, save from the panel's export button (where supported).
+
+## See also
+
+- [File Editing](file-editing.md)
+- [Experiment Versioning](../03-protocols/experiment-versioning.md)
+- [Autonomous Research](../03-protocols/autonomous-research.md)

package/src/docs/04-ui/pinboard-selection.md

@@ -0,0 +1,66 @@
+# Pinboard & Selection Context
+
+Two mechanisms for feeding context into the chat without typing it out.
+
+## Pinboard
+
+A persistent shelf of items attached to the current chat session. Appears above the input box.
+
+### Pin types
+
+- **File pins** — full file contents included with the next user prompt.
+- **Snippet pins** — a range of lines from a file.
+- **Note pins** — free-text notes.
+- **Symbol pins** — a function, class, or variable resolved via the symbol index.
+
+### Pinning
+
+- From the editor: select text → right-click → "Pin selection".
+- From the Explorer: right-click a file → "Pin to chat".
+- From the command palette: `Cmd+K` → "Pin file".
+- Keyboard: `Cmd+Shift+P` pins the current selection.
+
+### Managing pins
+
+- Click the X on a pin to remove it.
+- Drag pins to reorder.
+- "Clear pinboard" button clears all.
+- Pinboard state persists in `.shards/sessions/<id>/pinboard.json`.
+
+## Selection context
+
+Separate from the pinboard. When you select text in the editor, the selection is offered as **context for the next message only** (not persistent).
+
+- "Include selection" toggle in the input row.
+- Auto-cleared after the message is sent.
+- Use it when you want one-shot context without managing pins.
+
+## How pins reach the agent
+
+The pin payload is appended to the user prompt before it's sent to Claude:
+
+```
+<pins>
+  <file path="src/foo.py">...contents...</file>
+  <snippet path="src/bar.py" lines="10-30">...</snippet>
+  <note>Remember: teacher_activity has hidden grain.</note>
+</pins>
+
+<user prompt here>
+```
+
+The agent sees the pins as part of the prompt; there is no special tool for them.
+
+## When to use which
+
+| Scenario | Use |
+|---|---|
+| You'll reference the same file for multiple turns | Pin the file |
+| You want to ask one question about a specific block | Selection context |
+| You're building up a brief across several messages | Notes pins |
+| You want the agent to focus on one function | Symbol pin |
+
+## See also
+
+- [Chat Pane](chat-pane.md)
+- [Code Intel](code-intel.md)

package/src/docs/04-ui/quick-open-palette.md

@@ -0,0 +1,56 @@
+# Quick Open & Command Palette
+
+Two overlays for fast navigation and action.
+
+## Quick Open — `Cmd+P`
+
+Fuzzy file finder.
+
+- Type to filter files by path.
+- `Enter` opens in the active tab; `Cmd+Enter` opens in a new tab.
+- Recent files shown first when the input is empty.
+- Scope: the entire project working directory.
+- Respects `.gitignore` — node_modules, build artifacts, etc., are excluded.
+
+### Modifiers in the input
+
+- `@symbol` — switch to symbol search within the currently open file.
+- `#symbol` — switch to project-wide symbol search (equivalent to `Cmd+T`).
+- `:42` — jump to line 42 in the currently open file.
+
+## Command Palette — `Cmd+K`
+
+All registered commands.
+
+- Type to filter commands.
+- Shows keybindings alongside each command.
+- Commands include: toggle panels, switch agents, open settings, change theme, open the guide, and more.
+
+### Common commands
+
+| Command | Default keybinding |
+|---|---|
+| Open Guide | (via palette) |
+| Toggle Split View | `Cmd+\` |
+| Toggle Explorer | `Cmd+B` |
+| Open Settings | `Cmd+,` |
+| Switch Theme | (via palette) |
+| Focus Chat | `Cmd+1` |
+| Focus Editor | `Cmd+2` |
+| Clear Pinboard | (via palette) |
+| Reload Window | (via palette) |
+
+New commands are registered in `src/ui/js/command-palette.js`.
+
+## Differences
+
+| | Quick Open | Palette |
+|---|---|---|
+| Trigger | `Cmd+P` | `Cmd+K` |
+| Scope | Files + symbols + lines | Actions |
+| Opens something | Always a file/location | Runs a command |
+
+## See also
+
+- [Keybindings](keybindings.md)
+- [Code Intel](code-intel.md)