hammoc 1.5.0 → 1.7.0

package/packages/server/resources/manual/02-chat.md

@@ -56,6 +56,7 @@ Attach images to your messages for Claude to analyze:
 - Maximum: 5 images per message, 10MB per image
 - Images preview in the input area before sending
 - Sent images display as clickable thumbnails above the message text. Clicking a thumbnail opens the full image viewer with multi-image navigation (see §6.4)
+- Image attachments work with both conversation engines (SDK and CLI). With the CLI engine the image is passed to Claude by file reference instead of being embedded inline, but you attach it exactly the same way — the model still sees it
 
 ### 2.5 Tool Call Visualization
 
@@ -127,7 +128,7 @@ Monitor token usage in real-time:
 - **Rate limit dots** — 5h/7d utilization indicators in the input area
 - **Color thresholds** — Green (normal), Yellow (moderate), Red (high usage)
 - **Context compaction** — Click the usage donut to trigger compaction, which summarizes the conversation to free up context space. At critical usage levels, clicking instead creates a new session
-- **Auto-compact on overflow** — When message history hits the context window limit, Hammoc automatically compacts the context and retries the message instead of losing the session
+- **Auto-compact on overflow** — When message history hits the context window limit, Hammoc automatically compacts the context and retries the message instead of losing the session. A master switch in Advanced Settings (see §13.17) lets you disable auto-compaction entirely and manage compaction manually instead
 
 ### 2.11 Aborting Responses
 
@@ -169,19 +170,27 @@ When Claude uses extended thinking, the reasoning is shown in a collapsible bloc
 
 The model selector button is located in the chat input toolbar. It displays the current model family name (e.g., "Opus", "Sonnet", "Haiku") directly on the button. When using the default model, it shows "Default". Click to open a dropdown for choosing a different model and adjusting thinking effort.
 
+**1M context window** — For models that support a 1-million-token context window (Opus 4.8, Sonnet 4.6), a **"1M context"** toggle appears near the top of the dropdown:
+
+- **Opus** — Locked on. The 1M window is included with your Max subscription at no extra cost, so it is always engaged and cannot be switched off (the toggle shows "Included with Max").
+- **Sonnet** (and other non-Opus 1M-capable models) — Off by default. Sonnet's 1M window bills to usage credits rather than your subscription, so you opt in explicitly. The toggle shows a "Requires usage credits" hint that turns amber once enabled. Left off, Sonnet runs at the standard 200K context window.
+- **Fable 5** — Opt-in, same as Sonnet. The toggle appears and defaults to off.
+
+The toggle only appears for 1M-capable models; every other model uses its native context window and shows no toggle.
+
 ### 2.16 Thinking Effort
 
 Control how much Claude "thinks" before responding. The intensity bar appears inside the model selector dropdown. The number of bars depends on the selected model:
 
 - **Low / Medium / High** — 3 levels, available for all models
 - **Max** — 4th level, added for Opus 4.6 / Sonnet 4.6
-- **XHigh** — 5th level, added only for **Opus 4.7** (the default effort for this model is XHigh)
+- **XHigh** — 5th level, added for **Opus 4.7+** and **Fable 5** (the default effort for these models is XHigh)
 
 Behavior:
 
 - Click the currently active level again to reset to default
 - Cannot be changed while Claude is responding
-- If you switch to a model that doesn't support the current level (e.g., XHigh → non-Opus-4.7, or Max → model without Max), the effort automatically resets to the highest supported level
+- If you switch to a model that doesn't support the current level (e.g., XHigh → model without XHigh, or Max → model without Max), the effort automatically resets to the highest supported level
 - When the active model is temporarily unknown (e.g., right after switching projects before the resolved model arrives), the dropdown keeps your saved choice instead of resetting it. As soon as the model is known, the effort is reclamped if necessary
 
 The default thinking effort for new sessions can be configured in Settings > Global.
@@ -274,7 +283,7 @@ Browse all conversation branches in a read-only mode:
 
 ### 2.24 Max Budget Warning Banner
 
