hammoc 1.3.0 → 1.5.0

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
+

package/packages/server/resources/manual/05-projects.md

@@ -0,0 +1,74 @@
+## 5. Projects
+
+### 5.1 Project List
+
+The project list page shows all your Claude Code projects in a responsive grid:
+
+Each project card displays:
+
+- **Project name** — Derived from the directory name
+- **Path** — Full project directory path
+- **Session count** — Number of chat sessions
+- **Last modified** — When the project was last active
+- **BMad badge** — Indicates BMAD-METHOD enabled projects
+- **Status indicators** — Active sessions (green dot), queue status badge, terminal count (updates in real-time)
+
+Each card has a **kebab menu** (⋮) with:
+
+- **Setup BMad** — Initialize BMAD-METHOD on non-BMad projects (with version selection)
+- **Hide / Unhide** — Toggle project visibility
+- **Delete** — Remove the project
+
+**Dashboard summary bar** appears at the top when projects exist, showing aggregate stats: Projects, Sessions, Active, Queue, Terminals.
+
+### 5.2 Creating a New Project
+
+1. Click **"New Project"** on the project list page
+2. Enter the project directory path
+3. The path is validated automatically with a short debounce while you type (`"Validating path..."` helper text is shown). Blurring the field validates immediately
+4. Path collision detection — if the path already belongs to an existing project, an amber warning appears with a **"Navigate to existing"** link and the **Create** button is disabled until you pick a different path
+5. Invalid paths show the server's validation message in red below the input, and also disable **Create**
+6. Optionally enable BMad Method initialization with version selection
+
+### 5.3 Project Settings
+
+Per-project settings live in their own tab inside each project (Overview / Queue / Git / Files / Terminal / Board / **Settings**), no longer under the global Settings page. Opening the tab takes you directly to that project's configuration — there is no project dropdown to disambiguate.
+
+The Settings tab has a two-pane layout:
+
+- **Left nav** — Two top-level groups: **General** and **Harness Workbench** (see §12)
+- **Right panel** — Form contents for the selected group
+
+**General group** (per-project override fields):
+
+- **Default model** — Override the global model selection
+- **Permission mode** — Override the global permission mode (Plan, Ask before edits, Edit automatically). Note: Bypass permissions is not available at project level
+- **Hidden toggle** — Hide the project from the project list
+- **Reset to Global Defaults** — Remove all overrides at once
+
+On narrow screens, the left nav collapses into a row of buttons above the right panel (the inner Harness Workbench navigator beneath it becomes the horizontally-scrolling pill row — see §12.1).
+
+### 5.4 Hiding Projects
+
+- Hide projects from the kebab menu or project settings
+- Hidden projects appear with reduced opacity when visible
+- Toggle "Show hidden" (eye icon in header) to reveal them
+- Hiding doesn't delete any data
+
+### 5.5 Project Overview Page
+
+Clicking a project card opens the Overview tab:
+
+- **Stats cards** — Three cards showing Total Sessions, Total Messages, and Active Sessions
+- **Recent Sessions** — Last 5 sessions with streaming indicators, session name badges, and message counts. Click to navigate directly to the session
+- **Quick Start** — Buttons for New Session, Queue Runner, and File Explorer
+- **Active streaming banner** — Green banner shown when sessions are actively streaming
+
+For BMad projects, additional sections appear above this standard overview (see §11.4).
+
+### 5.6 Deleting Projects
+
+- Delete removes the project from Hammoc's list
+- Optionally check **"Delete project files"** to also remove the directory on disk
+- Confirmation dialog prevents accidental deletion
+

package/packages/server/resources/manual/06-file-explorer-editor.md

