trekoon 0.4.2 → 0.4.4

package/.agents/skills/trekoon/reference/sync.md

@@ -1,129 +1,82 @@
 # Sync Reference
 
-## Sync reminders
+Trekoon uses one live SQLite database per repository at
+`<sharedStorageRoot>/.trekoon/trekoon.db`. Linked worktrees share it. `git
+checkout` and `git switch` do not roll back tracker state. Sync imports tracker
+events between branches; never copy or commit the `.db` file.
 
-Same-branch sync is a no-op: `sync pull --from main` while on `main` produces
-zero conflicts and simply advances the cursor. `sync status` returns `behind=0`
-on the source branch. No action is needed.
+Same-branch sync is a no-op. Cross-branch sync matters before merging a feature
+branch back.
 
-Cross-branch sync matters before merging a feature branch back:
+## Before Merge
 
-- Before merge, pull tracker events from the base branch:
+Pull tracker events from the base branch:
 
-  ```bash
-  trekoon --toon sync pull --from main
-  ```
-
-- If conflicts exist, inspect and resolve them explicitly:
+```bash
+trekoon --toon sync pull --from main
+```
 
-  ```bash
-  trekoon --toon sync conflicts list
-  trekoon --toon sync conflicts show <conflict-id>
-  trekoon --toon sync resolve <conflict-id> --use theirs --dry-run
-  trekoon --toon sync resolve <conflict-id> --use ours
-  ```
+If conflicts exist:
 
-### Conflict resolution: ours vs theirs
+```bash
+trekoon --toon sync conflicts list
+trekoon --toon sync conflicts show <conflict-id>
+trekoon --toon sync resolve <conflict-id> --use theirs --dry-run
+trekoon --toon sync resolve <conflict-id> --use ours
+```
 
-Conflicts are **field-level**, not whole-record. Each conflict targets one field
-(e.g., `status`, `title`, `description`) on one entity.
+## Conflict Rules
 
-- `--use ours` — keep the current entity field value in the shared DB. The
-  entity is not written, but the conflict record is marked resolved and a
-  resolution event is appended.
-- `--use theirs` — overwrite the shared DB entity field with the source-branch
-  value. The conflict record is marked resolved and a resolution event is
-  appended.
-- `--dry-run` — preview the resolution without mutating the database. Returns
-  `oursValue`, `theirsValue`, `wouldWrite`, and `dryRun: true`. Use this before
-  committing to a resolution.
+Conflicts are field-level, not whole-record. Each conflict targets one field on
+one entity.
 
-**Example:** after `sync pull --from main`, a conflict appears on epic `abc123`,
-field `status`:
-- ours (current DB): `in_progress`
-- theirs (source branch): `done`
-- `--use ours` keeps status as `in_progress`
-- `--use theirs` changes status to `done` in the live shared DB
+- `--use ours`: keep the current shared DB field value; mark conflict resolved.
+- `--use theirs`: write the source-branch field value into the shared DB; mark
+  conflict resolved.
+- `--dry-run`: preview without mutation. Returns `oursValue`, `theirsValue`,
+  `wouldWrite`, and `dryRun: true`.
 
-Always inspect conflicts with `sync conflicts show` before resolving. Choosing
-`theirs` without inspection can overwrite in-progress work in the shared DB.
+Always inspect with `sync conflicts show` before resolving. Choosing `theirs`
+without inspection can overwrite in-progress shared DB work.
 
-### Understanding why conflicts happen
+Typical choices:
 
-| Scenario | Typical resolution | Why |
+| Scenario | Usually use | Why |
 |---|---|---|
-| Completed work vs stale main state | ours | Your branch has the latest progress |
+| Completed work vs stale main | ours | Your branch has latest progress |
 | Enriched descriptions vs original | ours | Your descriptions are more detailed |
-| Upstream updates from another agent | theirs | Accept the newer upstream state |
-| User-intentional reset | theirs | Respect the user's explicit action |
+| Upstream updates from another agent | theirs | Accept newer upstream state |
+| User-intentional reset | theirs | Respect explicit user action |
 
-### Agent decision framework
+When unsure, ask the user.
 