-When the **Max Budget (USD)** advanced setting (see §13.16) is configured, a sticky banner appears at the top of the chat area once the session cost approaches the limit:
+When the **Max Budget (USD)** advanced setting (see §13.17) is configured, a sticky banner appears at the top of the chat area once the session cost approaches the limit:
 
 - **Yellow warning** (80% threshold) — "Budget warning: $X.XXXX / $Y.YYYY used (ZZ%) — approaching Max Budget limit."
 - **Red critical warning** (95% threshold) — "Budget critical: $X.XXXX / $Y.YYYY used (ZZ%) — stream will auto-stop when limit is exceeded."
@@ -283,3 +292,13 @@ When the **Max Budget (USD)** advanced setting (see §13.16) is configured, a st
 
 The banner disappears automatically once the running cost falls back below the warning threshold (for example, after starting a new session).
 
+### 2.25 Background Task Wait Card
+
+When Claude launches background tasks (e.g., background `Agent` sub-tasks), an amber notification card appears below the message stream showing:
+
+- **Elapsed timer** — A running clock (mm:ss) counting how long the background work has been running
+- **Pending count** — Number of background tasks still in progress
+- **Stop button** — Appears after a configurable delay (default 60 seconds) to let you abort if something seems stuck
+
+The card disappears automatically once all background tasks complete.
+

package/packages/server/resources/manual/03-sessions.md

@@ -13,6 +13,7 @@ Access the session list via the sidebar or quick panel:
 - **Streaming indicator** — Green dot with animation when streaming
 - **Waiting indicator** — Amber pulsing dot with "Waiting" badge when a session is connected but not yet streaming
 - **Queue badge** — Shown when queue runner is active on the session
+- **Early visibility** — New sessions appear in the list as soon as a message is sent, with no brief delay
 - Empty sessions are hidden by default (toggle with the eye icon)
 
 ### 3.2 Creating a New Session

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

@@ -21,28 +21,41 @@ Each card has a **kebab menu** (⋮) with:
 
 **Dashboard summary bar** appears at the top when projects exist, showing aggregate stats: Projects, Sessions, Active, Queue, Terminals.
 
+**Header brand logo (Hammoc)** — The Hammoc logo on the left of every header is clickable and always returns you to the project list from any page (project Overview, Board, Sessions, Queue, Files, Git, Terminal, project Settings, chat session). Use it as a one-tap "Home" without going through the back button.
+
 ### 5.2 Creating a New Project
 
 1. Click **"New Project"** on the project list page
-2. Enter the project directory path
+2. Enter the project directory path, or click **Browse** to pick a folder visually (see below)
 3. The path is validated automatically with a short debounce while you type (`"Validating path..."` helper text is shown). Blurring the field validates immediately
 4. Path collision detection — if the path already belongs to an existing project, an amber warning appears with a **"Navigate to existing"** link and the **Create** button is disabled until you pick a different path
 5. Invalid paths show the server's validation message in red below the input, and also disable **Create**
 6. Optionally enable BMad Method initialization with version selection
 
+**Browse for a directory** — Instead of typing the path, click **Browse** to open a visual directory picker:
+
+- It opens expanded at your home directory. Click **My PC** to jump up to the drive roots (Windows) or filesystem root, then drill back down
+- A breadcrumb across the top shows your current location; click any segment to jump straight to that level
+- The folder tree lazy-loads subfolders as you expand them — only folders are shown, never files
+- Create a folder in place with **New folder**, or rename one with **Rename** (there is no delete here, by design)
+- Click **Select this path** to drop the highlighted folder into the path field. Browsing only fills the input; the normal validation and **Create** step still apply
+
+This is most useful on mobile or tablet, where typing a long absolute path by hand is awkward.
+
 ### 5.3 Project Settings
 
 Per-project settings live in their own tab inside each project (Overview / Queue / Git / Files / Terminal / Board / **Settings**), no longer under the global Settings page. Opening the tab takes you directly to that project's configuration — there is no project dropdown to disambiguate.
 
 The Settings tab has a two-pane layout:
 
