@shivaedev/work-board 0.12.0 → 0.14.0

package/README.md

@@ -26,6 +26,10 @@ A **workspace** is a folder of Markdown files. Those files are authoritative: pl
 
 During normal watching, each settled batch re-reads changed Markdown paths and retains unchanged parsed documents and search entries. Adds, deletes and renames update the same index. Watcher recovery checks source bytes and reuses unchanged parses. The synthetic 2,000-item benchmark runs with `node --conditions=source packages/work-board/src/test-support/indexBenchmark.ts` from the repository root; it records index time, files read and files parsed for cold start, edit, add, delete and rename.
 
+Identified documents open with a sticky title, kind icon, recorded status, owner and next action. Favorite and handoff controls sit in the header. Known Fleet items also show their stage and PR. An open rail shows criteria, relationships with target titles and statuses, and backlinks grouped by kind; membership and Markdown links keep their own groups. At 1024px the rail sits beside the 68ch Markdown column; on smaller screens it follows the introduction. The Source tab holds the file location, original frontmatter and recorded handoff, question, response and request-receipt details. Passage links into Source reveal the tab before scrolling and focusing the record.
+
+Open requests place an answer card directly below their source header and the headers of the items they unblock. The card renders the reason as Markdown, offers the recorded options with the recommendation marked, and retains response drafts through live reads. Record saves the answer against the request’s reviewed source. More holds the author label, optional Markdown preview, draft tools and response details; the default author is maintainer when no saved label exists. Managed decisions use the title of the work they unblock; generated identities remain in Source. Legacy response URLs redirect to the item and focus its card.
+
 A file can declare an optional **item ID**. That ID connects it to other files, criteria and boards without tying the connection to its filename. A **criterion** is an explicitly named requirement; an **evidence record** is an author's claim about an observation. The board displays that claim and its provenance; it does not run the check or establish acceptance.
 
 An **attention request** explicitly asks for a decision, review or help with a blocker. It is separate from an item's status. A **question** asks for a person's answer. It can be authored as a standalone item or captured from an attention request with its exact source text, source path and reviewed SHA-256. A **response** is an independent Markdown record of a person's answer, clarification or deferral. Responses retain their reviewed context; they do not close requests, change task status or start an agent. An optional execution integration can acknowledge a managed decision through a separate immutable request receipt. That receipt is distinct from a handoff receipt, execution or acceptance.
@@ -34,7 +38,7 @@ A **handoff** captures direction and the exact source the person reviewed in ano
 
 A **result** is an author's report linked explicitly to work and criteria. Its recorded status does not change the linked task's status. A result review presents the report, its claims and limitations with human feedback pinned to the reviewed source bytes and path. Choosing an authored acceptance option does not supply missing criterion evidence.
 
-Browser preferences, drafts and the explicit **seen baseline** are personal state, scoped to the workspace and server origin. They do not change project meaning. Agents own normal project-file edits. Work Board owns the human response content it records. An agent's run completion, a recorded answer and an accepted result remain separate facts.
+Browser preferences and drafts are personal state, scoped to the workspace and server origin. They do not change project meaning. Agents own normal project-file edits. Work Board owns the human response content it records. An agent's run completion, a recorded answer and an accepted result remain separate facts.
 
 The work has three parts: choose a workspace once, author useful files per feature, and read or respond as the work changes.
 
@@ -44,11 +48,11 @@ The work has three parts: choose a workspace once, author useful files per featu
 work-board ./project-notes --home plan.md
 ```
 
-This serves the existing folder on `http://127.0.0.1:4747`. The optional home file is resolved from that folder and rendered as a heading board at `/`; other files are documents. Without a home, `/` shows the first listed document. An empty workspace opens getting-started guidance. **Getting started** remains available at `/_board/start`, with copyable project, investigation and agent-result templates. Save them through your editor or agent tool; the reader does not create files.
+This serves the existing folder on `http://127.0.0.1:4747`. The first screen at `/` is **Today**: a linked summary, **Needs you**, **In progress** and **Goals**. Human asks come from the shared attention projection. Needs-you entries stay within 48px. For questions with one-choice options, Answer opens a popover with buttons that record an answer against the current reviewed context. In progress shows up to eight items Fleet holds in executing, reviewing, repairing or adopting, with their stage and recorded PR link; **All in Now →** opens the full work view. Its summary counts all held items, including those beyond the preview. An unavailable Fleet source shows an unknown count. Goal cards show the next action clamped to two lines and done, in-progress and planned work with an **N of M done** count; criteria and their evidence counts sit behind a closed **Criteria** disclosure. These counts describe recorded source, not verified success. The optional home file remains a heading board through **Workspace notes**; other files remain documents. An empty Today links to getting-started guidance. **Getting started** remains available at `/_board/start`, with copyable project, investigation and agent-result templates. Save them through your editor or agent tool; the reader does not create files.
 
 A heading board uses `#` for its title, text before the first `##` for its intro, `##` for sections and `###` for cards. A section without cards shows its text. A `---` after the last heading starts the footer; a divider inside a card before another heading stays in that card. Code spans, reference links, footnotes and `<details>` can stay in the Markdown body. Leave a blank line after `<summary>` and before `</details>` when its content is Markdown.
 
-The sidebar starts with fixed Home, Inbox, Overview, Work, Changes and Diagnostics rows. Project files scroll independently, and opening a document reveals its highlighted file. Below 768px, Files in the top bar opens an overlay drawer; Escape or a tap outside closes it and returns focus to Files. The sidebar groups Markdown into nested folders and keeps the home file first. Folder expansion choices survive live file changes; opening a document expands its ancestors. Empty folders without indexed Markdown stay out of the tree. File links keep their logical workspace paths, including reference-directory aliases.
+The sidebar shows Today, Goals, Now, Library and System, with counts only on Today and Now, followed by pinned documents, active goals with linked-work status bars and quiet done/total figures, and at most five recent documents. Today counts waiting human actions and Now counts open tasks. Each active-goal bar names its done count for assistive technology and shows the same count on hover. Below 768px, Files in the top bar opens an overlay drawer; Escape or a tap outside closes it and returns focus to Files. Library lists document titles with kind and status filters, a folder view that loads immediate children on expansion, and a Recently changed view sorted by file modification time. Links preserve logical workspace paths, including reference-directory aliases.
 
 Directory links can include reference Markdown without copying it:
 
@@ -103,7 +107,7 @@ items: [work.search]
 Inspect the selected work and its source before giving direction.
 ```
 
-Open **Work** to switch between boards and tables. The same item may belong to several boards; a board definition is excluded from All work. Columns use exact recorded status, with missing status disclosed separately. Filters use status, owner and work text; sorting uses title, owner or status, with missing values last. The URL carries board, filters, layout, sort and selected item. Board and table share the projection and source detail; native links and GET filters work without JavaScript. Missing, repeated and ambiguous members are disclosed.
+Open **Work** on Now, or choose All work and Table. The same item may belong to several boards; a board definition is excluded from All work. All work columns use exact recorded status; missing status stays blank. Filters use status, owner and work text; sorting uses title, owner or status, with missing values last. The URL carries board, filters, layout, sort and selected item. Board and table render the same projection and source detail in React. Missing, repeated and ambiguous members are disclosed.
 
 Use `relationships` for `implements`, `informs`, `depends_on` or `relates_to` links to an item or `item#criterion`. A result can record evidence against the criterion. Save this as `result.md`:
 
