hammoc 1.4.0 → 1.5.0

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 only for **Opus 4.7** (the default effort for this model 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 → non-Opus-4.7, 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
+

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
+