-1. List conflicts: `trekoon --toon sync conflicts list`
-2. Group by pattern — are conflicts on the same field or direction?
-3. If uniform pattern, batch resolve: `trekoon --toon sync resolve --all --use ours`
-4. If mixed, narrow by entity or field, or inspect individually
-5. When unsure, ask the user
-
-### Batch resolve patterns
-
-Common scenarios:
+## Batch Resolve
 
 ```bash
-# Resolve all conflicts at once (most common after completing work)
-trekoon --toon sync resolve --all --use ours
-
-# Preview before resolving
 trekoon --toon sync resolve --all --use ours --dry-run
-
-# Narrow to status field conflicts only
+trekoon --toon sync resolve --all --use ours
 trekoon --toon sync resolve --all --use ours --field status
-
-# Narrow to a specific entity
 trekoon --toon sync resolve --all --use theirs --entity <id>
-
-# Combine filters
 trekoon --toon sync resolve --all --use ours --entity <id> --field description
 ```
 
-## Shared-database model
-
-Trekoon uses **one live SQLite database per repository**. The file lives at
-`<sharedStorageRoot>/.trekoon/trekoon.db`, where `sharedStorageRoot` is the
-parent of `git rev-parse --git-common-dir` (i.e., the main worktree root).
-
-Key consequences:
-
-- **All linked worktrees share the same database.** A status change in one
-  worktree is immediately visible in every other worktree.
-- **`git checkout` / `git switch` does not change tracker state.** The database
-  is outside the git object store, so switching branches does not roll back or
-  swap task data.
-- **Sync operates on tracker events, not on the database file itself.** Use
-  `sync pull` to import events between branches — never copy or commit the
-  `.db` file.
-
-Treat every write as a mutation of shared repo-wide state, not branch-scoped
-state.
-
-**Conflicts are scoped per worktree + branch.** `sync_conflicts` rows are
-recorded with the originating worktree path and current branch, so resolving a
-conflict in one worktree never erases a peer worktree's conflict on the same
-entity. `sync conflicts list` and `sync resolve` from a given worktree only
-see and act on rows scoped to that worktree's branch.
-
-## Worktree diagnostics and destructive scope
-
-- Inspect machine-readable storage fields when debugging worktrees:
-  `storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
-  `databaseFile`.
-- `sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
-  worktrees.
-- If `trekoon wipe --yes --toon` is explicitly requested, warn that it deletes
-  shared storage for the entire repository and every linked worktree.
-- Wipe is destructive recovery only; it is never the right fix for a tracked DB
-  or gitignore mistake.
-
-Trekoon stores local state in `.trekoon/trekoon.db`. In git repos and
-worktrees, storage resolves from the shared repository root rather than each
-worktree independently.
+Use batch resolve only when the conflict pattern is uniform. Otherwise inspect
+and resolve individually or narrow by `--entity` / `--field`.
+
+## Worktree Scope
+
+Inspect machine-readable storage fields when debugging worktrees:
+`storageMode`, `repoCommonDir`, `worktreeRoot`, `sharedStorageRoot`, and
+`databaseFile`.
+
+Conflicts are scoped per worktree and branch. `sync conflicts list` and
+`sync resolve` only act on rows for the current worktree/branch, so resolving a
+conflict does not erase a peer worktree's conflict on the same entity.
+
+## Destructive Recovery
+
+`sharedStorageRoot` is the repo-scoped source of truth for `.trekoon` in git
+worktrees. If the user explicitly requests `trekoon wipe --yes --toon`, warn
+that it deletes shared storage for the whole repository and every linked
+worktree. Wipe is destructive recovery only; it is never the fix for a tracked
+DB or gitignore mistake.

package/README.md

@@ -90,8 +90,8 @@ What the agent does during execution:
    calls `task done`
 6. `task done` returns which downstream tasks just became unblocked, so the
    orchestrator knows what to dispatch next
-7. After all tasks complete: code review, tests, manual verification, then marks
-   the epic `done`
+7. After all tasks complete: review agent or review skill for non-trivial
+   changes, tests, manual verification, then marks the epic `done`
 
 The orchestrator uses `task done` responses to drive the whole loop. No polling,
 no guessing. When a task finishes, Trekoon tells you exactly what's ready next.
