hammoc 1.4.0 → 1.6.0

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.8 (most capable, 1M context), 4.7, 4.6, 4.5, 4.1, 4
+- Sonnet 4.6 (1M context), 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, Opus 4.7, and Opus 4.8
+- XHigh is available on Opus 4.7 and Opus 4.8 (and is the SDK default for those models)
+- 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) |

package/packages/server/resources/manual/INDEX.md

@@ -0,0 +1,60 @@
+# Hammoc Manual Index (Sharded)
+
+This is a sharded mirror of `docs/MANUAL.md`, generated by `npm run build:manual-shards`.
+Each chapter lives in its own file so an agent can load only the part it needs instead of the full ~31k-token manual.
+
+## How to use this index
+
+1. Skim the chapter list below to find the topic that matches the current task.
+2. Check the audience tag — `[agent]` chapters are the ones written for an automated assistant to act on; `[user-setup]` chapters are reference material for the human operator and rarely help an agent.
+3. Read the chapter file you need with the file Read tool. Don't load the whole manual at once.
+
+When the user mentions a Hammoc-specific concept (queue, snippet, board, BMad agent, project, session, etc.) and you are not sure how the feature behaves, the matching chapter below is the source of truth — read it before guessing or improvising.
+
+## Chapters
+
+<!-- chapter-list:start -->
+- 1. [Getting Started](./01-getting-started.md)
+- 2. [Chat](./02-chat.md)
+- 3. [Sessions](./03-sessions.md)
+- 4. [Slash Commands & Favorites](./04-slash-commands-favorites.md)
+- 5. [Projects](./05-projects.md)
+- 6. [File Explorer & Editor](./06-file-explorer-editor.md)
+- 7. [Git](./07-git.md)
+- 8. [Terminal](./08-terminal.md)
+- 9. [Queue Runner](./09-queue-runner.md)
+- 10. [Project Board](./10-project-board.md)
+- 11. [BMAD-METHOD Integration](./11-bmad-method-integration.md)
+- 12. [Harness Workbench](./12-harness-workbench.md)
+- 13. [Settings](./13-settings.md)
+- 14. [Keyboard Shortcuts](./14-keyboard-shortcuts.md)
+- 15. [Environment Variables](./15-environment-variables.md)
+- 16. [Troubleshooting](./16-troubleshooting.md)
+<!-- chapter-list:end -->
+
+## Audience and trigger keywords
+
+| # | Chapter | Audience | Read when the user mentions / asks about |
+|---|---|---|---|
+| 1 | Getting Started | `[user-setup]` | Hammoc install, CLI flags, HTTPS / TLS, mobile access, reverse proxy. (Operator setup; rarely useful to an agent.) |
+| 2 | Chat | `[agent]` | streaming, message edit, conversation fork / branching, summarize & continue, code rewind, prompt chaining, extended thinking, model selector, thinking effort, context usage, abort behaviour |
+| 3 | Sessions | `[agent]` | session list, session search, rename / delete, quick session panel, active streaming indicator |
+| 4 | Slash Commands & Favorites | `[agent]` **(important)** | `/` slash commands, `%` snippets, snippet arguments and context blocks, multi-prompt snippets, snippet hierarchy (project / global / bundled), star palette, favorites |
+| 5 | Projects | `[agent]` | project list, project creation (with optional BMad init), per-project settings, project overview page, hide / delete projects |
+| 6 | File Explorer & Editor | `[user-setup]` | UI panel that the user operates by hand. The agent uses Read / Write / Edit tools directly instead. |
+| 7 | Git | `[user-setup]` | UI panel for staging / committing / branching. The agent uses git via Bash directly. |
+| 8 | Terminal | `[user-setup]` | UI terminal panel. The agent uses Bash / PowerShell tools directly. |
+| 9 | Queue Runner | `[agent]` **(important)** | queue editor, special commands (`@new`, `@save`, `@load`, `@pause`, `@model`, `@delay`, `@pauseword`, `@loop` / `@end`, `@(` / `@)`, `#` comments), multiline prompts, pauseword, loop blocks, templates, session locking, story-based generation, variable substitution |
+| 10 | Project Board | `[agent]` | Kanban / list view, issue types (Bug / Improvement), severity (Low / Medium / High / Critical), status workflow (Open → Draft → Approved → In Progress → Blocked → Review → Done → Closed), card context menu, attachments |
+| 11 | BMAD-METHOD Integration | `[agent]` **(important)** | BMad agents (SM, PM, Architect, Dev, QA, PO, etc.), agent switching, `.bmad-core` setup, PRD → Queue automation, project overview dashboard, workflow phases, story workflows |
+| 12 | Harness Workbench | `[agent]` **(important)** | Editing `.claude/` items (skills, MCP, hooks, slash commands, sub-agents, `CLAUDE.md`), Hammoc `%snippets` and command favorites, share badges / mode banner, static lint, secret-on-shared guard. Also see the on-disk layout in `~/.hammoc/docs/internals/harness-files.md`. |
+| 13 | Settings | `[mixed]` | Read individual subsections only. `[agent]`-relevant: System Prompt (13.15), Default Permission Mode (13.4), Default Model (13.3), Default Thinking Effort (13.10), Advanced Settings (13.16). Per-project overrides now live with the project (see chapter 5.3 / chapter 12). The rest is `[user-setup]`. |
+| 14 | Keyboard Shortcuts | `[user-setup]` | Reference table for the human operator. The agent does not press keys. |
+| 15 | Environment Variables | `[user-setup]` | Server / Vite env vars for operator configuration. |
+| 16 | Troubleshooting | `[user-setup]` | Operator-facing diagnosis recipes (CLI not found, auth, port in use, etc.). |
+
+## Notes for maintainers
+
+- `docs/MANUAL.md` is the single source of truth. Edit it, then run `npm run build:manual-shards` to regenerate the chapter files. The chapter-list block above is auto-updated; everything else in this file is hand-maintained.
+- The audience table above is **manually curated**. When you add a new chapter, decide whether it is `[agent]`, `[user-setup]`, or `[mixed]` and add a row.
+- Shards are packaged into the npm tarball under `packages/server/resources/manual/` and synced to `~/.hammoc/docs/manual/` on Hammoc server boot, so any user environment running Hammoc can read this index.

