> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase17-session03-server-routes-and-websocket-parity` **Package**: apps/server, packages/protocol **Started**: 2026-06-05 20:11 **Last Updated**: 2026-06-05 20:36

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 24 / 24 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

### Task T024 - Run focused tests, typechecks, and ASCII/LF validation

**Started**: 2026-06-05 20:36 **Completed**: 2026-06-05 20:36 **Duration**: 1 minute

**Notes**:

* Formatted touched code and test files with Biome.
* Server and protocol package typechecks passed under temporary Node 26.2.0.
* Focused Vitest coverage passed for protocol events, protocol REST contracts, Notice Board REST routes, legacy routes, and WebSocket behavior.
* Focused Biome lint passed for touched code and test files.
* ASCII and CRLF checks found no matches in the session-touched files.

**Files Changed**:

* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked final task and completion checklist complete.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged verification results.

**BQC Fixes**:

* N/A - verification task only.

***

### Task T023 - Update legacy route compatibility tests

**Started**: 2026-06-05 20:35 **Completed**: 2026-06-05 20:36 **Duration**: 1 minute

**Notes**:

* Extended existing legacy route tests to assert compatibility notices include canonical content aliases.
* Added `/api/notice` and `/api/notices` compatibility coverage after dedicated router extraction.
* Preserved legacy `targets` validation detail behavior for compatibility errors.

**Files Changed**:

* `apps/server/tests/routes.test.ts` - expanded legacy Notice Board compatibility assertions.
* `apps/server/src/routes/noticeBoard.ts` - preserved compatibility `targets` error detail naming.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged legacy compatibility test updates.

**BQC Fixes**:

* Contract alignment: tests verify root and `/api` compatibility paths after route extraction.
* Error information boundaries: compatibility validation keeps stable field names without exposing raw request payloads.

***

### Task T022 - Update WebSocket tests

**Started**: 2026-06-05 20:34 **Completed**: 2026-06-05 20:35 **Duration**: 1 minute

**Notes**:

* Updated deterministic hydration assertions to include canonical `messages`.
* Updated compatibility post assertions to require `message` aliases.
* Added persisted hydrate, expanded `post_notice`, and route-triggered resolve broadcast coverage.

**Files Changed**:

* `apps/server/tests/websocket.test.ts` - extended Notice Board WebSocket coverage.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged WebSocket test coverage.

**BQC Fixes**:

* State freshness on re-entry: tests verify new sockets hydrate persisted notices.
* Contract alignment: tests verify canonical and compatibility WebSocket payload keys.

***

### Task T021 - Add real-mode canonical route tests

**Started**: 2026-06-05 20:33 **Completed**: 2026-06-05 20:34 **Duration**: 1 minute

**Notes**:

* Added isolated real-mode route tests with temporary Notice Board storage.
* Covered canonical post, list, debug provenance, compatibility list, session filtering, context lookup, resolve, include-resolved behavior, compatibility post/list, invalid filters, and unsafe related-file rejection.

**Files Changed**:

* `apps/server/tests/noticeBoardRoutes.test.ts` - added focused Notice Board REST coverage.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged route test coverage.

**BQC Fixes**:

* Failure path completeness: tests assert invalid queries and unsafe related files fail without mutating stored notices.
* Contract alignment: tests assert canonical and compatibility REST envelopes.

***

### Task T020 - Update WebSocket post\_notice validation

**Started**: 2026-06-05 20:32 **Completed**: 2026-06-05 20:33 **Duration**: 1 minute

**Notes**:

* `post_notice` now accepts either canonical `content` or compatibility `body`.
* Added enum validation for notice type, priority, author type, and severity.
* Added bounded validation for tags, author metadata, target session ids, parent ids, room codes, expiration, and related files.
* Related files use protocol Notice Board relative-path validation before the handler can mutate state.

**Files Changed**:

* `apps/server/src/ws/clientMessageValidation.ts` - expanded `post_notice` validation and normalized returned client message fields.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged WebSocket validation changes.

**BQC Fixes**:

* Trust boundary enforcement: expanded WebSocket notice fields are validated before manager mutation.
* Contract alignment: validation now matches the protocol `ClientPostNotice` shape.
* Failure path completeness: malformed expanded fields return `server_toast` validation failures without mutating notice state.

***

### Task T019 - Update WebSocket hydration and post\_notice pass-through

**Started**: 2026-06-05 20:31 **Completed**: 2026-06-05 20:32 **Duration**: 1 minute

**Notes**:

* WebSocket connection hydration now reads persisted active-room notices through `getMessages`.
* Hydration sends both compatibility `notices` and canonical `messages`.
* `post_notice` now passes expanded Notice Board fields through to the manager while preserving `body`, `severity`, and `targets` compatibility.
* Broadcasts `notice_board_message` with both `notice` and `message` keys.

**Files Changed**:

* `apps/server/src/ws/handlers.ts` - updated hydrate and client post handling.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged WebSocket runtime changes.

**BQC Fixes**:

* State freshness on re-entry: new sockets hydrate from persisted manager state instead of stale compatibility-only state.
* Contract alignment: WebSocket frames now carry canonical and compatibility Notice Board payload keys.

***

### Task T018 - Emit Notice Board message and resolve frames

**Started**: 2026-06-05 20:30 **Completed**: 2026-06-05 20:31 **Duration**: 1 minute

**Notes**:

* Canonical and compatibility post routes emit `notice_board_message` with both `notice` and `message` payload keys.
* Resolve route emits `notice_resolved` with `noticeId`, `messageId`, optional resolution metadata, room code, and both `notice` and `message` payload keys.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added route broadcast helpers and integrated post/resolve emissions.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged event emission behavior.

**BQC Fixes**:

* Contract alignment: route broadcasts now match protocol canonical and compatibility event keys.
* Error information boundaries: broadcast payloads are manager-normalized notices, not raw request bodies.

***

### Task T017 - Implement POST /notice-board/:id/resolve

**Started**: 2026-06-05 20:29 **Completed**: 2026-06-05 20:30 **Duration**: 1 minute

**Notes**:

* Added canonical resolve route with safe id validation, optional body handling, optional room override, optional resolution text, optional resolved timestamp, and optional author session id.
* Uses the local room fallback when no explicit room code is provided.
* Returns `{ success: true, noticeId, resolvedAt }` for found room-local notices and compact `not_found` for missing notices.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added resolve route and parser.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged resolve behavior.

**BQC Fixes**:

* Trust boundary enforcement: path params, body fields, and room overrides are validated before manager access.
* Failure path completeness: missing room-local notices return a stable 404 envelope.

***

### Task T016 - Implement compatibility POST /notice adapter

**Started**: 2026-06-05 20:28 **Completed**: 2026-06-05 20:29 **Duration**: 1 minute

**Notes**:

* Added `POST /notice` to the dedicated Notice Board router.
* Preserves required legacy `body`, optional `severity`, and optional `targets` behavior while storing through the shared manager.
* Maintains legacy response shape by returning the stored notice directly.
* Uses the same in-flight duplicate guard as canonical posts.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added compatibility create route and parser.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged compatibility post behavior.

**BQC Fixes**:

* Duplicate action prevention: compatibility posts share the in-flight duplicate guard.
* Contract alignment: legacy post clients store through the same canonical manager path.
* Trust boundary enforcement: compatibility input is validated and normalized before storage.

***

### Task T015 - Implement related-file boundary validation

**Started**: 2026-06-05 20:27 **Completed**: 2026-06-05 20:28 **Duration**: 1 minute

**Notes**:

* Added route-level related-file sanitizer for canonical posts.
* Reuses protocol `normalizeNoticeRelatedFiles` to reject absolute paths, parent traversal, URLs, Windows absolute paths, backslashes, empty segments, and oversized entries.
* Resolves each normalized path against the current project root and rejects entries that would escape that root.
* Included normalized related files in the duplicate in-flight key.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added related-file boundary checks and canonical create integration.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged related-file validation.

**BQC Fixes**:

* Trust boundary enforcement: file references crossing the route boundary are validated before storage.
* Error information boundaries: rejected file paths return stable validation messages without echoing absolute paths.

***

### Task T014 - Implement expanded canonical post normalization

**Started**: 2026-06-05 20:31 **Completed**: 2026-06-05 20:35 **Duration**: 4 minutes

**Notes**:

* Extended canonical create parsing for priority, tags, author machine/session/name/avatar/type, target session ids, parent message id, expiration, and severity aliases.
* Used protocol normalizers for tags and target session ids so server route behavior follows shared Notice Board contracts.
* Kept content capped at the protocol limit before manager storage.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - expanded canonical create normalization.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged expanded normalization behavior.

**BQC Fixes**:

* Contract alignment: route normalization uses protocol Notice Board helpers for shared array fields.
* Trust boundary enforcement: expanded author, targeting, parent, expiration, and severity fields are validated before storage.

***

### Task T013 - Implement canonical POST /notice-board validation and duplicate guard

**Started**: 2026-06-05 20:27 **Completed**: 2026-06-05 20:31 **Duration**: 4 minutes

**Notes**:

* Added canonical `POST /notice-board` route.
* Requires schema-validated `type` and `content`.
* Uses a route-local in-flight key to reject concurrent duplicate post attempts with a compact `409 conflict` response.
* Returns the canonical `{ notice }` response envelope.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added canonical create route, parser, and in-flight duplicate guard.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged canonical post behavior.

**BQC Fixes**:

* Duplicate action prevention: concurrent identical canonical posts are blocked while a matching post is in flight.
* Trust boundary enforcement: canonical create body requires validated type and bounded content.
* Failure path completeness: validation and duplicate failures return explicit client-visible responses.

***

### Task T012 - Implement GET /notice-board/context validation and response mapping

**Started**: 2026-06-05 20:25 **Completed**: 2026-06-05 20:27 **Duration**: 2 minutes

**Notes**:

* Added canonical context route with required `sessionId` validation.
* Added bounded optional `limit` validation and shared optional `roomCode` override validation.
* Returns the manager's context response directly, preserving context text plus bounded message metadata.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added context route and parser.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged context route behavior.

**BQC Fixes**:

* Trust boundary enforcement: context query values are schema-validated before manager access.
* Failure path completeness: invalid context queries return compact `invalid_request` responses.

***

### Task T011 - Implement compatibility GET /notices adapter

**Started**: 2026-06-05 20:24 **Completed**: 2026-06-05 20:25 **Duration**: 1 minute

**Notes**:

* Added `GET /notices` to the dedicated Notice Board router.
* Reuses manager `list` behavior and preserves the legacy `{ notices }` response envelope.
* Validates optional `roomCode` overrides through the same active-room helper.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added compatibility list route.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged compatibility list behavior.

**BQC Fixes**:

* Contract alignment: legacy list clients now share the canonical manager path.

***

### Task T010 - Implement GET /notice-board query validation and list mapping

**Started**: 2026-06-05 20:20 **Completed**: 2026-06-05 20:24 **Duration**: 4 minutes

**Notes**:

* Added canonical `GET /notice-board` route.
* Validates `type`, `since`, `forSession`, `limit`, `offset`, `includeResolved`, `roomCode`, and `debug`.
* Delegates ordering and pagination to `NoticeBoard.getMessages`.
* Adds a compact debug provenance payload only when `debug=1` is explicitly supplied.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - implemented list route and query validators.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged canonical list route behavior.

**BQC Fixes**:

* Trust boundary enforcement: query values are parsed and bounded before manager access.
* Failure path completeness: invalid query values return compact `invalid_request` responses.

***

### Task T009 - Implement active-room resolution helper

**Started**: 2026-06-05 20:18 **Completed**: 2026-06-05 20:20 **Duration**: 2 minutes

**Notes**:

* Added route-local safe id validation for explicit `roomCode` overrides.
* Added active-room resolution metadata that distinguishes explicit overrides from manager-local fallback behavior.
* Kept the no-override path as undefined so custom manager defaults are not overwritten by the route layer.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - added room override validation and active-room resolution helper.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged active-room helper behavior.

**BQC Fixes**:

* Trust boundary enforcement: room overrides are validated before reaching the manager.

***

### Task T008 - Remove legacy Notice Board handlers from generic read router

**Started**: 2026-06-05 20:17 **Completed**: 2026-06-05 20:18 **Duration**: 1 minute

**Notes**:

* Removed `GET /notices` and `POST /notice` handlers from `readRouter`.
* Removed Notice Board manager dependency and old notice-specific imports/constants from `heroes.ts`.
* Updated the server runtime to stop passing `notices` into `readRouter`.

**Files Changed**:

* `apps/server/src/routes/heroes.ts` - removed legacy Notice Board route ownership.
* `apps/server/src/server.ts` - narrowed `readRouter` dependency injection.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged route extraction cleanup.

**BQC Fixes**:

* Contract alignment: Notice Board route behavior is centralized in the dedicated route module.

***

### Task T007 - Mount Notice Board router before generic read routes

**Started**: 2026-06-05 20:16 **Completed**: 2026-06-05 20:17 **Duration**: 1 minute

**Notes**:

* Imported `noticeBoardRouter` in the server runtime.
* Mounted the router before `readRouter` inside `mountLocalApiRoutes`, which applies to root and `/api` route groups.

**Files Changed**:

* `apps/server/src/server.ts` - mounted the dedicated Notice Board router.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged router mount placement.

**BQC Fixes**:

* Contract alignment: canonical and compatibility Notice Board paths now have an explicit owner before the generic read route module.

***

### Task T006 - Create dedicated Notice Board router scaffold

**Started**: 2026-06-05 20:14 **Completed**: 2026-06-05 20:16 **Duration**: 2 minutes

**Notes**:

* Added the dedicated Notice Board route module with dependency typing for the manager and broadcaster.
* Added route-local body-shape validation and compact `invalid_request` mapping for manager validation errors.

**Files Changed**:

* `apps/server/src/routes/noticeBoard.ts` - created router scaffold and validation/error helpers.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged router scaffold creation.

**BQC Fixes**:

* Failure path completeness: manager validation errors now have a compact route-layer mapping path.

***

### Task T005 - Extend Notice Board REST contract tests

**Started**: 2026-06-05 20:13 **Completed**: 2026-06-05 20:14 **Duration**: 1 minute

**Notes**:

* Added concrete canonical list, context, create, and resolve response examples that satisfy exported REST contracts.
* Added compatibility list response coverage and expanded canonical create request type coverage for author metadata, targeting, related files, room code, expiration, and severity aliases.

**Files Changed**:

* `packages/protocol/tests/rest.test.ts` - extended canonical and compatibility Notice Board REST contract coverage.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged REST test changes.

**BQC Fixes**:

* N/A - protocol test task only.

***

### Task T004 - Extend Notice Board event contract tests

**Started**: 2026-06-05 20:12 **Completed**: 2026-06-05 20:13 **Duration**: 1 minute

**Notes**:

* Expanded `ClientPostNotice` test coverage to include canonical content, compatibility body, priority, tags, author metadata, canonical and compatibility targets, parent id, related files, room code, expiration, and severity.
* Added runtime assertions that Notice Board message, hydrate, and resolve events preserve canonical and compatibility payload aliases.

**Files Changed**:

* `packages/protocol/tests/events.test.ts` - extended Notice Board event and client message contract coverage.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged protocol event test changes.

**BQC Fixes**:

* N/A - protocol test task only.

***

### Task T003 - Audit current WebSocket hydration and post\_notice handling

**Started**: 2026-06-05 20:10 **Completed**: 2026-06-05 20:12 **Duration**: 2 minutes

**Notes**:

* `registerWsHandlers` sends `notice_board_hydrate` with only the compatibility `notices` key.
* The `post_notice` case passes only `body`, `severity`, and `targets` into the manager, dropping expanded fields already present in protocol.
* `clientMessageValidation.ts` requires `body` and does not accept canonical `content`, `noticeType`, priority, tags, author fields, target session ids, parent id, related files, room code, or expiration.

**Files Changed**:

* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged WebSocket findings.

**BQC Fixes**:

* N/A - audit task only.

***

### Task T002 - Audit current Notice Board route ownership and mount order

**Started**: 2026-06-05 20:09 **Completed**: 2026-06-05 20:12 **Duration**: 3 minutes

**Notes**:

* Found legacy `GET /notices` and `POST /notice` handlers in `apps/server/src/routes/heroes.ts`.
* Confirmed `readRouter` is mounted inside both root and `/api` route groups, after health/event routes and before permission, LLM, export, orchestration, guarded-action, erasure, and diagnostics routers.
* Dedicated Notice Board router should mount before `readRouter` for both route groups, then legacy Notice Board ownership can be removed from `heroes.ts`.

**Files Changed**:

* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged route ownership findings.

**BQC Fixes**:

* N/A - audit task only.

***

### Task T001 - Verify Session 01 protocol and Session 02 manager prerequisites

**Started**: 2026-06-05 20:09 **Completed**: 2026-06-05 20:11 **Duration**: 2 minutes

**Notes**:

* Confirmed protocol Notice Board contracts include canonical list, context, create, resolve, compatibility REST aliases, expanded `ClientPostNotice`, and canonical/compatibility event keys.
* Confirmed server manager provides persistent `getMessages`, compatibility `list`, `getContextForSession`, `post`, `resolveForRoom`, ingest, pruning, and validation errors.

**Files Changed**:

* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/tasks.md` - marked task complete and updated progress.
* `.spec_system/specs/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md` - logged prerequisite findings.

**BQC Fixes**:

* N/A - audit task only.

***

## Task Log

### 2026-06-05 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed through bundled apex-spec scripts
* [x] apps/server package context verified
* [x] packages/protocol package context verified
* [x] Directory structure ready

**Notes**:

* Local `.spec_system/scripts` is absent, so bundled apex-spec scripts were used.
* System `node` is v24.14.0 while the repository engine requires Node >=26.2.0.
* Temporary validation with `npx -y node@26.2.0` is available for Node 26 gates.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase17-session03-server-routes-and-websocket-parity/implementation-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.