@@ -110,13 +110,15 @@ agents don't know how to use Trekoon properly.
 ```bash
 trekoon skills install          # repo-local (.agents/skills/trekoon/)
 trekoon skills install -g       # global (~/.agents/skills/trekoon)
+trekoon skills install --link --editor codex    # editor link (.codex/skills/trekoon)
 trekoon update                  # refresh all installed skills
 ```
 
-The skill bundles three reference documents that agents load on demand:
+The skill bundles reference documents that agents load on demand:
 
 | Agent needs to... | Skill reads | What it covers |
 | --- | --- | --- |
+| Coordinate across harnesses | `reference/harness-primitives.md` | Universal subagent, question, local task display, review, and evidence-recording guidance |
 | Plan a feature | `reference/planning.md` | Decomposition, writing standard, dependency modeling, validation |
 | Execute an epic | `reference/execution.md` | Graph building, lane grouping, sub-agent dispatch, verification (universal) |
 | Execute with Agent Teams | `reference/execution-with-team.md` | TeamCreate/SendMessage, parallel Claude Code instances in tmux |
@@ -145,6 +147,16 @@ Execute only:
 /trekoon <epic-id> execute
 ```
 
+When you execute an epic, use subagents by default for any meaningful work that
+can run independently. Keep small or tightly coupled tasks in the parent agent.
+Use the main context for orchestration, dependency decisions, user
+communication, and final synthesis while Trekoon remains the durable source of
+truth.
+
+If a harness has a higher-priority rule requiring explicit permission before
+subagents, surface that immediately instead of silently doing broad work
+yourself.
+
 Plan and execute end to end:
 
 ```
@@ -154,9 +166,11 @@ dependency order until the epic is complete
 
 ## Agent Teams
 
-For larger epics, Trekoon supports Claude Code Agent Teams. Instead of
-sequential sub-agents, you get real parallel Claude Code instances coordinated
-through `TeamCreate` and `SendMessage`, each running in its own tmux pane.
+For larger epics, use the current harness's native subagent mechanism for
+meaningful work that can run independently. Claude Code Agent Teams are one
+runtime-specific option: instead of sequential sub-agents, you get real parallel
+Claude Code instances coordinated through `TeamCreate` and `SendMessage`, each
+running in its own tmux pane.
 
 Requires Claude Code env variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`.
 
@@ -182,14 +196,19 @@ call it from any non-done status.
 
 ## Local board
 
-Trekoon includes a browser-based board for humans who like having visual overview.
-No build step, no framework dependencies, works offline.
+Trekoon includes a browser-based board for humans who like having a visual
+overview. No build step, no framework dependencies, works offline.
 
 ```bash
 trekoon board open      # starts a local server, opens browser
-trekoon board update    # refresh assets only
 ```
 
+Board code (HTML, JS, CSS, fonts) comes from the running Trekoon install.
+Board data comes from the repo where `trekoon board open` is invoked. Updating
+Trekoon updates the board bundle; no per-repo asset copy is needed.
+Repos with an old ignored `.trekoon/board` directory keep those files on disk,
+but Trekoon no longer reads or refreshes them.
+
 Binds to `127.0.0.1` only with a per-session token. Gives you an epics
 overview, kanban workspace per epic, task detail modals, and search. The board
 client subscribes to `/api/snapshot/stream` (SSE), so mutations from another
@@ -201,7 +220,7 @@ shell, worktree, or browser tab show up live without a manual refresh.
 | --- | --- |
 | Set up a repo | `trekoon init` |
 | Open the local board | `trekoon board open` |
-| Plan work | `trekoon epic create ...`, `trekoon epic expand ...` |
+| Plan work | `trekoon --toon epic create ...`, `trekoon --toon epic expand ...` |
 | Create tasks in bulk | `trekoon task create-many ...` |
 | Add dependencies | `trekoon dep add-many ...` |
 | Start an agent session | `trekoon session --epic <id>` |

package/docs/ai-agents.md

@@ -14,22 +14,39 @@ agent to:
 - append progress and blocker notes instead of rewriting descriptions
 - preview scoped replace before `--apply`
 - treat `.trekoon` as shared repo-scoped state
+- use harness-local todo/task tools as a live progress display while keeping
+  Trekoon as the durable source of truth
+- use subagents by default for meaningful work that can run independently when
+  the harness exposes them
+- keep small or tightly coupled tasks in the parent agent so the main context
+  stays available for orchestration and decisions
 
 The skill ships with reference guides so the agent can handle the full
 plan-to-completion workflow from one install:
 
 ```
 .agents/skills/trekoon/