@@ -127,17 +131,17 @@ The recorded check is a source claim. Review its evidence before accepting it.
 
 Record an outcome only after an actual observation, and save its supporting `evidence.md`; omit evidence until that check exists.
 
-`source` is required for an evidence record; `criterion`, `checked_revision`, `observed_at`, `method` and `outcome` are optional. This example has no checked revision or observation time, so both stay **Not recorded**. When known, record a full 40- or 64-digit hexadecimal revision and an ISO timestamp with a timezone. Source paths resolve from the file holding the claim.
+`source` is required for an evidence record; `criterion`, `checked_revision`, `observed_at`, `method` and `outcome` are optional. This example has no checked revision or observation time, so both stay blank. When known, record a full 40- or 64-digit hexadecimal revision and an ISO timestamp with a timezone. Source paths resolve from the file holding the claim.
 
-Criteria collect explicitly linked claims across files. **Referenced by** also shows incoming relationships, board membership, evidence sources and ordinary Markdown links. Decisions keep their options and rationale in body Markdown. Old recorded revisions remain visible; the viewer does not compare them with current Git state or infer human acceptance. See the [source field reference](docs/delivery/source-examples.md) and [attention field reference](docs/delivery/attention-examples.md) for complete shapes.
+Criteria collect explicitly linked claims across files. **Referenced by** also shows incoming relationships, board membership, evidence sources and ordinary Markdown links. Each source appears under its most specific kind. Repeated source titles collapse into a count that expands to the individual links. Decisions keep their options and rationale in body Markdown. Old recorded revisions remain visible; the viewer does not compare them with current Git state or infer human acceptance. See the [source field reference](docs/delivery/source-examples.md) and [attention field reference](docs/delivery/attention-examples.md) for complete shapes.
 
 #### Richer reading in ordinary documents
 
-Tables, task lists, footnotes, raw-HTML details and highlighted fenced code render on the server. Heading passage links and an **On this page** outline distinguish duplicate headings. Relative document links resolve from their source file, including a nested home served at `/`.
+`DocumentView` renders tables, task lists, footnotes, raw-HTML details and highlighted fenced code in the browser from typed document-query data. The server delivers the React shell rather than document HTML. Heading passage links and an **On this page** outline distinguish duplicate headings. Relative document links resolve from their source file, including a nested home served at `/`.
 
-Document content starts with its title and, for frontmatter documents, source status and next action. Missing authored values say **Not recorded**. **Context and tools** follows the introduction in document order and contains source provenance, backlinks, the outline and the favorite control. DOM fixtures check this order, the disclosure's desktop/narrow media-query defaults, and a CSS upper bound on title placement using the viewport height and capped page controls. They also check the question form's text-column width and margins and the desktop grid's row allocation. These checks do not measure browser layout or establish physical-device behavior.
+Document content starts with its title and, for frontmatter documents, source status and next action. Missing authored values render nothing. **Context and tools** follows the introduction in document order and contains source provenance, backlinks, the outline and the favorite control. DOM fixtures check this order, the disclosure's desktop/narrow media-query defaults, and a CSS upper bound on title placement using the viewport height and capped page controls. They also check the question form's text-column width and margins and the desktop grid's row allocation. These checks do not measure browser layout or establish physical-device behavior.
 
-`mermaid` fences draw locally in the browser. Diagrams follow the theme and keep unchanged drawings during refresh. A parse failure exposes its source and error; without JavaScript the source remains readable.
+`mermaid` fences draw locally in the browser. Diagrams follow the theme and keep unchanged drawings during refresh. A parse failure exposes its source and error in the React document view.
 
 Metrics and progress use fixed directives with a label and a source:
 
@@ -153,29 +157,31 @@ The component shows the authored tally. Unknown or zero-total counts do not fabr
 
 Use ordinary image Markdown for source-relative PNG, JPEG, GIF or WebP files. The image route serves at most 16 MiB per file inside the real workspace; images in outside reference folders must be copied inside that boundary. The image gallery and **Inspect diagram** provide zoom and keyboard dismissal. Local image downloads and SVG downloads of a rendered diagram use the browser. A source update marks an already-open preview as older and requires reopening before saving. These actions do not write source or establish acceptance.
 
-### 3. Every day: read, compare and give direction
+### 3. Every day: read and give direction
 
-**Search** or Ctrl/Cmd+K finds document titles/paths, headings, passages and recorded work fields. Matching uses the first 200 query characters and up to eight terms; each of those terms must occur in a block, ignoring case. Titles rank before headings, then passages. At most 40 results are shown with the full match count. Arrow keys choose, Enter opens, and Escape closes. Incomplete reads are disclosed, and older requests cannot replace a newer query. Search requires JavaScript.
+**Search** or Ctrl/Cmd+K opens the command palette. Go-to commands open Today, Goals, Now, Library, System and each open goal from the goals query. Appearance commands toggle the file sidebar, density and theme. Results update as you type; matching commands come first. Search finds document titles/paths, IDs, headings, passages and recorded work fields. Matching uses the first 200 query characters and up to eight terms; each term must occur in a block, ignoring case. Item results rank before headings and passages. Within items, open work ranks before closed and deferred work, title and ID matches rank before body matches, then the most recently changed sources come first. Body matches also return the item itself. Each anchor appears once, retaining its best match before the result limit and count. Item results show their ID, kind and authored status; rows without a recorded status omit the chip. Fleet decisions, captured questions, responses, application receipts, `fleet/status.md` and `responses/fleet-report.*` appear only when the query starts with `records:`. Snippets omit structured metadata. At most 40 source results are shown with the full match count. Arrow keys choose, Enter opens, and Escape closes. Incomplete reads are disclosed, and older requests cannot replace a newer query. Search requires JavaScript. `src/server/search/palette.spec.ts`, `src/server/search/ranking.spec.ts`, `src/client/react/palette.dom.spec.tsx` and `src/client/react/searchRanking.dom.spec.tsx` and `src/client/react/fleetSearch.dom.spec.tsx` cover record filtering, ranking, snippets and commands with fixtures.
 
-Back restores selected text and expanded details. Recent documents opens a bounded reading-history dialog with favorites and up to ten unique recents. Favorites and recents belong to the workspace/origin; deleted favorites remain labeled missing. Save up to ten named Work views with the applied board, filters, sort and layout. Selection stays in the URL, and saving the same name updates it. At capacity, remove or update a view; none is silently evicted. Unavailable storage is disclosed, with controls usable for the current page.
+Back restores selected text and expanded details. Reading history opens a bounded dialog with favorites and up to ten unique recents. Favorites and recents belong to the workspace/origin; deleted favorites remain labeled missing. Save up to ten named Work views with the applied board, filters, sort and layout. Selection stays in the URL, and saving the same name updates it. At capacity, remove or update a view; none is silently evicted. Unavailable storage is disclosed, with controls usable for the current page.
 
