> 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/phase18-session11-validation-documentation-and-handoff/phase18-docs-handoff.md). # Phase 18 Docs Handoff **Session ID**: `phase18-session11-validation-documentation-and-handoff` **Phase**: 18 - Quest Board Suggestion Parity **Last Updated**: 2026-06-10 11:56 *** ## Stable Doc Ownership Matrix | Surface | File | Current Coverage | Required Closeout Update | | ------------------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | | External API | `docs/api/README_api.md` | Updated with shipped `/suggestions/*`, `/issues/:issueId/dismiss`, summary/status routes, aliases, validation, errors, and `suggestion_update`. | Complete; validate workflow should verify. | | Architecture | `docs/ARCHITECTURE.md` | Updated with manager-owned Quest Board runtime flow, persistence, engine write paths, snapshot delivery, and web action boundaries. | Complete; validate workflow should verify. | | Privacy/security | `docs/privacy-and-security.md` | Updated with `suggestions.json`, local data inventory, manual deletion path, provider opt-in, hosted exclusions, and trusted-erasure no-claim wording. | Complete; validate workflow should verify. | | Docs index | `docs/README_docs.md` | Updated with Quest Board routing entries to API, architecture, privacy, protocol, server, and web docs. | Complete; validate workflow should verify. | | Protocol package | `packages/protocol/README_protocol.md` | Updated with post-Phase 18 contract ownership, REST aliases, compatibility event guidance, and exclusions. | Complete; validate workflow should verify. | | Server package | `apps/server/README_server.md` | Updated with final route ownership, manager/engine boundaries, persistence, scan privacy, and unsupported-route posture. | Complete; validate workflow should verify. | | Web package | `apps/web/README_web.md` | Updated with typed card model, states, actions, scan triggers, feedback, and shortcuts. | Complete; validate workflow should verify. | | Idle prompt | `apps/server/src/llm/prompts/idle-suggestion-engine.md` | Updated to match shipped hero-idle lifecycle, fallback behavior, session summaries, manager state, actions, and shortcuts. | Complete; validate workflow should verify. | | Unsupported routes | `apps/server/src/lib/unsupportedRoutes.ts` | Updated so shipped issue-dismiss and suggestion route families are not caught by planned unsupported prefixes. | Complete; focused unsupported-route test passed. | | Phase PRD | `.spec_system/PRD/phase_18/PRD_phase_18.md` | Updated with Session 11 implementation closeout and Appendix A status handoff. | Complete; validate workflow remains next. | | Master PRD | `.spec_system/PRD/PRD.md` | Updated with Phase 18 implementation closeout status and validate handoff. | Complete; validate workflow remains next. | *** ## Current Source Coverage Inventory | Runtime Area | Source Files | Tests/Evidence | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Protocol contracts | `packages/protocol/src/suggestions.ts`, `packages/protocol/src/events.ts`, `packages/protocol/src/rest.ts` | `packages/protocol/tests/suggestions.test.ts`, `events.test.ts`, `rest.test.ts` | | Suggestion manager and persistence | `apps/server/src/managers/suggestionManager.ts` | `apps/server/tests/suggestionManager.test.ts`, `suggestionManagerLifecycle.test.ts` | | REST routes | `apps/server/src/routes/suggestions.ts`, `apps/server/src/server.ts` | `apps/server/tests/suggestionRoutes.test.ts`, `routes.test.ts` | | WebSocket hydration | `apps/server/src/ws/handlers.ts`, `apps/server/src/lib/suggestionBroadcast.ts` | `apps/server/tests/suggestionWebsocket.test.ts`, `websocket.test.ts` | | Idle lifecycle | `apps/server/src/lib/idleSuggestionLifecycle.ts`, `idleSuggestionContext.ts`, `apps/server/src/llm/engines/idleSuggestionEngine.ts`, `apps/server/src/routes/event.ts` | `apps/server/tests/idleSuggestionLifecycle.test.ts`, `idleSuggestionContext.test.ts`, `llm.test.ts`, `routes.test.ts` | | Session summaries/noise filtering | `apps/server/src/lib/sessionSummaryLifecycle.ts`, `sessionSummaryEngine.ts`, `analysisNoiseFilter.ts` | `apps/server/tests/sessionSummaryLifecycle.test.ts`, `sessionSummaryEngine.test.ts`, `analysisNoiseFilter.test.ts` | | Codebase scanners | `apps/server/src/lib/codebaseIssueScanners.ts` | `apps/server/tests/codebaseIssueScanners.test.ts` | | Scan orchestration and ignores | `apps/server/src/lib/codebaseScanOrchestrator.ts`, `questIgnore.ts`, `apps/web/src/lib/scanCodebase.ts`, `apps/web/src/store/useSettingsStore.ts` | `apps/server/tests/codebaseScanOrchestrator.test.ts`, `questIgnore.test.ts`, `apps/web/tests/scanCodebase.test.ts`, `SettingsScan.test.tsx` | | Analysis and project scans | `apps/server/src/lib/onDemandAnalysisEngine.ts`, `projectScanEngine.ts`, `apps/server/src/llm/prompts/project-scan.md` | `apps/server/tests/onDemandAnalysisEngine.test.ts`, `projectScanEngine.test.ts`, `suggestionRoutes.test.ts` | | Web cards/actions/shortcuts | `apps/web/src/lib/questBoard.ts`, `questBoardModel.ts`, `questBoardActions.ts`, `apps/web/src/store/useGameStore.ts`, `apps/web/src/components/QuestBoard.tsx`, `apps/web/src/lib/useKeyboardShortcuts.ts`, `KeyboardShortcutsModal.tsx` | `apps/web/tests/questBoard.test.ts`, `questBoardStore.test.ts`, `QuestBoard.test.tsx`, `questBoardActions.test.ts`, `keyboardShortcuts.test.ts`, `KeyboardShortcutsModal.test.tsx` | *** ## Route Support Inventory | Route/Event | Status | Notes | | ---------------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- | | `GET /suggestions/summary` and `/api/suggestions/summary` | Shipped | Returns manager summary counts and severity buckets. | | `POST /suggestions/:suggestionId/accept` and `/api/...` | Shipped | Validates safe ids, prevents duplicate in-flight accepts, returns `send_prompt` or `prompt_sent`. | | `POST /suggestions/:suggestionId/dismiss` and `/api/...` | Shipped | Validates safe ids, prevents duplicate dismissals, persists dismissed suggestion ids. | | `POST /issues/:issueId/dismiss` and `/api/...` | Shipped | Validates safe ids, prevents duplicate dismissals, persists dismissed issue ids. | | `POST /suggestions/scan`, `GET /suggestions/scan/status`, and `/api/...` | Shipped | Supports full, diff, and daily modes, status, conflict responses, and ignore patterns. | | `POST /suggestions/analyze`, `GET /suggestions/analyze/status`, and `/api/...` | Shipped | Supports fresh-cache return, force refresh, status, fallback, and conflict responses. | | `POST /suggestions/project-scan`, `GET /suggestions/project-scan/status`, and `/api/...` | Shipped | Supports fresh-cache return, force refresh, status, fallback, startup stale scan, and conflict responses. | | WebSocket `suggestion_update` | Shipped | Canonical typed snapshot emitted on connect and manager mutations. | | WebSocket `idle_suggestion` | Compatibility | String-only event remains for migration compatibility; not the canonical contract. | | Historical issue query/accept/task-queue routes | Unsupported/follow-up | Keep unsupported unless a future executor or queue threat model ships. | | Suggestion telemetry and entitlement gate | Deliberately excluded | Local-first posture has no analytics capture or entitlement system in this phase. | *** ## Update Checklist * [x] API docs include all shipped Quest Board routes, aliases, validation, and error envelopes. * [x] Architecture docs identify `SuggestionManager` as the source of truth. * [x] Privacy docs inventory `suggestions.json` with manual deletion only. * [x] Docs index links readers to API, architecture, privacy, protocol, server, and web docs. * [x] Protocol docs explain active `suggestion_update`, frozen `idle_suggestion`, retired `quest_board`, and REST consumers. * [x] Server docs remain aligned after unsupported-route reconciliation. * [x] Web docs describe typed cards, action states, trigger states, offline/error states, and shortcuts. * [x] Prompt docs describe hero-idle runtime behavior and avoid non-shipped claims. * [x] Unsupported route code leaves shipped issue-dismiss and suggestion routes out of unsupported catch-all families. *** ## Document Update Status | File | Status | Validation Needed | | ------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `docs/api/README_api.md` | Updated | Route and WebSocket contract text matches `apps/server/src/routes/suggestions.ts` and `packages/protocol/src/events.ts`; broad gates passed. | | `docs/ARCHITECTURE.md` | Updated | Runtime flow matches server manager, engines, WebSocket hydration, and web action boundaries; broad gates passed. | | `docs/privacy-and-security.md` | Updated | `suggestions.json` inventory includes data classes, local storage path, manual deletion, and no trusted-erasure claim. | | `docs/README_docs.md` | Updated | Quest Board readers can find API, architecture, privacy, protocol, server, and web docs. | | `packages/protocol/README_protocol.md` | Updated | Contract ownership and compatibility event guidance match final Phase 18 state. | | `apps/server/README_server.md` | Updated | Route inventory and privacy boundaries remain aligned after final reconciliation. | | `apps/web/README_web.md` | Updated | Typed cards, actions, triggers, feedback, and shortcuts are documented without hosted or executor claims. | | `apps/server/src/llm/prompts/idle-suggestion-engine.md` | Updated | Prompt doc describes shipped hero-idle lifecycle and manager-backed output. | | `apps/server/src/lib/unsupportedRoutes.ts` | Updated | Unsupported prefixes do not catch shipped Quest Board routes; focused test passed. | | `.spec_system/PRD/phase_18/PRD_phase_18.md` | Updated | Session 11 implementation status and Appendix A closeout status are updated; validate workflow remains next. | | `.spec_system/PRD/PRD.md` | Updated | Phase 18 progress is synchronized with Session 11 implementation closeout status. | *** ## Privacy Inventory Changes | Data Surface | Data Classes | Storage/Transfer | Deletion/No-Claim Notes | | ------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | `suggestions.json` | Relative file paths, code-derived suggestion text, IDs, timestamps, summary counts, scan status, dismissed IDs | Local file under `FACTIONOS_HOME` or `~/.factionos`; no hosted storage, analytics, entitlement, Worker federation, or provider transfer by persistence alone | Manual deletion while server is stopped; trusted unified erasure remains no-claim for this file. | | Runtime scan inputs | Approved local root, relative paths, bounded command status/failure metadata | Local process memory; provider transfer disabled unless both key and explicit opt-in exist | Do not store raw file contents, command bodies, terminal output, or broad absolute paths in evidence. | | Provider fallback records | Compact fallback labels and schema-valid generated items | Local manager state only when provider is unavailable or transfer disabled | Evidence records counts/status only, not generated prompt payloads. | *** ## Handoff Notes * Treat `EXAMPLES/` as traceability evidence only. Do not copy or transform historical implementation code. * Keep evidence safe: record commands, statuses, counts, and redacted summaries only. * Do not add telemetry, entitlement gates, executors, hosted storage, issue-accept behavior, or trusted-erasure claims during closeout. * Next workflow step after implementation gates is `validate`; PRD records intentionally say Session 11 is implementation-complete rather than validated. --- # 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/phase18-session11-validation-documentation-and-handoff/phase18-docs-handoff.md?ask=&goal= ``` `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.