hammoc 1.4.0 → 1.6.0

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

@@ -0,0 +1,76 @@
+## 5. Projects
+
+### 5.1 Project List
+
+The project list page shows all your Claude Code projects in a responsive grid:
+
+Each project card displays:
+
+- **Project name** — Derived from the directory name
+- **Path** — Full project directory path
+- **Session count** — Number of chat sessions
+- **Last modified** — When the project was last active
+- **BMad badge** — Indicates BMAD-METHOD enabled projects
+- **Status indicators** — Active sessions (green dot), queue status badge, terminal count (updates in real-time)
+
+Each card has a **kebab menu** (⋮) with:
+
+- **Setup BMad** — Initialize BMAD-METHOD on non-BMad projects (with version selection)
+- **Hide / Unhide** — Toggle project visibility
+- **Delete** — Remove the project
+
+**Dashboard summary bar** appears at the top when projects exist, showing aggregate stats: Projects, Sessions, Active, Queue, Terminals.
+
+**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
+3. The path is validated automatically with a short debounce while you type (`"Validating path..."` helper text is shown). Blurring the field validates immediately
+4. Path collision detection — if the path already belongs to an existing project, an amber warning appears with a **"Navigate to existing"** link and the **Create** button is disabled until you pick a different path
+5. Invalid paths show the server's validation message in red below the input, and also disable **Create**
+6. Optionally enable BMad Method initialization with version selection
+
+### 5.3 Project Settings
+
+Per-project settings live in their own tab inside each project (Overview / Queue / Git / Files / Terminal / Board / **Settings**), no longer under the global Settings page. Opening the tab takes you directly to that project's configuration — there is no project dropdown to disambiguate.
+
+The Settings tab has a two-pane layout:
+
+- **Left nav** — 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
+- **Hidden toggle** — Hide the project from the project list
+- **Reset to Global Defaults** — Remove all overrides at once
+
+On narrow screens, the left nav collapses into a row of buttons above the right panel (the inner Harness Workbench navigator beneath it becomes the horizontally-scrolling pill row — see §12.1).
+
+### 5.4 Hiding Projects
+
+- Hide projects from the kebab menu or project settings
+- Hidden projects appear with reduced opacity when visible
+- Toggle "Show hidden" (eye icon in header) to reveal them
+- Hiding doesn't delete any data
+
+### 5.5 Project Overview Page
+
+Clicking a project card opens the Overview tab:
+
+- **Stats cards** — Three cards showing Total Sessions, Total Messages, and Active Sessions
+- **Recent Sessions** — Last 5 sessions with streaming indicators, session name badges, and message counts. Click to navigate directly to the session
+- **Quick Start** — Buttons for New Session, Queue Runner, and File Explorer
+- **Active streaming banner** — Green banner shown when sessions are actively streaming
+
+For BMad projects, additional sections appear above this standard overview (see §11.4).
+
+### 5.6 Deleting Projects
+
+- Delete removes the project from Hammoc's list
+- Optionally check **"Delete project files"** to also remove the directory on disk
+- Confirmation dialog prevents accidental deletion
+

package/packages/server/resources/manual/06-file-explorer-editor.md

