trekoon 0.2.7 → 0.2.9

package/README.md

@@ -48,6 +48,7 @@ These are the commands most people need to recognize quickly:
 | Goal | Commands |
 | --- | --- |
 | Initialize a repo | `trekoon init` |
+| Install/open/update the local board | `trekoon board open`, `trekoon board update` |
 | Learn the CLI | `trekoon help [command]`, `trekoon quickstart` |
 | Plan work | `trekoon epic ...`, `trekoon task ...`, `trekoon subtask ...`, `trekoon dep ...` |
 | Start an execution session | `trekoon session` |
@@ -65,6 +66,65 @@ Machine output modes:
 For the full command surface, flags, filters, and bulk update rules, read the
 [command reference](docs/commands.md).
 
+## Local board workflow
+
+Trekoon ships a no-extra-install local board for browsing and updating work in a
+browser.
+
+- `trekoon init` creates the shared `.trekoon` storage, database, and board
+  runtime under `.trekoon/board`
+- `trekoon board open` ensures those bundled board assets are installed, starts a
+  token-gated loopback server on `127.0.0.1`, and launches the browser
+- `trekoon board update` refreshes the board runtime assets only; it does not
+  start the server or open a browser
+
+Keep the operator path simple:
+
+```bash
+trekoon board open
+```
+
+Use `trekoon board update` only when you want to refresh the copied runtime
+assets without opening a session.
+
+The browser flow is local-only by design:
+
+- Trekoon copies the board shell and app files into repo-shared storage, so the
+  board still starts with one CLI command and no separate frontend build step
+- the board server binds only to `127.0.0.1`
+- every `board open` session uses a per-session token in the URL/API requests
+- command output always includes a manual fallback URL if the browser launch
+  fails
+
+Current runtime expectations:
+
+- the local runtime is served from `.trekoon/board`
+- the shell currently loads Vue from `unpkg.com`, Tailwind from
+  `cdn.tailwindcss.com`, and Google-hosted fonts/icons when the page renders
+- if your environment blocks those hosts, `trekoon board open` still starts the
+  local server, but the browser UI may render without the enhanced shell until
+  network access is restored
+
+Current board behavior to expect:
+
+- the topbar is a compact single-row navbar showing the workspace name, active
+  epic context, Epics and Board navigation, search, theme toggle, and a
+  workspace info popover
+- wide screens show the epic switcher sidebar, task workspace, and task
+  inspector together; narrower screens collapse these into stacked panels or
+  drawer-style views
+- the page scrolls naturally as a single SPA surface; modal overlays (task
+  detail, subtask editor) lock body scroll while open
+- overview cards are the primary entry point into an epic; clicking a card opens
+  that epic's board workspace
+- task cards show truncated descriptions; clicking anywhere on a card opens the
+  task detail modal with the full description
+- search is debounced and filters client-side across titles, descriptions,
+  statuses, and subtask content
+
+For the full lifecycle and examples, read [Quickstart](docs/quickstart.md) and
+[Command reference](docs/commands.md).
+
 ## AI skill
 
 Trekoon ships with a bundled `trekoon` skill for AI agents. It teaches the

package/docs/commands.md

@@ -6,6 +6,7 @@ surface, defaults, and flag rules.
 ## Command surface
 
 - `trekoon init`
+- `trekoon board <open|update>`
 - `trekoon help [command]`
 - `trekoon quickstart`
 - `trekoon epic <create|expand|list|show|search|replace|update|delete>`
@@ -40,6 +41,105 @@ trekoon quickstart --json
 Trekoon uses long-form options for command and subcommand flags. Root help and
 version aliases `-h` and `-v` are also supported.
 
+## Board lifecycle commands
+
+Board terminology in docs matches `trekoon help board`:
+
+- `trekoon board open`
+  - ensures board assets are installed in the repo-shared runtime directory
+  - starts a local board server on `127.0.0.1`
+  - launches the browser and returns the board URL, fallback URL, and launch
+    metadata in machine output
+- `trekoon board update`
+  - refreshes board runtime assets only
+  - does not start the server or open a browser
+
+Operator guidance:
+
+- use `trekoon board open` as the normal one-command startup path
+- use `trekoon board update` when you specifically need to refresh copied assets
+  before the next launch
+
+Board commands do not accept command-specific options yet. For tests and local
+development only, `TREKOON_BOARD_ASSET_ROOT` can override the bundled asset
+source used by `init`, `board open`, and `board update`.
+
+Runtime layout and security model:
+
+- `trekoon init` installs or refreshes the board runtime under `.trekoon/board`
+- `board open` serves those bundled files over a loopback-only server instead of
+  opening a raw file directly
+- the server binds to `127.0.0.1` on a random port
+- every session gets a per-session token; browser/API requests must present that
+  token
+- static responses use `cache-control: no-store`, and CLI output always includes
+  a manual fallback URL
+
+Current shell/runtime notes:
+
+- the runtime copied into `.trekoon/board` includes the HTML shell, local app
+  modules, and shared styles
+- the current shell also requests Vue from `unpkg.com`, Tailwind from
+  `cdn.tailwindcss.com`, and Google-hosted fonts/icons in the browser
+- if those remote dependencies are blocked, the local server still starts and
+  the fallback URL remains valid, but the browser UI may not fully load until
+  network access is restored
+
+Board UI architecture:
+
+- the board is a single-page application served from `.trekoon/board` with Vue 3
+  (shell) and vanilla JS (board app) loaded from CDN dependencies
+- the backend is a Bun HTTP server exposing a REST API at `/api/*` with
+  token-based authentication; every mutation response includes an updated
+  snapshot so the client always has fresh state
+- the frontend uses optimistic updates: the UI changes immediately on user
+  action, then rolls back if the server rejects the mutation
+
+Board layout behavior:
+
+- the topbar is a compact flex-row navbar with workspace identity, Epics and
+  Board navigation pills, a debounced search input, theme toggle, and a
+  workspace info popover
+- extra-wide layouts show the epic switcher sidebar, task workspace, and task
+  inspector or detail modal together
+- narrower layouts progressively collapse support surfaces into stacked panels
+  or drawer-style views
+- task cards show truncated descriptions; clicking anywhere on a card opens the
+  task detail modal
+
+Scroll and overlay behavior:
+
+- the page scrolls naturally as a single document; there are no internal scroll
+  containers trapping wheel events in the main content area
+- when a modal overlay opens (task detail, subtask editor), body scroll is
+  locked and the modal surface becomes the scroll container
+- close overlays from the top down: subtask modal → task detail → broader board
+  context; each close unlocks body scroll and returns to the previous context
+
+Board API endpoints (all require token authentication):
+
+- `GET /api/snapshot` — full board state (epics, tasks, subtasks, dependencies,
+  counts)
+- `PATCH /api/epics/{id}` — update epic title, description, or status
+- `PATCH /api/tasks/{id}` — update task title, description, or status
+- `PATCH /api/subtasks/{id}` — update subtask title, description, or status
+- `POST /api/subtasks` — create subtask (requires taskId, title)
+- `DELETE /api/subtasks/{id}` — delete subtask
+- `POST /api/dependencies` — add dependency edge (sourceId, dependsOnId)
+- `DELETE /api/dependencies?sourceId=...&dependsOnId=...` — remove dependency
+
+Token is sent as `Authorization: Bearer {token}` header or `x-trekoon-token`
+header or `?token={token}` query parameter. Invalid tokens return `401`.
+
+Examples:
+
+```bash
+trekoon init
+trekoon board open
+trekoon --json board open
+trekoon board update
+```
+
 ## Human views
 
 - List and show commands default to table output in human mode.

