hammoc 1.4.0 → 1.5.0

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
+

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

@@ -0,0 +1,193 @@
+## 10. Project Board
+
+Visual task and issue management for your projects. The board displays three card types: Issues, Stories, and Epics.
+
+### 10.1 Kanban Board
+
+The default view is a scrollable Kanban board:
+
+- **Columns** represent statuses — each with a colored top border, label, and item count badge
+- **Cards** display issues, stories, and epics with type badges: **[I]** (amber), **[S]** (blue), **[E]** (purple)
+- **Horizontal scroll** — overflow columns peek from the edge (no drag-and-drop between columns). On desktop, vertical mouse wheel scrolling in empty column areas is automatically converted to horizontal scroll
+- Status changes are made via the card **context menu** (⋮), not by dragging
+- Columns are fully customizable (see §10.11)
+
+### 10.2 List View
+
+Switch to an accordion-style list view:
+
+- Items grouped by status column with chevron toggle
+- **Item count** displayed next to each group header
+- Only **non-empty columns** are shown (empty ones are hidden)
+- On mobile, the last column auto-collapses to save space
+- Compact card layout for browsing many items at once
+
+### 10.3 Creating Issues
+
+Click **"New Issue"** to create:
+
+| Field | Details |
+|-------|---------|
+| **Title** | Required, max 200 characters |
+| **Description** | Optional, supports markdown |
+| **Type** | Bug, Improvement |
+| **Severity** | Low, Medium, High, Critical |
+| **Attachments** | Optional — drag-and-drop, click to browse, or paste from clipboard |
+
+Status is automatically set to **Open** (not a user-editable field). Each issue is assigned a sequential ID in the **ISSUE-N** format (e.g., ISSUE-1, ISSUE-2) automatically.
+
+### 10.4 Editing Issues
+
+Click the context menu (⋮) → **Edit** on any issue card:
+
+- Same fields as the create dialog (title, description, type, severity)
+- **Existing attachments** are shown with a delete button to remove each one
+- **Add new attachments** via drag-and-drop, click, or paste
+
+### 10.5 Issue Types
+
+- **Bug** — Something is broken and needs fixing
+- **Improvement** — Enhancement to existing functionality
+
+### 10.6 Severity Levels
+
+Severity badges are color-coded on cards:
+
+- **Critical** — Red badge, urgent, needs immediate attention
+- **High** — Orange badge, important, prioritize soon
+- **Medium** — Yellow badge, should be addressed in normal workflow
+- **Low** — Gray badge, minor issue, no urgency
+
+### 10.7 Status Workflow
+
+Items follow this lifecycle. Issues and stories use overlapping but distinct subsets of these statuses:
+
+**Issue statuses:**
+```
+Open → In Progress → Ready for Done → Done → Closed
+                                               ↓
+                                           Promoted
+```
+
+**Story statuses (with QA gate):**
+```
+Draft → Approved → In Progress → Ready for Review → Done
+                                       ↓
+                              ┌────────┴────────┐
+                          QA Passed          QA Failed
+                          QA Waived          QA Concerns
+                              ↓                  ↓
+                        Ready for Done     QA Fixed → (re-review)
+```
+
+**QA gate badges** — When a story reaches "Ready for Review", the QA gate result determines the compound badge:
+- **QA Passed** — Quality review passed
+- **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
+
+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.
+
+### 10.8 File Attachments
+
+Attach image files to issues:
+
+- Up to **10 files** per issue
+- Maximum **10MB** per file
+- Supported formats: PNG, JPEG, GIF, WebP
+- Upload methods: **drag-and-drop** onto the attachment zone, **click** to browse, or **paste** from clipboard
+- Attachments are managed in the issue create/edit dialogs — they are not shown inline on board cards
+- Preview thumbnails are shown in a grid with a remove button (×) for each
+
+### 10.9 Card Context Menu
+
+Click the **⋮** button on any card to open the context menu. Actions vary by card type:
+
+**Issue actions (by status):**
+- **Open:**
+  - **Quick Fix** — Marks the issue as Done and opens a dev session with the issue context
+  - **Promote to Story** — Convert an issue into a development story (disabled if already linked)
+  - **Promote to Epic** — Elevate an issue into an epic (disabled if already linked)
+  - **Edit** — Open the issue edit dialog
+  - **Close** — Close the issue
+- **In Progress:**
+  - **Resume Dev** — Resume development session for this issue
+- **Ready for Done:**
+  - **Commit and Mark Done** — Commit related changes and mark as Done
+  - **Mark Done** — Mark as Done without committing
+- **Closed / Done / Promoted:**
+  - **Reopen** — Reopen the issue
+- **Delete** — Permanently remove the issue (available in all states)
+
+**Story actions (by status):**
+- **Draft:**
+  - **Validate and Fix** — Validate the story draft and fix issues
+  - **Validate Only** — Validate the story draft without fix
+- **Approved:**
+  - **Start Development** — Begin implementing the story
+  - **Validate and Fix** / **Validate Only** — Re-validate if needed
+- **In Progress:**
+  - **Resume Development** — Continue implementing the story
+- **QA Passed / QA Waived:**
+  - **Commit and Complete Story** — Commit related changes and mark as Done
+  - **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
+- **QA Fixed:**
+  - **Review Story** — Request re-review after fixes
+- **Ready for Review / Ready for Done (no QA gate):**
+  - **Review Story** — Request quality review
+
+**Epic actions:**
+- **View Sub-Stories** — Open a dialog showing all stories under the epic
+- **Create Next Story** — Draft the next story for this epic with the SM agent (hidden when the epic is Done)
+
+The menu supports keyboard navigation (Arrow Up/Down, Enter, Escape).
+
+### 10.10 Card Behavior
+
+Cards display information based on their type:
+
+- **Type badge** — [I], [S], or [E] with color coding
+- **Severity badge** — For issues only, color-coded by level
+- **Status badge** — Color-coded status indicator (stories also show QA gate badges such as QA Passed, QA Failed, etc.)
+- **Issue number prefix** — Issues now show a short `#N` prefix (e.g., `#1`, `#42`) in monospace gray immediately before the title, so a board card and a chat mention or filename like `ISSUE-42.md` can be matched at a glance. Legacy issues without an `ISSUE-N` ID do not get a prefix
+- **Epic progress bar** — On epic cards, shows completion percentage with done/total count
+- **Story epic number** — Shows the parent epic reference
+- **Unmapped status warning** — ⚠ triangle icon when a card's status doesn't map to any column
+
+**Click behavior:** Clicking a card navigates to its associated file in the development session.
+
+### 10.11 Board Configuration
+
+Customize the board layout via the gear icon:
+
+**Columns:**
+- Add, remove, and **reorder** columns (Arrow Up/Down buttons)
+- Maximum **10 columns** allowed
+- **Required columns** (mapped to essential statuses) cannot be deleted
+- Each column has a name and an optional color
+
+**Colors:**
+- Pick from a preset **color palette** (swatches) or leave as default
+- Colors appear as the column's top border
+
+**Status Mapping:**
+- Map statuses and QA gate badges (Open, Draft, Approved, In Progress, Blocked, Ready for Review, QA Passed, QA Waived, QA Failed, QA Concerns, QA Fixed, Ready for Done, Done, Closed, Promoted) to columns
+- **Custom status mapping** — Define additional custom status strings and assign them to columns
+
+**Reset:**
+- **Reset to defaults** button restores the original column layout (with confirmation dialog)
+
+### 10.12 Mobile Kanban
+
+On small screens, the board uses a swipe carousel:
+
+- **Swipe left/right** to navigate between columns
+- **Rubber-band resistance** at the first and last columns (cannot swipe past edges)
+- **Indicator dots** at the bottom show current position
+- Smooth transition animation between columns
+- Touch-optimized card layout
+