-  SKILL.md                      <- command reference, status machine, agent loop
+  SKILL.md                      <- command router and operating contract
   reference/
+    harness-primitives.md       <- universal agent/task/question/review primitives
     planning.md                 <- decomposition, writing standard, validation
     execution.md                <- graph building, lane dispatch, verification
     execution-with-team.md      <- Agent Teams pattern (Claude Code only)
 ```
 
-The agent loads the relevant reference on demand: `planning.md` when asked to
-plan, `execution.md` when asked to execute, `execution-with-team.md` when Agent
-Teams are available.
+The command shape determines what the agent loads:
+
+| User command | Required references |
+| --- | --- |
+| `/trekoon plan <goal>` | `harness-primitives.md`, then `planning.md` |
+| `/trekoon <id>` | `SKILL.md` only, unless deeper analysis is needed |
+| `/trekoon <id> analyze` | `SKILL.md` plus targeted Trekoon reads |
+| `/trekoon <id> execute` | `harness-primitives.md`, then `execution.md` |
+| `/trekoon <id> team execute` | `harness-primitives.md`, then `execution-with-team.md` |
+
+`harness-primitives.md` is loaded before planning or execution because those
+modes may need structured questions, local progress displays, subagent
+delegation, review agents, and runtime-specific orchestration.
 
 ## Install the skill
 
@@ -42,6 +59,7 @@ Create a project-local editor link when your agent environment supports it:
 ```bash
 trekoon skills install --link --editor opencode
 trekoon skills install --link --editor claude
+trekoon skills install --link --editor codex
 trekoon skills install --link --editor pi
 trekoon skills install --link --editor opencode --to ./.custom-editor/skills
 trekoon skills update
@@ -52,6 +70,7 @@ Path behavior:
 - Canonical install: `.agents/skills/trekoon/SKILL.md`
 - OpenCode link: `.opencode/skills/trekoon`
 - Claude link: `.claude/skills/trekoon`
+- Codex link: `.codex/skills/trekoon`
 - Pi link: `.pi/skills/trekoon`
 - `--to <path>` changes only the editor link root
 - `--allow-outside-repo` is for intentional external links
@@ -97,6 +116,17 @@ Typical flow:
 
 The core loop: **session, work, task done, repeat**.
 
+When you execute an epic, use subagents by default for any meaningful work that
+can run independently. Keep small or tightly coupled tasks in the parent agent.
+Build the Trekoon execution graph, group ready tasks into lanes, keep a local
+todo/task display for the user, and synthesize the results. Use the parent
+context for dependency decisions and finishing the epic.
+
+Some harnesses have higher-priority rules that require explicit user permission
+before spawning subagents. When that happens, say so immediately after
+discovering independent lanes and ask for permission before broad execution. Do
+not silently default to single-agent execution.
+
 Start with a single orientation call, optionally scoped to an epic:
 
 ```bash
@@ -193,6 +223,20 @@ notes, mark it done, and repeat until there are no ready tasks or you hit a
 blocker.
 ```
 