package/docs/quickstart.md

@@ -34,11 +34,84 @@ trekoon --toon sync status
 Bootstrap rules:
 
 - Run `trekoon --toon init` once per repository to create or re-bootstrap the
-  shared storage root.
+  shared storage root and install the bundled board runtime under
+  `.trekoon/board`.
 - Run `trekoon --toon sync status` before agent work to inspect diagnostics.
 - If diagnostics report `recoveryRequired`, a tracked or ignored mismatch, or an
   ambiguous recovery path, stop and repair setup before continuing.
 
+## Open the local board
+
+After `trekoon init`, you can browse and update the same repo-shared Trekoon
+state in the browser:
+
+```bash
+trekoon board open
+trekoon board update
+```
+
+For day-to-day use, treat `trekoon board open` as the one-command entry point.
+It both verifies the runtime files and launches the board. Reach for
+`trekoon board update` only when you need to refresh the copied runtime without
+opening the browser.
+
+What these commands do:
+
+- `trekoon board open` ensures bundled board assets are installed, starts a
+  loopback-only server on `127.0.0.1`, opens the browser, and prints a fallback
+  URL you can paste manually if launch fails
+- `trekoon board update` refreshes the runtime assets in `.trekoon/board`
+  without opening a browser or starting the server
+
+Why the board uses a local server instead of a bare HTML file:
+
+- the UI needs live reads and writes against Trekoon data, not a static export
+- the server binds only to `127.0.0.1`
+- each `board open` call generates a per-session token used by the browser/API
+- bundled assets are copied from the CLI package into `.trekoon/board`, so the
+  board works without a separate frontend install or local build step
+
+Current runtime expectations for operators:
+
+- the served HTML, styles, and board app files come from the local
+  `.trekoon/board` runtime directory
+- the current shell also pulls Vue from `unpkg.com`, Tailwind from
+  `cdn.tailwindcss.com`, and Google-hosted fonts/icons at page load time
+- if those hosts are unavailable, the command still starts the loopback server
+  and prints the fallback URL, but the shell may not fully hydrate in the
+  browser until network access is available again
+
+Current layout behavior:
+
+- the topbar is a compact navbar with workspace identity, Epics and Board
+  navigation, debounced search, theme toggle, and workspace info
+- on wide displays, expect a three-surface workspace: epic switcher sidebar,
+  task workspace, and task inspector
+- on medium and small displays, secondary surfaces collapse into stacked panels
+  or drawer-style views so the board remains navigable on narrower widths
+- the page scrolls naturally as one document; modal overlays lock body scroll
+  while open
+- task cards show truncated descriptions; clicking a card opens the task detail
+  modal with the full description and edit controls
+- search filters client-side across titles, descriptions, statuses, and subtask
+  content with a 180ms debounce
+
+Verification checklist for operators:
+
+1. Open the board with `trekoon board open` and confirm the first view is the
+   epic overview with all epics listed and scrollable.
+2. Click an epic card and confirm you enter the board workspace with the topbar
+   showing the active epic context.
+3. Type in search and verify results filter as you type; confirm focus stays in
+   the search input while typing.
+4. Click a task card and confirm the task detail modal opens with the full
+   description, edit form, and subtask list.
+5. On desktop width, confirm the epic switcher sidebar, workspace, and detail
+   panel can all be visible simultaneously.
+6. Resize to a narrow viewport and confirm the layout stacks cleanly without
+   horizontal overflow.
+7. Close modals and confirm you return to the previous board context.
+
 ## Create an epic, task, and subtask
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",
@@ -11,6 +11,7 @@
     "bin",
     "docs",
     "src",
+    "src/board/assets",
     ".agents/skills/trekoon/SKILL.md",
     "README.md",
     "LICENSE"