hammoc 1.4.0 → 1.6.0

package/packages/server/resources/internals/image-storage.md

@@ -0,0 +1,43 @@
+# Image Storage
+
+When the user attaches an image to a chat message, Hammoc saves it under **Claude Code's per-project session data**, not inside the project being worked on. The user does not see this — they just attach and send. This document is for an agent that needs to read or correlate the file directly.
+
+## On-disk location
+
+```
+<homeDir>/.claude/projects/<encoded-project-path>/images/<sessionId>/<filename>
+```
+
+- `<homeDir>` — User home directory (Read/Edit tools do not expand `~`, so resolve to the absolute path first).
+- `<encoded-project-path>` — Claude Code's project slug. Path separators (`/`, `\`) and colons (`:`) in the original project path are replaced with hyphens. Example: `D:\repo\hammoc` → `D--repo-hammoc`.
+- `<sessionId>` — UUID of the chat session containing the message.
+- `<filename>` — `<sha256-prefix-16chars>.<ext>` for the original. Thumbnails use `<sha256-prefix-16chars>_thumb.<ext>`.
+- `<ext>` — One of `.png`, `.jpg`, `.gif`, `.webp`.
+
+## Supported MIME types
+
+| MIME | Extension |
+|---|---|
+| image/png | .png |
+| image/jpeg | .jpg |
+| image/gif | .gif |
+| image/webp | .webp |
+
+Anything else is rejected at attach time.
+
+## How an agent reaches these files
+
+- The chat message references each image via the API URL `/api/projects/<projectSlug>/sessions/<sessionId>/images/<filename>`. That URL is for the **browser** to render thumbnails — it is not a file-system path and Read tools cannot use it directly.
+- To open the file from disk, build the absolute path under `<homeDir>/.claude/projects/...` using the rules above, then call Read with that path.
+
+## Lifecycle
+
+- Images are written the moment the user sends a message with attachments.
+- A session's `images/<sessionId>/` directory is removed when the session itself is deleted.
+- Filenames are content-addressed (sha256 prefix), so attaching the same image bytes twice within a session reuses the same filename — automatic deduplication.
+
+## Limits
+
+- 5 images per message
+- 10 MB per image
+- Total per-session storage is bounded only by disk; there is no automatic eviction other than session deletion.

package/packages/server/resources/internals/observability-storage.md