+### Execute with subagents where useful
+
+```text
+/trekoon <epic-id> execute -- use subagents by default for meaningful work that
+can run independently, keep Trekoon as the source of truth, and use local task
+tools to show live progress.
+```
+
+Short form for harnesses that require explicit delegation wording:
+
+```text
+/trekoon <epic-id> execute with subagents
+```
+
 ### Plan and execute end to end
 
 ```text

package/docs/commands.md

@@ -6,7 +6,7 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 ## Command surface
 
 - `trekoon init`
-- `trekoon board <open|update>`
+- `trekoon board <open>`
 - `trekoon help [command]`
 - `trekoon quickstart`
 - `trekoon epic <create|expand|list|show|search|replace|update|delete|progress>`
@@ -22,8 +22,8 @@ the quickest way to get started, read [Quickstart](quickstart.md) first.
 - `trekoon sync resolve <conflict-id> --use ours|theirs [--dry-run]`
 - `trekoon sync resolve --all --use ours|theirs [--entity <id>] [--field <name>] [--dry-run]`
 - `trekoon sync conflicts <list|show> [--mode pending|all]`
-- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
-- `trekoon skills install -g|--global [--editor opencode|claude|pi]`
+- `trekoon skills install [--link --editor opencode|claude|codex|pi] [--to <path>] [--allow-outside-repo]`
+- `trekoon skills install -g|--global [--editor opencode|claude|codex|pi]`
 - `trekoon skills update`
 - `trekoon wipe --yes`
 - `trekoon serve` (experimental)
@@ -50,25 +50,31 @@ also accept `-h` and `-v`.
 
 ## Board commands
 
-`trekoon board open` installs board assets (if needed), starts a loopback-only
-server on `127.0.0.1` with a random port, opens the browser, and returns the
-board URL plus a manual fallback URL.
+`trekoon board open` starts a loopback-only server on `127.0.0.1` with a
+random port, opens the browser, and returns the board URL plus a manual
+fallback URL.
 
-`trekoon board update` refreshes board runtime assets without starting the
-server or opening a browser. Use this when you need to update copied assets
-before the next launch.
+Board code (HTML, JS, CSS, fonts) comes from the running Trekoon install —
+a global install serves the global package assets; a project-local install
+serves the project-local package assets. Board data comes from the repo where
+`trekoon board open` is invoked. Updating Trekoon updates the board bundle;
+no per-repo asset copy is needed.
 
 Security model:
 
 - Every `board open` session gets a unique token
-- Requests must include it as `Authorization: Bearer {token}`,
-  `x-trekoon-token` header, or `?token={token}` query parameter
+- Initial board HTML bootstrap accepts `?token={token}` once, sets an
+  HttpOnly `trekoon_board_session` cookie, and redirects to the same URL
+  without the token query parameter
+- Board API requests must authenticate with the session cookie,
+  `Authorization: Bearer {token}`, or `x-trekoon-token` header
+- API routes reject token query parameters
+- `/api/snapshot/stream` is authenticated by the session cookie
 - Invalid tokens return `401`
 - Static responses use `cache-control: no-store`
 
 The board is a self-hosted single-page app (vanilla JS, bundled CSS and fonts,
-no framework or CDN dependencies) served from `.trekoon/board`. Works fully
-offline once initialized.
+no framework or CDN dependencies). Works fully offline.
 
 Board API endpoints (all require token authentication):
 
@@ -84,27 +90,30 @@ Board API endpoints (all require token authentication):
 | `POST` | `/api/dependencies` | Add dependency edge (sourceId, dependsOnId) |
 | `DELETE` | `/api/dependencies?sourceId=...&dependsOnId=...` | Remove dependency |
 
-**Note:** the SSE auth token rides as a `?token=` query parameter on
-`/api/snapshot/stream` (EventSource cannot set custom headers), so it may
-appear in reverse-proxy access logs; treat access logs as sensitive if the
-board is exposed beyond localhost.
-
 Board mutations from any source — board UI, CLI in another shell, or another
 worktree — propagate to every connected client through the SSE stream. The CLI
 side is driven by a WAL-watcher that diffs the snapshot when
 `.trekoon/trekoon.db-wal` changes; in-process mutations publish deltas
-directly. PATCH endpoints accept `If-Match: <updatedAt-ms>` for optimistic
-concurrency: a stale value returns `409` with `currentUpdatedAt`. Missing
-`If-Match` is allowed for back-compat.
-
-Board commands don't accept command-specific options yet. For tests and local
-development, `TREKOON_BOARD_ASSET_ROOT` overrides the bundled asset source.
+directly. PATCH endpoints accept `If-Match: <version>` for optimistic
+concurrency; RFC 7232 strong or `W/`-prefixed weak ETag forms are accepted,
+but the `*` wildcard is not. A stale value returns `409` with
+`currentVersion` and `providedVersion`. Missing `If-Match` is allowed for
+back-compat.
+
+Repos that already have an ignored `.trekoon/board` directory keep those files
+on disk, but current Trekoon versions no longer read, create, refresh, or
+delete them. Remove that directory manually only if you want to clean up the
+old copied board bundle.
+
+`trekoon board open` accepts `--reveal-token` to include the raw tokenized URL,
+server token, and browser launch arguments in machine output. Other board
+subcommands and flags are rejected. `TREKOON_BOARD_ASSET_ROOT` overrides the
+asset source for tests and local development.
 
 ```bash
 trekoon init
 trekoon board open
 trekoon --json board open