-- **Left nav** — Two top-level groups: **General** and **Harness Workbench** (see §12)
+- **Left nav** — Top-level groups: **General**, **Harness Workbench** (see §12), **Context Builder** (§12.17), **Observability** (§12.18), and **Marketplace** (§12.19). BMad projects also get a **BMad Settings** group (§12.16)
 - **Right panel** — Form contents for the selected group
 
 **General group** (per-project override fields):
 
 - **Default model** — Override the global model selection
 - **Permission mode** — Override the global permission mode (Plan, Ask before edits, Edit automatically). Note: Bypass permissions is not available at project level
+- **Conversation engine** — Override which engine this project runs on: **Use Global default**, **SDK**, or **CLI** (see §13.16). When set to anything other than Global default, a "Project override" badge appears next to the field. The effective engine is resolved as project override → global setting → SDK
 - **Hidden toggle** — Hide the project from the project list
 - **Reset to Global Defaults** — Remove all overrides at once
 

package/packages/server/resources/manual/10-project-board.md

@@ -85,7 +85,7 @@ Draft → Approved → In Progress → Ready for Review → Done
 - **QA Waived** — Quality review waived/skipped
 - **QA Failed** — Quality review failed, fixes needed
 - **QA Concerns** — Quality review raised concerns
-- **QA Fixed** — Fixes applied, ready for re-review
+- **QA Fixed** — The developer has recorded a fix for the current gate; ready for re-review
 
 Not all statuses are required. Use the context menu to change status directly. **Promoted** indicates an issue that has been escalated to a story or epic.
 
@@ -134,9 +134,10 @@ Click the **⋮** button on any card to open the context menu. Actions vary by c
   - **Complete Story** — Mark as Done without committing
   - **Request QA Review** — Re-request quality review
 - **QA Failed / QA Concerns:**
-  - **Apply QA Fix** — Apply fixes for QA issues
+  - **Apply QA Fix** — Apply fixes for QA issues (always offered)
+  - **Review Story** — Re-request QA review; also offered unless Hammoc has confirmed fixes are still pending for the current gate (e.g., legacy stories or external BMad projects)
 - **QA Fixed:**
-  - **Review Story** — Request re-review after fixes
+  - **Apply QA Fix** / **Review Story** — Apply further fixes, or request re-review
 - **Ready for Review / Ready for Done (no QA gate):**
   - **Review Story** — Request quality review
 

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

@@ -60,6 +60,8 @@ Click the **Agent Button** (Users icon, in the chat bottom bar right of the mode
 
 For BMad projects, the overview page displays additional sections above the standard project overview (see §5.5):
 
+**QA gate parse warning** — If any QA gate file has formatting errors, an amber warning banner lists the affected files at the top of the overview so you can fix them.
+
 **BMad Summary Card:**
 - Overall **completion percentage** with a progress bar
 - **Done/total epics** and **done/total stories** counts
@@ -108,14 +110,16 @@ The Next Step Recommender analyzes the project state and suggests actions based
 
 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)
+- **Priority 1:** QA Passed/Waived stories → Commit and mark Done, mark Done without committing, or re-request QA review → Dev/QA agent
+- **Priority 2:** QA Failed/Concerns stories → the next step depends on whether the developer has already recorded a fix for the *current* gate:
+  - Fix already applied for this gate → Request QA re-review → QA agent
+  - Fix still needed → Apply QA fixes → Dev agent
+  - State unknown (a story from before this tracking existed, an external BMad project, or a manually-edited gate) → **both** "Apply QA fixes" and "Request QA review" are offered (apply-fixes leading) so you choose
+- **Priority 3:** Ready for Review stories (no QA gate) → Request QA review → QA agent
+- **Priority 4:** In Progress stories → Continue development → Dev agent
+- **Priority 5:** Approved stories → Start development (Dev), or re-validate with Validate and Fix / Validate Only → PO agent
+- **Priority 6:** Draft stories → Validate and Fix / Validate Only → PO agent
+- **Priority 7:** Create next story → SM agent (when no actionable stories)
 
 **Phase 4: Completed** (all planned stories are Done)
 - Brainstorm new features → Analyst agent

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

@@ -2,6 +2,8 @@
 
 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.
 