@@ -0,0 +1,90 @@
+## 6. File Explorer & Editor
+
+### 6.1 File Explorer
+
+Access the file explorer from the sidebar tab. Toggle between views with the toolbar button:
+
+**Grid View (Finder-style, default)**
+- Icon-based card display with folder/file icons
+- Click folders to navigate in, click files to open
+- ".." entry to navigate to parent directory
+- Breadcrumb navigation at the top
+
+**List View (hierarchical tree)**
+- Recursive tree with expand/collapse chevrons
+- Lazy-loaded subdirectories
+- Sorted by type (folders first) then by name
+- Keyboard navigation: ArrowUp/Down/Left/Right, Enter, Home/End
+
+**Context Menu** (right-click or ⋮ button on hover)
+- **New File** / **New Folder** — Creates via inline input
+- **Copy** / **Cut** / **Paste** — Copy or move files and folders within the project
+- **Download** — Download individual files (files only)
+- **Rename** — Inline renaming
+- **Delete** — With confirmation dialog
+
+**File Upload**
+- Drag and drop files from your OS into the Grid view to upload them
+- Paste files from clipboard (`Ctrl+V`) while the file explorer is focused
+
+**Toolbar**
+- **Search** — File search with real-time filtering
+- **Hidden files** — Toggle visibility of ignored patterns (`.git`, `node_modules`, `.env`, `dist`, etc.)
+- **View toggle** — Switch between Grid and List views
+- **Open in OS explorer** — Opens the project folder in your OS file manager (Explorer, Finder, etc.). Only shown when accessing via localhost
+- Default view mode configurable in settings
+
+### 6.2 Text Editor
+
+Click any text file to open it in the built-in editor:
+
+- **Syntax highlighting** — Language-aware (detected from file extension)
+- **Line numbers** and **active line highlighting**
+- **Save** — `Ctrl+S` / `Cmd+S` or the save button
+- **Close** — `Escape` key or the X button
+- **Unsaved changes warning** — Confirmation dialog prevents accidental data loss
+- **File size limit** — Files over 1MB are truncated and read-only
+- **Binary files** — When a binary file is opened (images, PDFs, executables, etc.), the editor body shows the file's human-readable size (e.g., `104 B`, `5.0 MB`) together with a **Download** button for direct download
+
+**External change detection**
+
+The server watches open files and pushes a notification if the file changes on disk outside Hammoc. An alert banner appears above the editor:
+
+- **File modified on disk (clean editor)** — Amber banner with **Reload** (re-read from disk) and **Dismiss** (keep current view)
+- **File modified on disk (with unsaved edits)** — Amber banner warning that saving will overwrite the external changes; same Reload / Dismiss buttons
+- **File deleted on disk** — Red banner with a **Dismiss** button (no reload is possible)
+- **Stale-write conflict** — If you try to save a file that was modified on disk since you opened it, the save is rejected and a red banner offers **Reload** (discard your edits) or **Overwrite** (force-save over the external changes)
+
+### 6.3 Markdown Preview
+
+For `.md` files:
+
+- Toggle between **Edit** and **Preview** modes via the header button
+- Preview renders full markdown with styles
+- Default mode (Edit or Preview) configurable in settings
+
+### 6.4 Image Viewer
+
+Click any image file to open the viewer in a fullscreen overlay:
+
+- **Zoom in/out** — Button controls or mouse wheel scroll (wheel zoom cancels any active fit mode)
+- **Drag to pan** — Click and drag to move the image. Pan position is clamped so the zoomed image cannot be dragged completely off-screen
+- **Zoom percentage** — Displayed between zoom buttons
+- **Fit controls** — Header buttons for **Actual size (100%)**, **Fit to screen**, **Fit to width**, and **Fit to height**. The active fit mode is cleared when you manually zoom with the wheel
+- **Touch gestures** (mobile / touchscreen):
+  - **Pinch** with two fingers to zoom. The zoom is anchored at the midpoint between the two fingers so the content under your fingers stays put
+  - **One-finger drag** pans the image when it's zoomed in (with edge clamping)
+  - **One-finger horizontal swipe** (when the image fits on screen) navigates to the previous / next image in the set. A swipe needs to exceed roughly 50 px horizontally and be more horizontal than vertical to trigger
+- **Multi-image navigation** — When multiple images are available (a chat message with multiple attachments, **or a file-explorer image opened from a folder containing other images**), they form a navigable set. Left/right arrow keys move between images and zoom resets to fit on each change. The header shows the current position (e.g., `filename (2/5)`)
+- **Close** — `Escape` key or the X button
+- Supports PNG, JPEG, GIF, WebP, SVG, BMP, ICO
+
+### 6.5 Quick File Panel
+
+Access files without leaving the chat:
+
+- Open the quick panel and switch to the Files tab
+- **Recently opened** files appear at the top (max 5 per session)
+- Search and navigate the file tree
+- Click to open in the editor overlay
+

package/packages/server/resources/manual/07-git.md