-**Overview** groups explicit open decision, review and blocker requests. Status, owner, file edits and finished runs do not imply a request. Each entry links its reason, recipients, targets and source context. Closed requests remain readable without asserting a recorded answer or acceptance. Invalid or ambiguous requests stay outside the queue with diagnostics; incomplete indexes withhold counts.
+**Work** opens on **Now**: fixed Queued, Executing, Reviewing, Delivering, Waiting on a person, and collapsed Done in the last 7 days lanes. Fleet stages set the lane even when the source still says `planned`; reviewing, repairing and validating share Reviewing. Lanes hold tasks only. Every available Fleet stage takes precedence over authored status, including prepared and human-waiting work whose source is inactive. Without a matching Fleet item, authored superseded, deferred, cancelled, done and completed items stay outside Now. Done includes only recent Fleet completions. Queued holds prepared tasks or approved tasks waiting to start, never unapproved planned work. Cards show one Fleet-derived StatusChip and show the holder, PR link and time in stage only when known. When Fleet is unavailable, lanes use authored status and disclose the fallback. Saved views and filters sit behind **Filter**, collapsed by default on Now. Completed work with no known completion time is available through **All work**. All work keeps status columns in a fixed order; **Table** uses the chosen row sort. Decisions, questions, responses, results and request receipts remain readable in their source views and stay outside these work lists. Lists over 200 rows render a moving window inside bounded scrolling lanes or a table. `src/client/react/WorkNow.dom.test.tsx`, `workRecords.dom.spec.tsx` and `workScale.dom.spec.tsx` cover these projections and the rendered row bound with a 1,500-item fixture.
 
-**Diagnostics** in the sidebar reads Codex usage windows labelled by duration, GitHub REST and GraphQL rate limits, and Fleet health through the Fleet daemon's `daemon.diagnostics` HTTP RPC query at `127.0.0.1:3457`. Set `--fleet-port <port>` or `BoardOptions.fleetPort` to select another daemon port. A stopped daemon leaves Diagnostics available with an explicit unavailable state and a start command; the next refresh retries. Board does not start provider commands or read Fleet's database or health file. The daemon reads Codex and GitHub with its existing CLI authentication, caches rate-limit observations for one minute across Board clients and reports each source's missing configuration or error independently.
+**System** in the sidebar reads Codex usage windows labelled by duration, GitHub REST and GraphQL rate limits, and Fleet health through the Fleet daemon's `daemon.diagnostics` HTTP RPC query at `127.0.0.1:3457`. Set `--fleet-port <port>` or `BoardOptions.fleetPort` to select another daemon port. A stopped daemon leaves System available with an explicit unavailable state and a start command; the next refresh retries. Board does not start provider commands or read Fleet's database or health file. The daemon reads Codex and GitHub with its existing CLI authentication, caches rate-limit observations for one minute across Board clients and reports each source's missing configuration or error independently.
 
-The view refreshes through the native page query every 15 seconds while visible. Pause updates holds the displayed state; resume and returning to a visible tab refresh it. The shared `DiagnosticsContract` and `DiagnosticsSnapshot` schemas live in `@shivaedev/work-board/diagnostics/daemonContract.ts`; the version 2 `FleetHealth` schema lives in `@shivaedev/work-board/diagnostics/health.ts`. The page shows the publisher's observation time, freshness, running and queued counts and waiting counts for maintainer, orchestrator and automation, concurrency cap, last scheduler pass and last observed provider capacity rejection. Stale snapshots show a Stale badge and dimmed counts. Reset times show relative time and the browser’s local clock; without JavaScript they use the server’s local clock. Communication failures and API-key accounts explain why their data is unavailable. A publisher clock ahead of Board is disclosed; absent scheduler/rejection observations remain unknown or unobserved.
+The view refreshes through `client.api.diagnostics.query()` every 15 seconds while visible. Pause updates holds the displayed state; resume and returning to a visible tab refresh it. The shared `DiagnosticsContract` and `DiagnosticsSnapshot` schemas live in `@shivaedev/work-board/diagnostics/daemonContract.ts`; the version 2 `FleetHealth` schema lives in `@shivaedev/work-board/diagnostics/health.ts`. The Fleet lane lists every running or waiting item from `client.api.fleetItems.query()` by source title, stage and recorded PR, with explicit loading, unavailable and empty states. Items without readable source retain their work ID; missing PRs remain explicit. The page also shows the publisher's observation time, freshness, running and queued counts and waiting counts for maintainer, orchestrator and automation, concurrency cap, last scheduler pass and last observed provider capacity rejection. Stale snapshots show a Stale badge. Reset times show relative time and the browser’s local clock; System requires JavaScript. Communication failures and API-key accounts explain why their data is unavailable. A publisher clock ahead of Board is disclosed; absent scheduler/rejection observations remain unknown or unobserved.
 
-**Changes** starts remembering only through **Start remembering changes**. After review, **Mark current workspace seen** replaces the baseline; **Clear remembered history** turns it off. Opening a view and receiving live updates never mark it seen. Compare additions, removals, fields and source text against that one browser-local baseline. Unique IDs match moved items; plain-file renames are removed/added paths. The baseline is bounded to 2 MiB and 30 days, with expiry, corruption, incomplete reads and oversized workspaces disclosed. It holds Markdown, not image bytes.
+`client.api.fleetItems.run(undefined)` reads per-item execution through the same daemon client. A `ready` result has `items` for every stage except `completed` and `released`, and `completed` for current records completed within the last seven days, including the boundary. Each item carries `workId`, `stage`, a waiting `attentionOwner` when present, `prUrl` when known, and millisecond `stageEnteredAt` and `updatedAt`; completions also carry `completedAt`. Board joins each unique matching ID to `document: { file, title, metadata }`; missing or duplicate IDs keep the Fleet item with `document: null`. For legacy records, stage entry and completion times remain unknown until an observed stage transition; `updatedAt` becomes known on the next write. A stopped daemon, communication failure or Board index failure returns `{ state: "unavailable", reason }`. Set `BoardOptions.fleetPort: null` to disable the item integration. `src/server/views/fleetItems.test.ts` covers these reads through HTTP RPC with a synthetic daemon.
 
 **Pause updates** holds the displayed reading state while counting observed hints, bounded at **256+**. Resume and reconnect reconcile the workspace. Unrelated source edits retain mounted document reads; relevant updates retain unchanged reading blocks. A failed read keeps visible source and says **refresh failed**. Connection or watcher loss says **reconnecting**. These are reconciliation hints, not a durable event journal or a count of completed work.
 
 #### Find what waits on you
 
