> 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_23/session_07_scanner_and_golden_age_states.md). # Session 07: Scanner And Golden Age States **Session ID**: `phase23-session07-scanner-and-golden-age-states` **Package**: apps/web **Status**: Not Started **Estimated Tasks**: \~18 **Estimated Duration**: 2-4 hours *** ## Objective Make scan progress, failed scans, not-yet-scanned state, mock drills, and clean scanner snapshots legible on the battlefield without inventing enemy progress. *** ## Scope ### In Scope (MVP) * Use existing scan trigger and scan-status state. * Add Dispatch Scouts battlefield presentation for qualifying manual scans. * Add explicit Golden Age and scan-not-run presentation. * Keep scan configuration, scan roots, ignore patterns, disabled gating, and diagnostics in existing utility UI. * Add focused battlefield, settings, or scan tests where behavior lands. ### Out of Scope * Scan configuration ownership. * Ignore-pattern editing. * Disabled run gating. * Scan diagnostics. * Public-demo synthetic fronts. * Required new audio assets. * Camp clearing on failed scans unless a real scanner snapshot removes issues. *** ## Detailed Requirements * Dispatch Scouts makes manual scans legible: * Starting a codebase, analysis, or project scan shows a scout ceremony on the battlefield when the existing scan state can identify the run. * While the scan is running, the board shows a static/reduced-motion status twin as well as any normal motion treatment. * Completion resolves into the updated camp census from the next `suggestion_update`. * Failed scan state is legible but does not become enemy progress. * Daily or automatically triggered scans do not need a new ceremony in this phase. If existing scan status exposes them, they may reuse the same patrol report states; their camp outcome still comes only from the next `suggestion_update`. * When a qualifying scan is triggered, set a short-lived `scouts dispatched` UI state. * While scan status is running, render scout activity on or near the battlefield. * Normal motion can show riders leaving the keep, a scouting trail, or a report unfurling on completion. * Reduced motion must use static equivalents. * Reduced-motion mode must show a static scout-status badge rather than moving riders or trails. * When scan status completes or fails, clear the running ceremony and let the next Quest Board snapshot drive camp changes. * Failed scans must not clear existing camps unless the scanner snapshot says they are gone. * Scan root, ignore-pattern editing, disabled run gating, and scan error summary stay in their existing utility UI. * The battlefield may summarize running, complete, failed, or idle scan status, but it does not own scan configuration. * This phase can reuse existing audio hooks if a safe, rate-limited cue already exists, but it must not add a required new audio asset. * Golden Age is explicit: * If a scan completes with zero active codebase issues, the board shows a clean-state treatment. * If the latest scanner snapshot has zero codebase issues, render a calm Golden Age treatment. * The state can be a board tint, legend chip, and concise status text. * Neutral ambience is allowed if it is clearly non-work and non-threat. * It must be visually distinct from loading, offline, disconnected, and scan failed states. * It must not create camps, issue ids, rewards, enemies, or urgency. * It must work in reduced-motion mode. * If the scanner has never produced a snapshot, show a scan-not-run or scouts available state instead of Golden Age. * With zero active heroes, the board may show the keep, last known war state, scout status, Golden Age, or a small camp census, but it must not imply an army is present. * Mock or synthetic drill camps from Session 04 must be bannered or otherwise distinguishable as non-progress state if they are visible here. * Add `data-testid` hooks for Golden Age, scan-not-run, failed-scan, and reduced-motion scout-state behavior. *** ## Required Tests * `apps/web/tests/Battlefield.test.tsx` * Golden Age renders for an empty snapshot * scan-not-run does not render Golden Age * running scouts state renders * failed scan state renders without clearing existing camps * reduced-motion scout badge replaces moving riders or trails * zero-hero state does not imply an army is present * mock drill state is visibly non-progress * Existing settings or scan tests should cover Dispatch Scouts if the scan trigger/status integration lands outside `Battlefield.test.tsx`. *** ## Prerequisites * [ ] Session 06 battlefield structure and callbacks are implemented. * [ ] Existing scan status is available to the battlefield or settings surface. *** ## Deliverables 1. Battlefield scan-state and Golden Age presentation. 2. Tests covering scan lifecycle states, clean snapshots, zero-hero state, mock drill labeling, and reduced-motion static equivalents. *** ## Dependencies / Notes * Depends on Session 06 battlefield structure and callbacks. * If no safe, rate-limited audio hook already exists, omit audio for this phase. * Scan configuration ownership, ignore-pattern editing, disabled run gating, scan diagnostics, public-demo synthetic fronts, and new audio assets are out of scope. *** ## Success Criteria * [ ] A viewer can distinguish clean, Legion present, scan in progress, scan failed, and not-yet-scanned states in the battlefield UI. * [ ] Failed scans do not erase camps unless a real scanner snapshot says the issues are gone. * [ ] Golden Age never creates issue ids, enemies, rewards, or urgency. * [ ] A not-yet-scanned state does not masquerade as Golden Age. * [ ] Reduced-motion mode has complete static equivalents. --- # 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_23/session_07_scanner_and_golden_age_states.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.