+The same Settings tab also hosts four sibling harness-engineering panels next to the Workbench (each a top-level nav item, not one of the Workbench's own sections): **BMad Settings** (§12.16, BMad projects only), **Context Builder** (§12.17), **Observability** (§12.18), and **Plugin Marketplace** (§12.19).
+
 ### 12.1 Layout
 
 The workbench has two stacked headers above an eight-section navigator:
@@ -31,7 +33,7 @@ A workbench-wide banner just above the navigator tells you how the project share
 
 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.
+> The Private mode banner surfaces an **Export** action on its right edge (in addition to the workbench-wide Bundle menu) so you can ship the current harness state to a teammate as a single `.zip` bundle. See §12.15 for the full export/import flow.
 
 ### 12.3 Share Badges
 
@@ -173,3 +175,82 @@ The dialog lists exactly which values were flagged (line numbers for text files,
 
 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.
 
+### 12.15 Bundle Export / Import (Team Sharing)
+
+When your project's `.claude/` tree is **fully git-ignored** (Mode B — typical when you use Hammoc itself to develop on Hammoc, or when your team intentionally keeps the harness out of source control), you can still share the entire workbench configuration with a teammate by exporting it as a single `.zip` bundle and importing on the other side. The workbench shows a **Bundle** menu (top-right of the workbench header, also surfaced as an **Export** button on the Mode B banner), with two actions:
+
+- **Export bundle** — Opens a dialog summarizing what will be packed (the five domain cards + `CLAUDE.md` + snippets) and lets you choose how secrets are handled:
+  - **Exclude (default)** — Secrets detected by the heuristic are stripped before packing; the recipient sees a *"N secrets removed"* toast after import. Use this when you want your teammate to fill in their own credentials.
+  - **Include as `${ENV_REF}` placeholders** — Detected secrets are replaced with named environment-variable references and a hint table lists which keys the recipient needs to set. Good for sharing a config skeleton without leaking real values.
+  - **Include explicit (with secrets)** — Plain-text secrets are packed as-is. This is the *"send it over secure DM and delete after use"* mode: you must check a second confirmation box before the dialog enables the download button, the resulting filename contains a visible `WITH-SECRETS` token, and a 5-second warning toast appears after the download starts.
+- **Import bundle** — Drop a `.zip` (or browse for one). Before anything is applied, Hammoc shows a preview of every incoming item alongside what already exists, with three per-item actions (Overwrite / Skip / Add only if missing) and three bulk-action shortcuts. Bundles tagged *"with secrets"* require the recipient to acknowledge a separate *"this bundle contains plaintext secrets"* checkbox before the apply button activates, and bundles produced by a newer Hammoc version (`bundleVersion` greater than what the local server supports) are rejected outright with an upgrade hint.
+
+The export/import flow only touches the workbench items themselves — `package.json`, repository code, and tracked files outside `.claude/` are never bundled. Bundles produced and consumed by the same Hammoc version are round-trip identical: re-importing your own export into an empty project reproduces the workbench cards byte-for-byte (handy for backups or for setting up a new dev machine).
+
+### 12.16 BMad Settings (core-config Editor)
+
+> Shown only for BMad projects (those with a `.bmad-core/` folder). For non-BMad projects this nav item is hidden entirely — no empty placeholder.
+
+A form-based editor for BMad's `core-config.yaml`, so you can change BMad's paths and flags without opening a terminal or text editor. It is a top-level item in the project Settings left nav (a sibling of the Harness Workbench, not one of its sections).
+
+Keys are organized into collapsible groups — **General**, **QA**, **PRD**, **Architecture**, and **Brownfield Epic** — and each value uses a widget matched to its type:
+
+- **Toggle** for boolean flags (e.g., Markdown Exploder, PRD Sharded)
+- **Path picker** for file/folder paths — a **Browse** button opens a file-tree dialog; paths are relative to the project root (e.g., Dev Story Location, QA Location)
+- **Text** for plain strings (e.g., PRD Version, Slash Prefix)
+- **Glob** with a live match preview that counts the files matching the pattern (e.g., Epic File Pattern)
+- **Drag-sortable list** for path arrays (e.g., Dev Load Always Files, Custom Technical Documents)
+
+Other behaviors:
+
+- **Auto-save** — Text/path/glob edits debounce-save (~300 ms); toggles and list changes save immediately. Saves write `.bmad-core/core-config.yaml` while preserving comments and key order.
+- **Raw YAML toggle** — A **Form / Raw** switch in the top-right lets you edit the file as raw YAML; switching back to Form preserves comments and ordering. A parse error keeps you in Raw mode until it is fixed.
+- **Unknown Keys** — Keys the form doesn't recognize (for example, a newer BMad schema) are preserved and listed read-only in an "Unknown Keys" section at the bottom; edit them in Raw mode.
+- **External-change banner** — If the file changes outside Hammoc while the panel is open, a banner with a **Reload** button appears.
+
+After you change a path such as **Dev Story Location**, the BMad agents (e.g., `/dev`) pick up the new value on their next run.
+
+### 12.17 Context Builder
+
+The **Context Builder** automatically injects a block of context into every new chat session, so you don't have to re-explain "what was I working on" each time. It does this by generating a Claude Code **SessionStart hook** for you. Available on all projects.
+
+You declare three kinds of content in the panel:
+
+- **Reference files** — Project files that are read fresh and injected at each session start. Each file shows its byte size and an approximate token count. If the combined size nears the SessionStart output cap an amber warning appears; past the hard cap (red), the content spills to a file plus a preview instead of being injected inline, so trim the list when warned.
+- **Dynamic variables** — Built-in values recomputed every session, each with an on/off toggle:
+  - **Current branch** — the active git branch
+  - **Active BMad story** — title and status of the most recently modified story file
+  - **Recent commits** — the most recent commit subjects (count configurable)
+  - **Today** — today's date
+  - **Uncommitted files** — count of files with uncommitted changes
+- **Custom commands** (advanced) — Arbitrary shell commands whose output is appended. Because these run automatically at every session start, each requires you to tick a confirmation checkbox ("I understand this command runs automatically at every session start"). Hammoc also flags commands that look like they contain a secret.
+
+When you save, Hammoc generates a hook script under the project's `.hammoc/` folder and registers a SessionStart entry in `.claude/settings.json`. In the **Hooks** panel (§12.7) that entry is marked **"Hammoc Context Builder"**; editing it by hand there raises a sync-loss warning, since the Context Builder owns it — change it from this panel instead. The token-size hints reuse the same approximation as Observability (§12.18).
+
+### 12.18 Observability
+
+The **Observability** panel is the feedback loop for harness tuning: it shows which tools get called and how much of the context window each harness element consumes. Available on all projects.
+
+**MCP / tool calls:**
+
+- A **timeline** of recent tool calls (server, tool, response time, and success / failed / no-response status) and an **aggregate chart** of calls per server and per tool with average response time and error counts.
+- **Filters** by server, tool, and time window (default: last 30 days).
+- Only call **metadata** is recorded — server, tool, timestamp, argument and response **sizes**, and duration. Argument and response **bodies are never stored**, so file contents and secrets don't leak into the log.
+
+**Token attribution:**
+
+- A bar chart of how many tokens each harness element contributes — project and global `CLAUDE.md`, each skill's `SKILL.md`, and the Context Builder's injected block — with an overlay showing the total against the current model's context window.
+- Inline hints show an **approximate** token count prefixed with `~` (a fast byte-based estimate), expressed two ways at once: as a percentage of the context window and as a share of the total harness prompt.
+- An **Exact count** button calls Anthropic's official token-count API and caches the result by file content; if the call fails, the approximation is kept.
+
+### 12.19 Plugin Marketplace
+
+The **Marketplace** panel lets you discover Claude Code plugins from the marketplaces registered on your machine, complementing the install/toggle view in the Plugins panel (§12.4). Available on all projects.
+
+- **Catalog** — One card per plugin parsed from each registered marketplace, showing name, description, version, author, category, a type badge (**Plugin** or **External MCP**), bundled-component counts, and an **Installed** badge when applicable.
+- **Filter & search** — By name, category, type, and installed state.
+- **Install / Uninstall guide** — Because Claude Code's plugin commands are interactive slash commands (not shell subcommands), the **Install** and **Uninstall** buttons open a dialog containing the exact command — e.g. `/plugin install <name>@<marketplace>` — with a **Copy** button. Paste it into your Claude CLI session to run it; plugin commands can't be executed from the Hammoc chat.
+- **Add marketplace** — A form takes a marketplace URL and produces the matching `/plugin marketplace add <url>` command to copy.
+- **Auto-refresh** — After you install or remove a plugin in your CLI session, Hammoc detects the on-disk change and updates both this catalog's **Installed** badges and the Plugins panel cards automatically.
+- **Resilience** — If one marketplace's catalog file can't be read, only that marketplace shows an error badge and the rest still load. If the installed-plugins file is in an unrecognized format, a warning banner notes that installed state may be incomplete.
+

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

@@ -4,12 +4,16 @@ Access settings via the gear icon or the Settings page. The page has **8 tabs**:
 
 > 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).
 
+**Multi-device sync** — Settings here are stored on the server, so they apply to every device and browser signed in to the same server, not just the one you changed them on. When you change a setting on one browser, other open browsers update live over the WebSocket connection without a manual refresh (the browser you changed it on is excluded from its own echo). This covers the Global and Advanced settings on this page and per-project settings (§5.3). Credential-style settings (Telegram bot token, Web Push) are managed through their own masked endpoints and are **not** broadcast. A few view-only states that depend on screen size — quick panel width/side, board view mode, Git diff layout, queue wrap — stay local to each browser by design.
+
 ### 13.1 Theme
 
 - **Dark** — Dark background, light text (default)
 - **Light** — Warm gray background, dark text
 - **System** — Follows your OS/browser preference
 
+Theme is stored locally per device (a "this device only" badge is shown next to the picker), so each browser/device can use a different theme even though other settings sync across devices (see multi-device sync above).
+
 ### 13.2 Language
 
 Hammoc supports 6 languages:
@@ -35,9 +39,12 @@ Choose the default Claude model:
 - **Opus** — Latest Opus
 - **Haiku** — Latest Haiku
 
+**Mythos-class:**
+- Fable 5 (1M opt-in)
+
 **Claude 4.x:**
-- Opus 4.7 (most capable, 1M context), 4.6, 4.5, 4.1, 4
-- Sonnet 4.5, 4
+- 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:**
@@ -45,6 +52,8 @@ Choose the default Claude model:
 - Haiku 3.5
 - Opus 3, Sonnet 3, Haiku 3
 
+> **1M context window**: Opus 4.8 always runs with its 1M window (included with Max). Sonnet 4.6's 1M window is **opt-in** and bills to usage credits — enable it per session with the "1M context" toggle in the model selector (see §2.15). Left off, Sonnet uses a 200K window.
+
 Can be overridden per-project (see §5.3).
 
 ### 13.4 Default Permission Mode
@@ -100,15 +109,15 @@ How long to wait for Claude's response:
 - 10 minutes
 - 30 minutes
 
-The timeout resets on every activity. If overridden by an environment variable, the field is disabled with an amber warning.
+The timeout resets on every activity, and it only guards Claude's own generation. Waiting for **your** input — approving a permission prompt or answering an `AskUserQuestion` selection — pauses the timer, so those prompts never time out; step away and respond whenever you're back. 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)
+- 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)
 