-trekoon board update
 ```
 
 ## Human views

package/docs/machine-contracts.md

@@ -647,7 +647,7 @@ any `ok: false` response will be one of the following strings.
 | `orphaned_external_node` | Dependency graph contains a node that belongs to a different epic. |
 | `outside_repo_target` | Skill install target path is outside the repository root. |
 | `permission_denied` | File-system permission denied for the requested path. |
-| `precondition_failed` | `If-Match` precondition header did not match the entity's current `updatedAt`. |
+| `precondition_failed` | `If-Match` precondition header did not match the entity's current version. Error details include `currentVersion` and `providedVersion`. |
 | `row_not_found` | Sync resolve target row no longer exists in the database. |
 | `status_transition_invalid` | Requested status transition is not permitted by the status machine. |
 | `stream_unavailable` | SSE snapshot stream is not available (board not initialised or shutting down). |

package/docs/quickstart.md

@@ -50,9 +50,8 @@ trekoon --toon init
 trekoon --toon sync status
 ```
 
-Run `init` once per repository. It creates the shared storage root and installs
-the board runtime under `.trekoon/board`. If `sync status` reports
-`recoveryRequired` or a tracked/ignored mismatch, fix the setup before
+Run `init` once per repository. It creates the shared storage root. If `sync status`
+reports `recoveryRequired` or a tracked/ignored mismatch, fix the setup before
 continuing.
 
 ## Open the board
@@ -62,14 +61,15 @@ trekoon board open
 ```
 
 Starts a loopback-only server on `127.0.0.1`, opens the browser, and prints a
-fallback URL. The board is a self-hosted single-page app with no CDN
-dependencies, so it works offline once initialized. Use `trekoon board update`
-if you just need to refresh the runtime assets without opening the browser.
+fallback URL. Board code (HTML, JS, CSS, fonts) comes from the running Trekoon
+install; board data comes from the repo where the command is invoked. The board
+works fully offline. To get an updated board UI, update Trekoon itself. Old
+ignored `.trekoon/board` copies are left on disk but are no longer used.
 
 ## Create work
 
 ```bash
-trekoon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
+trekoon --toon epic create --title "Agent backlog stabilization" --description "Track stabilization work" --status todo
 trekoon task create --title "Implement sync status" --description "Add status reporting" --epic <epic-id> --status todo
 trekoon subtask create --task <task-id> --title "Add cursor model" --status todo
 ```
@@ -88,7 +88,7 @@ trekoon task list --all --view compact
 If you already know the full epic tree, create everything in one call:
 
 ```bash
-trekoon epic create \
+trekoon --toon epic create \
   --title "Batch command rollout" \
   --description "Ship one-shot planning workflows" \
   --task "task-a|First task|First description|todo" \
@@ -118,7 +118,7 @@ For larger updates, use batch commands instead of looping:
 | Multiple tasks under one epic | `trekoon task create-many --epic <epic-id> --task ...` |
 | Multiple subtasks under one task | `trekoon subtask create-many <task-id> --subtask ...` |
 | Multiple dependency edges | `trekoon dep add-many --dep ...` |
-| Expand an existing epic | `trekoon epic expand <epic-id> ...` |
+| Expand an existing epic | `trekoon --toon epic expand <epic-id> ...` |
 
 These validate the whole batch before applying, so a bad input fails the entire
 operation instead of leaving partial state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "AI-first task tracking that lives in your repo. You describe what to build, your agent plans it as a dependency graph, then executes it task by task",
   "keywords": [
     "ai",
@@ -40,7 +40,7 @@
   ],
   "scripts": {
     "run": "bun run ./src/index.ts",
-    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && cp ./package.json ./dist/package.json && rm -rf ./dist/assets && cp -R ./src/board/assets ./dist/assets",
     "test": "bun test ./tests",
     "lint": "bunx tsc --noEmit"
   },