@@ -0,0 +1,90 @@
+## 6. File Explorer & Editor
+
+### 6.1 File Explorer
+
+Access the file explorer from the sidebar tab. Toggle between views with the toolbar button:
+
+**Grid View (Finder-style, default)**
+- Icon-based card display with folder/file icons
+- Click folders to navigate in, click files to open
+- ".." entry to navigate to parent directory
+- Breadcrumb navigation at the top
+
+**List View (hierarchical tree)**
+- Recursive tree with expand/collapse chevrons
+- Lazy-loaded subdirectories
+- Sorted by type (folders first) then by name
+- Keyboard navigation: ArrowUp/Down/Left/Right, Enter, Home/End
+
+**Context Menu** (right-click or ⋮ button on hover)
+- **New File** / **New Folder** — Creates via inline input
+- **Copy** / **Cut** / **Paste** — Copy or move files and folders within the project
+- **Download** — Download individual files (files only)
+- **Rename** — Inline renaming
+- **Delete** — With confirmation dialog
+
+**File Upload**
+- Drag and drop files from your OS into the Grid view to upload them
+- Paste files from clipboard (`Ctrl+V`) while the file explorer is focused
+
+**Toolbar**
+- **Search** — File search with real-time filtering
+- **Hidden files** — Toggle visibility of ignored patterns (`.git`, `node_modules`, `.env`, `dist`, etc.)
+- **View toggle** — Switch between Grid and List views
+- **Open in OS explorer** — Opens the project folder in your OS file manager (Explorer, Finder, etc.). Only shown when accessing via localhost
+- Default view mode configurable in settings
+
+### 6.2 Text Editor
+
+Click any text file to open it in the built-in editor:
+
+- **Syntax highlighting** — Language-aware (detected from file extension)
+- **Line numbers** and **active line highlighting**
+- **Save** — `Ctrl+S` / `Cmd+S` or the save button
+- **Close** — `Escape` key or the X button
+- **Unsaved changes warning** — Confirmation dialog prevents accidental data loss
+- **File size limit** — Files over 1MB are truncated and read-only
+- **Binary files** — When a binary file is opened (images, PDFs, executables, etc.), the editor body shows the file's human-readable size (e.g., `104 B`, `5.0 MB`) together with a **Download** button for direct download
+
+**External change detection**
+
+The server watches open files and pushes a notification if the file changes on disk outside Hammoc. An alert banner appears above the editor:
+
+- **File modified on disk (clean editor)** — Amber banner with **Reload** (re-read from disk) and **Dismiss** (keep current view)
+- **File modified on disk (with unsaved edits)** — Amber banner warning that saving will overwrite the external changes; same Reload / Dismiss buttons
+- **File deleted on disk** — Red banner with a **Dismiss** button (no reload is possible)
+- **Stale-write conflict** — If you try to save a file that was modified on disk since you opened it, the save is rejected and a red banner offers **Reload** (discard your edits) or **Overwrite** (force-save over the external changes)
+
+### 6.3 Markdown Preview
+
+For `.md` files:
+
+- Toggle between **Edit** and **Preview** modes via the header button
+- Preview renders full markdown with styles
+- Default mode (Edit or Preview) configurable in settings
+
+### 6.4 Image Viewer
+
+Click any image file to open the viewer in a fullscreen overlay:
+
+- **Zoom in/out** — Button controls or mouse wheel scroll (wheel zoom cancels any active fit mode)
+- **Drag to pan** — Click and drag to move the image. Pan position is clamped so the zoomed image cannot be dragged completely off-screen
+- **Zoom percentage** — Displayed between zoom buttons
+- **Fit controls** — Header buttons for **Actual size (100%)**, **Fit to screen**, **Fit to width**, and **Fit to height**. The active fit mode is cleared when you manually zoom with the wheel
+- **Touch gestures** (mobile / touchscreen):
+  - **Pinch** with two fingers to zoom. The zoom is anchored at the midpoint between the two fingers so the content under your fingers stays put
+  - **One-finger drag** pans the image when it's zoomed in (with edge clamping)
+  - **One-finger horizontal swipe** (when the image fits on screen) navigates to the previous / next image in the set. A swipe needs to exceed roughly 50 px horizontally and be more horizontal than vertical to trigger
+- **Multi-image navigation** — When multiple images are available (a chat message with multiple attachments, **or a file-explorer image opened from a folder containing other images**), they form a navigable set. Left/right arrow keys move between images and zoom resets to fit on each change. The header shows the current position (e.g., `filename (2/5)`)
+- **Close** — `Escape` key or the X button
+- Supports PNG, JPEG, GIF, WebP, SVG, BMP, ICO
+
+### 6.5 Quick File Panel
+
+Access files without leaving the chat:
+
+- Open the quick panel and switch to the Files tab
+- **Recently opened** files appear at the top (max 5 per session)
+- Search and navigate the file tree
+- Click to open in the editor overlay
+