@@ -0,0 +1,94 @@
+## 7. Git
+
+### 7.1 Git Status
+
+The Git tab shows the current repository state with automatic refresh:
+
+- **Top bar** — Branch selector dropdown + Pull/Push buttons
+- **File groups** — Three collapsible sections (chevron toggle), each with file count badge:
+  - **Staged Changes** — Files ready to commit (status indicators: M green, A green, D red, R blue)
+  - **Unstaged Changes** — Modified files not yet staged (status indicators: M yellow, D red)
+  - **Untracked Files** — New files not tracked by Git (status indicator: ?)
+- **File click** — Clicking a file name opens the Diff viewer slide panel (see 7.8)
+- **Error banner** — Git errors appear at the top and auto-clear; dismiss manually with X
+- **Clean state** — When no changes exist, a green checkmark with "No changes" message is shown
+
+### 7.2 Staging Files
+
+- **Stage individual files** — Click the "+" button next to each file (appears on hover)
+- **Stage all** — Click "+ All" in the group header to stage all files in that group
+- **Unstage individual** — Click the "-" button on staged files (appears on hover)
+- **Unstage all** — Click "- All" in the Staged Changes group header
+
+### 7.3 Committing
+
+1. Stage the files you want to commit
+2. Write a commit message in the textarea
+3. Click **"Commit"** (enabled only when staged files exist and message is non-empty)
+4. The commit history refreshes automatically after a successful commit
+
+> **Note:** "Stage All & Commit" is available only in the Quick Git Panel (see 7.7). The full Git tab requires staging first, then committing separately.
+
+### 7.4 Branch Management
+
+- **Branch selector** — Dropdown button in the top bar showing the current branch
+- **Branch list** — All local branches displayed; current branch highlighted with a blue checkmark
+- **Create branch** — Input field at the bottom of the dropdown; press Enter to create
+- **Switch branch** — Click on a branch name to switch
+- **Uncommitted changes warning** — If there are staged, unstaged, or untracked files, a confirmation dialog appears before switching
+- **Keyboard navigation** — ArrowUp/Down to navigate, Enter to select, Escape to close dropdown
+
+### 7.5 Commit History
+
+- Browse recent commits (up to 20 in the full tab):
+  - Short commit hash
+  - Commit message
+  - Author name
+  - Relative timestamp (e.g., "2 hours ago", "3 days ago")
+
+### 7.6 Pull & Push
+
+- **Pull** — Fetch and merge remote changes (↓ arrow button)
+- **Push** — Upload local commits to remote (↑ arrow button)
+- **Ahead/Behind counts** — Each button shows the number of commits ahead or behind the remote
+- Errors displayed in the error banner
+
+### 7.7 Quick Git Panel
+
+Lightweight Git access from the quick panel side bar:
+
+- **Branch name** with changed file count badge (e.g., "3 changes")
+- **Commit input** — Textarea for commit message
+- **"Stage All & Commit"** — Single green button that automatically stages all unstaged/untracked files and commits in one action
+- **Success message** — Displayed briefly after a successful commit
+- **Recent commits** — Shows only the 3 most recent commits (hash, timestamp, message)
+- **"View in Git Tab"** link — Navigates to the full Git tab for advanced operations
+- **Git init support** — If the project is not a Git repository, shows an init button
+
+### 7.8 Diff Viewer
+
+- Clicking a file in the Git tab opens a **slide panel** from the right side
+- Shows the diff for the selected file, using side-by-side or inline layout based on screen width
+- **Layout toggle** — A button in the viewer header switches between side-by-side and inline layout. The choice is persisted per user (see §2.7)
+- **Close** — Click X button, click the backdrop, or press Escape
+
+### 7.9 Git Repository Initialization
+
+If the project directory is not a Git repository:
+
+- **Git tab** — Shows an "Initialize Repository" button
+- **Quick Git panel** — Shows a message and init button
+- After initialization, the Git status refreshes automatically
+
+### 7.10 AI-Assisted Split Commit
+
+A purple dashed chip — **"Split changes into logical commits / Claude handles it in a new session"** — appears in the Git tab below the file list whenever there are uncommitted changes (staged, unstaged, or untracked). The chip is hidden on a clean working tree.
+
+Clicking it:
+
+1. Creates a fresh chat session
+2. Auto-sends the bundled `%split-commit` snippet, which asks Claude to inspect the working tree (`git status` / `git diff`), group changes into coherent units, and produce one conventional-style commit per group
+3. Navigates you into that session so you can watch the work and approve each commit
+
+The chip lives only on the full Git tab — the Quick Git panel keeps its single "Stage All & Commit" action for fast manual commits.
+

