@turmind/halo 0.1.9

package/bundled-docs/requirements/source-control.md

@@ -0,0 +1,82 @@
+# Source Control — Requirements
+
+A focused Git panel for **viewing changes, committing, pushing, and managing credentials** — not a full VSCode SCM clone. The guiding principle: this is *your workstation's* git view (what did I change, commit it, push it), not the *project's* full topology sandbox (that lives on GitHub/GitLab). Scope is deliberately trimmed to the "view + commit + credentials" core; branch operations, AI commit messages, clone, conflict resolution, stash and the DAG graph are explicitly out of this round.
+
+Backed by `GET/POST/DELETE /api/git/*` (see [dev/api.md](../dev/api.md#source-control-git)). Core lives in `packages/core/src/workspace/git-manager.ts` (simple-git wrapper); routes in `packages/server/src/routes/git.ts`; panel UI in `packages/admin/src/features/source-control/`.
+
+## Entry visibility (git-gated)
+
+The Source Control **activity-bar entry itself is hidden in non-git workspaces** — a non-developer's notes folder shouldn't carry a panel that doesn't apply to it. Visibility is a three-state signal (`useIsRepo`) derived from the *same* `GET /api/git/status` call that already drives the Explorer decorations (no extra fetch):
+
+- **`'unknown'`** (status not yet resolved) → **show**. Defaulting to visible means no first-paint flicker, and a clean repo (no changes) is never momentarily mis-hidden while its status is in flight.
+- **`true`** (confirmed repo, including a clean one) → **show**.
+- **`false`** (confirmed non-repo) → **hide**. If `localStorage` had restored the active tab to Source Control, the layout falls back to Explorer — guarded on the confirmed-`false` state so an in-flight check can't kick the user off the tab.
+
+**Auto-surface on `git init`**: creating a repo (panel **Initialize** *or* a terminal `git init` / `git clone`) makes the entry appear on its own, no page refresh. The backend's `GitDirWatcher` runs in a degraded "watch the workspace root for `.git` appearing" mode while the folder is a non-repo; the moment `.git` shows up it fires a `file:changed`, the frontend re-queries status, the repo signal flips `true`, and the entry surfaces. See [Auto-refresh](#auto-refresh-no-polling) for the two-phase watcher.
+
+## Panel states (three-gate onboarding)
+
+Once the entry is shown, the panel resolves to one of these on open, driven by `GET /api/git/status`:
+
+1. **Not a repo** (`{isRepo: false}`) — the folder has no git work-tree at its root (either no repo at all, or it only sits *inside* an ancestor's repo). Shows an **Initialize Repository** empty state. Never a 500/console error — a non-repo folder is a normal state.
+2. **Repo, no remote** — `GET /api/git/remotes` is empty. Shows an **Add Remote** prompt to guide first publish. Adding a remote is a purely local op with **no commit precondition** — a freshly-`init`'d empty repo can set its remote URL right away (not gated behind "must have a commit first", which would be a mis-applied VSCode *Publish* gate).
+3. **Repo with remote** — the full panel: CHANGES list, commit box, history graph.
+
+### Ancestor-repo guard
+A workspace placed *under* another repo (e.g. a dotfiles `$HOME`, or a monorepo subdirectory) must **not** show that ancestor's git state. `git` resolves `.git` by walking up the tree, so the backend guards with an explicit `isRepoRoot()` check — only the workspace root being a real work-tree root counts. Without this, a workspace would leak the enclosing repo's changes.
+
+## Changes (working tree)
+
+- CHANGES section lists every modified/added/deleted/untracked/renamed file, split into **Staged** and **Changes** groups (mirrors the porcelain X/Y status chars).
+- Each row shows a VSCode-style status badge: **M** modified (blue), **A** added / **U** untracked (green), **D** deleted (red), **R** renamed / **C** copied (blue), **U→Conflict** unmerged (red).
+- Stage / unstage individual files or all at once (`POST /api/git/stage` · `unstage`).
+- Click a file → opens a **Monaco side-by-side diff** (`GET /api/git/diff`); original side is HEAD (or the rename's old path), modified side is the working/staged copy. Binary files show git's "Binary files differ" rather than crashing.
+- **Single-file discard is intentionally omitted** — it's an "operation", not a "view". Use the command line (`git checkout`).
+
+## Commit & sync
+
+- Commit box: type a message, commit staged changes (`POST /api/git/commit`). Blank message is rejected.
+- **Push** (`POST /api/git/push`): first push of an untracked branch sets upstream automatically (`-u origin <branch>`).
+- **Push failure is surfaced as a friendly red banner**, never a raw leak. A missing-credentials push (`fatal: could not read Username for 'https://...'`) is detected and rephrased into a "configure credentials" guide rather than dumping git's stderr.
+- Pull (`POST /api/git/pull`).
+
+## Auto-refresh (no polling)
+
+The panel, the history graph, and the Explorer git decorations all refresh on the WebSocket `file:changed` event (debounced ~400ms), never by polling.
+
+- **Panel-driven writes**: every git mutation route (stage/unstage/commit/push/pull/init/remote) re-broadcasts `file:changed` (path `.git`) itself, because the workspace file watcher deliberately ignores `.git`. So after a commit the CHANGES list auto-clears with no manual refresh.
+- **Command-line writes**: a lightweight, **non-recursive** watch on the `.git` directory's top-level `HEAD` / `index` files (separate from the recursive workspace watcher, which excludes `.git` to avoid being overwhelmed by object-store inodes) catches terminal `git commit` / `checkout` / `add` / `reset` and broadcasts the same `file:changed`. `.lock` churn is filtered; the operation's events are debounced into a single refresh. So a commit made in the integrated terminal updates the panel without a manual refresh.
+- **Two-phase watcher**: `GitDirWatcher` adapts to whether the workspace is a repo yet. A real work-tree watches `.git` directly (the steady state above). A **non-git folder** instead watches the workspace *root* (still non-recursive) for one thing only — `.git` appearing — so a terminal `git init` / `git clone` is noticed and upgrades the watcher onto `.git`, firing once so the [entry auto-surfaces](#entry-visibility-git-gated). The root-watch handler compares the event filename before any disk IO (ordinary file churn costs one string compare), and a real repo never enters this degraded mode.
+
+## Explorer git decorations
+
+The file tree colors and badges files by git status (VSCode-style), driven by the same `/api/git/status` + `/api/git/ignored` data (see also [explorer.md](explorer.md)):
+
+- Changed files get a status-colored name + letter badge; a folder bubbles up its subtree's status (a single color, or neutral gray when the subtree mixes kinds).
+- **Ignored files/folders are dimmed.** `GET /api/git/ignored` collapses an ignored directory (e.g. `node_modules`) to one entry; the tree dims that node and everything under it (prefix match). Ignored paths run through `core.quotepath=false` so **non-ASCII paths (Chinese, emoji) dim correctly** — without it git octal-escapes them and the prefix match silently fails.
+- A real change always wins over ignored (a force-added file that's both ignored and modified shows its change badge, not dimmed).
+- A non-repo workspace (`isRepo:false`) carries no decorations — the tree stays clean.
+
+## History graph
+
+- Commit list from `GET /api/git/log`, newest first; each commit expands to its changed files (`GET /api/git/commit-files`), each file drills into the commit's own diff (`GET /api/git/diff?commit=`).
+- **Ref badges, tiered coloring**: local branch (e.g. `main`) solid/highlighted; remote branch (`origin/main`) dimmed outline, no fill; tag amber; current `HEAD` blue.
+- **Node coloring by push state** (two independent dimensions, mirrors VSCode's graph):
+  - *Color* — a **local-only** commit (not yet on any remote) is bright `--primary` blue so it stands out; a **pushed** commit dims to `--muted-foreground` gray (it has "sunk" onto the remote). Driven by the `pushed: boolean` each commit carries from `GET /api/git/log`.
+  - *Shape* — the **newest** commit (`HEAD`, list head) is a hollow ring (colored border, background fill); every commit below is a solid dot. So the topmost local-only commit reads as a **blue hollow ring**, older unpushed ones as blue solid dots, pushed ones as gray solid dots.
+  - **Pushed判定**: `git-manager` computes unpushed hashes from the *current branch's upstream* when one is set; when the branch has **no upstream but a remote exists**, it falls back to `rev-list HEAD --not --remotes` (commits on HEAD but on no remote branch) — **not** `rev-list HEAD`, which would wrongly paint the entire history local-only and ignore the visible `origin/*` tracking branches.
+- **Infinite scroll**: an IntersectionObserver sentinel at the bottom raises `limit` by a page (50) at a time (`log` is capped server-side at 2000). Stops automatically when fewer than `limit` commits come back (reached the root).
+
+## Credentials & SSH
+
+- Managed from a gear (titled **Git Credentials**) on the panel.
+- **HTTPS credentials, multiple per setup**: `~/.git-credentials` is the **single source of truth** (one `https://user:token@host` line per host, file mode 0600). No separate encrypted mirror.
+  - List shows configured `{host, username}` rows; **the token is never returned to the client / never re-displayed**.
+  - Add a new credential without closing the modal (supports adding several in a row).
+  - Delete is per-host with an **inline two-step confirm**; deleting actually removes the line from `~/.git-credentials` (idempotent).
+- **SSH**: lists private keys in `~/.ssh` (with an `encrypted` flag, never key contents) and ssh-agent reachability + loaded-key count. An encrypted, not-yet-loaded key shows an **Unlock** button → inline passphrase field → on submit, loads the key into the shared ssh-agent (`POST /api/git/ssh/unlock`) and flips it to **Loaded** — no copying an `ssh-add` command into the terminal. The passphrase reaches `ssh-add` only through a throwaway `SSH_ASKPASS` helper (never argv / disk / log), and the helper is **answer-once** so a wrong passphrase fails fast instead of hanging on a retry prompt. "Restart needs re-unlock" note retained (the agent is process-scoped).
+- **Remote protocol switch**: rewrite `origin` between HTTPS and scp-style SSH (`GET/POST /api/git/remote/protocol`).
+
+## Out of scope (this round)
+
+Branch create / switch / merge, ahead/behind indicator, AI-generated commit messages, clone, merge-conflict resolution UI, stash, worktree, timeline, PR management, the **DAG rail graph** (branch fork/merge visualization), and single-file discard. The DAG graph + ahead/behind are deferred to the branch-operations round, where they have live branch actions to feed them — standalone they're decoration, not a viewing need.

package/bundled-docs/requirements/terminal.md

@@ -0,0 +1,118 @@
+# Terminal — Requirements
+
+xterm.js terminal with a node-pty backend, multi-tab, reconnect-resilient.
+
+## Core behaviour
+
+### Multi-tab
+- Each tab owns an independent PTY
+- Every terminal has a unique `terminalId` for routing
+- Tabs close independently
+- All tabs on a client share one WebSocket connection (multiplexed by `terminalId`)
+
+### Working directory
+
+| Scenario | Initial cwd |
+|---|---|
+| Default workspace terminal | Current project's workspace root (`activeProject.path`) |
+| Skill mini-workspace terminal | The skill directory (cwd prop passed by caller) |
+| No workspace bound | `?folder=` URL param, falling back to server `$HOME` |
+
+Derivation in [packages/admin/src/features/terminal/terminal-panel.tsx:108](../../../packages/admin/src/features/terminal/terminal-panel.tsx#L108); backend resolution in [packages/server/src/ws/terminal-manager.ts:46](../../../packages/server/src/ws/terminal-manager.ts#L46).
+
+Workspace switch does **not** migrate existing terminals — they keep their original cwd. Close and reopen to pick up the new workspace root.
+
+### Reconnect resilience
+
+When the WebSocket drops:
+
+1. PTYs are **not killed** — they stay in the module-level `terminals` map with `currentWs = null` (`packages/server/src/ws/terminal-manager.ts`)
+2. Output during detach is buffered (ring buffer, up to `config.limits.terminalOutputBuffer` = 50 KB per terminal)
+3. Grace period: `config.timeout.terminalGrace` (default 5 min)
+4. On reconnect, the client sends `terminal:reattach` (sent on initial mount **and** on every subsequent `_connected` event)
+5. Server replays the entire output buffer, reattaches live I/O, and responds with `terminal:reattached { terminalIds: [...] }`
+6. If the grace timer expires first, the PTY is killed and the detach entry removed
+
+Connection-level liveness and reconnect (server keepalive tolerance, client self-check timer, auth-expiry handling) are owned by the shared WS client — see [design/ws.md](../design/ws.md#client-side-liveness--reconnect).
+
+On the reattach handler ([packages/admin/src/features/terminal/terminal-panel.tsx](../../../packages/admin/src/features/terminal/terminal-panel.tsx)), each id in `terminalIds` is dispatched by whether a local xterm instance already exists:
+
+- **Already exists** (typical after a transient WS reconnect): only a `terminal:resize` is sent so server PTY dimensions resync; the existing instance keeps its scrollback and continues receiving live output.
+- **Does not exist** (first mount, or the previous instance was disposed): a fresh xterm container is created and bound to that id. Bracketed paste mode is resynced by locally writing `\x1b[?2004h` into the new instance — bash enabled the mode on the PTY at spawn time, but that sequence went to the disposed instance; without the resync, a multi-line paste into the reattached terminal would be sent unbracketed and execute line by line.
+
+### Environment
+- Shell: `$SHELL` or `/bin/bash`
+- Terminal type: `xterm-256color`
+- Default size: 80 × 24 (resize requests override)
+- Strips `npm_config_prefix` env (avoids nvm warnings when starting node)
+
+### Lifecycle
+
+```
+          ┌─────────────┐
+create ──▶│ in this WS  │
+          │ session map │
+          └──────┬──────┘
+                 │ WS drops
+                 ▼
+          ┌─────────────┐
+          │  detached   │  (grace timer = 5min, ring buffer active)
+          │    pool     │
+          └──┬───────┬──┘
+   reattach  │       │  grace expires
+             ▼       ▼
+       ┌─────────┐  kill PTY, clean up
+       │ replay +│
+       │ live IO │
+       └─────────┘
+```
+
+Close semantics:
+- Explicit `terminal:close` — PTY killed immediately, detach entry (if any) cleaned up
+- WS drop → grace expires (default 5 min) without reattach → PTY killed
+- Server shutdown — all PTYs die with the process
+
+## WebSocket protocol
+
+| Direction | Type | Fields | Purpose |
+|---|---|---|---|
+| C→S | `terminal:start` | `terminalId?`, `cwd?`, `cols?`, `rows?` | Spawn a new PTY |
+| C→S | `terminal:input` | `terminalId`, `data` | Send user keystrokes |
+| C→S | `terminal:resize` | `terminalId`, `cols`, `rows` | Resize PTY (screen resize) |
+| C→S | `terminal:close` | `terminalId` | Explicit close |
+| C→S | `terminal:reattach` | — | Reattach all detached terminals after reconnect |
+| S→C | `terminal:ready` | `terminalId` | PTY spawned and ready |
+| S→C | `terminal:output` | `terminalId`, `data` | PTY stdout/stderr |
+| S→C | `terminal:exit` | `terminalId`, `exitCode` | PTY exited |
+| S→C | `terminal:reattached` | `terminalIds` | Reattach completed for these |
+
+Source: [packages/server/src/ws/terminal-manager.ts](../../../packages/server/src/ws/terminal-manager.ts).
+
+## Config
+
+| Config key | Default | Purpose |
+|---|---|---|
+| `config.timeout.terminalGrace` | 300,000 ms | Detach retention period |
+| `config.limits.terminalOutputBuffer` | 50,000 bytes | Detach output ring buffer cap |
+
+Defined in [packages/server/src/config.ts](../../../packages/server/src/config.ts).
+
+## Test cases
+
+| # | Scenario | Expected |
+|---|---|---|
+| T1 | Start, run `ls` | Output arrives; prompt returns |
+| T2 | Start in skill mini-workspace | cwd is the skill directory (`pwd` confirms) |
+| T3 | Resize window | PTY cols/rows update; long-running process (e.g. `watch ls`) reflows |
+| T4 | Disconnect mid-command (`sleep 5 && echo done`) → reconnect within grace period | Buffered output replayed; `done` visible |
+| T5 | Disconnect → wait > grace period → reconnect | Terminal gone (PTY killed at grace expiry) |
+| T6 | Open 3 tabs, close 1 explicitly | Other 2 keep their PTYs; closed one gets `terminal:exit` |
+| T7 | `exit` from within shell | `terminal:exit` with exitCode=0; tab shows closed |
+| T8 | Paste a 10 KB block | Sent as `terminal:input` without choking; shell echoes in chunks |
+
+Follows the pattern of [test/session.md](../test/session.md).
+
+## Related design
+
+- Detach / reattach plumbing: [design/architecture.md#terminalmanager](../design/architecture.md#terminalmanager--pty-management)
+- WS envelope shape: [design/ws.md](../design/ws.md)

package/bundled-docs/requirements/workspace.md

@@ -0,0 +1,80 @@
+# Workspace Layout — Requirements
+
+Overall workspace layout: Activity Bar + Sidebar + main content + a resizable bottom panel.
+
+## Layout structure
+
+Most tabs use the standard layout (with bottom panel):
+
+```
++---+-------------+---------------------------+
+| A |  Sidebar     |  Main Content Area        |
+| c |              |                           |
+| t |  (tab-       |  (Canvas / agent configs/ |
+| i |   dependent) |   …)                       |
+| v |              +---------------------------+
+| i |              |  Bottom Panel             |
+| t |              |  (Chat | Terminal)        |
+| y |              |                           |
+| B |              |                           |
+| a |              |                           |
+| r |              |                           |
++---+--------------+---------------------------+
+```
+
+**Skills** is an exception — SkillsMain (file tree + Canvas) uses the full height, no bottom panel.
+
+The Bottom Panel (Chat + Terminal) can also be **floated** into a draggable window that survives activity-tab switching — see "Bottom panel" below.
+
+## Activity Bar tabs
+
+| Icon | Tab | Sidebar | Main content | Bottom panel |
+|---|---|---|---|---|
+| FolderTree | Explorer | File tree + ops | Canvas (Monaco + previews) | Chat + Terminal |
+| MessageSquare | Sessions | Session list | Session message viewer | Chat + Terminal |
+| Zap | Skills | Skill list | SkillsMain (full height) | — |
+| Bot | Agents | — | Agent config editor + Test (full width) | Chat + Terminal |
+| MessageCircle | Channels | Channel list | Channel config editor | Chat + Terminal |
+| Sparkles | Evolution | — | Evolution main (run/apply review) | Chat + Terminal |
+| Clock | Cron | — | Cron job list + run audit | Chat + Terminal |
+| Settings2 | Settings | — | Settings panel | Chat + Terminal |
+
+## Resizable panels
+- **Sidebar width**: drag between sidebar and main content
+- **Bottom panel height**: drag between main content and bottom panel
+- Sizes persisted via localStorage
+
+## Bottom panel
+
+Two tabs:
+- **Chat**: the main chat panel
+- **Terminal**: xterm multi-tab terminal
+
+Current tab stored in `editorStore.bottomTab`.
+
+### Floating mode
+The tab bar has a float button on the far right. Toggling it detaches the panel into a draggable window:
+- **Default position/size**: bottom-right corner, 480×640 with a 24px margin
+- **Drag**: grab the tab bar (anywhere except buttons) to reposition
+- **Resize**: four edges (N/S/E/W) + four corners (NW/NE/SW/SE), minimum size 320×240
+- **Visible from any activity tab** — Explorer's in-layout bottom panel is hidden while floating; Canvas takes full height
+- **Only one instance** mounted at a time (xterm DOM gets rebuilt once on dock/undock; server-side terminal sessions are preserved and reattached, scroll buffer is lost)
+- **State is in `sessionStorage`** (`halo_bottom_floating` + `halo_bottom_float_rect`) — page refresh reverts to docked mode
+- **Agent "Test" button** dispatches `halo:navigate → explorer` to surface Chat; this jump is suppressed while floating since Chat is already globally visible
+- **Close (✕) button** on the float window's tab bar docks it back
+
+## Shortcuts
+
+| Shortcut | Action |
+|---|---|
+| Cmd/Ctrl + P | Quick Open (fuzzy file search) |
+| Cmd/Ctrl + S | Save current file |
+| Alt + W | Close current tab (Cmd+W cannot be overridden in browsers) |
+
+## Auth
+
+Login page sits in front of the Activity Bar:
+- Password login via `POST /api/auth/login`
+- JWT in an HTTP-only cookie
+- Auto-refresh after 24 hours
+- Token lifetime up to 14 days

package/bundled-docs/test/docs-seeding.md

@@ -0,0 +1,101 @@
+# Platform Docs Seeding Test Cases
+
+Test URL: local server (default `http://localhost:9527/?folder=<absolute-workspace-path>`).
+Password: whatever `HALO_PASSWORD` is set to, or the random password printed by the server on first startup.
+
+Prerequisite: `~/.halo/global/` already exists from a prior run. Pick any workspace that is **not** the halo source repo (e.g. `/path/to/test-workspace`).
+
+---
+
+## Test matrix
+
+### A. First-time seed
+
+| # | Scenario | Method | Expected |
+|---|---|---|---|
+| A1 | Fresh install simulation | `rm -rf ~/.halo/global/docs && restart server` | Startup log: `[Init] Seeding platform docs from ...`; `~/.halo/global/docs/` has 13 files |
+| A2 | Source detection in monorepo | Start server from `/path/to/halo`, delete docs first | Log: `Seeding platform docs from /path/to/halo/.halo/docs` |
+| A3 | Source detection for packaged install | Create `packages/server/bundled-docs/guide/skills.md` with "FAKE"; delete `~/.halo/global/docs/`; restart | Log says `Seeding platform docs from .../bundled-docs`; `~/.halo/global/docs/guide/skills.md` contains "FAKE" |
+| A4 | No source at all | Move init.js somewhere isolated (no repo parent, no bundled-docs), run | Log: `[Init] No docs source found — skipping platform docs seed`; no crash; `~/.halo/global/docs/` not created |
+| A5 | Allowlist boundary | After A1, check what's in `~/.halo/global/docs/` | Only 13 files: `guide/` (8), `dev/` (3), `requirements/` (2). **No** `INDEX.md`, `design/`, `test/`, `plans/`, or other `dev/`/`requirements/` files (the doc lookup table now lives inline in the `halo` skill) |
+
+### B. User edits and upgrades
+
+| # | Scenario | Method | Expected |
+|---|---|---|---|
+| B1 | User edit preserved | Edit `~/.halo/global/docs/guide/skills.md` → restart server | Edit intact; no `[Init] Created` log for that file |
+| B2 | Deleted file restored | `rm ~/.halo/global/docs/guide/agents.md` → restart | Log: `[Init] Created .../agents.md`; file restored from source |
+| B3 | Version bump hint | Set `.template-version` to a value below the current `TEMPLATE_VERSION` (see `packages/server/src/init.ts`), restart | Log: `[Init] Seed templates updated: v<old> → v<current>. To refresh a specific file, delete it from ... and restart.` Plus `[Server] Templates outdated (v<old> → v<current>), refreshing ~/.halo/global/` from the startup version-check |
+| B4 | Idempotent second run | Restart the server twice in a row | Second run has **no** `[Init] Created` logs; `.template-version` stays at the current `TEMPLATE_VERSION` |
+
+### C. Agent-facing integration
+
+| # | Scenario | Input | Expected |
+|---|---|---|---|
+| C1 | `halo` skill carries the doc table | Open any chat with the default agent, Debug mode → first message → Prompt button | System prompt lists the `halo` skill in the available-skills block. Activate it (`activate_skill halo`) and the loaded body contains `### Platform Documentation` with the "User asks … / Read …" lookup table |
+| C2 | Agent knows about bundled docs | Open chat in a non-halo workspace, ask: "what platform docs ship with halo?" | Agent activates the `halo` skill and answers from its lookup table (no `file_read` needed for the overview) |
+| C3 | Answer to "how do I test my skill?" | New chat, ask: "I just made a skill. How do I test it?" | Agent reads `~/.halo/global/docs/guide/testing-agents-and-skills.md` directly (path from system prompt table), answers with the attach-to-agent → Test → trigger flow |
+| C4 | Answer to "where do API keys go?" | New chat, ask: "I want my skill to use an API key. Where do I put it?" | Agent reads `guide/secrets-and-credentials.md`, explains schema in `config.yaml` + value in `settings.yaml` + `<<ENV>>` + skill body using `{{params.<key>}}` short form |
+| C5 | Answer for a question NOT in bundled docs | New chat, ask: "how does the file watcher debounce work?" | Agent looks for it in the docs, doesn't find (bundled docs don't have `design/`), falls back to reading code or admits it doesn't know — **does not hallucinate** |
+| C6 | Works in any workspace | Repeat C3 in a workspace that has **no** `.halo/docs/` of its own (e.g. `/path/to/test-workspace`) | Same answer — proves docs come from `~/.halo/global/`, not the workspace |
+
+### D. Negative / edge cases
+
+| # | Scenario | Method | Expected |
+|---|---|---|---|
+| D1 | Permissions issue | `chmod -w ~/.halo/global/docs/` → delete one file → restart | `[Init] Failed to read template` or similar error logged; server still starts (seed is best-effort) |
+| D2 | Concurrent starts | Start two server processes at the same time against the same home dir | Only one wins the pid lock; losers exit cleanly (not a seed-specific test, but confirms seed doesn't race) |
+| D3 | Partially-populated docs | Remove half the files in `~/.halo/global/docs/guide/`; restart | Exactly the removed files get `[Init] Created` logs; others untouched |
+| D4 | Garbage `.template-version` | Write `abc` to `~/.halo/global/.template-version`; restart | Treated as 0; seed runs; version is reset to the current `TEMPLATE_VERSION` at the end |
+
+---
+
+## Verification helpers
+
+### Check seeded file count
+
+```bash
+find ~/.halo/global/docs -type f | wc -l
+# Expected: 13
+```
+
+### Check allowlist boundary (A5)
+
+```bash
+# These should all NOT exist
+ls ~/.halo/global/docs/design/ 2>&1  # No such file
+ls ~/.halo/global/docs/test/ 2>&1    # No such file
+ls ~/.halo/global/docs/plans/ 2>&1   # No such file
+ls ~/.halo/global/docs/requirements/terminal.md 2>&1  # No such file
+ls ~/.halo/global/docs/dev/api.md 2>&1                # No such file
+```
+
+### Check `halo` skill carries the doc table (C1)
+
+```bash
+grep -A 3 "Platform Documentation" ~/.halo/global/skills/halo/SKILL.md
+# Expected: "### Platform Documentation" section with the inline "User asks … / Read …" lookup table
+```
+
+### Check source that was used
+
+```bash
+grep "Seeding platform docs\|No docs source" /tmp/halo.log 2>/dev/null | tail -1
+# Or check server's stdout — the log line is emitted once per startup
+```
+
+### Force a fresh seed
+
+```bash
+rm -rf ~/.halo/global/docs ~/.halo/global/.template-version
+# Restart server
+# Expected: 13 [Init] Created log lines for docs/*
+```
+
+---
+
+## Known limitations
+
+- **Cross-links to non-bundled docs** (e.g. `guide/skills.md` → `design/prompt-system.md`) will 404 if an agent tries to follow them. Agents should answer from the doc body rather than chase links. Noted in the `halo` skill body.
+- **Version downgrade** not detected: if you set `.template-version` higher than the current `TEMPLATE_VERSION`, nothing happens — no warning, no overwrite. Not a concern in practice.
+- **Seed does not overwrite**. If a user edits a file and a newer Halo version ships a fix to the same doc, the user's edit wins. Workaround: `rm` the file and restart.