-The sidebar and top bar offer **Inbox** with a live count, including on narrow screens. It lists open human-owned next actions, unaddressed standalone questions, and work whose status is `needs-human`. Addressed questions, including registered questions on ordinary attention sources and Fleet's open managed decisions, enter the Inbox only when their attention request's `response_from` includes the maintainer label. The default label is `maintainer`; set `--maintainer <name>` to use another literal, case-sensitive label. Questions for other responders remain reachable through their item, Responses and the Work board/table. Boards without addressed questions keep the same Inbox membership. Managed decisions leave the Inbox when their exact-context acknowledgement retires them. Question and managed-request rows open the response form directly; other rows link to the source. Each row shows the reason and time since the source last changed. Overview links to an Inbox count summary. The Work board/table mark the same items as **Waiting on you** while keeping every card in its recorded status column. Missing or duplicated item IDs remain listed with a visible problem and a link to each source. Ages of 48 hours or more use days.
+**Today** and its navigation badges count human asks from the shared attention projection. They include human-owned next actions, unaddressed standalone questions, `needs-human` work, and validated open attention requests addressed to the maintainer label. Set `--maintainer <name>` to select another literal, case-sensitive label. The default is `maintainer`. Questions open an answer card; other rows open their source. Each row shows its reason and age. Missing or duplicated identities stay visible with a problem and source link. Incomplete indexes withhold membership and counts.
+
+A recorded answer to a uniquely registered ordinary request retires that ask only for the reviewed source bytes and path. Managed decisions retire after an exact-context acknowledgement or when all their targets are closed or deferred. Active asks for the same target set share one row, using the newest reason and response link. Agent-only asks remain available through the typed attention projection. Source diagnostics never create human asks. Work cards show Fleet state, or **needs-you** for an authored ask when Fleet has no item state. These projections do not edit source status.
 
-Owner labels are local conventions: `codex`, `claude`, `fleet`, `agent`, `automation`, `bot` and `copilot`, including labels beginning with those names followed by a dash, underscore, dot, space or slash, denote automation. Other nonblank owner labels denote people. A human owner needs a nonblank `next_action` to enter the Inbox. Statuses `closed`, `done`, `completed`, `cancelled`, `canceled`, `resolved` and `released` leave the queue. These rules classify waiting work; they do not edit the recorded status.
+Owner labels are local conventions: `codex`, `claude`, `fleet`, `orchestrator`, `agent`, `automation`, `bot` and `copilot`, including labels beginning with those names followed by a dash, underscore, dot, space or slash, denote automation. Other nonblank owner labels denote people. A human owner needs a nonblank `next_action` to enter Today. Statuses `closed`, `done`, `superseded`, `completed`, `cancelled`, `canceled`, `resolved` and `released` leave the queue. These rules classify waiting work; they do not edit the recorded status.
 
-Fleet decision sources, captured questions and their answers are grouped under a collapsed **Fleet records** section in the sidebar. Ordinary human questions and answers remain in their source folders. Opening a grouped source reveals its group; the underlying files remain readable and searchable.
+Fleet decision sources, captured questions, their answers and request receipts are hidden by default in Library. **Show Fleet records (N)** includes them in the current view. Ordinary authored questions remain visible, and all underlying files remain readable and searchable with the `records:` query prefix.
 
 An agent can ask a standalone question with frontmatter:
 
@@ -198,7 +204,7 @@ Choose where the project keeps its readable source.
 
 `options` is optional and accepts up to 32 entries with unique nonblank labels and descriptions. `recommended` names an option label. The item page presents buttons, marks the recommendation without selecting it, and accepts another answer as free text. Omit `options` for a text-only question. Use frontmatter options or a Markdown question packet on a question, rather than both.
 
-Start with `--responses` to enable saving. Preview and record the answer on the item page with a local author label. The browser remembers that label for the workspace. The required author label stays visible; response kind and superseding controls sit in a collapsed details section; option questions show a choice and one answer box by default. Closed questions and invalid options keep recorded answers readable, with a clear message when another answer is unavailable. The existing publisher captures the reviewed source as a `kind: question` record in `responses/`, then writes a `kind: response` that links to that capture. Its `question.item` links back to the authored question. An `answer` removes the authored question from the Inbox for those exact source bytes and path; clarification and deferral keep it waiting. An edited question needs another answer. The original source file stays unchanged, and the answer does not establish acceptance or start an agent.
+Start with `--responses` to enable saving. Preview and record the answer on the item page with a local author label. The browser remembers that label for the workspace. The required author label stays visible; response kind and superseding controls sit in a collapsed details section; option questions show a choice and one answer box by default. Closed questions and invalid options keep recorded answers readable, with a clear message when another answer is unavailable. The existing publisher captures the reviewed source as a `kind: question` record in `responses/`, then writes a `kind: response` that links to that capture. Its `question.item` links back to the authored question. An `answer` removes the authored question from Today for those exact source bytes and path; clarification and deferral keep it waiting. An edited question needs another answer. The original source file stays unchanged, and the answer does not establish acceptance or start an agent.
 
 #### Record a human response
 
