marketing-site

docs/guides/docusaurus-site-guide.md

@@ -17,7 +17,9 @@ The dev server hot-reloads on file changes.
 ```
 website/
 ├── docs/                    # Markdown documentation pages
-│   └── intro.md            # Main docs entry point
+│   ├── intro.md            # Getting Started (sidebar_position: 1)
+│   ├── td.md               # TD task manager docs (sidebar_position: 2)
+│   └── git-plugin.md       # Git plugin docs (sidebar_position: 3)
 ├── blog/                    # Blog posts (date-prefixed markdown)
 │   ├── authors.yml         # Blog author definitions
 │   └── tags.yml            # Blog tag definitions
@@ -65,8 +67,48 @@ export default function Home() {
 
 ## Writing Documentation
 
+> **For AI agents**: Use the `dev-docs` skill (`~/.claude/skills/dev-docs/SKILL.md`) when writing documentation. It provides patterns for user-first, scannable docs with proper code examples.
+
 Docs live in `website/docs/` as Markdown files with YAML frontmatter.
 
+### Documentation Principles
+
+Follow these patterns from the dev-docs skill:
+
+- **User-first**: Answer "what can I do?" before "how does it work?"
+- **Scannable**: Use headers, code blocks, tables for keyboard shortcuts
+- **Progressive disclosure**: Quick overview → detailed usage → full reference
+- **Working examples**: Every feature needs runnable code, not `...` placeholders
+
+### Plugin Documentation Pattern
+
+For Sidecar plugins, use this structure:
+
+```markdown
+# Plugin Name
+
+One-line description of what it does.
+
+![Screenshot](/img/screenshots/plugin-name.png)
+
+## Overview
+Brief explanation of the UI layout and core purpose.
+
+## Feature Section
+Description with keyboard shortcut table:
+
+| Key | Action |
+|-----|--------|
+| `s` | Stage file |
+| `d` | View diff |
+
+## Navigation
+How to move around within the plugin.
+
+## Command Reference
+Complete list of all shortcuts by context.
+```
+
 ### Creating a New Doc
 
 ```markdown

website/docs/conversations-plugin.md

@@ -0,0 +1,190 @@
+---
+sidebar_position: 5
+title: Conversations Plugin
+---
+
+# Conversations Plugin
+
+Browse and search your Claude Code sessions with turn-based organization, message expansion, and session analytics—see what your agent has been doing.
+
+## Overview
+
+The Conversations plugin provides a two-pane layout:
+
+- **Left pane**: Session list with search and filters
+- **Right pane**: Message detail with expandable turns
+- **Draggable divider**: Resize panes to your preference
+
+Toggle the sidebar with `\` to maximize message space.
+
+## Session List
+
+Browse all Claude Code sessions from your local history.
+
+| Key | Action |
+|-----|--------|
+| `j`, `↓` | Move down |
+| `k`, `↑` | Move up |
+| `g` | Jump to first session |
+| `G` | Jump to last session |
+| `ctrl+d` | Page down |
+| `ctrl+u` | Page up |
+| `enter` | View selected session |
+
+### Search & Filter
+
+| Key | Action |
+|-----|--------|
+| `/` | Search sessions by title or ID |
+| `f` | Filter by project |
+| `esc` | Clear search/filter |
+
+Search matches session titles and conversation content.
+
+### Session Actions
+
+| Key | Action |
+|-----|--------|
+| `y` | Copy session as markdown |
+| `o` | Open session in CLI (`claude resume`) |
+
+## Message View
+
+Two view modes for reading conversations:
+
+| Key | Action |
+|-----|--------|
+| `l` or `r` | Toggle between flow and turn view |
+
+### Conversation Flow
+
+Messages display in order, similar to the Claude Code web UI:
+- User messages with prompts
+- Assistant responses with tool results collapsed
+- Expandable tool invocations
+
+### Turn View
+
+Groups messages into conversation "turns" (user prompt + assistant response):
+- Collapsed by default
+- Shows token counts and tool summary
+- Expand to see full message content
+
+## Message Navigation
+
+| Key | Action |
+|-----|--------|
+| `j`, `↓` | Next turn/message |
+| `k`, `↑` | Previous turn/message |
+| `enter` or `d` | Expand/collapse turn or view detail |
+| `y` | Copy turn content |
+| `o` | Open in CLI |
+
+### Detail View
+
+Press `enter` on a turn to see full details in the right pane:
+
+| Key | Action |
+|-----|--------|
+| `j`, `↓` | Scroll down |
+| `k`, `↑` | Scroll up |
+| `ctrl+d` | Page down |
+| `ctrl+u` | Page up |
+| `y` | Copy detail content |
+| `h`, `←` | Return to turn list |
+| `esc` | Close detail view |
+
+## Pane Navigation
+
+| Key | Action |
+|-----|--------|
+| `tab` | Switch to next pane |
+| `shift+tab` | Switch to previous pane |
+| `l`, `→` | Focus message pane |
+| `h`, `←` | Focus sidebar |
+| `\` | Toggle sidebar visibility |
+
+## Session Analytics
+
+View statistics about a session:
+- Model usage breakdown (tokens by model)
+- File impacts (which files were created/modified)
+- Tool invocations (count by tool type)
+- Total token consumption
+
+## Pagination
+
+Sessions load 50 messages at a time. Scroll to load older messages automatically with "load older" support for long conversations.
+
+## Incremental Updates
+
+The plugin watches for new messages and coalesces updates for performance. Your session list stays current as agents work.
+
+## Render Caching
+
+Markdown rendering is cached per-message to maintain smooth scrolling even with large conversations.
+
+## Mouse Support
+
+- **Click session**: Select and view
+- **Click turn**: Expand/collapse
+- **Click tool**: Toggle tool result visibility
+- **Drag divider**: Resize panes
+- **Scroll**: Navigate lists and content
+
+## State Persistence
+
+These preferences save across sessions:
+- Sidebar width
+- View mode (flow/turn)
+- Expanded states
+
+## Command Reference
+
+All keyboard shortcuts by context:
+
+### Sidebar Context (`conversations-sidebar`)
+
+| Key | Action |
+|-----|--------|
+| `j`, `↓` | Move down |
+| `k`, `↑` | Move up |
+| `g` | Jump to top |
+| `G` | Jump to bottom |
+| `ctrl+d` | Page down |
+| `ctrl+u` | Page up |
+| `/` | Search sessions |
+| `f` | Filter by project |
+| `enter` | View session |
+| `y` | Copy markdown |
+| `o` | Open in CLI |
+| `l`, `→` | Focus messages |
+| `tab` | Focus messages |
+| `\` | Toggle sidebar |
+
+### Messages Context (`conversations-messages`)
+
+| Key | Action |
+|-----|--------|
+| `j`, `↓` | Next turn |
+| `k`, `↑` | Previous turn |
+| `l` or `r` | Toggle view mode |
+| `enter`, `d` | Expand/view detail |
+| `y` | Copy content |
+| `o` | Open in CLI |
+| `h`, `←` | Focus sidebar |
+| `tab` | Focus sidebar |
+| `esc` | Return to sidebar |
+| `\` | Toggle sidebar |
+
+### Detail Context (`conversations-detail`)
+
+| Key | Action |
+|-----|--------|
+| `j`, `↓` | Scroll down |
+| `k`, `↑` | Scroll up |
+| `ctrl+d` | Page down |
+| `ctrl+u` | Page up |
+| `y` | Copy content |
+| `h`, `←` | Close detail |
+| `esc` | Close detail |