package/packages/server/resources/manual/07-git.md

@@ -0,0 +1,94 @@
+## 7. Git
+
+### 7.1 Git Status
+
+The Git tab shows the current repository state with automatic refresh:
+
+- **Top bar** — Branch selector dropdown + Pull/Push buttons
+- **File groups** — Three collapsible sections (chevron toggle), each with file count badge:
+  - **Staged Changes** — Files ready to commit (status indicators: M green, A green, D red, R blue)
+  - **Unstaged Changes** — Modified files not yet staged (status indicators: M yellow, D red)
+  - **Untracked Files** — New files not tracked by Git (status indicator: ?)
+- **File click** — Clicking a file name opens the Diff viewer slide panel (see 7.8)
+- **Error banner** — Git errors appear at the top and auto-clear; dismiss manually with X
+- **Clean state** — When no changes exist, a green checkmark with "No changes" message is shown
+
+### 7.2 Staging Files
+
+- **Stage individual files** — Click the "+" button next to each file (appears on hover)
+- **Stage all** — Click "+ All" in the group header to stage all files in that group
+- **Unstage individual** — Click the "-" button on staged files (appears on hover)
+- **Unstage all** — Click "- All" in the Staged Changes group header
+
+### 7.3 Committing
+
+1. Stage the files you want to commit
+2. Write a commit message in the textarea
+3. Click **"Commit"** (enabled only when staged files exist and message is non-empty)
+4. The commit history refreshes automatically after a successful commit
+
+> **Note:** "Stage All & Commit" is available only in the Quick Git Panel (see 7.7). The full Git tab requires staging first, then committing separately.
+
+### 7.4 Branch Management
+
+- **Branch selector** — Dropdown button in the top bar showing the current branch
+- **Branch list** — All local branches displayed; current branch highlighted with a blue checkmark
+- **Create branch** — Input field at the bottom of the dropdown; press Enter to create
+- **Switch branch** — Click on a branch name to switch
+- **Uncommitted changes warning** — If there are staged, unstaged, or untracked files, a confirmation dialog appears before switching
+- **Keyboard navigation** — ArrowUp/Down to navigate, Enter to select, Escape to close dropdown
+
+### 7.5 Commit History
+
+- Browse recent commits (up to 20 in the full tab):
+  - Short commit hash
+  - Commit message
+  - Author name
+  - Relative timestamp (e.g., "2 hours ago", "3 days ago")
+
+### 7.6 Pull & Push
+
+- **Pull** — Fetch and merge remote changes (↓ arrow button)
+- **Push** — Upload local commits to remote (↑ arrow button)
+- **Ahead/Behind counts** — Each button shows the number of commits ahead or behind the remote
+- Errors displayed in the error banner
+
+### 7.7 Quick Git Panel
+
+Lightweight Git access from the quick panel side bar:
+
+- **Branch name** with changed file count badge (e.g., "3 changes")
+- **Commit input** — Textarea for commit message
+- **"Stage All & Commit"** — Single green button that automatically stages all unstaged/untracked files and commits in one action
+- **Success message** — Displayed briefly after a successful commit
+- **Recent commits** — Shows only the 3 most recent commits (hash, timestamp, message)
+- **"View in Git Tab"** link — Navigates to the full Git tab for advanced operations
+- **Git init support** — If the project is not a Git repository, shows an init button
+
+### 7.8 Diff Viewer
+
+- Clicking a file in the Git tab opens a **slide panel** from the right side
+- Shows the diff for the selected file, using side-by-side or inline layout based on screen width
+- **Layout toggle** — A button in the viewer header switches between side-by-side and inline layout. The choice is persisted per user (see §2.7)
+- **Close** — Click X button, click the backdrop, or press Escape
+
+### 7.9 Git Repository Initialization
+
+If the project directory is not a Git repository:
+
+- **Git tab** — Shows an "Initialize Repository" button
+- **Quick Git panel** — Shows a message and init button
+- After initialization, the Git status refreshes automatically
+
+### 7.10 AI-Assisted Split Commit
+
+A purple dashed chip — **"Split changes into logical commits / Claude handles it in a new session"** — appears in the Git tab below the file list whenever there are uncommitted changes (staged, unstaged, or untracked). The chip is hidden on a clean working tree.
+
+Clicking it:
+
+1. Creates a fresh chat session
+2. Auto-sends the bundled `%split-commit` snippet, which asks Claude to inspect the working tree (`git status` / `git diff`), group changes into coherent units, and produce one conventional-style commit per group
+3. Navigates you into that session so you can watch the work and approve each commit
+
+The chip lives only on the full Git tab — the Quick Git panel keeps its single "Stage All & Commit" action for fast manual commits.
+