package/src/board/asset-root.ts

@@ -0,0 +1,73 @@
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { BoardAssetError } from "./types";
+
+export const BOARD_BUNDLED_ASSET_DIRNAME = "assets";
+export const BOARD_ENTRY_FILENAME = "index.html";
+export const BOARD_ASSET_ROOT_ENV_VAR = "TREKOON_BOARD_ASSET_ROOT";
+
+export type BoardAssetRootSource = "override" | "environment" | "package";
+
+export interface BoardAssetRoot {
+  readonly assetRoot: string;
+  readonly entryFile: string;
+  readonly source: BoardAssetRootSource;
+}
+
+export interface ResolveBoardAssetRootOptions {
+  readonly assetRootOverride?: string;
+  readonly env?: NodeJS.ProcessEnv;
+}
+
+function resolvePackageBoardAssetRoot(): string {
+  return fileURLToPath(new URL(`./${BOARD_BUNDLED_ASSET_DIRNAME}`, import.meta.url));
+}
+
+interface SelectedAssetRoot {
+  readonly rootPath: string;
+  readonly source: BoardAssetRootSource;
+}
+
+function selectAssetRoot(options: ResolveBoardAssetRootOptions): SelectedAssetRoot {
+  if (options.assetRootOverride !== undefined) {
+    return { rootPath: resolve(options.assetRootOverride), source: "override" };
+  }
+
+  const env = options.env ?? process.env;
+  const envOverrideRaw = env[BOARD_ASSET_ROOT_ENV_VAR];
+  const envOverride = typeof envOverrideRaw === "string" ? envOverrideRaw.trim() : "";
+  if (envOverride.length > 0) {
+    return { rootPath: resolve(envOverride), source: "environment" };
+  }
+
+  return { rootPath: resolvePackageBoardAssetRoot(), source: "package" };
+}
+
+export function resolveBoardAssetRoot(options: ResolveBoardAssetRootOptions = {}): BoardAssetRoot {
+  const { rootPath, source } = selectAssetRoot(options);
+
+  if (!existsSync(rootPath) || !statSync(rootPath).isDirectory()) {
+    throw new BoardAssetError("missing_asset", `Board asset root not found at ${rootPath}`, {
+      assetRoot: rootPath,
+      source,
+    });
+  }
+
+  const entryFile = resolve(rootPath, BOARD_ENTRY_FILENAME);
+  if (!existsSync(entryFile)) {
+    throw new BoardAssetError("missing_asset", `Board entry file not found at ${entryFile}`, {
+      assetRoot: rootPath,
+      entryFile,
+      source,
+      missingFile: BOARD_ENTRY_FILENAME,
+    });
+  }
+
+  return {
+    assetRoot: rootPath,
+    entryFile,
+    source,
+  };
+}

package/src/board/assets/app.js

@@ -156,7 +156,7 @@ export async function bootLegacyBoard(options = {}) {
             </div>
             <span class="${sectionLabelClasses()}">Board ready</span>
             <h1 class="mt-2 text-3xl font-semibold tracking-tight text-[var(--board-text)]">No work has been published yet</h1>
-            <p class="mx-auto mt-3 max-w-2xl text-sm leading-6 text-[var(--board-text-muted)] sm:text-base">Once the board snapshot is installed into <code class="rounded-lg border border-[var(--board-border)] bg-white/[0.04] px-2 py-1 text-[var(--board-text)]">.trekoon/board</code>, epics and tasks will appear here.</p>
+            <p class="mx-auto mt-3 max-w-2xl text-sm leading-6 text-[var(--board-text-muted)] sm:text-base">Create or sync an epic in this repository and it will appear here.</p>
           </div>
         </section>
       `;
@@ -479,9 +479,11 @@ export async function bootLegacyBoard(options = {}) {
       rerender,
     });
     if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
-      window.addEventListener("beforeunload", () => {
+      const disposeSnapshotSubscription = () => {
         snapshotSubscription.dispose();
-      }, { once: true });
+      };
+      window.addEventListener("beforeunload", disposeSnapshotSubscription, { once: true });
+      window.addEventListener("pagehide", disposeSnapshotSubscription, { once: true });
     }
 
     // Actions for delegation