@@ -0,0 +1,23 @@
+# Observability Storage
+
+Hammoc's Observability panel (user-facing, manual §12.18) persists two kinds of data under the user's home `.hammoc` directory. These are **not** under `.claude/` and are reached with direct file reads, not through the harness file service.
+
+`<homeDir>` must be resolved before use — Read does not expand `~`. On Windows that is `C:\Users\<user>\`.
+
+## MCP / tool call log
+
+- **Path:** `<homeDir>/.hammoc/observability/<projectSlug>.jsonl`
+- **Format:** JSON Lines — one tool-call record per line. Each record holds: tool-use id, project slug, session id, server name (parsed from the `mcp__<server>__<tool>` prefix; `null` for built-in tools like Read/Edit/Bash), tool name, start timestamp (epoch ms), duration in ms (`null` if the call never returned), argument byte size, result byte size (`null` if no response), and a success flag (`null` if no response).
+- **Bodies are never written** — only sizes. The log therefore cannot leak file contents or secrets.
+- **Retention:** records older than 30 days (override with the `OBSERVABILITY_RETENTION_DAYS` env var) are pruned on append (throttled to ~30 min) and at server startup.
+- **Written by:** the chat service hooks the existing SDK message stream and appends one record per tool result. "Orphan" calls (started, never returned) are flushed once at turn end with `null` duration / result / success.
+
+## Exact token-count cache
+
+- **Path:** `<homeDir>/.hammoc/observability/token-count-cache.json`
+- **Format:** a JSON object mapping a SHA-256 hash of the input text → official token count.
+- The **Exact count** button calls Anthropic's count-tokens API; the result is cached here keyed by content hash, so re-counting an unchanged file is free and the cache is shared across projects (identical files hash the same).
+
+## Tokenizer preference
+
+- The inline `~` hint is always a byte-size heuristic (size ÷ 4); a tokenizer-grade tier was evaluated but not adopted (it drifted 25–45% from the official count on Claude 4.x). The preference lives in `<homeDir>/.hammoc/preferences.json` under `observabilityTokenizer` and is global (all projects), though its toggle UI sits inside the Observability panel.

package/packages/server/resources/manual/01-getting-started.md

@@ -0,0 +1,104 @@
+## 1. Getting Started
+
+### 1.1 Installation
+
+**Option A: Run with npx (no install)**
+
+```bash
+npx hammoc
+```
+
+**Option B: Global install**
+
+```bash
+npm install -g hammoc
+hammoc
+```
+
+**Option C: From source (development)**
+
+```bash
+git clone https://github.com/starsh2001/hammoc.git
+cd hammoc
+npm install
+npm run dev
+```
+
+### 1.2 System Requirements
+
+- **Node.js** >= 18.0.0 (v22 LTS recommended)
+- **Claude Code CLI** installed and authenticated
+- Modern browser (Chrome, Firefox, Safari, Edge)
+
+### 1.3 First Launch
+
+1. Open http://localhost:3000 in your browser
+2. **Password Setup**: Set an admin password on first visit. This protects your instance from unauthorized access.
+3. **Login**: Enter your password to sign in. **"Stay signed in"** keeps you logged in for 30 days (checked by default). After too many failed attempts, login is temporarily locked with a countdown timer.
+4. **CLI Verification**: The onboarding wizard checks that Claude Code CLI is installed and authenticated. Follow the prompts if any step fails.
+5. **Project Selection**: Choose an existing Claude Code project or create a new one.
+
+### 1.4 Mobile Access
+
+Hammoc is fully responsive. From any device on the same network:
+
+```
+http://<your-computer-ip>:3000
+```
+
+- Desktop: Enter sends message, Shift+Enter for new line
+- Mobile (touch devices): Enter adds new line, tap the send button to send
+- **Pull-to-refresh**: Swipe down on the session list to refresh
+
+### 1.5 CLI Options
+
+```bash
+hammoc --port 8080          # Custom port
+hammoc --host localhost     # Bind to localhost only
+hammoc --trust-proxy        # Enable reverse proxy support
+hammoc --cors-origin <url>  # Restrict CORS to specific origin
+hammoc --reset-password     # Reset admin password
+hammoc --version            # Show version
+hammoc --help               # Show help
+```
+
+All options are also available as environment variables (see [Environment Variables](#14-environment-variables)).
+
+### 1.6 Remote Access (Reverse Proxy)
+
+If you need to expose Hammoc through a reverse proxy (Cloudflare Tunnel, nginx, etc.), use `--trust-proxy` and `--cors-origin`:
+
+```bash
+npx hammoc --trust-proxy --cors-origin https://hammoc.yourdomain.com
+```
+
+**What `--trust-proxy` enables:**
+- Reads real client IP from proxy headers for access control (e.g. localhost-only endpoints)
+- Sets session cookies with `Secure` flag (HTTPS-only)
+
+**What `--cors-origin` does:**
+- Restricts cross-origin requests to the specified URL only
+- Without it, any website can make authenticated requests to your Hammoc instance
+
+**Security features (always active, no configuration needed):**
+- Security headers (CSP, X-Frame-Options, HSTS, etc.)
+- Server management APIs (restart, update) restricted to localhost only
+- Terminal access restricted to local network IPs
+- Login brute-force protection (5 failed attempts → 30s lockout per IP)
+
+> **Note:** Hammoc does not apply request-level rate limiting itself — traffic shaping is an infrastructure concern. Configure it at your reverse proxy / WAF / API gateway (nginx `limit_req`, Cloudflare WAF rules, etc.).
+
+### 1.7 HTTPS / TLS
+
+Hammoc automatically enables HTTPS when TLS certificates are found:
+
+1. Place your certificate files in the `~/.hammoc/` directory:
+   - `~/.hammoc/key.pem` — Private key
+   - `~/.hammoc/cert.pem` — Certificate (or full chain)
+2. Restart Hammoc — it will detect the files and start an HTTPS server
+3. The startup log will show `TLS: enabled (certs from ~/.hammoc/)`
+
+If no certificates are found, the server runs over HTTP as usual.
+
+> **Tip:** For local development, you can generate self-signed certificates with `mkcert` or `openssl`. For production, use certificates from Let's Encrypt or your domain provider.
+

package/packages/server/resources/manual/02-chat.md

@@ -0,0 +1,285 @@
+## 2. Chat
+
+The chat interface is the core of Hammoc. It provides a rich, real-time conversation experience with Claude.
+
+### 2.1 Sending Messages
+
+- Type your message in the input area at the bottom
+- **Desktop**: Press `Enter` to send, `Shift+Enter` for a new line
+- **Mobile**: Press `Enter` for a new line, tap the send button to send
+- The input area auto-expands as you type
+
+### 2.2 Streaming Responses
+
+Claude's responses stream in real-time, character by character. You'll see:
+
+- **Text content** — Rendered as markdown as it arrives
+- **Tool calls** — Shown as expandable cards with tool name, inputs, and results
+- **Thinking blocks** — Claude's extended reasoning displayed in collapsible sections
+- **Timestamps** — Each message shows a relative timestamp (e.g., "2 hours ago")
+- **Copy button** — Click the copy icon on any message to copy its content to the clipboard
+- **Scroll to bottom** — When scrolled up, a down-arrow button appears to jump back to the latest message
+
+### 2.3 Markdown & Code Blocks
+
+Messages support full GitHub-flavored markdown:
+
+- Headers, bold, italic, strikethrough
+- Ordered and unordered lists
+- Tables
+- Blockquotes
+- Links (open in new tab)
+- Inline code and fenced code blocks
+
+**HTML support:**
+- Inline HTML tags are rendered alongside markdown (e.g., `<div>`, `<span>`, `<table>`)
+- Dangerous elements (`<script>`, `<iframe>`, `<style>`, event handlers) are automatically stripped for XSS protection
+
+**Relative path resolution:**
+- File links and image references in markdown resolve relative to the source file's directory
+- Parent traversal (`../`) is supported (e.g., `../../config.json` navigates up two levels)
+- Clicking resolved file links opens them in the text editor; images open in the image viewer
+
+**Code blocks** have:
+- Language-specific syntax highlighting
+- Copy button (top-right corner)
+- File reference links that open directly in the editor
+
+### 2.4 Image Attachments
+
+Attach images to your messages for Claude to analyze:
+
+- Click the attachment button (paperclip icon) in the input area
+- Drag and drop images directly onto the input area
+- Paste from clipboard (`Ctrl+V` / `Cmd+V`)
+- Supported formats: PNG, JPEG, GIF, WebP
+- Maximum: 5 images per message, 10MB per image
+- Images preview in the input area before sending
+- Sent images display as clickable thumbnails above the message text. Clicking a thumbnail opens the full image viewer with multi-image navigation (see §6.4)
+
+### 2.5 Tool Call Visualization
+
+When Claude uses tools (reading files, editing code, running commands), each tool call is shown as a card:
+
+- **Tool name** — e.g., Read, Edit, Bash, Grep
+- **Input parameters** — What was passed to the tool
+- **Status indicator** — Running (spinner), completed (checkmark), failed (X), denied (shield icon)
+- **Execution time** — How long the tool took
+- **Result** — Expandable section showing tool output
+- **File paths** — Toggle between short and full path display
+
+### 2.6 Task Notifications
+
+When Claude runs background tasks (e.g., Agent sub-tasks), a notification card appears in the message stream upon completion:
+
+- **Status indicators** — Completed (green checkmark), Failed (red alert), Stopped (bell icon)
+- **Summary text** — Brief description of the task outcome
+- **Clickable** — When linked to a tool call, clicking the card scrolls to the associated Agent tool card and highlights it briefly
+
+### 2.7 Diff Viewer
+
+When Claude modifies files, a diff viewer shows the changes:
+
+- **Side-by-side mode** — Before and after comparison (wide screens)
+- **Inline mode** — Unified diff view (narrow screens or mobile)
+- **Syntax highlighting** — Language-aware coloring
+- **Diff navigation** — `F7` next change, `Shift+F7` previous change
+- **Large file handling** — Very large files are handled with optimized rendering
+- **Responsive layout** — Automatically switches between side-by-side and inline modes based on screen width (768px breakpoint)
+- **Manual layout toggle** — A toggle button in the viewer header (Columns2 / Rows2 icon) lets you force side-by-side or inline. The choice is persisted per user and overrides the responsive default until reset
+
+### 2.8 Permission Requests
+
+Depending on your permission mode, Claude may ask for approval before modifying files:
+
+- **Approve** — Allow the change
+- **Reject** — Block the change
+- View the diff before deciding
+- See the list of requested permissions
+
+### 2.9 Prompt Chaining
+
+Queue multiple prompts for sequential execution. Chain state is managed server-side, enabling multi-browser sync and background execution.
+
+1. Toggle **chain mode** ON via the chain button (link icon next to send) or hold `Ctrl`
+2. Type your first prompt and send it — the send button label changes to **"Add to chain"**
+3. While Claude is responding, type the next prompt and send — it enters the chain
+4. Up to **10** prompts can be queued
+5. A **violet banner** shows the chain status:
+   - **Collapsed mode** — First prompt preview + "+N" count indicator
+   - **Expanded mode** — Full list with individual **Remove** buttons (click to expand when 2+ items)
+   - **Drag-and-drop reorder** — In the expanded list, grab the grip handle (GripVertical icon) on the left of any pending item to drag it up or down. Items that are actively sending show a spinner instead of a grip and cannot be moved
+   - **Cancel all** — Clear the entire chain
+6. Each prompt auto-executes when the previous one completes
+
+**Server-side features:**
+- **Multi-browser sync** — Chain state is synchronized across all browser tabs/windows
+- **Background execution** — Chain continues running even if all browsers are closed
+- **Auto-retry** — Failed items are automatically retried before being marked as failed
+
+### 2.10 Context Usage
+
+Monitor token usage in real-time:
+
+- **Usage donut** — Visual indicator showing used/limit tokens and percentage
+- **Cost display** — Estimated cost for the session
+- **Cache tokens** — Cache creation and read token counts
+- **Rate limit dots** — 5h/7d utilization indicators in the input area
+- **Color thresholds** — Green (normal), Yellow (moderate), Red (high usage)
+- **Context compaction** — Click the usage donut to trigger compaction, which summarizes the conversation to free up context space. At critical usage levels, clicking instead creates a new session
+- **Auto-compact on overflow** — When message history hits the context window limit, Hammoc automatically compacts the context and retries the message instead of losing the session
+
+### 2.11 Aborting Responses
+
+Stop Claude mid-response:
+
+- Click the **Stop** button (appears during streaming)
+- Press `ESC` key
+- Press `Ctrl+C` (when no text is selected in the input)
+
+### 2.12 Prompt History
+
+Navigate through your previous inputs:
+
+- Press `↑` (Up arrow) to recall the previous prompt
+- Press `↓` (Down arrow) to go forward
+- History is per-session
+
+### 2.13 Voice Input (Speech Recognition)
+
+Dictate messages using your browser's built-in speech recognition:
+
+- **Microphone button** — Located inside the chat input area (right side). Only shown when the browser supports the Web Speech API (Chrome, Edge, Safari)
+- **Toggle** — Click the mic button to start/stop listening
+- **Visual indicator** — Green indicator while actively listening
+- **Language-aware** — Automatically matches the app's language setting (English, Korean, Chinese, Japanese, Spanish, Portuguese)
+- Recognized text is added to the current input without replacing existing text
+- **Auto-stop** — Voice recognition stops automatically when sending a message or when the session becomes locked
+- **Error handling** — Toast notification shown if microphone access is denied or recognition fails
+
+### 2.14 Extended Thinking
+
+When Claude uses extended thinking, the reasoning is shown in a collapsible block:
+
+- Click to expand/collapse
+- Thinking content is visually distinct from the main response
+- Useful for understanding Claude's decision-making process
+
+### 2.15 Model Selector
+
+The model selector button is located in the chat input toolbar. It displays the current model family name (e.g., "Opus", "Sonnet", "Haiku") directly on the button. When using the default model, it shows "Default". Click to open a dropdown for choosing a different model and adjusting thinking effort.
+
+### 2.16 Thinking Effort
+
+Control how much Claude "thinks" before responding. The intensity bar appears inside the model selector dropdown. The number of bars depends on the selected model:
+
+- **Low / Medium / High** — 3 levels, available for all models
+- **Max** — 4th level, added for Opus 4.6 / Sonnet 4.6
+- **XHigh** — 5th level, added for **Opus 4.7+** (the default effort for these models is XHigh)
+
+Behavior:
+
+- Click the currently active level again to reset to default
+- Cannot be changed while Claude is responding
+- If you switch to a model that doesn't support the current level (e.g., XHigh → model without XHigh, or Max → model without Max), the effort automatically resets to the highest supported level
+- When the active model is temporarily unknown (e.g., right after switching projects before the resolved model arrives), the dropdown keeps your saved choice instead of resetting it. As soon as the model is known, the effort is reclamped if necessary
+
+The default thinking effort for new sessions can be configured in Settings > Global.
+
+### 2.17 Message Actions
+
+Each message has an action bar that appears at its bottom-right corner. Available actions depend on the message type:
+
+**On all messages:**
+- **Copy** — Copy the message text to clipboard
+
+**On user messages:**
+- **Edit** — Open an inline editor to modify the message (see §2.18)
+- **Summarize & Continue** — Generate an AI summary of the conversation up to that point (see §2.19)
+- **Rewind Code** — Restore the codebase to the state it was in when this message was sent (see §2.20)
+
+**On assistant messages:**
+- **Fork** — Create a new session branching from this response (see §2.21)
+
+All action buttons are disabled during streaming, and while another action (edit, rewind, summarize) is in progress. Actions are also disabled when viewing an old branch or in branch viewer mode (see §2.23).
+
+### 2.18 Message Edit
+
+Edit a previously sent user message to explore a different conversation path:
+
+1. Click the **Edit** button (pencil icon) on a user message
+2. The message transforms into an editable textarea with the original text
+3. Modify the text, then:
+   - **Accept** (checkmark button or `Ctrl+Enter`) — Send the edited message. Claude responds to the new version, creating a new conversation branch
+   - **Cancel** (X button or `Escape`) — Discard changes
+4. Empty messages cannot be submitted
+
+After editing, you can navigate between the original and edited branches using branch pagination (see §2.22).
+
+### 2.19 Summarize & Continue
+
+Compress a long conversation into a summary to free up context space while continuing the session:
+
+1. Click the **Summarize & Continue** button (sparkles icon) on a user message
+2. AI generates a summary of the conversation up to that point (spinner shown during generation)
+3. To cancel mid-generation, click the button again (shows X on hover)
+4. When complete, the inline edit form opens with the generated summary pre-filled
+5. Review, edit if needed, then **Accept** to continue with the summary or **Cancel** to discard
+
+### 2.20 Code Rewind
+
+Revert project files to a previous state in the conversation:
+
+1. Click the **Rewind Code** button (undo icon) on a user message
+2. A dry-run preview shows how many files will change (insertions/deletions count)
+3. Review the file list and click **Rewind** to confirm, or **Cancel** to abort
+4. On success, a toast confirms the number of files restored
+
+If no checkpoint is available for that message, or the code is already at that state, an error message is shown.
+
+### 2.21 Session Fork
+
+Branch into a completely new session from any assistant response:
+
+1. Click the **Fork** button (git-fork icon) on an assistant message
+2. A dialog appears with an optional message field (defaults to "Continue from here")
+3. Click **Fork** to create the new session
+4. The new session starts with the full conversation history up to that point, plus your fork message
+5. You are automatically navigated to the new session
+
+The original session remains unchanged.
+
+### 2.22 Conversation Branching
+
+When you edit a message, the conversation splits into branches. Branch pagination controls appear at the bottom-left of user messages that have multiple branches:
+
+- **← / →** arrows to navigate between branches
+- **"X / Y"** indicator showing current branch number and total count
+- Keyboard: **Left/Right arrow keys** to navigate (when the pagination is focused)
+- Navigation is disabled during streaming
+
+Switching branches replaces all messages from that point forward with the selected branch's history.
+
+### 2.23 Branch Viewer
+
+Browse all conversation branches in a read-only mode:
+
+1. Click the **branch history button** (git-branch icon) in the chat header — only visible when the session has branches
+2. The chat enters read-only mode:
+   - Branch pagination controls become active at every branch point
+   - Navigate freely between branches using ← / → arrows
+   - The input area shows "Branch viewer mode (read-only)"
+   - All message actions (edit, rewind, summarize, fork) are disabled
+3. Click **"Exit branch viewer"** in the header to return to the active conversation
+
+### 2.24 Max Budget Warning Banner
+
+When the **Max Budget (USD)** advanced setting (see §13.16) is configured, a sticky banner appears at the top of the chat area once the session cost approaches the limit:
+
+- **Yellow warning** (80% threshold) — "Budget warning: $X.XXXX / $Y.YYYY used (ZZ%) — approaching Max Budget limit."
+- **Red critical warning** (95% threshold) — "Budget critical: $X.XXXX / $Y.YYYY used (ZZ%) — stream will auto-stop when limit is exceeded."
+- Cost is shown to 4 decimal places
+- The banner is informational; the SDK auto-stops the stream once the limit is actually crossed
+
+The banner disappears automatically once the running cost falls back below the warning threshold (for example, after starting a new session).
+

package/packages/server/resources/manual/03-sessions.md

@@ -0,0 +1,48 @@
+## 3. Sessions
+
+### 3.1 Session List
+
+Access the session list via the sidebar or quick panel:
+
+- **Preview** — First prompt of each session
+- **Session name badge** — Custom name shown as a blue badge (if renamed)
+- **Agent badge** — Active BMad agent shown as a purple badge (if set)
+- **Session ID** — Truncated identifier
+- **Message count** — Number of messages in the session
+- **Date** — When the session was last active
+- **Streaming indicator** — Green dot with animation when streaming
+- **Waiting indicator** — Amber pulsing dot with "Waiting" badge when a session is connected but not yet streaming
+- **Queue badge** — Shown when queue runner is active on the session
+- Empty sessions are hidden by default (toggle with the eye icon)
+
+### 3.2 Creating a New Session
+
+- Click the **New Session** button in the header
+- Each session gets a unique ID
+
+### 3.3 Session Search
+
+Two distinct search modes:
+
+- **By name/ID** — Client-side filtering of the session list by name or session ID
+- **By content** — Toggle "Search content" to search through actual conversation messages (server-side, slower but thorough)
+- Matching sessions are filtered and displayed in the list
+- "Load more" pagination for large result sets
+
+### 3.4 Session Operations
+
+- **Rename** — Click the edit icon next to the session name
+- **Delete** — Remove a session (with confirmation)
+- **Selection mode** — Select multiple sessions for batch delete
+- **Delete empty sessions** — Bulk-delete all empty sessions at once
+
+### 3.5 Quick Session Panel
+
+Access sessions without leaving the chat:
+
+- Open the quick panel (sidebar tab)
+- Switch between sessions instantly
+- See session previews and status
+- **Side toggle** — Move the panel to the left or right side using the button in the panel header
+- **Mobile swipe** — Swipe inward from the screen edge to open, swipe back toward the edge to close
+

package/packages/server/resources/manual/04-slash-commands-favorites.md

@@ -0,0 +1,152 @@
+## 4. Slash Commands & Favorites
+
+### 4.1 Command Palette
+
+Type `/` in the chat input to open the command palette:
+
+- Browse available commands grouped by category — **Agents**, **Tasks**, **Skills**, **Slash Commands** (project / global / plugin `.claude/commands/*.md` files), and **Commands** (everything else)
+- Filter by typing: `/test` shows commands containing "test"
+- Commands are project-specific — loaded from the project's configured agents and tasks
+- **Real-time refresh** — The command and skill list is fetched from the server each time the palette opens, reflecting newly added or removed commands
+- Navigate with **ArrowUp/Down**, close with **Escape**
+- Press **Enter** or click to insert the selected command
+
+### 4.2 Star Command Palette
+
+Type `*` in the chat input to open the star command palette (requires an active agent):
+
+- Shows commands specific to the currently active agent
+- Filter by typing: `*create` filters matching commands
+- Navigate with **ArrowUp/Down**, close with **Escape**
+- Press **Enter** or click to insert — placeholders like `{name}` are auto-selected
+- Add to star favorites by clicking the star icon on any command
+
+### 4.3 Favorites
+
+Pin your most-used slash commands for quick access:
+
+- **Favorites bar** — Appears above the chat input (hidden when empty)
+- Hold up to **20 favorites**
+- Click a favorite chip to instantly insert it
+- **Add**: Click the star icon on any command in the slash command palette
+- **Remove**: Open the favorites popup and click the X button
+- **Reorder**: Open the favorites popup and drag to rearrange
+- Disabled during queue runner execution
+
+### 4.4 Star Favorites
+
+Mark up to **10 star favorites** per agent for even quicker access:
+
+- Star favorites appear with a yellow indicator and `*` prefix
+- They are prioritized at the top of the favorites bar, before slash favorites
+- **Add**: Click the star icon on any command in the star command palette (`*`)
+- **Remove**: Open the favorites popup and click the X button
+
+### 4.5 Favorite Management
+
+Click the star button (★) on the favorites bar to open the management popup:
+
+- **Two sections**: "Agent Command" (star favorites) and "Slash Command" (slash favorites), separated by a divider
+- Remove favorites with the X button
+- Drag to reorder within each section
+- Click a command to insert it into the chat input
+
+### 4.6 Prompt Snippets
+
+Prompt snippets are reusable prompt templates stored as files. Invoke them with the `%` prefix in the chat input.
+
+**Snippet storage (3-tier hierarchy, highest priority first):**
+
+1. **Project snippets** — `.hammoc/snippets/` in the project directory
+2. **Global snippets** — `~/.hammoc/snippets/`
+3. **Bundled snippets** — Built-in snippets shipped with Hammoc (~22 standard snippets)
+
+If the same snippet name exists in multiple tiers, the highest-priority source is used. You can override bundled snippets by placing a file with the same name in your project or global snippets directory.
+
+**Snippet files:**
+- Plain text files (optionally with `.md` extension)
+- File name becomes the snippet name (e.g., `commit-and-done` or `commit-and-done.md`)
+- Maximum file size: 100KB
+
+**Bundled standard snippets include:**
+- Workflow: `commit-and-done`, `mark-done`, `apply-qa-fixes`, `validate-and-approve`, `validate-and-fix`
+- Issues: `quick-fix-issue`, `promote-issue`, `promote-to-story`, `promote-to-epic`
+- Research: `brainstorm`, `competitor-analysis`, `market-research`, `create-prd`, `create-project-brief`
+- Architecture: `create-backend-arch`, `create-frontend-arch`, `create-fullstack-arch`, `create-frontend-spec`
+- Stories: `develop-story`, `draft-story`, `brownfield-create-story`, `brownfield-create-epic`
+- QA: `qa-review`, `validate-story`
+
+### 4.7 Snippet Autocomplete
+
+Type `%` in the chat input to open the snippet autocomplete popup:
+
+- **Grouped by source** — Sections labeled "Project", "Global", and "Bundled"
+- **Preview** — Shows the first line of each snippet's content (up to 80 characters)
+- **Real-time filtering** — Type after `%` to filter by name or preview text (case-insensitive)
+- **Keyboard navigation** — ArrowUp/Down to navigate, Enter or Tab to select, Escape to close
+- **Click** to select a snippet
+- **Real-time refresh** — The snippet list is fetched from the server each time the popup opens, reflecting any file changes
+
+Selecting a snippet inserts `%snippet-name ` (with trailing space) into the input. Deduplication ensures only the highest-priority version of each snippet name appears.
+
+### 4.8 Snippet Arguments & Context
+
+Snippets support placeholder substitution for dynamic content.
+
+**Positional arguments** (`{arg1}`, `{arg2}`, ...):
+
+Arguments are space-separated after the snippet name:
+
+```
+%commit-and-done BS-2
+```
+
+If the snippet file contains `Commit changes for story {arg1}`, this resolves to `Commit changes for story BS-2`.
+
+**Quoted arguments** — Use double quotes for multi-word arguments:
+
+```
+%promote-issue "Fix login button" critical bug
+```
+
+Here `{arg1}` = `Fix login button`, `{arg2}` = `critical`, `{arg3}` = `bug`. Inside quotes, use `\"` for literal quotes and `\\` for literal backslashes.
+
+**Context blocks** (`{context}` + `---context`):
+
+For injecting longer text into a snippet, add `---context` after the arguments followed by the content:
+
+```
+%quick-fix-issue docs/issues/ISSUE-1.md critical bug
+---context
+# Button fails on mobile
+The login button doesn't render on iOS devices.
+```
+
+The text after `---context` replaces all `{context}` placeholders in the snippet.
+
+**Unreferenced arguments** are ignored. Unreplaced placeholders remain as literal text.
+
+### 4.9 Multi-Prompt Snippets
+
+Snippets can contain multiple prompts separated by `---` on its own line:
+
+```
+*validate-story-draft {arg1}
+---
+Please fix all identified issues.
+---
+Mark as approved.
+```
+
+When invoked as `%validate-and-fix BS-2`:
+
+1. The first prompt executes immediately as the chat message
+2. Remaining prompts are added to the prompt chain queue (see §2.9) for sequential execution
+
+The total number of chain items is subject to the 10-item chain limit.
+
+**Usage in different contexts:**
+- **Chat messages** — First prompt sent immediately, remaining prompts queued as chain items
+- **Prompt chain** — All resolved prompts added as chain items
+- **Queue scripts** — Snippet is expanded inline, with additional prompts spliced into the queue
+