package/packages/server/resources/manual/08-terminal.md

@@ -0,0 +1,59 @@
+## 8. Terminal
+
+### 8.1 Web Terminal
+
+Full terminal access in your browser:
+
+- **Shell emulation** — Real terminal connection to your system shell
+- **Working directory** — Opens in your project directory
+- Supports all shell commands, interactive programs, and TUI apps
+- **Theme** — Automatically matches app theme (dark/light)
+- **Font** — Monospace font (JetBrains Mono, Fira Code, Cascadia Code)
+
+### 8.2 Multiple Tabs
+
+- Click **"New Terminal"** button (+ icon) in the header to open a new terminal tab
+- **Maximum 5 terminals** per project; button disabled at limit
+- **Tab labels** — Named after shell (e.g., "bash", "zsh"); numbered when multiple share the same shell ("bash 1", "bash 2")
+- **Switch tabs** — Click on a tab label or use **ArrowLeft/ArrowRight** keyboard navigation
+- **Close tabs** — Click the X button on each tab, or press **Delete** to close the active tab
+- **Empty state** — When no terminals exist, a centered prompt with "New Terminal" button is shown
+
+### 8.3 Font Size
+
+Font size controls are available both via keyboard shortcuts and GUI buttons in the header:
+
+- **GUI controls** — Minus (-), current size display (click to reset), Plus (+) buttons in the header
+- `Ctrl+=` / `Ctrl++` — Increase font size
+- `Ctrl+-` — Decrease font size
+- `Ctrl+0` — Reset to default size
+
+### 8.4 Connection Status
+
+The header shows the current terminal status:
+
+- **Connecting** — Spinner with "Connecting..." text
+- **Connected** — Green dot indicator with "Connected" text
+- **Disconnected** — Red dot; "Disconnected" message shown over the terminal
+- **Exited** — Gray dot with exit code displayed
+
+### 8.5 Security
+
+Terminal access is restricted for safety:
+
+- **Local network only** — Blocked when accessed from outside the local/private network. When behind a reverse proxy with `TRUST_PROXY=true`, real client IPs are used for access control
+- **Access denied warning** — When access is denied, a shield icon with explanation is shown
+- **Configurable** — Enable/disable via the `TERMINAL_ENABLED` environment variable (set `false` to disable)
+- **Max sessions** — Server-side limit of 10 (configurable via `MAX_TERMINAL_SESSIONS`); client limits to 5 per project
+- **Session persistence** — Terminal sessions survive browser refreshes and temporary network interruptions
+
+### 8.6 Quick Terminal
+
+Lightweight terminal access from the quick panel side bar:
+
+- **Multi-terminal support** — Same tab management as the full Terminal tab (create, switch, close, max 5)
+- **Font size controls** — Minus, size display (click to reset), Plus buttons in the header
+- **"Open in Tab"** link — Navigate to the full Terminal tab
+- **Tab keyboard navigation** — ArrowLeft/Right to switch, Delete to close
+- **Security warning** — Same access denied warning when terminal access is restricted
+