> 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/phases/phase_18/prd_phase_18.md). # PRD Phase 18: Quest Board Suggestion Parity **Status**: Complete **Sessions**: 11 (initial estimate) **Estimated Duration**: 4-6 days **Progress**: 11/11 sessions validated; Phase 18 complete *** ## Overview Source-backed port of the historical Quest Board / idle suggestion system recovered from `EXAMPLES/` evidence into the current codebase, as scoped by the Quest Board parity audit dated 2026-06-07. The audit's source document (`docs/ongoing-projects/quest-board.md`) is being deleted; its full content, including every `EXAMPLES/` and current-code reference path, is preserved in Appendix A of this PRD, which is now the canonical evidence index for this phase. The current Quest Board is a transient display list: the web panel renders up to six idle-suggestion strings fed by the `idle_suggestion` WebSocket event, with no persistence, no IDs, no actions, and no automatic generation. The historical system treated the Quest Board as a persisted, actionable orchestration queue: a server-side suggestion manager with disk persistence, typed multi-source cards (idle suggestions, codebase issues, on-demand analysis, project scan, session follow-ups), accept/dismiss APIs and shortcuts, hero-idle lifecycle generation with transcript context, codebase scan engines, ignore patterns, and a `suggestion_update` snapshot event. This phase recovers that functionality with canonical FactionOS contracts. `EXAMPLES/` material is traceability evidence only; no historical code, bundles, or assets are imported, copied, or transformed directly. The Quest Board surface is distinct from the mission/quest log surface (historical QuestLogPanel) and from the Phase 17 Notice Board; this phase does not merge those surfaces. Deliberate scope exclusions (documented here so they are not treated as missed parity): * Historical suggestion telemetry (`suggestion_generated`/`accepted`/ `dismissed` analytics events with `suggestion_id`, and `recordSuggestionAccepted()` on the accept route) is excluded. Analytics capture remains disabled by default per the hosted-services guardrails. * The historical suggestion-engine entitlement / feature gate (`SUGGESTION_ENGINE: "suggestion_engine"`, HTTP 403 with `upgrade: true`, and the `suggestion_engine_blocked` event) is excluded. FactionOS is local-first and has no entitlement system. * The historical codebase-issue quest-accept path (`acceptQuest`, returning `sourceType: "quest_board"`) was latent and unwired even in EXAMPLES; parity target is accept for idle suggestions and dismiss-only for codebase issues, with any issue-accept flow recorded as a deliberate extension if added. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | -------------------------------------------- | -------- | ---------- | ---------- | | 01 | Protocol Suggestion Contract Parity | Complete | 23 | 2026-06-09 | | 02 | Server Suggestion Manager And Persistence | Complete | \~12-25 | 2026-06-09 | | 03 | Suggestion Routes And WebSocket Parity | Complete | \~12-25 | 2026-06-10 | | 04 | Idle Lifecycle Engine Parity | Complete | \~12-25 | 2026-06-10 | | 05 | Session Summary Engine And Noise Filtering | Complete | \~12-25 | 2026-06-10 | | 06 | Codebase Issue Scanners | Complete | \~12-25 | 2026-06-10 | | 07 | Scan Orchestration And Quest Ignore Patterns | Complete | \~12-25 | 2026-06-10 | | 08 | On-Demand Analysis And Project Scan Engines | Complete | \~12-25 | 2026-06-10 | | 09 | Web Quest Board Typed Cards | Complete | \~12-25 | 2026-06-10 | | 10 | Quest Actions And Keyboard Shortcuts | Complete | \~12-25 | 2026-06-10 | | 11 | Validation Documentation And Handoff | Complete | 24 | 2026-06-10 | *** ## Completed Sessions * 2026-06-09 - Session 01: Protocol Suggestion Contract Parity (`packages/protocol`) completed. Canonical Quest Board suggestion contracts, snapshot event, accept/dismiss/scan/summary REST aliases, validation helpers, protocol tests, and README notes landed. Validation also fixed Vitest env-file isolation so ignored local `.env.local` values do not affect deterministic web tests. * 2026-06-09 - Session 02: Server Suggestion Manager And Persistence (`apps/server`) completed. The server now owns Quest Board suggestion state with local JSON persistence, dismissed-ID caps, freshness checks, summary aggregation, canonical `suggestion_update` emission, and shutdown flush wiring. Validation passed with focused server tests, server typecheck, and repo-root Vitest. * 2026-06-10 - Session 03: Suggestion Routes And WebSocket Parity (`apps/server`) completed. The server now ships the routed accept, dismiss, issue-dismiss, and summary endpoints under root and `/api`, emits canonical `suggestion_update` plus compatibility `idle_suggestion` frames, hydrates new WebSocket clients from manager state, and narrows unsupported-route claims to the still-unshipped scan engines. Validation passed with focused route and WebSocket tests plus server typecheck. * 2026-06-10 - Session 04: Idle Lifecycle Engine Parity (`apps/server`) completed. The server now triggers idle suggestion generation from hero-idle transitions, builds privacy-bounded idle context, enforces cooldown and in-flight guards, falls back deterministically on provider or parsing failure, stores typed suggestions through the manager, and broadcasts canonical plus compatibility Quest Board updates. Validation passed with repo-root Vitest, focused server tests, and server typecheck. * 2026-06-10 - Session 05: Session Summary Engine And Noise Filtering (`apps/server`) completed. The server now generates session follow-up summaries through a dedicated lifecycle coordinator, persists summary suggestions through the manager, and filters noisy analysis items at store and load time. Validation passed with focused summary/noise tests, server typecheck, and repo-root Vitest. * 2026-06-10 - Session 06: Codebase Issue Scanners (`apps/server`) completed. The server now has default-off TODO-family, git status, lint, build/typecheck, and test failure scanners that produce protocol-valid, capped, privacy-bounded codebase issues through `SuggestionManager.addCodebaseIssue`. Validation passed with focused scanner tests, full repo Vitest, lint, format check, and workspace typecheck. * 2026-06-10 - Session 07: Scan Orchestration And Quest Ignore Patterns (`apps/server`, `apps/web`) completed. The server now owns full, diff, and daily codebase scan orchestration with single-flight status, last-scan commit tracking, stale-startup triggering, and manager-owned persistence, while repo-level and Settings-backed ignore patterns are merged through `.factionos-questignore` and the scan payload. Validation passed with focused server and web tests plus server and web typechecks. * 2026-06-10 - Session 08: On-Demand Analysis And Project Scan Engines (`apps/server`) completed. The server now supports manager-owned on-demand analysis and project-level strategic scans with root and `/api` trigger/status routes, fresh-cache returns, single-flight conflict handling, fallback outputs, bounded provider timeouts, startup stale project scanning, and unsupported-route reconciliation. Validation passed with focused server tests and server typecheck plus repo-root Vitest. * 2026-06-10 - Session 09: Web Quest Board Typed Cards (`apps/web`) completed. The web Quest Board now normalizes canonical `suggestion_update` snapshots into typed multi-source cards, preserves legacy idle compatibility only until canonical state arrives, renders summary and status data, and keeps unsafe path payloads out of the UI. Validation passed with focused web tests, web typecheck, and repo-root Vitest. * 2026-06-10 - Session 10: Quest Actions And Keyboard Shortcuts (`apps/web`) completed. The web Quest Board now supports accept, dismiss, assign, manual scan triggers, reply focus, and the historical `1`/`2`/`3`/`Alt+X`/`Alt+R` shortcuts with duplicate-trigger prevention, optimistic feedback, and snapshot reconciliation. Validation passed with focused web tests, typecheck, lint, and repo-root Vitest. *** ## Next Workflow * Phase 18 is complete. Begin Phase Transition at `audit`. ## Session 11 Implementation Closeout * Stable docs now cover the Quest Board API, WebSocket snapshot, architecture, protocol ownership, server manager/engine boundaries, web cards/actions, privacy inventory, docs index routing, and prompt behavior. * `apps/server/src/lib/unsupportedRoutes.ts` no longer lists shipped Quest Board paths as planned unsupported route families. * Appendix A closeout classifications are recorded in `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/phase18-validation-record.md`. * Focused implementation evidence has passed for core Quest Board runtime, scan, analysis, project-scan, web card, action, and unsupported-route flows. * Broad format, lint, workspace typecheck, root test, ASCII/LF, secret scan, and diff checks passed during implementation closeout. * Remaining workflow work has concluded; Phase 18 exits the session-processing loop and begins Phase Transition. *** ## Objectives 1. Recover the persisted, actionable Quest Board model: a server-side suggestion manager with IDs, timestamps, accept/dismiss state, disk persistence, summary counts, and `suggestion_update` snapshots. 2. Recover the automatic idle-suggestion lifecycle: hero-idle triggered generation with transcript context, modified-file awareness, cooldown, in-flight guards, timeouts, and pattern-based fallbacks, plus session summaries with follow-up tasks. 3. Recover multi-source Quest Board cards: codebase issue scanners (TODO-family, git status, lint, build, tests), full/diff/daily scan orchestration, ignore patterns, on-demand analysis, and project scan, merged into typed web cards with accept/dismiss UI, hero assignment, and keyboard shortcuts. *** ## Prerequisites * Phase 17 completed (Notice Board parity establishes the contract-first, manager-owned persistence, and snapshot-event patterns this phase reuses). * Appendix A of this PRD reviewed as the feature inventory and EXAMPLES evidence index (the original audit document `docs/ongoing-projects/quest-board.md` is deleted). *** ## Technical Considerations ### Architecture * Contract-first: all shared suggestion, issue, analysis, project-scan, session-summary, snapshot-event, and route shapes land in `packages/protocol` before any package-specific behavior (Session 01), mirroring the Phase 17 approach. * Manager-owned state: a single server-side SuggestionManager owns state, filtering, dismissed-ID tracking, freshness, debounced atomic persistence, and shutdown flush. Engines (idle, session summary, codebase scan, analysis, project scan) write through the manager, never directly to disk or the socket layer. * Snapshot plus compat events: `suggestion_update` carries the full typed snapshot; the existing string-based `idle_suggestion` event remains as a compatibility emission until the web store fully migrates, and the unused `quest_board` protocol event is reconciled (implemented or formally retired) in Session 01. * Existing LLM boundary: all engine LLM calls go through the current `llmClient` abstraction and `llmPrivacy` approval rules. Historical child-process specifics (spawning `claude -p`, Haiku/Sonnet model flags, `--max-turns` budgets, `AGENTCRAFT_HAIKU_SUBPROCESS=1`, deleting `CLAUDECODE` from the child env) are evidence for timeout and turn-budget choices, not an implementation mandate. * Route family: the historical `/suggestions/*` family is implemented under current server conventions (Zod validation, rate limits, body caps) and removed from `unsupportedRoutes.ts` only as each route actually ships. ### Technologies * TypeScript across `packages/protocol`, `apps/server`, `apps/web` * Zod request validation on new routes * Vitest projects for protocol, server, and web coverage * Local JSON persistence under the FactionOS home directory (`suggestions.json`, atomic tmp-plus-rename writes, debounced saves) ### Risks * LLM-dependent engines are nondeterministic: keep parsing, filtering, fallback, and noise-filter logic pure and unit-testable with fixture responses; deterministic local fallback must produce schema-valid output. * Scan engines can be slow or noisy on large repos: scanners default off, issue counts are capped per category, ignore patterns apply consistently, and scans run with explicit status reporting. * New persisted file expands the personal-data surface: `suggestions.json` can contain file paths and code-derived text; it must be documented in the data inventory with a manual deletion path, and it widens the existing trusted-erasure no-claim rather than silently joining it. * Cross-package drift: suggestion shapes touch protocol, server, and web; shape changes must move together as in Phase 17 or compatibility drift returns. ### Relevant Considerations * \[P03-packages/protocol] **Protocol leads cross-package work**: Session 01 defines every shared shape before server or web sessions begin. * \[P17] **Notice Board parity is a shared contract**: the same coordinated cross-package discipline applies to suggestion shapes, routes, events, and UI; one-package changes will drift parity. * \[P17-apps/server] **Manager-owned persistence and cleanup**: the SuggestionManager owns filtering, pruning, debounce, and shutdown flush so test isolation stays predictable. * \[P17-apps/web] **Pure normalization before store mutation**: snapshot and event payloads are normalized by pure helpers before touching the Zustand store. * \[P01-apps/server] **Anthropic transfer is two-level opt-in**: idle, summary, analysis, and project-scan engines must not send prompts or file content to a provider without both the API key and `FACTIONOS_ALLOW_LLM_PROVIDER_TRANSFER=true`. * \[P03-apps/server] **Local server boundary must stay conservative**: every new `/suggestions/*` route ships with validation, rate limits, and body-size caps consistent with existing routes. * \[P07] **Redaction is boundary-specific**: suggestion text, issue messages, and persisted snapshots must avoid raw prompts, secrets, and broad absolute paths; scan output is minimized before storage and emission. * \[P17] **Do not expose raw lifecycle telemetry in coordination posts**: the same privacy-filtering discipline applies to automatically generated suggestions and session summaries. * \[P03] **Stable docs are the current contract**: `EXAMPLES/` and the preserved audit in Appendix A are traceability evidence only; no historical code or assets are imported. * \[P07] **Hosted services ship as disabled-default guardrails only**: historical suggestion telemetry and entitlement gating stay excluded. *** ## Success Criteria Phase complete when: * [x] All 11 sessions completed * [x] Quest Board state is server-owned, persisted, and hydrated via `suggestion_update` snapshots with accept/dismiss state surviving restarts * [x] Idle suggestions generate automatically on hero-idle transitions with transcript context, cooldown, in-flight guards, timeouts, and deterministic fallbacks * [x] Codebase issue scans (TODO-family, git status, lint, build, tests), full/diff/daily orchestration, ignore patterns, on-demand analysis, and project scan feed typed Quest Board cards * [x] Web Quest Board renders typed multi-source cards with accept, dismiss, hero assignment, action buttons, and keyboard shortcuts (1/2/3, Alt+X, Alt+R) * [x] Validation evidence, stable docs, privacy/data-inventory updates, and the Appendix A parity closeout are recorded *** ## Dependencies ### Depends On * Phase 17: Notice Board Coordination Parity ### Enables * Future phase: orchestration-queue integrations that consume accepted quests (executor work remains separately gated and out of scope here) *** ## Appendix A: Preserved Parity Audit (2026-06-07) > Preserved in full from `docs/ongoing-projects/quest-board.md` before its deletion. This appendix is the canonical evidence index for Phase 18. Scope of the original audit: compare the FactionOS "Quest board / Idle suggestions" implementation against the historical EXAMPLES codebase described by `EXAMPLES/README_examples.md`. The EXAMPLES tree is reference evidence only, never source code to import. Current-code line numbers are a snapshot as of 2026-06-07 and may drift. ### A.1 Current Implementation Snapshot (Pre-Phase) * `apps/web/src/components/QuestBoard.tsx:4` renders the "Quest board" / "Idle suggestions" panel from `questSuggestions`, shows an empty state, and displays up to six suggestion text cards. * `apps/web/src/store/useGameStore.ts:216` stores `questSuggestions` as `{ heroId, text }[]`. * `apps/web/src/store/useGameStore.ts:850` consumes only the `idle_suggestion` websocket event for Quest Board data and keeps the latest twelve strings. * `packages/protocol/src/events.ts:380` defines `idle_suggestion` as string prompts and `packages/protocol/src/events.ts:386` defines a `quest_board` event, but no current server or client flow uses `quest_board`. * `apps/server/src/routes/llm.ts:158` exposes `POST /llm/idle-suggestion`, emits `idle_suggestion`, and returns structured suggestions. * `apps/server/src/llm/engines/idleSuggestionEngine.ts:30` generates up to three suggestions from caller-provided context and drops generic output. * `apps/server/src/llm/prompts/idle-suggestion-engine.md:1` documents a richer intended idle engine, including mission-complete triggering, throttling, card clicks, and keyboard shortcuts that are not implemented in current code. * `apps/web/src/components/SettingsDrawer.tsx:612` has a manual "Codebase scan" settings section, but scan results do not feed the Quest Board. ### A.2 Parity Matrix (First Pass) Status legend: `Present` = current behavior covers the historical feature; `Partial` = some related behavior, material gaps remain; `Missing` = no current equivalent found. | Feature / functionality in EXAMPLES | Status | Current coverage (2026-06-07) | Historical reference location | | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Idle suggestion prompt guardrails: only concrete next-step work, no generic "run tests/review code/improve performance" suggestions, max 3 suggestions. | Partial | Forbidden pattern filtering and cap of 3 at `apps/server/src/llm/engines/idleSuggestionEngine.ts:5` and `:30`. UI receives only strings via `apps/server/src/routes/llm.ts:172`, so `title`, `category`, and `priority` are dropped. | `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:13`, `:28`; `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` around `generateLlmSuggestions` / `parseSuggestions`. | | Automatic idle generation after mission completion when a hero is idle (corrected by A.4: trigger is hero status transition to idle). | Missing | Real server generates only on `POST /llm/idle-suggestion`. Only automatic-looking source is mock data at `apps/server/src/managers/mockEventGenerator.ts:198`. No lifecycle listener calls the idle engine. | `EXAMPLES/findings/architecture.md:261`; `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:9`; `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` around `generateSuggestions`. | | Transcript-aware context building from recent session messages. | Missing | Route requires caller-provided `lastUserTask` and `recentActivity` at `apps/server/src/routes/llm.ts:159`. No current code reads a transcript for idle suggestions. | `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` around `readTranscript`, `buildContext`, `generateSuggestions`; `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:15`. | | Modified-file awareness for idle suggestions. | Missing | Prompt built only from request-body text at `apps/server/src/llm/engines/idleSuggestionEngine.ts:35`. | `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` top-level modified-file extraction regex and around `buildContext`; `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:17`. | | In-flight guard and cooldown for idle suggestion generation. | Missing | No in-flight session set or cooldown state. Prompt file mentions throttling at `apps/server/src/llm/prompts/idle-suggestion-engine.md:4` but runtime does not enforce it. | `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` fields `inFlightSessions`, `lastGenerationTime`, `COOLDOWN_MS=6e4`; `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:42`. | | LLM timeout and active process cleanup for idle suggestions. | Missing | Current `complete()` call has no engine-specific process tracking or timeout at `apps/server/src/llm/engines/idleSuggestionEngine.ts:43`. | `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` fields `activeHaikuProcesses`, `CLAUDE_TIMEOUT_MS=18e3`, cleanup in `cleanup()`. | | Pattern-based fallback suggestions when LLM returns nothing or fails. | Missing | `llmClient` has canned local fallback output, but it returns an object shape the current `safeParseArray` does not accept, so the idle engine returns no suggestions in that path. Sanitizer at `apps/server/src/llm/engines/idleSuggestionEngine.ts:53`. | `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` around `analyzeContextForSuggestion`, fallback patterns, and the fallback branch in `generateSuggestions`. | | Persistent suggestion manager backed by `~/.factionos/suggestions.json`. | Missing | Quest Board state is browser store memory plus event hydration. No server-side suggestion persistence. | `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/troubleshooting.md:144`, `:247`; `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `loadFromDisk`, `doSave`, `emitUpdate`. | | Suggestion IDs, session IDs, created-at timestamps, and per-session max idle suggestions. | Missing | Suggestions have only `heroId` and `text` at `apps/web/src/store/useGameStore.ts:216`. | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around constructor fields and `setIdleSuggestions`; `MAX_SUGGESTIONS_PER_SESSION=1`. | | `suggestion_update` websocket snapshot with idle suggestions, codebase issues, session summaries, analysis result, and project scan. | Missing | Protocol lists `idle_suggestion` and an unused `quest_board`; no `suggestion_update` event or snapshot state. | `EXAMPLES/findings/websocket-events.txt:53`, `:139`; `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `emitUpdate` and `getCurrentState`; `EXAMPLES/package-0.4.1/frontend/dist/assets/index-CuYaJ5lV.js:2` around `suggestion_update`. | | Accept idle suggestion from a card, route it to a hero or prompt pipeline. | Missing | Cards are non-clickable `
` elements at `apps/web/src/components/QuestBoard.tsx:26`. No accept route exists. | `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:81`; `EXAMPLES/findings/api-routes.txt:151`; `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `acceptSuggestion` and `acceptQuest`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `POST /suggestions/:suggestionId/accept`. | | Dismiss individual suggestions. | Missing | No dismiss control and no server route for dismissal. | `EXAMPLES/findings/api-routes.txt:152`; `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `dismissSuggestion`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `POST /suggestions/:suggestionId/dismiss`. | | Dismiss all idle suggestions with `Alt+X`. | Missing | Shortcut routing ignores Alt combinations at `apps/web/src/lib/useKeyboardShortcuts.ts:139`. | `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:88`; `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/keyboard-shortcuts.md:76`; `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md:309`. | | Accept top three suggestions with keyboard shortcuts `1`, `2`, and `3`. | Missing | No numeric suggestion acceptance at `apps/web/src/lib/useKeyboardShortcuts.ts:33`. | `EXAMPLES/findings/llm-prompts/idle-suggestion-engine.md:86`; `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/keyboard-shortcuts.md:72`; `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md:307`. | | Focus reply/composer input with `Alt+R`. | Missing | Shortcut help has `r` for demo reply; no `Alt+R` composer focus. Alt shortcuts skipped at `apps/web/src/lib/useKeyboardShortcuts.ts:139`. | `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/keyboard-shortcuts.md:78`; `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md:312`. | | Side-panel suggestion cards stacked under the selected hero / composer. | Missing | Board is a global dashboard widget at `apps/web/src/components/QuestBoard.tsx:10`, not selected-hero side-panel cards. | `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md:101`, `:307`; `EXAMPLES/package-0.4.1/frontend/dist/assets/index-CuYaJ5lV.js:2` around the side-panel component receiving `suggestions`, `onAcceptSuggestion`, `onDismissSuggestion`. | | Hero roster integration for idle suggestion actions. | Missing | Roster not found passing suggestion actions; Quest Board renders separately. | `EXAMPLES/package-0.4.1/frontend/dist/assets/index-CuYaJ5lV.js:2` around hero roster props `idleSuggestions`, `onExecuteSuggestion`, `onDismissSuggestion`. | | Multi-source Quest Board cards: idle suggestions, codebase issues, on-demand analysis, project scan, and session follow-ups. | Missing | Quest Board renders only idle suggestion strings. | `EXAMPLES/findings/architecture.md:153`; `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` fields `idleSuggestions`, `codebaseIssues`, `sessionSummaries`, `analysisResult`, `projectScan`; `EXAMPLES/package-0.4.1/frontend/dist/assets/index-CuYaJ5lV.js:2` around the Quest surface merging `codebaseIssues`, `analysisResult`, `projectScan`. | | Quest-card metadata: source type, category/type, severity/priority, file path, line, title/message, suggested prompt (and `suggestedAgentType`, per A.3). | Missing | Card model is text-only at `apps/web/src/store/useGameStore.ts:216` and `apps/web/src/components/QuestBoard.tsx:31`. | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `acceptQuest`; `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `parseTodoOutput`, `scanGitStatus`, `scanBuild`, `scanTests`; `EXAMPLES/package-0.4.1/server/dist/onDemandAnalysisEngine.js:1` around `parseAnalysisResponse`; `EXAMPLES/package-0.4.1/server/dist/projectScanEngine.js:1` around `parseProjectScanResponse`. | | Codebase issue scanning for TODO/FIXME comments (expanded by A.4 to five markers). | Missing | Current scan walks recent files and sends snippets to the LLM at `apps/server/src/lib/codebaseWalker.ts:135` and `apps/server/src/routes/llm.ts:119`. No TODO/FIXME categorization into Quest Board issues. | `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `scanTodos`, `scanTodosInFiles`, `parseTodoOutput`. | | Codebase issue scanning for dirty git status. | Missing | No git-status issue scanner. | `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `scanGitStatus`. | | Codebase issue scanning for lint errors. | Missing | No lint scan. | `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `scanLint`. | | Codebase issue scanning for build / TypeScript errors. | Missing | No build-error scanner. | `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `scanBuild`. | | Codebase issue scanning for test failures. | Missing | No test-failure scanner. | `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `scanTests`. | | Full and diff codebase scans with scan status. | Missing | Manual scan has local UI state only at `apps/web/src/components/SettingsDrawer.tsx:241`; no reusable `/suggestions/scan/status` equivalent. | `EXAMPLES/findings/api-routes.txt:154`, `:155`; `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `runFullScan`, `runDiffScan`, `getLastScanTime`, `isScanningNow`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `POST /suggestions/scan` and `GET /suggestions/scan/status`. | | Daily/background codebase scan when stale or git HEAD changes. | Missing | Scan is user-triggered from Settings. | `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` around `shouldRunDailyScan`, `getGitHead`, `getChangedFilesSince`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` near startup daily codebase scan wiring. | | On-demand analysis route integrated into persisted Quest Board results. | Partial | `apps/server/src/routes/llm.ts:61` has `POST /llm/analyze`, but it needs caller-provided files and only emits an opaque `mission_event`; results are not stored in Quest Board state. | `EXAMPLES/findings/api-routes.txt:153`, `:156`; `EXAMPLES/package-0.4.1/server/dist/onDemandAnalysisEngine.js:1` around `runAnalysis`, `getRecentModifiedFiles`, `parseAnalysisResponse`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `POST /suggestions/analyze` and `GET /suggestions/analyze/status`. | | Project-level strategic scan with 2-4 high-impact improvements. | Missing | No project scan route, engine, status, or Quest Board ingestion. | `EXAMPLES/findings/api-routes.txt:157`; `EXAMPLES/package-0.4.1/server/dist/projectScanEngine.js:1` around `runProjectScan`, `shouldRunDailyScan`, `parseProjectScanResponse`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `POST /suggestions/project-scan` and `GET /suggestions/project-scan/status`. | | Manual Quest Board action buttons for codebase scan, on-demand analysis, and project scan. | Missing | Settings has a manual codebase scan; Quest Board has no trigger controls. | `EXAMPLES/package-0.4.1/frontend/dist/assets/index-CuYaJ5lV.js:2` around Quest panel props `onTriggerCodebaseScan`, `onTriggerAnalysis`, `onTriggerProjectScan`. | | Quest summary endpoint with counts and severity buckets. | Missing | UI displays only `questSuggestions.length` at `apps/web/src/components/QuestBoard.tsx:16`. No summary endpoint. | `EXAMPLES/findings/api-routes.txt:158`; `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `getSummary`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `GET /suggestions/summary`. | | Codebase issue dismissal and dismissed-ID tracking. | Missing | No issue dismissal path or server-side dismissed issue set. | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `dismissIssue` and dismissed issue sets; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `POST /issues/:issueId/dismiss`. | | Quest accept path for codebase issues, including `sourceType: "quest_board"`. | Missing | Cards are idle strings only; no accept API. (Corrected by A.4: latent even in EXAMPLES; excluded from parity target.) | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `acceptQuest`. | | Quest ignore patterns in Settings. | Missing | Settings store has `scanRoot` but no `questIgnorePatterns` field at `apps/web/src/store/useSettingsStore.ts:61`. | `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/SKILL.md:319`; `EXAMPLES/package-0.4.1/frontend/dist/assets/SettingsModal-C8trQV74.js:1` around `questIgnorePatterns` state and "Quest Ignore Patterns" UI. | | `.agentcraftignore` support merged with Settings ignore patterns. | Missing | Codebase walker has fixed ignored directories at `apps/server/src/lib/codebaseWalker.ts:84`; no ignore-file or user pattern loader. | `EXAMPLES/package-0.4.1/server/dist/questIgnore.js:1` around `loadQuestIgnorePatterns` and `shouldIgnorePath`; `EXAMPLES/package-0.4.1/frontend/dist/assets/SettingsModal-C8trQV74.js:1` around text explaining `.agentcraftignore` merging. | | Quest Board troubleshooting behavior for wrong project selection / project filtering. | Partial | Scan root settable in Settings and privacy-validated at `apps/server/src/lib/llmPrivacy.ts:89`, but suggestions are not project-filtered persisted objects. | `EXAMPLES/1st-pass-artifacts/skills/factionos-guide/references/troubleshooting.md:130`, `:141`. | | Session summaries and follow-up suggestions attached to completed work. | Missing | No `sessionSummary` or follow-up store. | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `setSessionSummary`; `EXAMPLES/package-0.4.1/server/dist/idleSuggestionEngine.js:1` around `parseCombinedResponse` and storing `followUps`. | | Freshness windows for cached analysis and project scan results. | Missing | `/llm/analyze` and `/llm/scan-codebase` return request-scoped results only. | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` around `setAnalysisResult` freshness of 30 minutes and `setProjectScan` freshness of 24 hours. | | Rate-limited suggestion analysis and scan routes. | Missing | `/llm/idle-suggestion`, `/llm/analyze`, `/llm/scan-codebase` have no Quest-specific rate limit/status semantics. | `EXAMPLES/package-0.4.1/server/dist/index.js:1` around `/suggestions/analyze`, `/suggestions/scan`, `/suggestions/project-scan` route middleware. | | Historical `/suggestions/*` API family. | Missing | Supported route is `/llm/idle-suggestion`; `apps/server/src/lib/unsupportedRoutes.ts:94` treats historical `/suggestions` routes as planned/unsupported. | `EXAMPLES/findings/api-routes.txt:149`; `EXAMPLES/package-0.4.1/server/dist/index.js:1` around all `/suggestions` route registrations. | ### A.3 Second-Pass Gap Review: Newly Identified Services And Components A direct re-read (2026-06-07) of the EXAMPLES server engines, the `index.js` route/trigger wiring, the analytics layer, and the frontend bundle surfaced items the first-pass matrix did not capture or captured imprecisely. Every item was confirmed by reading the referenced file. | Feature / functionality in EXAMPLES | Status | Notes | Historical reference location | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Dedicated **SessionSummaryEngine** service (separate from the idle engine): on session end, reads the transcript, extracts modified files, calls Haiku for 1-2 follow-up tasks, stores them as a session summary. Own in-flight guard, active-process map, 15s timeout. Follow-up categories: `test`, `documentation`, `refactor`, `validation`. | Missing | First pass only noted `setSessionSummary` and the inline `parseCombinedResponse` path inside the idle engine. | `EXAMPLES/package-0.4.1/server/dist/sessionSummaryEngine.js:1` - `generateSessionSummary`, `_generateSessionSummaryImpl`, `callHaiku`, `HAIKU_TIMEOUT_MS=15e3`, `inFlightSessions`, `activeHaikuProcesses`. | | **Analysis noise filter**: drops analysis/scan items that are model self-talk about truncation ("incomplete file", "cut off", "truncat", "unable to read", "needs more context", "partial file"). Applied when setting analysis results and again on load-from-disk. | Missing | No current sanitizer rejects truncation / "can't read file" items; `/llm/analyze` has no equivalent filter. | `EXAMPLES/package-0.4.1/server/dist/analysisNoiseFilter.js:1` - `isNoiseAnalysisItem`; consumed in `suggestionManager.js:1` (`setAnalysisResult`, `loadFromDisk`) and `onDemandAnalysisEngine.js:1` (`parseAnalysisResponse`). | | **Suggestion-engine entitlement / feature gate**: `/suggestions/analyze` gated behind a `SUGGESTION_ENGINE` ("suggestion\_engine") feature; when not entitled returns HTTP 403 with `upgrade:true` and records a `suggestion_engine_blocked` event. | Excluded (phase decision) | No feature gate, entitlement check, or upgrade response exists in current code; grep for `SUGGESTION_ENGINE`/`featureGate`/`entitlement` in `apps/`/`packages/` returns nothing. | `EXAMPLES/package-0.4.1/server/dist/featureGates.js:1` - `SUGGESTION_ENGINE:"suggestion_engine"`; gate enforced in `index.js:1` at the `POST /suggestions/analyze` handler. | | **Suggestion telemetry**: analytics events `suggestion_generated`, `suggestion_accepted`, `suggestion_dismissed` (carrying `suggestion_id`), plus `recordSuggestionAccepted()` on the accept route. | Excluded (phase decision) | No suggestion analytics events in current code (grep for \`suggestion\_(accepted | dismissed | | **Accept routing semantics**: accepting a suggestion either (a) targets an internal hero - returns `action:"send_prompt"` with `endpoint:/internal-heroes/{heroId}/prompt`, after verifying the hero exists - or (b) broadcasts a `user_prompt` websocket message and returns `action:"prompt_sent"`. | Missing | Cards are non-interactive; no accept endpoint or hero/prompt routing. | `EXAMPLES/package-0.4.1/server/dist/index.js:1` - `POST /suggestions/:suggestionId/accept` body (`acceptSuggestion`, `send_prompt` vs `user_prompt` branches). | | **"Assign / execute quest to a chosen idle hero" UI flow**: side panel can route a suggestion to a specific idle hero, not just accept-in-place. | Missing | No assign-to-hero control on the current board. | `EXAMPLES/package-0.4.1/frontend/dist/assets/index-CuYaJ5lV.js:2` - strings "Assign to idle hero:", "Assign to an idle hero", "Failed to assign quest to hero:", "Failed to execute suggestion", `onExecuteSuggestion`. | | **Codebase-issue per-card `suggestedAgentType`** (e.g. `general-purpose`, `Bash`): each scanned issue carries the agent type best suited to fix it, used when spawning the fix. | Missing | First-pass card-metadata row omitted `suggestedAgentType`. Current card model is text-only. | `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` - `suggestedAgentType` set in `parseTodoOutput`, `scanGitStatus`, `scanLint`, `scanBuild`, `scanTests`. | | **Incremental issue API + issue queries**: `addCodebaseIssue` (dedupes by `type`+`filePath`+`line`), `getIssuesByType`, `getIssuesBySeverity`, `clearIssuesByType`. | Missing | First pass only referenced bulk `setCodebaseIssues`. | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` - `addCodebaseIssue`, `getIssuesByType`, `getIssuesBySeverity`, `clearIssuesByType`. | | **Bounded dismissed-ID sets**: dismissed suggestion and issue IDs capped at `MAX_DISMISSED=100` with FIFO eviction (`capDismissedSet`); both sets persist to disk. | Missing | First-pass dismissal rows did not note the cap or persistence; no current dismissed-ID store at all. | `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` - `static MAX_DISMISSED=100`, `capDismissedSet`, persisted `dismissedSuggestionIds`/`dismissedIssueIds`. | | **Daily/background scan on server start**: at startup the server runs a full codebase scan and a project scan when each is stale (`shouldRunDailyScan`). | Missing | First pass listed daily scan as a concept but not the concrete server-start wiring. | `EXAMPLES/package-0.4.1/server/dist/index.js:1` - "Running daily codebase scan on server start" -> `runFullScan()`, "Running daily project scan on server start" -> `runProjectScan()`. | | **QuestLogPanel is a distinct surface** (Active/Completed quests with agents plus started/completed timestamps) and must not be conflated with the Quest Board. | N/A (clarification) | Current code has a separate mission/quest log concept; this phase is scoped to the idle-suggestion Quest Board only. | `EXAMPLES/package-0.4.1/frontend/dist/assets/QuestLogPanel-DjBIg6EU.js:1` - strings "Quest Log", "Active Quests", "Completed", "No active quests". | ### A.4 Second-Pass Refinements And Corrections * **Idle trigger mechanism** (refines the "Automatic idle generation" row): the historical trigger is a hero status transition to `"idle"`, not a mission-complete callback. On that transition the server calls `generateSuggestions(sessionId, heroId, force=true, spawnFn, inMemoryMessages)`. The `spawnFn` is executor-aware (`mr(executorType, workingDir)`), and for `opencode`/`cursor` executors an in-memory message slice (`getMessages(sessionId, 30)`) is passed as a transcript fallback. Reference: `EXAMPLES/package-0.4.1/server/dist/index.js:1` (the `s==="idle"&&o.sessionId` branch) and `idleSuggestionEngine.js:1` (`generateSuggestions` cooldown/in-flight guard plus `spawnFn` param). * **TODO/FIXME scan is broader and quality-filtered**: it matches five markers - TODO, FIXME, HACK, XXX, BUG - with severity mapping (FIXME/BUG -> warning, HACK/XXX -> warning, TODO -> info), caps at `maxIssuesPerCategory=50`, and runs two quality filters: `isLikelyFalsePositive` (rejects markers embedded in identifiers or inside unbalanced quotes/strings) and `isEmptyMessage`. Reference: `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` - `scanTodos`, `scanTodosInFiles`, `parseTodoOutput`, `isLikelyFalsePositive`, `isEmptyMessage`. * **Scan options default OFF**: all five scanners (`scanTodos`, `scanGitStatus`, `scanLint`, `scanBuild`, `scanTests`) default to `false` and must be explicitly enabled via options. Reference: `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` - the default options object. * **Commit-aware full vs diff scan**: diff scan uses the stored `lastCodebaseScanCommit` plus `getChangedFilesSince(commit)` (combining `git diff` working/staged/committed), reuses `cachedTodoIssues` for unchanged files, and falls back to a full scan when there is no prior commit or the cache is empty. `POST /suggestions/scan?full=true` forces a full scan. Reference: `EXAMPLES/package-0.4.1/server/dist/codebaseScanEngine.js:1` - `runDiffScan`, `getChangedFilesSince`, `getGitHead`, `cachedTodoIssues`; `index.js:1` - the `?full=true` branch. * **Engine model / turns / timeout specifics**: idle and session-summary use Haiku with `--max-turns 1` (18s and 15s timeouts respectively); on-demand analysis and project scan use Sonnet with `--max-turns 15` and a 240s timeout. All spawn `claude -p` with env `AGENTCRAFT_HAIKU_SUBPROCESS=1` and delete `CLAUDECODE` from the child env. References: `idleSuggestionEngine.js:1` (`CLAUDE_TIMEOUT_MS=18e3`), `sessionSummaryEngine.js:1` (`HAIKU_TIMEOUT_MS=15e3`), `onDemandAnalysisEngine.js:1` (`TIMEOUT_MS=24e4`, `--model sonnet`), `projectScanEngine.js:1` (`TIMEOUT_MS=24e4`, `--model sonnet`). * **On-demand analysis card shape and input selection**: input files come from `git diff HEAD~10 HEAD` (fallback `git diff HEAD`), filtered to code extensions with `node_modules`/lockfiles excluded, sliced to 10. Item `type` is one of `potential_bug|error_handling|code_style|refactoring| performance|feature_idea|enhancement` with validated `priority`. Reference: `EXAMPLES/package-0.4.1/server/dist/onDemandAnalysisEngine.js:1` * `getRecentModifiedFiles` (top-level fn), `validateType`, `validatePriority`. * **Project-scan card shape**: each item has `title`, `description`, `prompt`, `category` (`architecture|dependencies|performance|security|testing|feature_idea`), `effort` (`small|medium|large`), and `priority`; capped at 4 items. Reference: `EXAMPLES/package-0.4.1/server/dist/projectScanEngine.js:1` - `parseSurveyResponse`, `validateCategory`, `validateEffort`. * **Freshness windows**: analysis result is fresh for 30 minutes (`1800*1e3`); project scan and codebase scan for 24 hours (`1440*60*1e3`). Reference: `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` - `isAnalysisFresh`, `isProjectScanFresh`, `isCodebaseScanFresh`. * **Persistence is atomic and debounced**: saves are debounced \~1s and written via a `suggestions.json.tmp` plus `rename` swap, with a `destroy()` that flushes a pending save on shutdown. Reference: `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` - `saveToDisk`, `doSave`, `destroy`. * **`acceptQuest` is defined but unwired** (correction to the "Quest accept path for codebase issues" row): `suggestionManager.acceptQuest` (which returns `sourceType:"quest_board"` for codebase issues) exists but is not called anywhere in `index.js`; the live accept route uses `acceptSuggestion` (idle suggestions only), and codebase issues expose only a dismiss route (`POST /issues/:issueId/dismiss`). Even in EXAMPLES, accepting a codebase issue as a quest was latent, not shipped. Reference: `EXAMPLES/package-0.4.1/server/dist/suggestionManager.js:1` (`acceptQuest`) vs `index.js:1` (no `acceptQuest` call; only `/issues/:issueId/dismiss`). * **Supporting modules behind the idle engine**: idle/session-summary context comes from `transcriptReader.js` (`readTranscript(sessionId, _, 30)`), with `transcriptMiner.js` adjacent; modified-file extraction uses the shared regex set in both `idleSuggestionEngine.js` and `sessionSummaryEngine.js`. No current equivalent transcript reader feeds idle suggestions. Reference: `EXAMPLES/package-0.4.1/server/dist/transcriptReader.js:1`, `transcriptMiner.js:1`. ### A.5 Current Features Comparable Or Better Than EXAMPLES * The current REST route validates idle-suggestion request bodies with Zod at `apps/server/src/routes/llm.ts:159`, while the historical route family evidence is bundled and harder to inspect for equivalent request validation. * Current codebase scanning has explicit privacy approval for scan roots at `apps/server/src/lib/llmPrivacy.ts:89`, including refusal of filesystem root scans and roots outside approved project paths. This must be preserved by all new scan engines. * Current docs already expose `/llm/idle-suggestion` at `docs/api/README_api.md:273`, while historical `/suggestions/*` routes are intentionally marked unsupported at `apps/server/src/lib/unsupportedRoutes.ts:94`. ### A.6 Audited Implementation Order And Session Mapping The audit recommended this parity order, which maps onto the Phase 18 sessions as follows: 1. Server-side Quest/Suggestion manager with persistent IDs, accept/dismiss APIs, summary state, and `suggestion_update` snapshots -> Sessions 01-03. 2. Idle generation wired to hero-idle lifecycle events with transcript context, modified-file extraction, cooldown, and fallback heuristics -> Sessions 04-05. 3. Client Quest Board data model upgraded from text-only cards to typed cards with source, title, prompt, category, priority/severity, timestamps, and actions -> Session 09. 4. Accept/dismiss UI and shortcuts: card click, `1`/`2`/`3`, `Alt+X`, `Alt+R` -> Session 10. 5. Codebase issue scans integrated into Quest Board state: TODO/FIXME, git dirty, lint, build, tests, full/diff scan modes, status, dismissed IDs -> Sessions 06-07. 6. Quest ignore settings plus ignore-file support applied consistently to scan, analysis, and project scan engines -> Session 07. 7. On-demand analysis and project strategic scan engines/routes/statuses merged into Quest Board cards -> Session 08. ### A.7 Bottom Line (As Audited) The pre-phase Quest Board covers only the lowest-level visual surface for idle suggestion text. It does not match the historical EXAMPLES system's action model, persistence, automatic idle lifecycle, keyboard flow, multi-source Quest Board, codebase scan engines, ignore settings, or `/suggestions/*` API family. The largest functional gap is that EXAMPLES treated the Quest Board as a persisted, actionable orchestration queue, while pre-phase FactionOS treats it as a transient display list fed by `idle_suggestion` events. ### A.8 Phase 18 Closeout Status Session 11 records the final Appendix A classifications in `.spec_system/specs/phase18-session11-validation-documentation-and-handoff/phase18-validation-record.md`. The closeout status is source-backed and scoped to the Phase 18 charter: * Shipped: server-owned suggestion manager, `suggestions.json` persistence, `suggestion_update` snapshots, idle lifecycle, session summaries, codebase scanners, scan orchestration, ignore patterns, on-demand analysis, project scan, typed web cards, card actions, issue dismissal, route statuses, freshness windows, fallback paths, and keyboard shortcuts. * Shipped with FactionOS-specific wording: bounded context replaces raw transcript evidence, `.factionos-questignore` is the supported ignore-file name, and rate limiting is inherited from shared local server middleware. * Shipped internally only: manager issue query/clear helpers exist for server orchestration, but only issue dismissal is externalized as a route. * Deliberately excluded: suggestion telemetry, suggestion-engine entitlement gates, codebase issue accept-as-quest/executor flow, and side-panel layout parity beyond the shipped global Quest Board. * Clarification: QuestLogPanel remains a distinct surface and is not part of the idle-suggestion Quest Board parity target. --- # 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/phases/phase_18/prd_phase_18.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.