package/packages/server/resources/manual/08-terminal.md

@@ -0,0 +1,59 @@
+## 8. Terminal
+
+### 8.1 Web Terminal
+
+Full terminal access in your browser:
+
+- **Shell emulation** — Real terminal connection to your system shell
+- **Working directory** — Opens in your project directory
+- Supports all shell commands, interactive programs, and TUI apps
+- **Theme** — Automatically matches app theme (dark/light)
+- **Font** — Monospace font (JetBrains Mono, Fira Code, Cascadia Code)
+
+### 8.2 Multiple Tabs
+
+- Click **"New Terminal"** button (+ icon) in the header to open a new terminal tab
+- **Maximum 5 terminals** per project; button disabled at limit
+- **Tab labels** — Named after shell (e.g., "bash", "zsh"); numbered when multiple share the same shell ("bash 1", "bash 2")
+- **Switch tabs** — Click on a tab label or use **ArrowLeft/ArrowRight** keyboard navigation
+- **Close tabs** — Click the X button on each tab, or press **Delete** to close the active tab
+- **Empty state** — When no terminals exist, a centered prompt with "New Terminal" button is shown
+
+### 8.3 Font Size
+
+Font size controls are available both via keyboard shortcuts and GUI buttons in the header:
+
+- **GUI controls** — Minus (-), current size display (click to reset), Plus (+) buttons in the header
+- `Ctrl+=` / `Ctrl++` — Increase font size
+- `Ctrl+-` — Decrease font size
+- `Ctrl+0` — Reset to default size
+
+### 8.4 Connection Status
+
+The header shows the current terminal status:
+
+- **Connecting** — Spinner with "Connecting..." text
+- **Connected** — Green dot indicator with "Connected" text
+- **Disconnected** — Red dot; "Disconnected" message shown over the terminal
+- **Exited** — Gray dot with exit code displayed
+
+### 8.5 Security
+
+Terminal access is restricted for safety:
+
+- **Local network only** — Blocked when accessed from outside the local/private network. When behind a reverse proxy with `TRUST_PROXY=true`, real client IPs are used for access control
+- **Access denied warning** — When access is denied, a shield icon with explanation is shown
+- **Configurable** — Enable/disable via the `TERMINAL_ENABLED` environment variable (set `false` to disable)
+- **Max sessions** — Server-side limit of 10 (configurable via `MAX_TERMINAL_SESSIONS`); client limits to 5 per project
+- **Session persistence** — Terminal sessions survive browser refreshes and temporary network interruptions
+
+### 8.6 Quick Terminal
+
+Lightweight terminal access from the quick panel side bar:
+
+- **Multi-terminal support** — Same tab management as the full Terminal tab (create, switch, close, max 5)
+- **Font size controls** — Minus, size display (click to reset), Plus buttons in the header
+- **"Open in Tab"** link — Navigate to the full Terminal tab
+- **Tab keyboard navigation** — ArrowLeft/Right to switch, Delete to close
+- **Security warning** — Same access denied warning when terminal access is restricted
+

package/packages/server/resources/manual/09-queue-runner.md

