> 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/phase02-session04-battlefield-state-and-interaction-polish/implementation-notes.md). # Implementation Notes **Session ID**: `phase02-session04-battlefield-state-and-interaction-polish` **Package**: apps/web **Started**: 2026-05-29 08:21 **Last Updated**: 2026-05-29 08:44 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 21 / 21 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Baseline Commands * `bash .spec_system/scripts/analyze-project.sh --json` - passed; current session resolved to `phase02-session04-battlefield-state-and-interaction-polish`. * `bash .spec_system/scripts/check-prereqs.sh --json --env` - passed. * `bash .spec_system/scripts/check-prereqs.sh --json --env --package apps/web` - passed. * `node --version && npm --version` - Node v24.14.0 and npm 10.5.1 available. * `npm run test -- apps/web/tests/Battlefield.test.tsx apps/web/tests/battlefield2d.test.ts apps/web/tests/achievementCelebration.test.ts` - passed; 3 files and 24 tests. *** ## Validation Commands * `npx biome format --write apps/web/src/components/battlefield/Battlefield.tsx apps/web/src/components/battlefield/achievementCelebration.ts apps/web/src/lib/battlefield2d.ts apps/web/src/index.css apps/web/tests/Battlefield.test.tsx apps/web/tests/BattlefieldInteraction.test.tsx apps/web/tests/battlefield2d.test.ts apps/web/tests/achievementCelebration.test.ts` - passed; fixed 2 files. * `npm run test -- apps/web/tests/Battlefield.test.tsx apps/web/tests/BattlefieldInteraction.test.tsx apps/web/tests/battlefield2d.test.ts apps/web/tests/achievementCelebration.test.ts` - passed; 4 files and 42 tests. * `npm run test -- apps/web/tests/HeroMissionWorkflow.test.tsx apps/web/tests/HeroRosterSort.test.tsx apps/web/tests/HeroDetailDrawer.test.tsx apps/web/tests/HeroCard.test.tsx` - passed; 4 files and 55 tests. * `npm --workspace apps/web run typecheck` - passed. * `npx biome lint apps/web/src/components/battlefield/Battlefield.tsx apps/web/src/components/battlefield/achievementCelebration.ts apps/web/src/lib/battlefield2d.ts apps/web/src/index.css apps/web/tests/Battlefield.test.tsx apps/web/tests/BattlefieldInteraction.test.tsx apps/web/tests/battlefield2d.test.ts apps/web/tests/achievementCelebration.test.ts` - passed. * `npx biome format apps/web/src/components/battlefield/Battlefield.tsx apps/web/src/components/battlefield/achievementCelebration.ts apps/web/src/lib/battlefield2d.ts apps/web/src/index.css apps/web/tests/Battlefield.test.tsx apps/web/tests/BattlefieldInteraction.test.tsx apps/web/tests/battlefield2d.test.ts apps/web/tests/achievementCelebration.test.ts` - passed. * `rg -nP '[^\\x00-\\x7F]' ...touched files...` - passed; no non-ASCII matches. *** ## Manual Battlefield Smoke Notes * Started Vite dev server with `npm --workspace apps/web run dev -- --host 127.0.0.1 --port 5173`. * Browser smoke opened `http://127.0.0.1:5173/`, selected a first-run faction when prompted, and reached the battlefield board. * Board rendered with nonzero dimensions: 543 x 306 at a 1280 x 820 viewport. * Background state was `loaded`; connection state was `offline`, with one expected refused local WebSocket console message because no local server was running. * Rendered 3 battlefield tokens and 3 static state badges. * Selecting a battlefield token opened hero detail; closing hero detail cleared the selected battlefield label. * Smoke screenshot: `/tmp/factionos-battlefield-smoke.png`. *** ## Source Audit * `Battlefield.tsx` already renders hero tokens as native buttons with `aria-pressed`, click selection, empty-board clearing, background fallback, faction-initial fallback, and achievement bursts. * `useGameStore.openHeroDetail` revalidates selected hero ids and clears stale mission selection when a newly selected hero does not match the selected mission. * `battlefield2d.ts` clamps x/z coordinates and expands world limits for server-spawned rings, but label placement remains component-local and needs explicit helper coverage. * `achievementCelebration.ts` exposes deterministic vectors and tone mapping, but cap and cleanup behavior currently live in `Battlefield.tsx`. * `index.css` distinguishes several states with color, ring, ping, and animation, but static text/state marks are not present on every token. * `docs/battlefield.md` documents the 2D DOM battlefield and public-demo boundary, but needs updated state labels, positioning bounds, and Session 05 ownership notes after implementation. *** ## Open Risks * Token state readability can still become color-only if static state labels are not visible without hover. * Achievement timers can leave stale timer ids in the ref after individual bursts expire unless cleanup prunes them. * Public-demo asset parity belongs to Session 05, so this session must not change public-demo behavior while documenting the boundary clearly. *** ## Battlefield Contract Audit | Contract Area | Current State | Implementation Gap | | --------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Native controls | Hero tokens are `button` elements with `aria-pressed`, click selection, and empty-board clear behavior. | Harden accessible names with selection and mission context tests. | | State treatment | CSS ring, color, ping, dimming, and animation cover several hero states. | Add always-present static labels or badges for active, awaiting input, verifying, error, spawning, dismissed, selected, and idle. | | Positioning | `battlefield2d.ts` clamps x/z and expands world limits for spawned rings. | Move label placement into a tested helper and cover top, bottom, missing, non-finite, and outlying inputs. | | Fallbacks | CSS fallback background and faction initials exist after image errors. | Add explicit board/asset state attributes and focused tests for loading, error, empty, and offline-readable states. | | Reduced motion | Store-driven class disables loop and burst animations. | Preserve static state labels, rings, selection halo, and reduced-motion achievement output in tests. | | Achievements | Fresh unlocks render DOM bursts and lifetime timers remove them. | Enforce cap behavior, clear all timers on unmount, and prune timer ids after expiration. | | Documentation | `docs/battlefield.md` documents the DOM/CSS battlefield and public-demo boundary. | Update final contract after code changes and keep Session 05 asset parity explicitly deferred. | *** ## Design Decisions ### Decision 1: Keep interaction store-owned and component-local **Context**: Battlefield, roster, and detail already share `selectedHeroId` through `useGameStore`. **Options Considered**: 1. Add a battlefield-local selection state - more moving parts and stale-state risk. 2. Keep selection in `useGameStore` and harden component labels/events - matches current contract. **Chosen**: Keep selection in `useGameStore`. **Rationale**: It preserves existing synchronization with roster, mission detail, and hero detail while keeping this session scoped to app-side battlefield polish. ### Decision 2: Preserve approved DOM/CSS 2D battlefield **Context**: PRD, ADRs, and docs exclude Three.js, WebGL, canvas physics, and unknown media promotion for this phase. **Options Considered**: 1. Replace battlefield rendering or assets - out of scope and risks Session 05 asset parity. 2. Add inspectable data attributes, labels, helper tests, and CSS state marks - matches Session 04. **Chosen**: Preserve the current DOM/CSS battlefield and approved app assets. **Rationale**: The active contract is local-first, accessible, asset-driven, and testable without new runtime dependencies. *** ## Task Log ### 2026-05-29 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Package prerequisites confirmed for `apps/web` * [x] Tools available * [x] Directory structure ready *** ### Task T001 - Verify prerequisites and baseline focused tests **Started**: 2026-05-29 08:21 **Completed**: 2026-05-29 08:22 **Duration**: 1 minute **Notes**: * Confirmed Session 01, Session 02, and Session 03 are complete in spec state. * Confirmed active package context is `apps/web`. * Ran existing focused battlefield component, coordinate helper, and celebration helper tests before edits. **Files Changed**: * `.spec_system/specs/phase02-session04-battlefield-state-and-interaction-polish/implementation-notes.md` - created implementation evidence log. **BQC Fixes**: * N/A - verification only. *** ### Task T002 - Create implementation notes **Started**: 2026-05-29 08:22 **Completed**: 2026-05-29 08:24 **Duration**: 2 minutes **Notes**: * Added baseline commands, source audit, open risks, and initial design decisions. * Reviewed local-first and quarantined-media ADRs to keep implementation inside app-side Session 04 boundaries. * Confirmed app-side changes should remain inside `apps/web` plus stable battlefield documentation. **Files Changed**: * `.spec_system/specs/phase02-session04-battlefield-state-and-interaction-polish/implementation-notes.md` - added session audit sections and task log. **BQC Fixes**: * N/A - documentation and planning evidence only. *** ### Task T003 - Audit current battlefield contract **Started**: 2026-05-29 08:24 **Completed**: 2026-05-29 08:25 **Duration**: 1 minute **Notes**: * Compared current battlefield implementation and docs against PRD, UX PRD, and the Phase 02 gap matrix. * Confirmed the app already satisfies the broad 2D DOM direction and selection synchronization baseline. * Identified implementation gaps around static state labels, tested label placement, explicit fallback states, and achievement timer cleanup evidence. **Files Changed**: * `.spec_system/specs/phase02-session04-battlefield-state-and-interaction-polish/implementation-notes.md` - added battlefield contract audit. **BQC Fixes**: * N/A - audit only. *** ### Task T004 - Refine battlefield coordinate and label-placement helper coverage **Started**: 2026-05-29 08:25 **Completed**: 2026-05-29 08:26 **Duration**: 1 minute **Notes**: * Added a pure `resolveBattlefieldLabelPlacement` helper for top, center, bottom, missing, and non-finite screen positions. * Expanded coordinate tests for null, partial, non-finite, and both outlying clamp directions. * Verified helper coverage with `npm run test -- apps/web/tests/battlefield2d.test.ts`. **Files Changed**: * `apps/web/src/lib/battlefield2d.ts` - added exported label placement helper. * `apps/web/tests/battlefield2d.test.ts` - added edge, missing, non-finite, and label placement coverage. **BQC Fixes**: * Contract alignment: label placement is now a pure tested helper instead of an implicit component threshold. *** ### Task T005 - Extend achievement celebration helper coverage **Started**: 2026-05-29 08:26 **Completed**: 2026-05-29 08:27 **Duration**: 1 minute **Notes**: * Added tests for fresh unlock ordering beyond the concurrent display cap. * Added full deterministic tone assertions for bronze, silver, gold, and platinum tiers. * Added bounded constant assertions for max concurrent bursts and lifetime cleanup windows. * Verified helper coverage with `npm run test -- apps/web/tests/achievementCelebration.test.ts`. **Files Changed**: * `apps/web/tests/achievementCelebration.test.ts` - expanded celebration helper coverage. **BQC Fixes**: * Contract alignment: helper tests now pin tier tone outputs and cap/lifetime assumptions used by the component lifecycle. *** ### Task T006 - Define battlefield token state-label and accessible-name decisions **Started**: 2026-05-29 08:27 **Completed**: 2026-05-29 08:28 **Duration**: 1 minute **Notes**: * Replaced the loose state label map with typed `HeroStateTreatment` metadata using `satisfies Record` for exhaustive protocol-state coverage. * Routed selected-label copy and accessible state detail through the shared state treatment metadata. * Switched component label placement to the tested `resolveBattlefieldLabelPlacement` helper. * Verified with `npm run test -- apps/web/tests/Battlefield.test.tsx apps/web/tests/battlefield2d.test.ts`. **Files Changed**: * `apps/web/src/components/battlefield/Battlefield.tsx` - added typed state treatment metadata and consumed the label placement helper. **BQC Fixes**: * Contract alignment: hero state labels now come from one exhaustive protocol-state table. *** ### Task T007 - Harden board selection clearing and token activation boundaries **Started**: 2026-05-29 08:28 **Completed**: 2026-05-29 08:29 **Duration**: 1 minute **Notes**: * Replaced the broad section click handler with a native empty-terrain button under the token layer. * Kept hero tokens as native buttons with pointer events isolated from empty-board clear behavior. * Updated the existing selection test to exercise the explicit empty-terrain clear control. * Verified with `npm run test -- apps/web/tests/Battlefield.test.tsx`. **Files Changed**: * `apps/web/src/components/battlefield/Battlefield.tsx` - added empty-terrain clear button and token-layer pointer boundary. * `apps/web/tests/Battlefield.test.tsx` - updated empty-board clear assertion to target the native clear control. **BQC Fixes**: * Accessibility and platform compliance: empty-space clearing is now a native button action with an accessible label. * State freshness on re-entry: clearing still flows through `setSelectedHeroId(null)` so stale selected hero context is removed through the shared store path. *** ### Task T008 - Establish focused battlefield interaction test scaffolding **Started**: 2026-05-29 08:29 **Completed**: 2026-05-29 08:30 **Duration**: 1 minute **Notes**: * Added reusable fixtures for all protocol hero states, selected state, reduced motion, and asset failures. * Added scaffold tests for state token rendering, selected/reduced-motion setup, and fallback setup. * Verified with `npm run test -- apps/web/tests/BattlefieldInteraction.test.tsx`. **Files Changed**: * `apps/web/tests/BattlefieldInteraction.test.tsx` - created focused battlefield interaction scaffold. **BQC Fixes**: * Contract alignment: all protocol hero states are now represented in a focused battlefield fixture. *** ### Task T009 - Update token names, selected semantics, and stale-state revalidation **Started**: 2026-05-29 08:30 **Completed**: 2026-05-29 08:31 **Duration**: 1 minute **Notes**: * Added selected hero revalidation so stale `selectedHeroId` values clear when the hero leaves the local store. * Made active mission context explicit in hero token accessible names. * Added component tests for active mission names and selected hero removal. * Corrected the new interaction scaffold mission fixture to match the protocol `Mission` contract. * Verified with `npm run test -- apps/web/tests/Battlefield.test.tsx apps/web/tests/BattlefieldInteraction.test.tsx`. **Files Changed**: * `apps/web/src/components/battlefield/Battlefield.tsx` - added stale selected hero cleanup and clearer active mission name text. * `apps/web/tests/Battlefield.test.tsx` - added active mission and stale selected hero coverage. * `apps/web/tests/BattlefieldInteraction.test.tsx` - corrected mission fixture shape. **BQC Fixes**: * State freshness on re-entry: stale selected hero ids now clear when local hero state is revalidated. * Contract alignment: battlefield mission fixture and accessible mission context now match protocol shapes. *** ### Task T010 - Add static state labels and selected indicators **Started**: 2026-05-29 08:31 **Completed**: 2026-05-29 08:32 **Duration**: 1 minute **Notes**: * Added always-rendered token state badges for spawning, idle, active, awaiting input, verifying, error, and dismissed heroes. * Added `data-state-label` attributes for inspectable state semantics. * Added explicit selected copy to the selected hero label. * Verified with `npm run test -- apps/web/tests/BattlefieldInteraction.test.tsx apps/web/tests/Battlefield.test.tsx`. **Files Changed**: * `apps/web/src/components/battlefield/Battlefield.tsx` - added static state badge and selected label copy. * `apps/web/tests/BattlefieldInteraction.test.tsx` - asserted state badges and selected label copy. **BQC Fixes**: * Accessibility and platform compliance: visible state meaning no longer depends only on color, hover, or animation. *** ### Task T011 - Refine token CSS state treatment **Started**: 2026-05-29 08:32 **Completed**: 2026-05-29 08:33 **Duration**: 1 minute **Notes**: * Added CSS for empty-terrain focus, token focus rings, state-specific badge treatment, selected rings, dismissed treatment, and reduced-motion static indicators. * Kept state differences visible through text, border style, ring weight, and static badge treatment. * Verified with `npm run test -- apps/web/tests/BattlefieldInteraction.test.tsx apps/web/tests/Battlefield.test.tsx`. **Files Changed**: * `apps/web/src/index.css` - refined battlefield token, state badge, selected, focus, dismissed, and reduced-motion styles. **BQC Fixes**: * Accessibility and platform compliance: focus-visible treatment and reduced-motion static indicators are now explicit in CSS. *** ### Task T012 - Harden background and hero asset fallback rendering **Started**: 2026-05-29 08:33 **Completed**: 2026-05-29 08:34 **Duration**: 1 minute **Notes**: * Added explicit background asset states for loading, loaded, and fallback. * Added explicit hero asset states for loading, loaded, and fallback. * Added board-level connection and hero-count state attributes plus visible local snapshot and empty battlefield states. * Added focused tests for asset load/error, fallback labels, offline state, and empty board behavior. * Verified with `npm run test -- apps/web/tests/BattlefieldInteraction.test.tsx apps/web/tests/Battlefield.test.tsx`. **Files Changed**: * `apps/web/src/components/battlefield/Battlefield.tsx` - added explicit asset, empty, and offline board states. * `apps/web/tests/BattlefieldInteraction.test.tsx` - added fallback, offline, and empty-state assertions. **BQC Fixes**: * Failure path completeness: failed background and hero assets now expose stable fallback DOM states. * State freshness on re-entry: asset load/error state is explicit and idempotent per faction/background. *** ### Task T013 - Refine label placement and bounded positioning behavior **Started**: 2026-05-29 08:34 **Completed**: 2026-05-29 08:35 **Duration**: 1 minute **Notes**: * Hardened coordinate projection against malformed custom world and screen limits so it cannot emit non-finite positions. * Kept component label placement on the pure helper added earlier. * Expanded helper tests for degenerate world extents and non-finite screen bounds. * Verified with `npm run test -- apps/web/tests/battlefield2d.test.ts apps/web/tests/Battlefield.test.tsx apps/web/tests/BattlefieldInteraction.test.tsx`. **Files Changed**: * `apps/web/src/lib/battlefield2d.ts` - added projection guards and midpoint fallback. * `apps/web/tests/battlefield2d.test.ts` - added malformed-limit coverage. **BQC Fixes**: * Failure path completeness: malformed helper inputs now fall back to bounded board coordinates instead of producing `NaN`. *** ### Task T014 - Harden achievement burst lifecycle **Started**: 2026-05-29 08:35 **Completed**: 2026-05-29 08:36 **Duration**: 1 minute **Notes**: * Replaced array timer tracking with keyed timer lifecycle management. * Timers now clear when bursts are capped out, expire, or the component unmounts. * Added component coverage for concurrent burst cap enforcement and unmount cleanup. * Verified with `npm run test -- apps/web/tests/Battlefield.test.tsx apps/web/tests/BattlefieldInteraction.test.tsx`. **Files Changed**: * `apps/web/src/components/battlefield/Battlefield.tsx` - added keyed celebration timer lifecycle cleanup. * `apps/web/tests/Battlefield.test.tsx` - added burst cap and unmount cleanup coverage. **BQC Fixes**: * Resource cleanup: celebration timers are cleared on cap removal, lifetime expiration, and unmount. * Concurrency safety: concurrent burst rendering is bounded to `CELEBRATION_MAX_CONCURRENT`. *** ### Task T015 - Refine achievement helper diffing and tones **Started**: 2026-05-29 08:36 **Completed**: 2026-05-29 08:37 **Duration**: 1 minute **Notes**: * Changed tier tone selection to an exhaustive switch over protocol achievement tiers. * Made fresh unlock diff output deterministic by sorting on `unlockedAt` and then achievement id. * Added helper coverage for timestamp/id ordering. * Verified with `npm run test -- apps/web/tests/achievementCelebration.test.ts apps/web/tests/Battlefield.test.tsx`. **Files Changed**: * `apps/web/src/components/battlefield/achievementCelebration.ts` - added deterministic sort and exhaustive tone switch. * `apps/web/tests/achievementCelebration.test.ts` - added deterministic ordering coverage. **BQC Fixes**: * Contract alignment: helper output no longer depends on caller array ordering when unlock timestamps differ. *** ### Task T016 - Document completed battlefield behavior and boundaries **Started**: 2026-05-29 08:37 **Completed**: 2026-05-29 08:38 **Duration**: 1 minute **Notes**: * Updated app-side battlefield interaction, positioning, visual state, fallback, achievement lifecycle, and validation docs. * Corrected documented z-axis board range to match the current helper limits. * Recorded that Session 05 owns public-demo parity, service worker cache updates, and asset-copy validation. **Files Changed**: * `docs/battlefield.md` - updated battlefield state, interaction, fallback, reduced-motion, and Session 05 boundary documentation. **BQC Fixes**: * N/A - documentation only. *** ### Task T017 - Update web package battlefield contract **Started**: 2026-05-29 08:38 **Completed**: 2026-05-29 08:39 **Duration**: 1 minute **Notes**: * Added the app-side battlefield contract to the web package README. * Recorded deferred public-demo parity, service worker cache, and app/demo asset-copy validation boundaries. **Files Changed**: * `apps/web/README_web.md` - added battlefield contract and deferred public-demo parity boundary. **BQC Fixes**: * N/A - documentation only. *** ### Task T018 - Write selection and synchronization component tests **Started**: 2026-05-29 08:39 **Completed**: 2026-05-29 08:40 **Duration**: 1 minute **Notes**: * Added keyboard activation coverage for hero token selection and empty-terrain clearing. * Existing component coverage now includes token accessible names, selected state, empty-board clear, stale selected hero cleanup, and roster/detail synchronization. * Verified with `npm run test -- apps/web/tests/Battlefield.test.tsx`. **Files Changed**: * `apps/web/tests/Battlefield.test.tsx` - added keyboard selection and empty-terrain clearing coverage. **BQC Fixes**: * Accessibility and platform compliance: keyboard activation is now directly covered for the native battlefield controls. *** ### Task T019 - Write battlefield state, fallback, and reduced-motion tests **Started**: 2026-05-29 08:40 **Completed**: 2026-05-29 08:41 **Duration**: 1 minute **Notes**: * Added reduced-motion coverage across every supported hero state badge. * Existing interaction coverage now asserts all hero states, static indicators, failed background fallback, failed hero art fallback, offline state, and empty board state. * Verified with `npm run test -- apps/web/tests/BattlefieldInteraction.test.tsx`. **Files Changed**: * `apps/web/tests/BattlefieldInteraction.test.tsx` - added all-state reduced-motion static indicator coverage. **BQC Fixes**: * Accessibility and platform compliance: reduced-motion mode is covered for every static battlefield state badge. *** ### Task T020 - Write fake-timer achievement lifecycle tests **Started**: 2026-05-29 08:41 **Completed**: 2026-05-29 08:42 **Duration**: 1 minute **Notes**: * Added reduced-motion achievement burst coverage with fake timers. * Existing fake-timer coverage includes burst lifetime removal, concurrent cap enforcement, and unmount cleanup. * Verified with `npm run test -- apps/web/tests/Battlefield.test.tsx`. **Files Changed**: * `apps/web/tests/Battlefield.test.tsx` - added reduced-motion achievement burst lifecycle coverage. **BQC Fixes**: * Resource cleanup: fake-timer tests now cover lifetime removal and unmount cleanup. * Accessibility and platform compliance: reduced-motion achievement state remains present as static DOM output. *** ### Task T021 - Run final battlefield quality gates **Started**: 2026-05-29 08:42 **Completed**: 2026-05-29 08:44 **Duration**: 2 minutes **Notes**: * Ran focused battlefield tests, relevant hero workflow tests, web typecheck, scoped Biome lint/format checks, ASCII validation, and a browser smoke check. * Confirmed the only browser console error was the expected offline local WebSocket refusal while no local server was running. * Left the Vite dev server running at `http://127.0.0.1:5173/` for review. **Files Changed**: * `.spec_system/specs/phase02-session04-battlefield-state-and-interaction-polish/implementation-notes.md` - added validation and smoke evidence. * `.spec_system/specs/phase02-session04-battlefield-state-and-interaction-polish/tasks.md` - marked final quality gate complete. **BQC Fixes**: * N/A - validation only. *** --- # 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/phase02-session04-battlefield-state-and-interaction-polish/implementation-notes.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.