package/packages/shared/dist/index.d.ts

@@ -24,4 +24,11 @@ export * from './types/terminal.js';
 export * from './types/dashboard.js';
 export * from './types/board.js';
 export { LogLevel, parseLogLevel } from './types/logger.js';
+export * from './types/harness.js';
+export * from './types/observability.js';
+export { splitMarkdownByH2, appendMarkdownSections, MarkdownH2Section, } from './utils/markdownSections.js';
+export * from './types/harnessBundle.js';
+export * from './types/bmadCoreConfig.js';
+export * from './types/contextBuilder.js';
+export * from './types/marketplace.js';
 //# sourceMappingURL=index.d.ts.map

package/packages/shared/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAC;AAG/B,cAAc,sBAAsB,CAAC;AAGrC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AAIrC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EACL,UAAU,EACV,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAIrF,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,4BAA4B,EAC5B,0BAA0B,EAC1B,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAG9F,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,2BAA2B,EAC3B,6BAA6B,EAC7B,eAAe,EACf,0BAA0B,EAC1B,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,cAAc,uBAAuB,CAAC;AAGtC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAG/F,cAAc,gBAAgB,CAAC;AAG/B,cAAc,qBAAqB,CAAC;AAGpC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAC;AAG/B,cAAc,sBAAsB,CAAC;AAGrC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AAIrC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,gBAAgB,CAAC;AAG/B,OAAO,EACL,UAAU,EACV,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,sBAAsB,EACtB,YAAY,GACb,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,YAAY,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAIrF,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,cAAc,EACd,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,eAAe,EACf,4BAA4B,EAC5B,0BAA0B,EAC1B,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAG9F,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,2BAA2B,EAC3B,6BAA6B,EAC7B,eAAe,EACf,0BAA0B,EAC1B,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,eAAe,EACf,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAG5B,cAAc,uBAAuB,CAAC;AAGtC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG/E,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAG/F,cAAc,gBAAgB,CAAC;AAG/B,cAAc,qBAAqB,CAAC;AAGpC,cAAc,sBAAsB,CAAC;AAGrC,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAG5D,cAAc,oBAAoB,CAAC;AAGnC,cAAc,0BAA0B,CAAC;AAGzC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAGrC,cAAc,0BAA0B,CAAC;AAGzC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,2BAA2B,CAAC;AAG1C,cAAc,wBAAwB,CAAC"}

package/packages/shared/dist/index.js

@@ -45,4 +45,18 @@ export * from './types/dashboard.js';
 export * from './types/board.js';
 // Logger types (shared between server and client)
 export { LogLevel, parseLogLevel } from './types/logger.js';