@@ -0,0 +1,262 @@
+## 9. Queue Runner
+
+The Queue Runner automates sequences of prompts for batch processing.
+
+### 9.1 Queue Editor
+
+The editor provides **syntax highlighting**:
+
+- **Directives** (`@new`, `@pause`, etc.) — purple
+- **Directive arguments** — teal
+- **Multiline markers** (`@(`, `@)`) — blue
+- **Comments** (`#`) — gray
+- **Regular prompts** — default text color
+
+A non-selectable **line-number gutter** runs down the left side, sticky during both vertical and horizontal scroll, so error messages like "parse error at line 47" become directly clickable without manual counting.
+
+**Toolbar buttons:**
+- **Run** (Play icon) — Start queue execution; also available via `Ctrl+Enter` / `Cmd+Enter`
+- **Load File** (Upload icon) — Import a `.txt`, `.qlaude-queue`, or similar script file (max 1 MB). Useful for loading shipped sample templates such as the BMad story workflow (see §9.9)
+- **Template** (FileText icon) — Open the template dialog (see §9.9)
+- **Word Wrap** (WrapText icon) — Toggle line wrapping (persisted across sessions)
+
+**Editor behavior:**
+- **Validation warnings** displayed above the editor (e.g., missing arguments, unclosed multiline blocks, unknown directives). When more than one warning exists, only the **most recent** is shown with a `(+N)` count badge for the others — keeps the warning area from pushing the editor down on scripts with many issues
+- **Empty state** shows a visual command reference overlay listing all available directives
+- Editor is hidden during queue execution, replaced by the runner panel
+
+Each line is one prompt. Special commands start with `@`. Empty lines are ignored.
+
+### 9.2 Special Commands
+
+| Command | Description |
+|---------|-------------|
+| `@new` | Start a new chat session before the next prompt |
+| `@save <name>` | Save the current session with a name |
+| `@load <name>` | Load a previously saved session |
+| `@pause [reason]` | Pause execution; optional reason text shown in the pause banner |
+| `@model <name>` | Switch Claude model (e.g., `@model opus`) |
+| `@delay <ms>` | Wait before the next prompt (positive integer in ms, e.g., `@delay 5000`) |
+| `@pauseword "<keyword>"` | Set a keyword that auto-pauses the queue when found in Claude's response. Use `@pauseword ""` to clear |
+| `@loop max=N [until="TOKEN"] [on_exceed="pause\|continue"]` | Start a loop block that repeats up to N times (see §9.5) |
+| `@end` | End a loop block |
+| `@label <name>` | Define a forward jump target (see §9.6) |
+| `@jumpif "<token>" <label>` | Jump to `<label>` if the previous prompt response contains `<token>` (see §9.6) |
+| `@(` | Start a multiline prompt (all lines until `@)` are treated as one prompt) |
+| `@)` | End a multiline prompt |
+| `# comment` | Comment line (not sent to Claude) |
+| `\@` | Escape: send literal `@` as a prompt (not treated as directive) |
+
+- Missing required arguments (e.g., `@save` without a name) produce a validation warning
+- Unknown directives (e.g., `@unknown`) produce a warning and are sent as regular prompts
+
+### 9.3 Multiline Prompts
+
+For prompts that span multiple lines, use `@(` and `@)`:
+
+```
+@(
+Please review this code and check for:
+1. Security vulnerabilities
+2. Performance issues
+3. Code style violations
+@)
+```
+
+An unclosed multiline block (missing `@)`) produces a warning and is still sent as a single prompt.
+
+### 9.4 Pauseword
+
+The `@pauseword` directive lets you set a keyword that automatically pauses queue execution when found in Claude's response.
+
+```
+@pauseword "DONE"
+Implement the login feature
+Fix any remaining issues
+@pauseword ""
+This prompt runs without pauseword
+```
+
+- **Set** — `@pauseword "KEYWORD"` activates the keyword for all subsequent items
+- **Clear** — `@pauseword ""` (empty string) removes the active pauseword
+- When Claude's response contains the keyword, the queue pauses for review
+- The pauseword is snapshotted at the start of each prompt execution
+- Quotes are required around the keyword; mismatched or empty quotes produce a validation warning
+
+### 9.5 Loop Blocks
+
+The `@loop`/`@end` directives create iterative workflows that repeat a block of prompts.
+
+```
+@loop max=5 until="SUCCESS" on_exceed="pause"
+  Review the code for issues
+  Fix any problems found
+@end
+```
+
+**Parameters:**
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `max=N` | Yes | Maximum number of iterations (positive integer) |
+| `until="TOKEN"` | No | Stop looping when this token appears in Claude's response |
+| `on_exceed="pause\|continue"` | No | Action when max iterations reached without the until token (default: `pause`) |
+
+**Behavior:**
+- Each iteration executes all prompts inside the block sequentially
+- If `until` token is detected in a response, the loop exits early
+- When `max` is reached without the `until` token: `pause` halts for review, `continue` moves to the next queue item
+- During execution, the banner shows loop progress (e.g., "Loop 2/5") with inner item tracking
+
+### 9.6 Conditional Jump
+
+The `@label` and `@jumpif` directives let you skip a range of queue items based on the previous prompt response. They are designed for fast-paths such as "if the QA gate already passed, skip the fix loop".
+
+```
+%qa-review {story_num}
+@(
+If the QA gate is PASS, write exactly QA_GATE_PASS as the last line.
+@)
+@jumpif "QA_GATE_PASS" qa_done
+
+@loop max=5 until="QA_GATE_PASS" on_exceed="pause"
+  %apply-qa-fixes {story_num}
+  %qa-review {story_num}
+  @(...QA_GATE_PASS check...@)
+@end
+
+@label qa_done
+
+@new
+%commit-and-done {story_num}
+```
+
+**`@label <name>`** — declares a jump target. The name must start with a letter or underscore and contain only letters, digits, underscore, or hyphen.
+
+**`@jumpif "<token>" <label>`** — when reached, looks for `<token>` (substring match) in the response of the immediately preceding prompt. If found, the executor jumps directly to the matching `@label`, skipping every item in between. If not found, execution falls through to the next item.
+
+**Rules:**
+- **Forward only** — the target `@label` must appear later in the script than the `@jumpif`. Backward jumps are rejected with a parse warning.
+- **Not allowed inside `@loop`** — both `@label` and `@jumpif` are rejected with a parse warning when nested inside a loop block. Use `until` for loop exit conditions instead.
+- **Quoted token** — the token must be wrapped in double quotes and cannot contain spaces or be empty. Mismatched or missing quotes produce a parse warning.
+- **Unique label names** — duplicate `@label` definitions emit a warning; only the first one is registered.
+- **Missing target at parse time** — if the target label is never defined later in the script, a parse warning is emitted.
+- **Missing target at runtime** — if the script is edited mid-run and the label disappears, the jump is silently skipped and execution falls through.
+
+The token search uses a plain substring match against the previous prompt's complete response text, so prefer artificial single-word tokens like `QA_GATE_PASS` over natural phrases.
+
+**Runner panel display** — In the queue runner item list, `@label` items show as `Label: <name>` and `@jumpif` items show as `Jump if: "<token>" → <target>`, so the control flow is easy to follow at a glance while the queue runs.
+
+**`@new` boundary** — the "previous prompt response" buffer is **not** cleared by `@new`. It only updates when the next prompt actually runs. So a `@jumpif` placed immediately after `@new` (with no prompt in between) will still see the *previous* session's last prompt response. Place a real prompt between `@new` and `@jumpif` if you need a fresh evaluation.
+
+**UI display of skipped items** — when a jump fires, the items between the `@jumpif` and its `@label` are not executed, but the runner panel currently shows them with the same green check icon as completed items. This is a cosmetic limitation; the items did not run and their session-link slots remain empty. The progress bar still advances correctly to the post-label position.
+
+### 9.7 Running the Queue
+
+1. Write your prompts in the queue editor
+2. Click **"Run"** or press `Ctrl+Enter` to start
+3. The editor switches to the **Runner Panel** showing:
+   - **Progress bar** — With percentage and count (completed / total)
+   - **Color coding** — Blue (running), amber (paused), green (completed), red (error)
+   - **Item list** with per-item status icons:
+     - Spinner (blue) — currently executing
+     - Pause icon (amber) — paused at this item
+     - Checkmark (green) — completed (shown with strikethrough text)
+     - X circle (red) — error
+     - Clock (gray) — pending
+   - **Auto-scroll** to the current item
+4. **Controls:**
+   - **Pause** — Schedule a pause after the current item finishes. While an item is executing, this sets a "pause reservation" rather than pausing immediately. A **Cancel Pause** button appears to revoke the reservation before the item completes.
+   - **Resume** — Shown during paused state; resumes execution from the next pending item
+   - **Edit Script** — Shown during paused state; switches to the text editor with remaining items serialized as script text. Edit freely, then click **Apply** to replace pending items or **Cancel** to discard changes.
+   - **Abort** — Always available (running or paused); requires confirmation
+   - **"Go to Session"** link — Navigate to the active chat session
+5. **Session links** — Completed items show a link icon to navigate to their associated session
+6. **"Back to Editor"** button — Dismiss the runner panel after completion or error
+
+**During execution (pending items only):**
+- **Drag-and-drop reorder** — Drag pending items by the grip handle to reorder
+- **Delete** — Click the trash icon to remove a pending item
+- **Add** — Inline input at the bottom to add new items to the queue
+
+### 9.8 Session Locking
+
+While the queue is running, a **sticky banner** appears at the top of chat sessions:
+
+- **Running** (blue) — Spinner + progress (current/total) + current prompt preview (desktop). Inside a `@loop` block, a loop badge shows iteration progress (e.g., "Loop 2/5")
+- **Pause requested** (amber pulse) — Pause scheduled after current item finishes; cancel pause button shown
+- **Waiting for input** (purple pulse) — Queue paused for permission approval or user question; respond in the session to continue
+- **Paused** (amber) — Pause icon + progress; pause reason shown below if provided
+- **Error-paused** (red) — Alert icon + error details
+- **Completed** (green) — Checkmark + total count; dismissible with X button
+- **Error-stopped** (red) — Error message + link to queue editor; dismissible
+
+**Expandable item list:**
+- When 2+ items exist, click the chevron to expand a scrollable list of all queue items with status indicators
+- Currently executing items are highlighted; completed items appear with strikethrough text
+
+**Banner controls:**
+- **Pause / Cancel Pause / Resume / Abort** buttons directly in the banner (icon-only on mobile, icon+text on desktop)
+- **"Queue Editor"** link — Navigate to the full queue editor (desktop only)
+- **"Go to Session"** link — Navigate to the active queue session
+
+**On other sessions:**
+- A banner shows "Queue running in another session" with a link to navigate to it
+- Other sessions remain fully accessible
+
+### 9.9 Templates
+
+Templates generate queue scripts by combining a template pattern with story selections from your project's PRD.
+
+**Template Dialog** (opened via FileText icon in toolbar):
+
+The dialog has two main sections:
+
+**1. Template Source** — Three tabs:
+- **Input** — Type template text directly in the editor with word wrap toggle; variable hint shown: `{story_num}, {epic_num}, {story_index}, {story_title}, {date}`
+- **File** — Upload a `.txt` or `.qlaude-queue` file (max 100KB) via drag area
+- **Saved** — Browse, select, edit, or delete previously saved templates
+
+**2. Story Selection** — Stories extracted from your PRD:
+- Grouped by epic with collapsible sections and checkbox selection
+- **Select All / Deselect All** toggle
+- **"Pause between epics"** checkbox — Inserts `@pause` between different epic groups
+- Each epic header shows selected/total count
+
+**Template Variables:**
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{story_num}` | Full story number | `3.1` |
+| `{epic_num}` | Epic number | `3` |
+| `{story_index}` | Story index within epic | `1` |
+| `{story_title}` | Story title (empty if not found) | `Login Page UI` |
+| `{date}` | Execution date (YYYY-MM-DD) | `2026-03-18` |
+
+```
+@load epic-{epic_num}-base
+Implement Story {story_num}: {story_title}
+@save {date}/epic-{epic_num}/story-{story_index}-done
+```
+
+**Live Preview** — Shows the generated script with syntax highlighting below the template and story selection.
+
+**Template Management:**
+- **Save** — Save the current template with a name (inline form)
+- **Update** — Overwrite a previously saved template
+- **Delete** — Remove a saved template (with confirmation)
+- Templates are saved per-project
+
+**Bundled sample template:**
+
+The Hammoc git repository ships a ready-to-use BMad story workflow template at `docs/queue-templates/bmad-story-workflow.qlaude-queue`. It drives a single story through Draft → Validate → Develop → QA Review → Commit and uses `@label` / `@jumpif` (see §9.6) so a first-pass QA PASS skips the fix loop entirely. To use it, download the file from the GitHub repository and import it via the **Load File** toolbar button, or paste its contents into the editor. The `{story_num}` placeholder must be replaced before running.
+
+### 9.10 Queue Status Badge
+
+A badge on the project card and session list shows queue status:
+
+- **Running** — Blue badge with play icon
+- **Paused** — Amber badge with pause icon
+- **Error** — Red badge with alert icon
+- **Idle** — No badge shown
+