@@ -206,13 +212,13 @@ Start with `--responses` to enable saving. Preview and record the answer on the
 work-board ./project-notes --responses
 ```
 
-Explicit opt-in enables writes. Open question packets offer **Answer these questions** once per packet, leading to the response form. Static options are reading text. For other requests, open the request in **Work details and source**, choose **Respond to this request**, inspect the exact source and reviewed SHA-256, enter a local author label, then preview and record the Markdown. **Answer** may say no; **Ask back / clarify** and **Not now** are separate reply kinds. Author labels provide local attribution, not authentication.
+Explicit opt-in enables writes. Open the item’s answer card, read the request reason, and inspect the original source in **Source**. Enter a local author label, choose an option or write an answer, then preview and record the Markdown. Questions and decisions can declare frontmatter options and a recommendation; the recommendation is marked but never selected for you. Requests with Markdown question directives keep their prompts and controls together in the card. **Answer** may say no; **Ask back / clarify** and **Not now** are separate reply kinds. Author labels provide local attribution, not authentication.
 
 Registration captures one question generation in `responses/`; submission creates an independent response file there. Original source bytes stay unchanged. Source edits or moves require a fresh review/preview; historical replies still identify the old context. Same-identity/content retries reconcile, conflicting contributions are rejected, and uncertain publication is reported explicitly.
 
-An execution integration may mark a generated `kind: decision` request with `attention[].managed: true`. A separate immutable `kind: result` document records `request_receipt` with the registered question ID, its `reviewedRevision`, `recordedAt` and disposition `applied` or `superseded`. An applied receipt names the unique current `answer`; clarification and deferral cannot acknowledge it. Supersession retires the request without inventing an answer. Only an unambiguous receipt matching the exact current source path and bytes removes the managed request from the overview and response surface. `currentResponses(responses)` from `@shivaedev/work-board/responses/current.ts` selects the latest response per author, ordered by recorded time and then response ID, and removes explicitly superseded responses. Managed acknowledgements use this selection; different authors remain competing, and superseding an author’s latest response does not revive an earlier answer. `src/responses/current.test.ts` and Fleet’s PostgreSQL question tests cover this rule. The source remains unchanged and readable. Ordinary authored requests remain source-driven; receipts grant no execution, acceptance or delivery authority.
+An execution integration may mark a generated `kind: decision` request with `attention[].managed: true`. A separate immutable `kind: result` document records `request_receipt` with the registered question ID, its `reviewedRevision`, `recordedAt` and disposition `applied` or `superseded`. An applied receipt names the unique current `answer`; clarification and deferral cannot acknowledge it. Supersession retires the request without inventing an answer. Only an unambiguous receipt matching the exact current source path and bytes removes the managed request from Today and the item's answer cards. `currentResponses(responses)` from `@shivaedev/work-board/responses/current.ts` selects the latest response per author, ordered by recorded time and then response ID, and removes explicitly superseded responses. Managed acknowledgements use this selection; different authors remain competing, and superseding an author’s latest response does not revive an earlier answer. `src/responses/current.test.ts` and Fleet’s PostgreSQL question tests cover this rule. The source remains unchanged and readable. Ordinary authored requests remain source-driven; receipts grant no execution, acceptance or delivery authority.
 
-Browser drafts have their own 2 MiB workspace bound and expire 30 days after their last edit. Navigation, reload and source refresh retain them; text edited while an earlier save completes remains an unsaved draft with a fresh identity. Corruption, expiry and storage failures are disclosed. Clearing drafts does not clear saved records or the seen baseline.
+Browser drafts use effect-form’s persisted drafts, keyed by workspace, item and request, with a 256 KiB limit per draft and a seven-day lifetime after the last edit. Navigation, reload and source refresh retain them; text edited while an earlier save completes remains an unsaved draft with a fresh identity. Malformed or expired drafts are discarded; unavailable storage leaves the form usable. **Clear draft** restores the current form’s initial values without changing saved records or saved responses.
 
 #### Wait for an attributable reply
 
@@ -268,15 +274,15 @@ Open a uniquely identified project item and choose **Prepare an agent handoff**.
 
 The agent edits `handoff.state` to `acknowledged`, `rejected` or `unavailable` and can add `handoff.by` and `handoff.note`. These are explicit local receipt facts, independent of task status, execution and human acceptance. An absent receipt stays unconfirmed; damaged or ambiguous history stays unavailable.
 
-Same-ID retries preserve receipt and extra metadata, including after source deletion. Restarted servers read the recorded receipt. Different direction and moved or duplicate identities are conflicts; a changed source before initial preparation requires another review. Saved context remains inspectable when its source disappears. Native navigation and Back retain owned draft text; source changes require a fresh preview. Drafts share the existing workspace store and its 30-day/2-MiB bounds. Clearing that store clears response and handoff drafts together.
+Same-ID retries preserve receipt and extra metadata, including after source deletion. Restarted servers read the recorded receipt. Different direction and moved or duplicate identities are conflicts; a changed source before initial preparation requires another review. Saved context remains inspectable when its source disappears. Native navigation and Back retain owned draft text; source changes require a fresh preview. Handoff drafts use effect-form with a separate key per workspace and item, under the same seven-day/256-KiB limits. **Clear draft** clears only the current form.
 
-The static handoff, response and question forms use `@shivaedev/effect-form` for Schema decoding, field messages and captured submissions. Board owns preview, reviewed-context checks and durable draft storage. Input typed during a response save remains available under a fresh draft identity; each form releases its registry on navigation or pagehide and rebinds on pageshow.
+Response and handoff forms are React components on `effect-react`’s `useCreate` and `effect-form`’s Schema decoding, field messages and persisted drafts. Board owns preview and reviewed-context checks. Draft text, source-change notices and caret selection survive query refresh and reload. Input typed during a response or handoff save remains an unsaved draft; a fresh preview assigns its next identity. The forms use the shell’s shared native registry.
 
 The [handoff source reference](docs/delivery/handoff-examples.md) shows a complete record, ordinary receipt edits and the boundary with optional execution integrations.
 
 #### Review the returned result
 
-A file with `kind: result` and a unique ID offers **Review returned result** at `/_board/result?item=<id>`. The page separates the report's authored status from linked work status, lists its criterion-level claims and missing provenance, and keeps the report, limitations and human feedback together. Reading through normal GET or the native page query leaves project files unchanged.
+A file with `kind: result` and a unique ID offers **Review returned result** at `/_board/result?item=<id>`. The page separates the report's authored status from linked work status, lists its criterion-level claims and missing provenance, and keeps the report, limitations and human feedback together. Reading through normal GET or the typed query leaves project files unchanged.
 
 The agent declares an explicit open `attention` request of kind `review` on the report. That request links into the existing response surface. A Markdown question packet can offer request revision or accept this exact report, with room for human rationale. These options are authored text, rather than reserved acceptance states. Preview and submit the response against the exact source you reviewed.
 
@@ -291,20 +297,21 @@ Import the module that defines a name. The package has no root entry; its manife
 | Module | Names and purpose |
 | --- | --- |
 | `board.ts` | `BoardOptions`, `boardLayer(options)`: Effect HTTP router Layer for the workspace |
-| `serve.ts` | `ServeOptions`, `HOST`, `listenOn(port)`, `serveBoard(options)`: Node loopback serving Layers |
+| `serve.ts` | `ServeOptions`, `HOST`, `serveBoard(options)`: loopback Board serving through Platform’s `appHost` |
 | `responses/agent.ts` | `AgentOptions`, `agentRequest(action, options, diagnostic?)`: Effect client for `question`, `response` or `wait` |
 | `browser/client.ts` | `Reader`, `BrowserClient`, `browserClient(url, options?)`: native reading, response and handoff bindings, registry and live updates |
 | `rpc/contract.ts` | `workContract`, `Subscribe`, `workRpcs`: reading queries and combined native RPC group |
 | `browser/document/schema.ts`, `browser/document/View.ts` | `Document`, `DocumentRequest`, `DocumentView`, `DocumentViewProps`: source query data and React document rendering |
 | `rpc/responseContract.ts` | `responseContract`: question/read/wait queries and register/record commands |
 | `rpc/handoffContract.ts` | `handoffContract`: source/history queries and reviewed preparation command |
-| `browser/navigation/schema.ts` | `Navigation`, `NavigationFolder`, `NavigationFile`: native navigation result schemas/types |
+| `browser/navigation/schema.ts` | `Navigation`: compact navigation result schema/type |
+| `browser/navigation/library.ts` | `Library`, `LibraryFile`, `LibraryInput`: titled document and folder query schemas |
 | `browser/responses/schema.ts` | Question, response, answer and draft schemas/types |
 | `rpc/rejections.ts` | `documentRejections`, `DocumentRejection`, `responseRejections`, `ResponseRejection`: declared taxonomy and application errors; `PublicationUncertain` and `Unanswered` |
 | `browser/handoffs/schema.ts` | Handoff record, input, reading and source-preview schemas/types |
 | `metadata/schema.ts`, `metadata/parse.ts`, `metadata/model.ts` | Source schemas, parsed fields/diagnostics and explicit identity/reference model |
 
-Other defining modules are also exposed by the wildcard. Their [source directory](https://github.com/ShivaeDev/platform/tree/main/packages/work-board/src) contains file/watch, HTTP, rendering, search, views, history and result-review helpers. Compose `boardLayer` to retain the package's source policy and request guards.
+Other defining modules are also exposed by the wildcard. Their [source directory](https://github.com/ShivaeDev/platform/tree/main/packages/work-board/src) contains file/watch, HTTP, rendering, search, views and result-review helpers. Compose `boardLayer` to retain the package's source policy and request guards.
 
 #### Embed the workspace
 
@@ -312,7 +319,7 @@ Other defining modules are also exposed by the wildcard. Their [source directory
 import { NodeServices } from "@effect/platform-node";
 import { boardLayer } from "@shivaedev/work-board/board.ts";
 import { Layer } from "effect";
-import { HttpRouter } from "effect/unstable/http";
+import { HttpRouter } from "effect/http";
 
 const board = HttpRouter.toWebHandler(
   Layer.provide(boardLayer({ root: "./project-notes", home: "plan.md" }), NodeServices.layer),
@@ -328,7 +335,7 @@ try {
 }
 ```
 