@@ -198,7 +207,32 @@ Customize Claude's behavior with a fully editable system prompt template:
 
 > 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
+### 13.16 Conversation Engine
+
+Hammoc can run conversations through one of two engines. The engine picker in Settings shows them as **side-by-side comparison cards** with a Recommended / Beta badge:
+
+- **SDK** (default, Recommended) — The Claude Agent SDK. Responses stream token-by-token. Every model and feature is supported.
+- **CLI** (Beta) — Routes your conversation through the Claude Code CLI. Its main draw is billing: it draws on your Claude **subscription** rather than separate API credits. Responses arrive block-by-block.
+
+**Trade-offs:**
+
+| | SDK | CLI |
+|---|---|---|
+| Billing | API credits | Subscription pool |
+| Response rendering | Token-by-token streaming | **Block-by-block** — each completed block appears at once |
+| Progress feedback | Live token stream | Optional "↓ N tokens · Ns" counter while generating |
+
+Your conversation history is identical either way — both engines write the same session files, so a chat created in CLI mode reloads and renders exactly like an SDK chat, and you can switch engines between sessions without losing or garbling history. The engine is chosen per session at the moment you send; there is no live mid-conversation switch.
+
+Everything interactive works the same in CLI mode as in SDK mode: live tool-call cards, permission prompts, selection cards, extended thinking, image attachments (see §2.4), and code rewind all behave identically. Claude is equally Hammoc-aware in both engines.
+
+**Live permission mode switch** — During a CLI chat, clicking the permission mode button (or pressing `Shift+Tab`) changes the mode immediately, not just for the next session.
+
+CLI engine settings have moved to **Advanced Settings** (see §13.17) under the "CLI engine only" group.
+
+### 13.17 Advanced Settings
+
+Settings in the Advanced tab are organized into groups by which conversation engine they apply to.
 
 **Server Management (mode-dependent):**
 
