hammoc 1.4.0 → 1.5.0

package/packages/server/resources/manual/11-bmad-method-integration.md

@@ -0,0 +1,128 @@
+## 11. BMAD-METHOD Integration
+
+Hammoc provides first-class support for the [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) (Breakthrough Method for Agile AI-Driven Development).
+
+### 11.1 What is BMAD-METHOD?
+
+BMAD-METHOD is an open-source framework that structures AI-driven software development. It defines:
+
+- **Agents** — Specialized AI roles organized by workflow phase
+- **Documents** — PRD, Architecture spec, Frontend spec, Stories, QA plans, and supplementary docs (brainstorming, market research, competitor analysis, project brief)
+- **Workflows** — Phase-based processes from research through implementation to completion
+
+### 11.2 Setting Up BMad in a Project
+
+BMad can be set up in two ways:
+
+**During project creation:**
+1. In the **New Project** dialog, the **"Setup BMad"** checkbox is enabled by default
+2. Select the BMAD-METHOD version from the dropdown (defaults to latest)
+3. The `.bmad-core` folder is automatically created when the project is registered
+
+**For existing projects:**
+1. Open the project card's **kebab menu** (⋮) on the project list page
+2. Click **"Setup BMad"** (only shown for non-BMad projects)
+3. Confirm the version to install
+4. The `.bmad-core` folder is created with the required files
+
+The `.bmad-core` folder contains agents, tasks, templates, workflows, and configuration files including `core-config.yaml`.
+
+### 11.3 BMad Agents
+
+Click the **Agent Button** (Users icon, in the chat bottom bar right of the model selector) to open the agent dropdown:
+
+**Planning group:**
+
+| Agent | Role |
+|-------|------|
+| **Analyst** | Brainstorming, market research, competitor analysis, project brief |
+| **PM** (Product Manager) | Defines PRD with epics and stories |
+| **UX Expert** | Creates frontend specifications |
+| **Architect** | Designs system architecture (backend, frontend, full-stack) |
+
+**Implementation group:**
+
+| Agent | Role |
+|-------|------|
+| **SM** (Scrum Master) | Drafts stories, orchestrates development |
+| **PO** (Product Owner) | Validates story drafts against PRD |
+| **Dev** (Developer) | Implements features, applies QA fixes |
+| **QA** | Reviews and validates implementation quality |
+
+**Agent dropdown features:**
+- **Categorized groups** — Planning, Implementation, Other (with section labels)
+- **Active agent checkmark** — Blue check icon next to the currently active agent
+- **Agent icon & description** — Emoji icon and hover tooltip with role description
+- **Keyboard navigation** — Arrow Up/Down to move, Enter to select, Escape to close
+- Selecting an agent sends the agent command (e.g., `/BMad:agents:pm`) as the first prompt in the session
+
+### 11.4 Project Overview Dashboard
+
+For BMad projects, the overview page displays additional sections above the standard project overview (see §5.5):
+
+**BMad Summary Card:**
+- Overall **completion percentage** with a progress bar
+- **Done/total epics** and **done/total stories** counts
+- Background refresh indicator
+
+**Next Step Recommender:**
+- Detects the current **workflow phase** (Pre-PRD, Pre-Architecture, Implementation, Completed)
+- Shows context-aware **action buttons** (primary/secondary) that navigate to the right agent + task command
+- Quick links: New Session, Queue Runner, File Explorer
+- See §11.5 for phase details
+
+**Document Status Card:**
+- Core documents: **PRD** and **Architecture** with exists/missing indicators
+- Supplementary documents: Brainstorming, Market Research, Competitor Analysis, Project Brief, Frontend Spec, UI Architecture
+- **"작성 필요"** (Required) badge for missing core documents; **"작성 권장"** (Recommended) for optional documents
+- **Agent shortcut buttons** (→) to create missing documents with the appropriate agent
+- **Sharded document support** — PRD and Architecture can be split into multiple files; expandable file tree view
+- **Auxiliary documents** section — Stories and QA files with counts and expandable file trees
+
+**Epic Progress Card:**
+- Each epic shows a **color-coded progress bar** that reflects completion level
+- **Done/planned** story count per epic
+- Click to **expand** and see individual story statuses with color-coded badges
+- Story file links to navigate directly to the story file
+- Unwritten story count shown when planned > written
+
+**Recent Issues Card** (replaces Quick Start for BMad projects):
+- Last 5 issues with severity dot, title, and status badge
+- Click to navigate to the project board
+- Link to "View Board"
+
+### 11.5 Workflow Phases & Recommendations
+
+The Next Step Recommender analyzes the project state and suggests actions based on four phases:
+
+**Phase 1: Pre-PRD** (PRD does not exist)
+- **Primary:** Create PRD → PM agent
+- **Secondary:** Brainstorming, Market Research, Competitor Analysis, Project Brief → Analyst agent
+- Once a Project Brief already exists, the **Brainstorming** suggestion is hidden — the recommender treats the Brief as the brainstorm output and stops nagging
+
+**Phase 2: Pre-Architecture** (PRD exists, Architecture does not)
+- **Primary:** Create Backend / Frontend / Full-stack Architecture → Architect agent
+- **Secondary:** Create Frontend Spec → UX Expert agent (if not exists)
+
+**Phase 3: Implementation** (both PRD and Architecture exist)
+
+Recommendations follow reverse workflow order (finish what's closest to done first):
+
+- **Priority 1:** QA Passed/Waived stories → Commit and mark Done, or re-request QA review → Dev agent
+- **Priority 2:** QA Fixed stories → Re-review → QA agent
+- **Priority 3:** QA Failed/Concerns stories → Apply QA fixes → Dev agent
+- **Priority 4:** Ready for Review stories (no QA gate) → Request QA review → QA agent
+- **Priority 5:** In Progress stories → Continue development → Dev agent
+- **Priority 6:** Approved stories → Start development (Dev), or re-validate with Validate and Fix / Validate Only → PO agent
+- **Priority 7:** Draft stories → Validate and Fix / Validate Only → PO agent
+- **Priority 8:** Create next story → SM agent (when no actionable stories)
+
+**Phase 4: Completed** (all planned stories are Done)
+- Brainstorm new features → Analyst agent
+- Add new epic → PM agent
+- Add story to existing epic → SM agent
+
+### 11.6 Queue Templates from PRD
+
+Queue templates automate story development in batch. For details, see §9.9 (Queue Templates).
+

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 |
+