+// Story 28.0.5: Harness workbench shared types (Epic 28 common infra)
+export * from './types/harness.js';
+// Story 31.3: Observability — MCP call log + token attribution (Epic 31)
+export * from './types/observability.js';
+// Story 29.1: Markdown H2 split/append helpers (shared by server & client)
+export { splitMarkdownByH2, appendMarkdownSections, } from './utils/markdownSections.js';
+// Story 30.3: Harness Export/Import bundle DTOs
+export * from './types/harnessBundle.js';
+// Story 31.1: BMad core-config.yaml editor DTOs (Epic 31)
+export * from './types/bmadCoreConfig.js';
+// Story 31.2: SessionStart context-builder DTOs (Epic 31)
+export * from './types/contextBuilder.js';
+// Story 31.4: Plugin marketplace catalog DTOs (Epic 31)
+export * from './types/marketplace.js';
 //# sourceMappingURL=index.js.map

package/packages/shared/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,cAAc,gBAAgB,CAAC;AAE/B,+CAA+C;AAC/C,cAAc,sBAAsB,CAAC;AAErC,2CAA2C;AAC3C,cAAc,sBAAsB,CAAC;AAErC,4DAA4D;AAC5D,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AAErC,kDAAkD;AAClD,2FAA2F;AAC3F,cAAc,oBAAoB,CAAC;AAEnC,iDAAiD;AACjD,cAAc,gBAAgB,CAAC;AAE/B,mDAAmD;AACnD,OAAO,EAGL,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,yBAAyB;AACzB,OAAO,EAKL,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,0CAA0C;AAC1C,OAAO,EAGL,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AAEzB,iCAAiC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAKtD,gDAAgD;AAChD,kDAAkD;AAClD,OAAO,EAGL,cAAc,GAYf,MAAM,oBAAoB,CAAC;AAM5B,gDAAgD;AAChD,OAAO,EAIL,mBAAmB,EASnB,mBAAmB,GAEpB,MAAM,wBAAwB,CAAC;AAiBhC,qEAAqE;AACrE,cAAc,uBAAuB,CAAC;AAEtC,uDAAuD;AACvD,cAAc,uBAAuB,CAAC;AAEtC,iCAAiC;AACjC,cAAc,kBAAkB,CAAC;AAEjC,kCAAkC;AAClC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE/E,uCAAuC;AACvC,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAE/F,kCAAkC;AAClC,cAAc,gBAAgB,CAAC;AAE/B,2CAA2C;AAC3C,cAAc,qBAAqB,CAAC;AAEpC,8BAA8B;AAC9B,cAAc,sBAAsB,CAAC;AAErC,oCAAoC;AACpC,cAAc,kBAAkB,CAAC;AAEjC,kDAAkD;AAClD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,cAAc,gBAAgB,CAAC;AAE/B,+CAA+C;AAC/C,cAAc,sBAAsB,CAAC;AAErC,2CAA2C;AAC3C,cAAc,sBAAsB,CAAC;AAErC,4DAA4D;AAC5D,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AAErC,kDAAkD;AAClD,2FAA2F;AAC3F,cAAc,oBAAoB,CAAC;AAEnC,iDAAiD;AACjD,cAAc,gBAAgB,CAAC;AAE/B,mDAAmD;AACnD,OAAO,EAGL,mBAAmB,EACnB,eAAe,GAChB,MAAM,iBAAiB,CAAC;AAEzB,yBAAyB;AACzB,OAAO,EAKL,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,0CAA0C;AAC1C,OAAO,EAGL,gBAAgB,GAGjB,MAAM,iBAAiB,CAAC;AAEzB,iCAAiC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAKtD,gDAAgD;AAChD,kDAAkD;AAClD,OAAO,EAGL,cAAc,GAYf,MAAM,oBAAoB,CAAC;AAM5B,gDAAgD;AAChD,OAAO,EAIL,mBAAmB,EASnB,mBAAmB,GAEpB,MAAM,wBAAwB,CAAC;AAiBhC,qEAAqE;AACrE,cAAc,uBAAuB,CAAC;AAEtC,uDAAuD;AACvD,cAAc,uBAAuB,CAAC;AAEtC,iCAAiC;AACjC,cAAc,kBAAkB,CAAC;AAEjC,kCAAkC;AAClC,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAE/E,uCAAuC;AACvC,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAE/F,kCAAkC;AAClC,cAAc,gBAAgB,CAAC;AAE/B,2CAA2C;AAC3C,cAAc,qBAAqB,CAAC;AAEpC,8BAA8B;AAC9B,cAAc,sBAAsB,CAAC;AAErC,oCAAoC;AACpC,cAAc,kBAAkB,CAAC;AAEjC,kDAAkD;AAClD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAE5D,sEAAsE;AACtE,cAAc,oBAAoB,CAAC;AAEnC,yEAAyE;AACzE,cAAc,0BAA0B,CAAC;AAEzC,2EAA2E;AAC3E,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,6BAA6B,CAAC;AAErC,gDAAgD;AAChD,cAAc,0BAA0B,CAAC;AAEzC,0DAA0D;AAC1D,cAAc,2BAA2B,CAAC;AAE1C,0DAA0D;AAC1D,cAAc,2BAA2B,CAAC;AAE1C,wDAAwD;AACxD,cAAc,wBAAwB,CAAC"}