@@ -209,14 +243,32 @@ Customize Claude's behavior with a fully editable system prompt template:
 - **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:**
+**Common (both engines):**
+- **Auto-compact when context fills** — Master switch for automatic context compaction (default: on). When enabled, conversations are automatically summarized when the context window fills up, so the session keeps going instead of stalling. When disabled, you manage compaction manually via `/compact` or the usage donut (see §2.10). Applies to both SDK and CLI engines.
+
+**SDK Parameters (SDK engine only):**
 - **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
+**CLI engine settings:**
+
+These settings apply only while the CLI engine is active (see §13.16):
+
+- **Show thinking summaries** — Surface Claude's thinking summaries while generating a response (default on). Whether summaries actually appear can also depend on your Claude version.
+- **Show generation progress** — Toggle the live "↓ N tokens · Ns" indicator shown during generation (default on).
+- **Synthetic typing** — Re-animate each completed block character-by-character as it arrives, mimicking the SDK's token-by-token feel. Purely cosmetic; off by default.
+- **Resume confirm** — When resuming a large or old session, Claude may show a confirm menu asking whether to "resume from summary" or "resume the full session". This setting controls how Hammoc handles that menu: **Ask each time** (default) shows an interactive card so you choose; **Auto: resume from summary** or **Auto: resume full session** auto-picks without blocking the turn.
+- **Screen-stall detection** — If generation appears stuck for a configurable duration (default 20 seconds), a soft amber warning appears with a "Stop" button. Advisory only — Hammoc never auto-aborts. Set to 0 to disable.
+- **Claude screen mirror** — Show a read-only terminal mirroring Claude's raw output during CLI-mode chats; on by default. Useful when a card is slow to arrive or the progress counter freezes. The panel is draggable and resizable, with a copy button for the full buffer. Turn it off if you find it distracting.
+- **Claude binary path** — Manually point Hammoc at a specific `claude` executable. Leave empty to auto-detect. If the path is invalid, Hammoc falls back to auto-detect.
+
+**Display:**
+- **Card entrance animation** — While a response streams, each message and tool card fades and slides up one at a time as it appears, instead of the whole batch popping in at once. Applies to both engines and affects live streaming only (reloaded history renders statically). Purely cosmetic; on by default.
+
+### 13.18 Help
 
 In-app usage guide within the Settings page:
 
