hammoc 1.3.0 → 1.5.0

package/packages/server/resources/manual/12-harness-workbench.md

@@ -0,0 +1,175 @@
+## 12. Harness Workbench
+
+The **Harness Workbench** is the unified surface for managing everything Claude Code reads from the `.claude/` configuration tree — plugins, skills, MCP servers, hooks, slash commands, sub-agents, `CLAUDE.md`, and Hammoc-native `%snippets`. It lives inside each project's **Settings** tab (see §5.3) under the "Harness Workbench" group, so the workbench is always scoped to the project you're working on but can also reach the global (`~/.claude/`) versions of each item.
+
+### 12.1 Layout
+
+The workbench has two stacked headers above an eight-section navigator:
+
+- **Mode banner** — Workbench-wide; explains whether the project's `.claude/` is git-tracked or ignored (see §12.2)
+- **Lint preferences button** — Top-right; opens a dialog to toggle the seven static-lint rules (see §12.12)
+
+The section navigator is a vertical sidebar on desktop and a horizontally-scrolling pill row on mobile. Sections, in order:
+
+1. **Plugins** — Installed Claude Code plugins (see §12.4)
+2. **Skills** — `SKILL.md` skill bundles (see §12.5)
+3. **MCP** — MCP server entries from `.mcp.json` / `~/.claude/.mcp.json` (see §12.6)
+4. **Hooks** — Lifecycle hooks declared in `settings.json` (see §12.7)
+5. **Commands** — Slash command files (see §12.8)
+6. **Agents** — Sub-agent definitions (see §12.9)
+7. **CLAUDE.md** — Project and global instruction documents (see §12.10)
+8. **Snippets** — Hammoc `%snippet` library + Claude Code slash-command favorites (see §12.11)
+
+When the workbench loads, every section's data is fetched in parallel and cached, so switching between sections feels instant. Each section's data also stays in sync with disk: any external change (made outside Hammoc) updates the corresponding card without a reload.
+
+### 12.2 Share Mode Banner
+
+A workbench-wide banner just above the navigator tells you how the project shares its `.claude/` configuration:
+
+- **Team-shared** (gray banner) — `.claude/` is **not** ignored by git. Files committed here (skills, hook definitions, the project `CLAUDE.md`, etc.) ship with the repo and reach every teammate.
+- **Private** (amber banner) — `.claude/` (or a parent path) is excluded by `.gitignore`. Files here stay on your machine, so a teammate cloning the repo gets none of them.
+
+The banner is derived from the project root's `.gitignore`. Edit the rules and the banner updates the next time the workbench refreshes.
+
+> An **Export bundle** action is planned for the Private mode banner so you can ship the current harness state to a teammate as a single file. The button is intentionally hidden until the export/import flow is fully wired — until then, copy individual files by hand or via the workbench's Project ↔ Global copy actions.
+
+### 12.3 Share Badges
+
+Every editable card (skill, MCP, hook, command, agent, `CLAUDE.md`, snippet) shows a small **share badge** indicating that specific file's git scope:
+
+- **Shared** (blue) — File tracked by git; team will see your edits after a commit
+- **Local** (gray) — File exists but is not tracked
+- **Ignored** (amber) — `.claude/` is fully git-excluded; this file will not be committed
+
+The badge is computed per-file so a single project can mix shared and local items.
+
+### 12.4 Plugins Panel
+
+Lists every Claude Code plugin discovered under the project and global plugin roots:
+
+- One card per plugin with name, version, and small component counts (skills, commands, agents, hooks, MCP servers it ships)
+- A toggle switch enables or disables the plugin without uninstalling it
+- Plugin-provided items appear (read-only) in the other workbench sections too, with a **"Plugin: <key>"** scope badge
+
+### 12.5 Skills Panel
+
+Card grid for skill bundles (a `SKILL.md` plus optional supporting files):
+
+- **Scope filter** — All / Project / Global / Plugin
+- **Card front** — Name, description, scope badge, share badge, lint marker (if the skill has lint issues), and a kebab menu for copy actions
+- **Open** — Click the card to open the **Skill Editor**, a modal with two modes:
+  - **Form mode** — Separate fields for the YAML frontmatter (Name, Description, Version) and a Markdown body with edit/preview toggle
+  - **Raw mode** — Edit the raw `SKILL.md` text directly when the frontmatter cannot be parsed
+- **Bundle resources** — A nested tree of supporting files (references, examples, scripts, assets) with file counts. Binary files are marked read-only; files over 1 MB are truncated
+- **Copy actions** — Copy a skill between Project / Global / Plugin scopes. If the destination already has a skill with the same name, a **conflict dialog** offers Overwrite / Skip / Rename
+- **Auto-save** — Edits debounce-save every ~300 ms; no manual save button
+- **External-change banner** — If another tool overwrites the skill while you are editing, the editor reloads with a banner explaining the change
+
+Bundled skills (from a plugin's `skills/`) can only be opened read-only — copy them to Project or Global scope first to customize.
+
+### 12.6 MCP Panel
+
+Card grid for MCP server entries (from `.mcp.json` or `~/.claude/.mcp.json`):
+
+- **Type badges** — `stdio`, `sse`, `http`, `ws`
+- **Toggle** — Enable / Disable a server. Disabling moves the entry to a backup section of the JSON file rather than deleting it, so you can re-enable later
+- **Editor** — Form fields for the server type, command, arguments (one per line), URL, headers (key/value rows), and environment variables (key/value rows). A mask toggle hides secret-looking values
+- **Secret detection** — Values that look like API keys are marked inline. When you copy a server between scopes, a warning dialog lists detected secrets and requires explicit acknowledgement before copying
+- **Fresh-spawn banner** — After enabling/disabling or editing a server, a banner reminds you that MCP changes only take effect on your **next** message in a new chat turn. A **Start new session** button is available
+
+### 12.7 Hooks Panel
+
+Hooks are grouped by lifecycle event (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification):
+
+- **Per-event sections** — Each event shows its hook cards and an inline "+ Add" button
+- **Type badges** — `command` (shell command) and `prompt` (LLM-invoking)
+- **Toggle** — Enable / Disable individual hooks
+- **Matcher field** — Regex pattern that filters which tool calls (or events) the hook applies to; empty matcher means "all"
+- **Parallel-execution badge** — Indicates when the hook runs alongside hooks from other sources for the same event
+- **Cost warning** — `prompt`-type hooks invoke the LLM each time and show a cost/latency warning banner
+- **Copy actions** — Same Project ↔ Global ↔ Plugin copy matrix as skills, with a review dialog that surfaces secret-looking values and command bodies before copying
+
+### 12.8 Commands Panel
+
+Slash command files (the `.md` files behind `/your-command`):
+
+- One card per command with name, description, scope badge, share badge, and lint marker
+- **Editor** — Markdown body with edit/preview toggle and frontmatter fields (description, argument hints)
+- **Copy / Override-clone** — Copy to the other scope, or clone a plugin-provided command into Project / Global so you can customize it without losing the upstream copy
+
+### 12.9 Agents Panel
+
+Sub-agent definitions (`AGENT.md`-style files used by the `Agent` tool):
+
+- One card per agent with name, role description, scope badge, share badge, lint marker
+- **Editor** — Frontmatter fields (Name, Description, Tools), Markdown system prompt body, edit/preview toggle
+- **Non-standard tools warning** — Lint rule flags tools that aren't part of the standard Claude Code toolset
+
+### 12.10 CLAUDE.md Editor
+
+Two-column editor for the instruction documents Claude Code loads at session start:
+
+- **Left column** — Global `~/.claude/CLAUDE.md`
+- **Right column** — Project `<root>/.claude/CLAUDE.md` with its own share badge
+- **Mobile** — Columns collapse to a User / Project toggle above a single editor pane
+
+Each column is a CodeMirror Markdown editor with edit/preview toggle and the same 300 ms debounce auto-save as the other panels. Copy buttons (← / →) move content between columns; if both files have content, a confirmation dialog warns before overwriting.
+
+Both files load into every Claude Code session in this project; the project version takes precedence when an instruction is defined in both.
+
+### 12.11 Snippets & Favorites Panel
+
+A single panel manages both Hammoc-native snippets and Claude Code slash-command favorites.
+
+**Snippets section** (top):
+
+- Manages `%name` snippets from `<project-root>/.hammoc/snippets/`, `~/.hammoc/snippets/`, and the bundled set shipped with Hammoc (see §4.6)
+- **Scope filter** — All / Project / Global / Bundled
+- **+ New snippet** — Choose scope (Project or Global) and a name; an empty file is created and the editor opens
+- **Editor** — CodeMirror with syntax highlighting for `%name%`, `{arg1}`, `{context}` tokens and an inline warning when a snippet references itself or forms a reference cycle (heuristic only — saves are not blocked)
+- **Kebab menu** — Copy to the other scope, delete (with confirmation)
+- **Bundled snippets** are read-only — copy to Project or Global scope first to customize
+
+**Command Favorites section** (bottom):
+
+- Drag-reorder list of slash command favorites (the same favorites shown in the chat input's favorites bar, see §4.3)
+- Each entry shows the command name, scope, and a star toggle that moves it between regular and star favorites
+- **Invalid chip** marker on favorites whose underlying command no longer exists on disk
+- Up to 20 regular + 10 star favorites per scope
+
+### 12.12 Static Lint
+
+Every harness panel (skills, MCP, hooks, commands, agents) runs a background static-lint pass against its files. Lint output surfaces in three places:
+
+- **Count badges on section nav** — A red dot with the error count and an amber dot with the warning count appear on the section tab when issues exist
+- **Inline marker on cards** — The card header shows a small red or amber pill with the issue count; clicking jumps to the card detail or opens the editor
+- **Issues list at the top of each panel** — Expandable list of every issue with file path, severity, message, and a "Open" link
+
+**Rule preferences:** The **Lint preferences** button at the top-right of the workbench opens a dialog listing all seven rules. Each rule has an on/off toggle plus a description, and a **Restore defaults** button reverts the preferences. Preferences are stored globally (not per-project).
+
+**Available rules:**
+
+| Rule | Default | Catches |
+|------|---------|---------|
+| `naming/duplicate-across-sources` | on | The same name exists in two scopes (project + global, etc.) — surfaces which copy will actually load |
+| `hook/matcher-regex-invalid` | on | Hook `matcher` regex won't compile |
+| `parse/yaml-json-error` | on | Frontmatter or JSON config can't be parsed |
+| `mcp/command-not-on-path` | off | MCP `stdio` command is not on the server's `PATH` |
+| `mcp/url-invalid` | on | MCP `url` field is malformed for the chosen transport |
+| `agent/tools-non-standard` | on | Agent declares a tool name Claude Code does not recognize |
+| `hook/env-var-undefined` | on | Hook body references `${VAR}` that is not set on the server |
+
+### 12.13 Secret-on-Shared Guard
+
+When you save (or copy) a harness file whose share badge is **Shared**, Hammoc scans the content for plaintext secrets — long base64-looking values, AWS-style keys, bearer tokens — using both pattern and Shannon-entropy checks. If a likely secret is detected, the save is blocked and a dialog appears with three options:
+
+- **Move to local file** — Auto-create a sibling file (e.g., `settings.local.json` next to `settings.json`), move the value there, and re-save the original with a reference. This keeps the secret out of git
+- **Mark this value as not a secret** — One-shot opt-out for this save only; the heuristic does not persist the decision
+- **Cancel** — Close the dialog without saving
+
+The dialog lists exactly which values were flagged (line numbers for text files, dot-paths for JSON/YAML) so you can verify before deciding. The entropy gate avoids tripping on ordinary base64-looking strings (image tokens, integration test fixtures) that fall below the threshold.
+
+### 12.14 Fullscreen Editor
+
+Every Markdown body in the workbench — skill body and raw view, skill bundle files, command body and raw view, agent system prompt and raw view, `CLAUDE.md` (both columns), snippet body — shows a small **Expand** button (⤢ icon) above the editor area. Clicking it opens a fullscreen overlay with the same CodeMirror instance, line wrapping, and a Markdown edit / preview toggle, so you can write long content without scrolling inside a narrow modal. Edits in the overlay sync back to the host panel through the same 300 ms debounce auto-save — there is no separate save button. Close the overlay with **X** or `Escape`. Read-only buffers (a plugin-scope file, a bundled snippet) show a small "read-only" chip in the overlay header.
+

package/packages/server/resources/manual/13-settings.md

@@ -0,0 +1,241 @@
+## 13. Settings
+
+Access settings via the gear icon or the Settings page. The page has **8 tabs**: Global, Project, Notifications, Claude Account, Hammoc User, Advanced, Help, and About. On desktop, tabs appear as a sidebar; on mobile, they use an accordion layout.
+
+> Per-project overrides have moved out of this page. See §5.3 — they now live in each project's own Settings tab (the workbench-level General section).
+
+### 13.1 Theme
+
+- **Dark** — Dark background, light text (default)
+- **Light** — Warm gray background, dark text
+- **System** — Follows your OS/browser preference
+
+### 13.2 Language
+
+Hammoc supports 6 languages:
+
+- English
+- 中文(简体) (Chinese Simplified)
+- 日本語 (Japanese)
+- 한국어 (Korean)
+- Español (Spanish)
+- Português (Portuguese)
+
+Language is auto-detected from your browser settings. Override it manually in settings.
+
+### 13.3 Default Model
+
+Choose the default Claude model:
+
+**Default:**
+- **Default** — Uses the SDK/system default model
+
+**Aliases (always latest version):**
+- **Sonnet** — Latest Sonnet
+- **Opus** — Latest Opus
+- **Haiku** — Latest Haiku
+
+**Claude 4.x:**
+- Opus 4.7 (most capable, 1M context), 4.6, 4.5, 4.1, 4
+- Sonnet 4.5, 4
+- Haiku 4.5
+
+**Claude 3.x:**
+- Sonnet 3.7, 3.5
+- Haiku 3.5
+- Opus 3, Sonnet 3, Haiku 3
+
+Can be overridden per-project (see §5.3).
+
+### 13.4 Default Permission Mode
+
+Set how Claude handles file modifications:
+
+| Mode | Behavior |
+|------|----------|
+| **Last Used** | Keeps the permission mode from the previous session |
+| **Plan** | Claude plans but doesn't make changes |
+| **Ask before edits** | Claude asks for approval before each change (default) |
+| **Edit automatically** | Claude edits files automatically |
+| **Bypass permissions** | Full autonomy, no restrictions |
+
+**Auto-approve safety checks** — When Bypass mode is selected, a checkbox option appears to automatically approve CLI safety check prompts without user confirmation. Enabled by default.
+
+Can be overridden per-project (see §5.3). Quick-cycle with `Shift+Tab` when the chat input is focused.
+
+### 13.5 Markdown File Open Mode
+
+Choose how `.md` files open by default:
+
+- **Edit** — Opens in text editing mode
+- **Preview** — Opens in rendered preview mode
+
+### 13.6 File Explorer View
+
+Default view for the file explorer:
+
+- **Grid** — Icon-based Finder-style layout (default)
+- **List** — Traditional file list
+
+### 13.7 Layout Mode
+
+Control the overall page width:
+
+- **Narrow** — Content centered with a max width
+- **Wide** — Full-width layout using all available screen space
+
+Toggle via the layout button in the header.
+
+### 13.8 Project Settings
+
+Per-project overrides have moved out of the global Settings page. They now live inside each project under **Project → Settings → General** (see §5.3). The Harness Workbench group on the same tab covers plugin / skill / hook / MCP / command / agent / CLAUDE.md / snippet management for that project (see §12).
+
+### 13.9 Chat Timeout
+
+How long to wait for Claude's response:
+
+- 1 minute
+- 3 minutes
+- **5 minutes** (default)
+- 10 minutes
+- 30 minutes
+
+The timeout resets on every activity. If overridden by an environment variable, the field is disabled with an amber warning.
+
+### 13.10 Default Thinking Effort
+
+Set the default thinking effort for new sessions:
+
+- **SDK Default** / Low / Medium / High / XHigh / Max
+- Max is available on Opus 4.6, Sonnet 4.6, and Opus 4.7
+- XHigh is available only on Opus 4.7 (and is the SDK default for that model)
+- If the active model does not support the configured level, it falls back to High automatically — the saved preference is kept, only the request to the SDK is clamped
+- The chosen level is preserved while the active model is still resolving (no flicker back to Default during project switches)
+
+### 13.11 Quick Panel Defaults
+
+- **Default Open** — Whether the quick panel opens automatically when entering a chat page (default: On)
+- **Default Side** — Which side the quick panel appears on:
+  - **Left** — Always opens on the left
+  - **Right** — Always opens on the right (default)
+  - **Last Used** — Remembers the last side you used and restores it
+
+### 13.12 Notifications
+
+The Notifications tab contains two sections: Web Push and Telegram.
+
+#### 13.12.1 Web Push Notifications
+
+Receive browser push notifications when Claude needs attention. Requires HTTPS and a browser that supports the Push API (Chrome, Firefox, Edge, Safari 16+).
+
+- **Subscribe** — Register the current browser to receive push notifications (requests browser notification permission)
+- **Unsubscribe** — Remove the current browser's push subscription
+- **Enable toggle** — Master switch to enable or disable web push delivery
+- **Subscribed devices** — Shows the number of browsers currently registered
+- **Test** — Send a test push notification to verify setup
+
+> iOS: Add Hammoc to Home Screen first, then subscribe from within the PWA.
+
+#### 13.12.2 Telegram Notifications
+
+Get notified on your phone when Claude needs attention:
+
+**Setup:**
+1. Create a Telegram bot via [@BotFather](https://t.me/BotFather) — enter the Bot Token
+2. Get your Chat ID via [@userinfobot](https://t.me/userinfobot) — enter the Chat ID
+3. Both fields support **change** and **delete** operations; bot tokens are shown **masked** for security
+
+**Enable/Disable:**
+- Master **enable checkbox** — requires both Bot Token and Chat ID to be configured before it can be toggled on
+
+**Chat Notification Types:**
+- **Permission requests** — Claude needs approval for file changes
+- **Completion** — Chat task finished
+- **Error** — Something went wrong during chat
+
+**Queue Notification Types:**
+- **Queue start** — Queue execution began
+- **Queue complete** — Queue finished all items
+- **Queue error** — Queue encountered an error
+- **Queue input needed** — Queue paused, waiting for user input
+
+**Other Options:**
+- **Always notify** — Get notified for every message (suppressed when the session is visible in the browser)
+
+**Test:** Click "Send Test" to verify your configuration.
+
+**Access URL:** Set your Hammoc base URL (e.g., `http://192.168.1.100:3000`) so notification links open directly in your browser.
+
+**Environment Variables:** Bot Token and Chat ID can be set via environment variables, which take priority over saved values (shown with an amber "Env" indicator).
+
+### 13.13 Claude Account
+
+Shows the Claude Code account that Hammoc is using, plus live subscription usage:
+
+- **Account info** — Email, Subscription plan, Provider (e.g., Claude API / Claude.ai), Organization (if applicable), and the timestamp of the last fetch
+- **Usage bars** — Two progress bars showing consumption of the **5-hour window** and **7-day window** quotas, with color thresholds (green / yellow / red at 50% / 80%) and reset times
+- **Refresh** — Manually fetch the latest account info and usage from the API (spinner shown while refreshing). Toast confirms success or failure
+- If no data has been fetched yet, a helper line explains that account info fills in automatically after the first chat or after clicking Refresh
+
+### 13.14 Hammoc User
+
+Local Hammoc authentication (independent of your Claude Code account):
+
+- **Change password** — Enter your current password, new password, and confirm. Minimum 4 characters. After changing, you'll be signed out and redirected to the login page.
+- **Logout** — Sign out immediately.
+
+### 13.15 System Prompt
+
+Customize Claude's behavior with a fully editable system prompt template:
+
+- **Warning banner** — Displayed at the top, cautioning about the impact of modifications
+- **Editable textarea** — Edit the system prompt with **auto-save**
+- **Character count** — Shown below the editor
+- **"Customized" indicator** — Blue banner when a custom prompt is active
+- **Restore to Default** button — Appears when the prompt has been modified
+- **Template variables** — Listed below the editor with descriptions (e.g., `{gitBranch}`, `{gitMainBranch}`, `{gitStatus}`); variables are resolved at runtime
+- **Resolved preview** — Toggle to see the fully rendered prompt with variables replaced for the current project
+
+> The default template focuses Claude on Hammoc-specific features (snippets, queue runner, board, BMAD, permission modes, sessions) and points at the manual + internals docs that Hammoc syncs to `~/.hammoc/docs/` on every server boot, so agents always have current docs even when run from a fresh install. The `{gitStatus}` block is no longer baked into the default — re-add it via this editor if you want it pre-included.
+
+### 13.16 Advanced Settings
+
+**Server Management (mode-dependent):**
+
+- **Development mode:** "Server Rebuild" button — rebuilds and restarts the server. Shows elapsed time during the build process
+- **Production mode:** Shows current version number, "Check for Updates" button, and "Install Update" button (appears only when an update is available). Includes build progress with elapsed timer
+
+**File Checkpointing:**
+- **Chat sessions** — Save file snapshots during chat for rewind/restore (default: on). Disabling this prevents the Code Rewind feature (see §2.20) from working
+- **Queue runner** — Save file snapshots during queue execution (default: off). Enabling increases JSONL session file size
+
+**SDK Parameters:**
+- **Max Thinking Tokens** — Limit Claude's extended thinking tokens (1,024–128,000)
+- **Max Turns** — Limit conversation turns per query (1–100)
+- **Max Budget (USD)** — Set cost limit per query ($0.01–$100)
+
+> **Scope (as of v1.3.0)**: these SDK parameters now apply to **both** direct chat sends and Queue Runner executions. Earlier releases silently dropped them in the queue path — if your queue runs started honoring Max Turns or Max Thinking Tokens after upgrading, this is why. Adjust the values if the new behavior surprises you.
+
+### 13.17 Help
+
+In-app usage guide within the Settings page:
+
+- **Basic chat usage** — How to use the chat interface
+- **Slash commands** — Available command reference
+- **Permission mode guide** — Plan, Ask Before Edits, Edit Automatically explained
+- **BMad Method** — Quick guide to the BMad workflow
+- **Keyboard shortcuts** — Key bindings table (Enter, Shift+Enter, Escape, Ctrl+C, F7/Shift+F7, /)
+
+### 13.18 About
+
+Displays app information:
+
+- App name and version number
+- Project description
+- Author with link
+- License type
+- **GitHub Issues** link
+- **Server status** — Healthy/unhealthy with color indicator dot
+- **Server version**
+- **Server time** — Localized timestamp
+

package/packages/server/resources/manual/14-keyboard-shortcuts.md

@@ -0,0 +1,68 @@
+## 14. Keyboard Shortcuts
+
+### Chat
+
+| Shortcut | Action |
+|----------|--------|
+| `Enter` | Send message (desktop only) |
+| `Shift+Enter` | New line in message |
+| `ESC` | Abort generation / close command palette |
+| `Ctrl+C` | Abort generation (only when no text is selected; otherwise copies) |
+| `↑` / `↓` | Navigate prompt history (when cursor is at start/end of input) |
+| `/` | Open slash command palette (auto-triggered when input starts with `/`) |
+| `*` | Open star command palette (auto-triggered when input starts with `*`, requires active agent) |
+| `%` | Open snippet autocomplete palette (auto-triggered when input starts with `%`) |
+| `Tab` | Select highlighted command from palette |
+| `Shift+Tab` | Cycle permission mode (Plan → Ask before edits → Edit automatically → Bypass) |
+| `Ctrl` (hold) | Temporary chain mode while held |
+
+### Message Actions
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Enter` / `Cmd+Enter` | Accept edited message |
+| `ESC` | Cancel message edit |
+
+### Quick Panel
+
+| Shortcut | Action |
+|----------|--------|
+| `Alt+1` | Toggle Sessions panel |
+| `Alt+2` | Toggle Files panel |
+| `Alt+3` | Toggle Git panel |
+| `Alt+4` | Toggle Terminal panel |
+
+Note: Quick panel shortcuts are disabled when an input or textarea is focused.
+
+### Editor
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+S` / `Cmd+S` | Save file |
+| `ESC` | Close editor |
+
+### Diff Viewer
+
+| Shortcut | Action |
+|----------|--------|
+| `F7` | Next change |
+| `Shift+F7` | Previous change |
+| `ESC` | Close diff viewer (fullscreen mode) |
+
+### Image Viewer
+
+| Shortcut | Action |
+|----------|--------|
+| `←` / `→` | Previous / next image (when multiple images form a set) |
+| `ESC` | Close image viewer |
+
+### Terminal
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl++` or `Ctrl+=` | Increase font size |
+| `Ctrl+-` | Decrease font size |
+| `Ctrl+0` | Reset font size |
+| `←` / `→` | Switch between terminal tabs |
+| `Delete` | Close active terminal tab |
+

package/packages/server/resources/manual/15-environment-variables.md

@@ -0,0 +1,28 @@
+## 15. Environment Variables
+
+### Server
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Server port |
+| `HOST` | `0.0.0.0` | Bind address (all interfaces) |
+| `NODE_ENV` | — | Set to `production` for optimized mode |
+| `TRUST_PROXY` | `false` | Enable reverse proxy support. Set to `true` when behind Cloudflare Tunnel, nginx, etc. |
+| `CORS_ORIGIN` | `true` | CORS origin policy. `true` allows any origin (local/VPN use). Set a specific URL (e.g., `https://hammoc.example.com`) to restrict |
+| `ANTHROPIC_API_KEY` | — | Anthropic API key (required for Claude Code to function) |
+| `CHAT_TIMEOUT_MS` | `300000` | Chat response timeout in milliseconds (5 minutes). Overrides the Settings UI value |
+| `LOG_LEVEL` | `INFO` (prod) / `DEBUG` (dev) | Logging level: ERROR, WARN, INFO, DEBUG, VERBOSE |
+| `TERMINAL_ENABLED` | `true` | Enable/disable terminal feature (set `false` to disable). Overrides the Settings UI value |
+| `SHELL_TIMEOUT` | `30000` | Time (in ms) before an idle terminal session is cleaned up |
+| `MAX_TERMINAL_SESSIONS` | `10` | Maximum concurrent terminal sessions |
+| `TELEGRAM_BOT_TOKEN` | — | Telegram bot token (takes priority over Settings UI value) |
+| `TELEGRAM_CHAT_ID` | — | Telegram chat ID (takes priority over Settings UI value) |
+| `BASE_URL` | — | Fallback base URL for Telegram notification links (e.g., `http://192.168.1.100:3000`) |
+
+### Client (Vite)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VITE_SERVER_PORT` | `3000` | Server port the client connects to (useful for multi-instance setups) |
+| `VITE_LOG_LEVEL` | — | Client-side debug log level: ERROR, WARN, INFO, DEBUG, VERBOSE |
+

package/packages/server/resources/manual/16-troubleshooting.md

@@ -0,0 +1,110 @@
+## 16. Troubleshooting
+
+### 16.1 "Claude Code CLI not found"
+
+Claude Code CLI must be installed and in your PATH:
+
+```bash
+claude --version
+```
+
+If not installed, follow the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code). The Onboarding page shows CLI installation, authentication, and API key status at a glance.
+
+### 16.2 "Authentication required" / `claude login`
+
+If the chat displays an authentication error, Claude Code CLI needs to be logged in:
+
+```bash
+claude login
+```
+
+The Onboarding page (shown when CLI is not authenticated) displays the current auth status and provides setup commands.
+
+### 16.3 API rate limit exceeded
+
+When Anthropic API rate limits are reached, the chat shows a rate limit error with a retry delay. Solutions:
+
+1. Wait for the indicated retry period and try again
+2. Reduce concurrent sessions or shorten prompts
+3. Check your API usage / plan limits on the Anthropic console
+4. The header status indicator shows API health (yellow triangle = API unavailable)
+
+### 16.4 "Connection lost" / Reconnecting
+
+Hammoc automatically reconnects when the connection is lost. The header shows a status indicator: green (connected), yellow spinning (reconnecting), or red (disconnected with manual Reconnect button).
+
+On mobile, the app automatically recovers when returning from background.
+
+If the connection doesn't recover:
+
+1. Check that the server is still running
+2. Click the Reconnect button in the header (appears when disconnected)
+3. Refresh the browser
+4. Restart the server: `hammoc` or `npm start`
+
+### 16.5 Port already in use
+
+The server automatically retries when the port is in use. If it still fails:
+
+```bash
+hammoc --port 3001
+```
+
+Or set the environment variable: `PORT=3001 hammoc`
+
+### 16.6 Terminal not available
+
+Terminal may be disabled when:
+
+- Accessing from an external network (security restriction — only local IPs are allowed)
+- `TERMINAL_ENABLED=false` is set in environment
+- Maximum terminal sessions reached (default 10, configurable via `MAX_TERMINAL_SESSIONS`)
+
+### 16.7 Reset password
+
+If you forgot your password:
+
+```bash
+hammoc --reset-password
+```
+
+This prompts you to set a new password. Alternatively, delete `~/.hammoc/config.json` and restart the server to re-trigger the password setup flow in the browser.
+
+### 16.8 Chat timeout
+
+If Claude's responses are timing out:
+
+1. Go to **Settings > Global** and adjust the **Chat Timeout** dropdown
+2. Available values: 1 min, 3 min, 5 min (default), 10 min, 30 min
+3. Complex tasks (large codebases, multi-file edits) may need longer timeouts
+4. If the `CHAT_TIMEOUT_MS` environment variable is set, it overrides the UI setting (shown with an indicator)
+
+### 16.9 Large file warning
+
+Files over 1 MB display a truncation warning. Consider:
+
+- Using the terminal to view large files
+- Opening in an external editor
+- Breaking large files into smaller ones
+
+### 16.10 Data locations
+
+If you need to find or back up your data:
+
+| Data | Path |
+|------|------|
+| App config & password | `~/.hammoc/config.json` |
+| User preferences | `~/.hammoc/preferences.json` |
+| Queue templates | `<project-root>/.hammoc/queue-templates.json` (per project) |
+| Chain failures | `~/.hammoc/chain-failures/<sessionId>.json` (per session) |
+| Global snippets | `~/.hammoc/snippets/` (shared across all projects) |
+| Project snippets | `<project-root>/.hammoc/snippets/` (per project) |
+| Global harness items | `~/.claude/` (skills, agents, commands, hooks, `CLAUDE.md`, `.mcp.json`, `settings.json`) |
+| Project harness items | `<project-root>/.claude/` (same layout as global; project takes precedence) |
+| Session data | `~/.claude/projects/` |
+| Web Push VAPID keys | `~/.hammoc/vapid-keys.json` |
+| Web Push subscriptions | `~/.hammoc/push-subscriptions.json` |
+| TLS certificates | `~/.hammoc/key.pem`, `~/.hammoc/cert.pem` |
+| Manual shards (synced) | `~/.hammoc/docs/manual/` and `~/.hammoc/docs/.manual-version` (auto-synced from the npm package on server boot; agents read these via the absolute path embedded in the system prompt) |
+| Internals docs (synced) | `~/.hammoc/docs/internals/` (agent-only mechanism reference; also re-synced when the package version changes) |
+| Server logs | `./logs/server-YYYY-MM-DD.log` (daily log files in working directory) |