package/packages/shared/dist/types/bmadCoreConfig.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Typed shape of the 18 known keys of `.bmad-core/core-config.yaml`.
+ *
+ * Every key is optional: a config that omits a key is valid, and the form
+ * renders an empty widget for it. The nested groups (`qa`, `prd`,
+ * `architecture`, `brownfieldEpic`) mirror the on-disk YAML nesting so the
+ * value of a leaf such as `prd.epicFilePattern` is reachable at the same path
+ * the AST patch op uses (`['prd', 'epicFilePattern']`).
+ *
+ * `customTechnicalDocuments` is `string[] | null` because the canonical
+ * default on disk is the literal `null` (an explicit "no extra docs" marker)
+ * that the form promotes to an array on first item add.
+ */
+export interface BmadCoreConfigKnownKeys {
+    markdownExploder?: boolean;
+    qa?: {
+        qaLocation?: string;
+    };
+    prd?: {
+        prdFile?: string;
+        prdVersion?: string;
+        prdSharded?: boolean;
+        prdShardedLocation?: string;
+        epicFilePattern?: string;
+    };
+    architecture?: {
+        architectureFile?: string;
+        architectureVersion?: string;
+        architectureSharded?: boolean;
+        architectureShardedLocation?: string;
+    };
+    customTechnicalDocuments?: string[] | null;
+    devLoadAlwaysFiles?: string[];
+    brownfieldEpic?: {
+        updateOnCreate?: string[];
+        doNotUpdate?: string[];
+    };
+    devDebugLog?: string;
+    devStoryLocation?: string;
+    slashPrefix?: string;
+}
+/**
+ * The 10 known TOP-LEVEL keys of `.bmad-core/core-config.yaml`. Any other
+ * top-level key in the parsed YAML is treated as "unknown" and round-trips
+ * untouched (AC4). Nested groups (`qa`/`prd`/`architecture`/`brownfieldEpic`)
+ * count as one top-level key each; their leaves are the 18-key matrix.
+ *
+ * Single source of truth shared by the server partition logic and any client
+ * consumer that needs to reason about top-level membership.
+ */
+export declare const BMAD_CORE_CONFIG_KNOWN_TOP_LEVEL_KEYS: readonly ["markdownExploder", "qa", "prd", "architecture", "customTechnicalDocuments", "devLoadAlwaysFiles", "brownfieldEpic", "devDebugLog", "devStoryLocation", "slashPrefix"];
+/** GET /api/harness/bmad-config/:projectSlug response. */
+export interface BmadCoreConfigReadResponse {
+    /** Full raw text of `.bmad-core/core-config.yaml` — feeds the Raw editor toggle. */
+    content: string;
+    /** ISO 8601 mtime — STALE_WRITE ETag echoed back on the next patch/raw write. */
+    mtime: string;
+    /** Known top-level keys, typed. Drives the 18-key form widgets. */
+    knownKeys: BmadCoreConfigKnownKeys;
+    /**
+     * Unknown top-level keys (BMad schema extensions or user-defined keys) shown
+     * read-only in the "unknown keys" section with a JS-type hint each (AC4.a).
+     */
+    unknownKeys: Record<string, unknown>;
+}
+/** PATCH / PUT(raw) write response. */
+export interface BmadCoreConfigWriteResponse {
+    /** ISO 8601 mtime after the write — the client persists this as the next ETag. */
+    mtime: string;
+}
+//# sourceMappingURL=bmadCoreConfig.d.ts.map

package/packages/shared/dist/types/bmadCoreConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bmadCoreConfig.d.ts","sourceRoot":"","sources":["../../src/types/bmadCoreConfig.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,uBAAuB;IACtC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,EAAE,CAAC,EAAE;QACH,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,YAAY,CAAC,EAAE;QACb,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;QAC7B,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,2BAA2B,CAAC,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,wBAAwB,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3C,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,cAAc,CAAC,EAAE;QACf,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAC1B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;KACxB,CAAC;IACF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,qCAAqC,kLAWxC,CAAC;AAEX,0DAA0D;AAC1D,MAAM,WAAW,0BAA0B;IACzC,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,SAAS,EAAE,uBAAuB,CAAC;IACnC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,uCAAuC;AACvC,MAAM,WAAW,2BAA2B;IAC1C,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf"}