@@ -226,7 +278,7 @@ In-app usage guide within the Settings page:
 - **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
+### 13.19 About
 
 Displays app information:
 

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

@@ -15,6 +15,7 @@ export { SlashCommand, StarCommand, CommandsResponse, SnippetItem } from './type
 export { CommandFavoriteEntry, UserPreferences, PromptHistoryData, DEFAULT_PREFERENCES, PreferencesApiResponse, TelegramSettings, TelegramSettingsApiResponse, UpdateTelegramSettingsRequest, WebPushSettings, WebPushSettingsApiResponse, WebPushSubscribeRequest, SupportedLanguage, SUPPORTED_LANGUAGES, PermissionSyncPolicy, } from './types/preferences.js';
 export { RawJSONLMessage, HistoryMessage, PaginationInfo, HistoryMessagesResponse, PaginationOptions, ContentBlock, TextContentBlock, ThinkingContentBlock, ToolUseContentBlock, ToolResultContentBlock, ImageContentBlock, } from './types/history.js';
 export * from './types/fileSystem.js';
+export * from './types/systemBrowse.js';
 export * from './types/bmadStatus.js';
 export * from './types/queue.js';
 export { parseQueueScript, serializeQueueItems } from './utils/queueParser.js';
@@ -25,6 +26,12 @@ 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 { sanitizeToolResultContent } from './utils/toolResultContent.js';
+export { INTERRUPT_FILLER_TEXTS, isInterruptFillerText } from './utils/interruptFiller.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;AAG5D,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAGrC,cAAc,0BAA0B,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,yBAAyB,CAAC;AAGxC,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,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAGzE,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAG3F,cAAc,0BAA0B,CAAC;AAGzC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,2BAA2B,CAAC;AAG1C,cAAc,wBAAwB,CAAC"}