-`boardLayer` needs `FileSystem`, `Path` and the HTTP router services; `NodeServices` provides the filesystem/path implementation here. `root` is required, `home` is optional, `maintainer` selects the Inbox responder label (default `maintainer`), and `responses: true` explicitly opts into publication. `HttpRouter.serve` can compose it beside application routes in a scoped Effect HTTP server. Requests still require a loopback `Host`; a missing/non-loopback host is refused, as is a known non-loopback remote address. The embedding host owns its trust boundary.
+`boardLayer` needs `FileSystem`, `Path` and the HTTP router services; `NodeServices` provides the filesystem/path implementation here. `root` is required, `home` is optional, `maintainer` selects the human responder label (default `maintainer`), and `responses: true` explicitly opts into publication. `HttpRouter.serve` can compose it beside application routes in a scoped Effect HTTP server. Requests still require a loopback `Host`; a missing/non-loopback host is refused, as is a known non-loopback remote address. The embedding host owns its trust boundary.
 
 #### Read and wait from a Node agent
 
@@ -377,7 +384,7 @@ export async function registerReviewedQuestion(url: string, revision: string) {
   const client = browserClient(url);
   try {
     const page = await client.read(
-      client.api.page.query({ url: "/_board/item/work.search/" }),
+      client.api.document.query({ url: "/_board/item/work.search/" }),
     );
     const question = await client.mutate(
       client.responses.registerQuestion.run({
@@ -398,7 +405,13 @@ export async function registerReviewedQuestion(url: string, revision: string) {
 
 Call this function with a revision whose source/context you have reviewed and a server started with `--responses`. `api` binds reading operations; `responses` binds question and response operations. `read` resolves a query atom, `run` executes a query Effect, and `mutate` executes a command with its invalidation service. `handoffs` binds source/history queries and the preparation command. The client also exposes `registry` and `updates`; dispose the registry when its owner ends.
 
-`client.api.navigation.query({ current: "notes/topic.md" })` returns navigation data rather than HTML. Pass the selected document's relative path, or `""` for a workspace view. `tree` contains ordered `files` and recursive `folders`, each with a descendant file `count` and an `active` flag. Files include their path, encoded href, display name, modification time and `current` flag. `records` holds the Fleet records separately with its count and active flag; `inboxCount` is a number or `null` when the index is unavailable. Optional `home` identifies the configured home board file and its unique identity. The React sidebar renders this query through `effect-react`, marks the selected file and retains the tree while a route change loads its next query.
+`client.api.navigation.query({ current: "" })` returns compact destination `counts`, `inboxCount` (a number or `null` when the index is unavailable), and optional `home` with the configured home file and its unique identity. It contains no file tree. `client.api.library.query({})` loads document metadata on demand: `files` contain `path`, encoded `href`, `title`, `modified`, `kind` and `status`; `kinds` and `statuses` populate filters, and `fleetCount` counts hidden generated records. Optional `kind`, `status` and `showFleet` filter the files. Passing `folder: ""` lists root files and immediate folder descriptors; passing a folder path loads its direct files and immediate child folders. Folder descriptors contain `path`, `name` and descendant `count`. The shell reads active goal status counts from `client.api.goals.query()`; opening Library loads its own query.
+
+A `kind: project` page puts goal progress before its authored Markdown: a large segmented bar with the goals query's **done / in progress / planned** counts and its goal-specific open-ask count, including zero. The progress header sits immediately below the item header, before open answer cards. Criteria, linked work and prose follow the answer cards. The header and each criterion render query counts directly, including Fleet-held work as in progress. These are work counts, never an overall success state or percentage. The open-ask count uses the same eligible, active, grouped rows as the maintainer's Today attention list; resolved, parked and earlier grouped asks do not add to it.
+
+Each criterion shows its progress split in one small line, targeting items and recorded evidence when present. Untargeted criteria retain their text without an extra label; absent evidence stays quiet. The table shows each implementing item once under nonempty In progress, Planned, Done (collapsed) or Deferred groups. Each row and criterion link has one state chip: the Fleet stage while held, otherwise the authored status. A released stage falls back to authored status; missing status and missing PR leave blank cells. Items without status belong to Planned. The outline rail remains beside the prose on wide screens and follows it on narrow screens. Closed projects show the same goal and criterion counts as open projects while staying outside active-goal navigation.
+
+`client.api.goals.query()` returns `{ closedGoals, goals, items }`. `items` contains every uniquely identified implementing document, including results, decisions, questions, responses and work targeting closed projects, with `file`, `id`, `title` and `metadata`. Goal criteria and work tables select from this same set used for counts. `goals` contains uniquely identified `kind: project` documents with an open status, using the attention projection's open-item convention. `closedGoals` contains the remaining identified projects with the same progress and criterion fields. Project pages read both lists; the sidebar and navigation count use only `goals`. The Goals view shows active goals as compact cards with next actions, linked-work progress and positive open-ask counts. Only criteria with linked work appear, as single-line links with done/total counts. Empty progress and zero-count metadata render nothing. Closed goals sit below the active cards in one disclosure, closed by default. Each goal includes `id`, `title`, optional authored `status`, `owner` and `nextAction`, and `criteria`. `linked` counts distinct identified items with an `implements` relationship targeting the goal or a criterion anchor. `counts` always has `done`, `"in progress"` and `planned` numbers, including zeros. Fleet-held stages override authored status: completed is done, prepared is planned and other held stages are in progress. Released stages and unavailable Fleet fall back to authored status: closed statuses are done, planned, deferred and missing statuses are planned, and other statuses are in progress. Deferred work keeps its own table group but contributes to planned progress. Multiple matching relationships on one item count once. Each criterion includes its `id`, `text`, `linked`, `counts` and `evidence`, the number of recorded claims targeting that exact criterion across indexed documents. `openAsks` counts eligible active attention rows whose targets include the goal, its criteria or a linked item, once per grouped row; it cannot exceed the attention count. A goal without linked items has zero counts, `linked: 0` and `unlinked: true`; an untargeted criterion has `linked: 0`. The query returns no completion percentage or overall success flag. Mounted queries refresh when indexed source changes.
 
 For a handoff, first read the preview with `client.run(client.handoffs.handoffSource.run({ item: "work.search" }))` and inspect its `context`. This complete program takes that reviewed path and revision as inputs:
 
@@ -420,7 +433,7 @@ export async function prepareReviewedHandoff(
         revision,
         recipient: "agent-navigation",
         goal: "Fix keyboard focus",
-        constraints: "Preserve no-JavaScript links.",
+        constraints: "Preserve keyboard navigation.",
         nextAction: "Inspect the current source and report browser evidence.",
       }),
     );
@@ -436,7 +449,7 @@ export async function prepareReviewedHandoff(
 
 Pass `preview.source` and `preview.reviewedRevision` only after reviewing the preview's context. `saved.prompt` is the short instruction to copy into the agent session, and `history` contains records plus paths whose history is unknown. Keep the same ID for a retry of identical direction; choose a new ID for new direction.
 
-Result reading uses the same page query as other workspace views:
+Result reading returns the report, linked criteria and revision-pinned feedback from its typed query:
 
 ```ts
 import { browserClient } from "@shivaedev/work-board/browser/client.ts";
@@ -445,7 +458,7 @@ export async function readReturnedResult(url: string, item: string) {
   const client = browserClient(url);
   try {
     return await client.read(
-      client.api.page.query({
+      client.api.result.query({
         url: `/_board/result?item=${encodeURIComponent(item)}`,
       }),
     );
@@ -463,7 +476,7 @@ RPC rejections use Platform taxonomy classes: `Forbidden` for disabled writes, `
 
 Read `client.api.document.run({ url: "/notes.md" })` to get Markdown body source, metadata and diagnostics, resolved links and references, file information, resolved question actions and request previews with response history. Identity URLs and `/` use the same document query. Missing and duplicate identities reject with `NotFound` and `Conflict`; incomplete history stays explicitly unavailable. The query sends no rendered HTML or syntax tree.
 
-Pass that data as the `document` prop of `DocumentView` from `@shivaedev/work-board/browser/document/View.ts`. The view uses the Board's GFM, directive, heading and footnote plugins with raw HTML, browser-side Shiki and a Mermaid code override. `idPrefix` scopes footnotes when a host displays several documents. The Board shell is a React app with TanStack Router. Its route loaders read document and page contract queries through `effect-react` in the shell's native registry; preloading and navigation share those reads. Document and item pages mount `DocumentView` from the typed document query; the configured home board and workspace views remain in `LegacyMain`. The optional `reading` data supplies source context, backlinks, criterion claims and managed receipts; request `prompts` supply answer controls. Hosts can mount `DocumentView` directly from source-query data, or pass `context` and `introduction` React nodes for its document layout.
+Pass that data as the `document` prop of `DocumentView` from `@shivaedev/work-board/browser/document/View.ts`. The view uses the Board's GFM, directive, heading and footnote plugins with raw HTML, browser-side Shiki and a Mermaid code override. `idPrefix` scopes footnotes when a host displays several documents. The Board shell is a React app with TanStack Router. Its route loaders read document and projection contract queries through `effect-react` in the shell's native registry; preloading and navigation share those reads. Document and item pages mount `DocumentView` from the typed document query; Today, Goals, Now, Library and System render typed projection queries in React, as do Workspace notes, Start, Respond, Handoff and Result. Their direct URLs load the shell and require JavaScript. The HTML page RPC is removed. The optional `reading` data supplies source context, backlinks, criterion claims and managed receipts; request `prompts` supply answer controls. Hosts can mount `DocumentView` directly from source-query data, or pass `context` and `introduction` React nodes for its document layout.
 
 #### Headless addon API
 
@@ -474,7 +487,7 @@ Work Fleet uses five server entry points and one portable metadata type entry po
 | `integration/board.ts` | `board`: `metadataParse`, `metadataModel`, `listMarkdown`, `markdownPath`, `watchChanges`, `searchSnapshot`; exported types `Diagnostic`, `ParsedMetadata`, `MetadataDocument`, `MetadataModel`, `MarkdownFile`, `Changes`, `Snapshot` |
 | `integration/metadata.ts` | Portable types `Diagnostic`, `ParsedMetadata`, `MetadataDocument`, `MetadataModel`, also available through `integration/board.ts` |
 | `integration/responses.ts` | `responses`: `Responses`, `ResponseConfig`, `readResponses`, `currentResponses`, `makeResponse`, `publish`, `revisionOf`, `questionId`, `questionFrom`, `questionMarkdown`, `responseMarkdown`, `DraftInput`, `Question`, `Reading`, `RecordedResponse`; exported types `DraftInput`, `Question`, `Reading`, `RecordedResponse`, `ResponseOptions` |
-| `integration/attention.ts` | `attention`: `RequestReceipt`, `managedRequestReceipt`; exported type `RequestReceipt` |
+| `integration/attention.ts` | `attention`: `RequestReceipt`, `managedRequestReceipt`, `projection(snapshot)`; exported types `RequestReceipt`, `AttentionProjection` |
 | `integration/diagnostics.ts` | `diagnostics`: `FleetHealth`, `CapacityRejection`, `FLEET_HEALTH_NAME`, `fleetHealth`, `DiagnosticsContract`, `DAEMON_PORT`, `DAEMON_RPC_PATH`, `DiagnosticsSources`, `SourceFailure`, `diagnostics`, `codexRateLimits`, `codexLimits`, `githubLimits`; exported types `FleetHealth`, `CapacityRejection`, `SourceFailure` |
 | `integration/publication.ts` | `publication`: `directoryPath`, `validateDirectory` for addons that publish their own records through open directory handles |
 
@@ -490,17 +503,36 @@ const read = Effect.scoped(Effect.gen(function* () {
 })).pipe(Effect.provide(NodeServices.layer));
 ```
 
-The snapshot retains parsed documents, identity diagnostics and unavailable paths. Compose `responses.Responses.layer` with `responses.ResponseConfig` containing that index, the same watcher, workspace root and explicit `enabled` write choice. Use the service to register reviewed questions and record answers; `responses.publish` writes an immutable record under `responses/` (or `handoffs/` when selected), and the record helpers preserve exact reviewed bytes and source path. Agent-owned items remain ordinary Markdown edits. `attention.managedRequestReceipt` qualifies an acknowledgement against those records; it does not confer execution or acceptance authority. The publication helpers retain the filesystem limits below.
+The snapshot retains parsed documents, identity diagnostics and unavailable paths. Compose `responses.Responses.layer` with `responses.ResponseConfig` containing that index, the same watcher, workspace root and explicit `enabled` write choice. Use the service to register reviewed questions and record answers; `responses.publish` writes an immutable record under `responses/` (or `handoffs/` when selected), and the record helpers preserve exact reviewed bytes and source path. Agent-owned items remain ordinary Markdown edits. `attention.projection(snapshot)` returns the typed attention projection: `you`, `agents`, `resolved`, `parked`, `issues` and `complete`, with `items` retaining the same rows as `you` for existing clients. `attention.managedRequestReceipt` qualifies an acknowledgement against those records; it does not confer execution or acceptance authority. The publication helpers retain the filesystem limits below.
 
 Fleet's production imports are fenced to these six entry points by `pnpm lint`; its test fixtures may still use Board modules directly. The packed-package consumer exercises the headless read, response and receipt path through these exports.
 
+#### Read the running board through MCP
+
+Start the board with `work-board /absolute/path/to/notes`. Register its read-only stdio MCP server with Claude Code or Codex:
+
+```sh
+claude mcp add --transport stdio work-board -- work-board mcp /absolute/path/to/notes
+codex mcp add work-board -- work-board mcp /absolute/path/to/notes
+```
+
+Both commands require `work-board` on the client's PATH. `work-board mcp <dir>` reads the running board through `<dir>/board.sock`; it uses the same computed queries as the browser. If no board answers, every tool returns one error naming the directory and the `work-board <dir>` command to start it.
+
+| Tool | Returns |
+| --- | --- |
+| `board_overview` | Needs-you count and items, in-flight Fleet items with stage and PR, and active and closed goal progress counts |
+| `needs_you` | The `you` lane with reason, frontmatter options, computed question prompts and their choices, recommendation, and `ageMs` since the source's last modification (`null` when unknown) |
+| `item` with `{ "id": "task.example" }` | Computed status, owner, criteria, relationships, Fleet stage and open decisions |
+
+Fleet unavailability stays explicit in results. These tools read state without changing files or starting a board.
+
 #### CLI reference
 
 | Server argument | Default | Meaning |
 | --- | --- | --- |
 | `<dir>` | Required | Existing folder to read |
-| `--home <file>` | None | Listed Markdown file rendered as a board at `/`; a missing file prevents startup |
-| `--maintainer <name>` | `maintainer` | Literal `response_from` label for Inbox questions; unaddressed standalone questions remain included |
+| `--home <file>` | None | Listed Markdown heading board linked as Workspace notes; a missing file prevents startup |
+| `--maintainer <name>` | `maintainer` | Literal `response_from` label for human questions; unaddressed standalone questions remain included |
 | `--port <number>` | `4747` | Loopback server port; `0` asks for a free port |
 | `--responses` | Off | Enable local question/response/handoff publication |
 
@@ -513,7 +545,19 @@ Fleet's production imports are fenced to these six entry points by `pnpm lint`;
 | `--port <number>` | Select the shared server's port; default `4747` |
 | `--url <origin>` | Select an HTTP loopback origin instead of `--port` |
 
-The browser uses local NDJSON RPC at `POST /_board/rpc`. Ordinary document GETs, `/_board/start`, `/_board/work`, `/_board/overview`, `/_board/changes`, `/_board/respond`, `/_board/handoff`, `/_board/result`, and identity links remain available alongside it. Search, retained-source history and live subscriptions use the same RPC route. There is no automatic workspace discovery or server launch in agent commands.
+The browser uses local NDJSON RPC at `POST /_board/rpc`. Ordinary document GETs, `/_board/start`, `/_board/goals`, `/_board/work`, `/_board/library`, `/_board/system`, `/_board/respond`, `/_board/handoff`, `/_board/result`, and identity links load the React shell. Search and live subscriptions use the same RPC route. There is no automatic workspace discovery or server launch in agent commands.
+
+A running `work-board <dir>` also serves that NDJSON RPC at `POST /_board/rpc` over the Unix socket `<dir>/board.sock`, using the same handlers and services as TCP. Tools can read `work-board.inbox`, `work-board.fleetItems` and `work-board.goals` from the board directory without knowing its port. Each board directory has its own socket. For example:
+
+```sh
+printf '%s\n' '{"_tag":"Request","id":"1","tag":"work-board.server","payload":null,"headers":[]}' |
+  curl --unix-socket ./notes/board.sock http://localhost/_board/rpc \
+    -H 'Content-Type: application/ndjson' --data-binary @-
+```
+
+The `work-board.server` query takes no payload and returns `{ url, directory }`, for example `{ "url": "http://127.0.0.1:4747/", "directory": "/home/me/project/notes" }`. It is available over both TCP and the socket; `url` uses the actual browser port, including when `--port 0` selects a free port. Its `Server` schema is exported from `@shivaedev/work-board/rpc/Server.ts`.
+
+The socket has owner-only access from creation: startup binds inside a private sibling directory at `.sXXXXXX/s`, applies mode `0600`, then publishes `board.sock`. The private socket pathname is no longer than the public pathname, so staging does not reduce the directory lengths that Unix sockets support. These permissions provide its access boundary because Unix connections have no TCP remote address. Requests to `http://localhost/_board/rpc` with `Host: localhost` work over the socket; TCP retains its loopback Host and remote-address checks. Startup removes an unanswered stale socket and refuses to start when another board already answers there. A temporary `.board.sock.starting/` directory serializes stale removal and publication across processes. It is removed when startup completes or its scope closes. The private staging directory is also removed when startup completes or its scope closes. If a process is forcibly killed during startup, the error identifies the lock directory; remove abandoned startup directories only after confirming that startup is no longer running. Closing the board removes its socket, including on SIGINT and SIGTERM. If the board directory is committed, add `board.sock` and `.board.sock.starting/` to that directory's ignore rules.
 
 ### Install and limits
 
@@ -529,6 +573,6 @@ Files/folders below the root beginning with a dot, and `node_modules`, are skipp
 
 Publication runs on Linux and macOS and needs a real workspace directory, hard links and directory synchronization. Linux anchors each step to open directory descriptors through `/proc/self/fd`. macOS has no such anchor in Node, so it uses canonical paths and checks the directories' device/inode identity before and after publishing; a directory or ancestor swapped between two checks is not detected, so keep write boundaries under trusted local ownership. Node's `fsync` on macOS does not issue `F_FULLFSYNC`, so a successful save is not a power-loss guarantee there. Read mode remains separate. No-replace publication and retry reconciliation protect recorded contributions; agents edit handoff receipt through ordinary files. An unrelated editor can still change source after preflight. Records retain the exact reviewed context, rather than claiming an atomic transaction with that editor. Moved directories or synchronization failures can produce an uncertain outcome.
 
-JavaScript enables live updates, search, draft/response/handoff controls and diagram inspection. Server-rendered documents, source details, native Work/Overview links, copyable templates and saved feedback remain readable without it. Image routes exclude SVG, HTML, PDF and arbitrary attachments. The board does not launch agents, verify recorded evidence or generate exported document packets.
+The browser workspace requires JavaScript. Tailwind and shared React primitives style its views; project Markdown remains readable in an editor independently of the browser. Image routes exclude SVG, HTML, PDF and arbitrary attachments. The board does not launch agents, verify recorded evidence or generate exported document packets.
 
-The [north star](docs/north-star.md) explains design priorities. The [roadmap](docs/roadmap.md) owns implementation status and unresolved decisions. [Experience designs and mockups](docs/experience.md) illustrate the product direction with fictional data.
+The [north star](docs/north-star.md) explains design priorities. The [roadmap](docs/roadmap.md) owns implementation status and unresolved decisions.