package/packages/shared/dist/index.js

@@ -27,6 +27,8 @@ export { PROJECT_ERRORS, } from './types/project.js';
 export { DEFAULT_PREFERENCES, SUPPORTED_LANGUAGES, } from './types/preferences.js';
 // Story 11.1: File System types for file read and directory list API
 export * from './types/fileSystem.js';
+// Story 34.1: System Browse types for directory-only system browse API (Epic 34)
+export * from './types/systemBrowse.js';
 // Story 12.1: BMad Status types for BMad Dashboard API
 export * from './types/bmadStatus.js';
 // Story 15.1: Queue Runner types
@@ -47,8 +49,20 @@ export * from './types/board.js';
 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';
+// tool_result content sanitization (shared by server engines & client render)
+export { sanitizeToolResultContent } from './utils/toolResultContent.js';
+// Interrupt / empty-turn filler detection (shared by historyParser & MessageArea)
+export { INTERRUPT_FILLER_TEXTS, isInterruptFillerText } from './utils/interruptFiller.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;AAE5D,sEAAsE;AACtE,cAAc,oBAAoB,CAAC;AAEnC,2EAA2E;AAC3E,OAAO,EACL,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,6BAA6B,CAAC;AAErC,gDAAgD;AAChD,cAAc,0BAA0B,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,iFAAiF;AACjF,cAAc,yBAAyB,CAAC;AAExC,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,8EAA8E;AAC9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAEzE,kFAAkF;AAClF,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAE3F,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"}

package/packages/shared/dist/types/bmadCoreConfig.js

@@ -0,0 +1,30 @@
+// Story 31.1: BMad core-config.yaml editor shared types (Epic 31)
+//
+// Single source of truth for the typed shape of the 18 known keys plus the
+// read-response envelope used by the BMad config form editor. The 18-key
+// widget matrix itself lives client-side (BMAD_KNOWN_KEYS_MATRIX in
+// bmadCoreConfigStore.ts); these types describe the *values* that travel over
+// the wire after the server partitions a parsed config into known vs unknown
+// top-level keys (see bmadCoreConfigService.parseUnknownKeys).
+/**
+ * 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 const BMAD_CORE_CONFIG_KNOWN_TOP_LEVEL_KEYS = [
+    'markdownExploder',
+    'qa',
+    'prd',
+    'architecture',
+    'customTechnicalDocuments',
+    'devLoadAlwaysFiles',
+    'brownfieldEpic',
+    'devDebugLog',
+    'devStoryLocation',
+    'slashPrefix',
+];
+//# sourceMappingURL=bmadCoreConfig.js.map

package/packages/shared/dist/types/bmadCoreConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bmadCoreConfig.js","sourceRoot":"","sources":["../../src/types/bmadCoreConfig.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,oEAAoE;AACpE,8EAA8E;AAC9E,6EAA6E;AAC7E,+DAA+D;AA4C/D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAG;IACnD,kBAAkB;IAClB,IAAI;IACJ,KAAK;IACL,cAAc;IACd,0BAA0B;IAC1B,oBAAoB;IACpB,gBAAgB;IAChB,aAAa;IACb,kBAAkB;IAClB,aAAa;CACL,CAAC"}