> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase37-session02-g4-status-equipment/spec.md). # Session Specification **Session ID**: `phase37-session02-g4-status-equipment` **Phase**: 37 - AI Rogue Visual Asset Finishing **Status**: Not Started **Created**: 2026-06-29 *** ## 1. Session Overview This session finishes the remaining G4 status, equipment, reward, loadout, ledger, and settings icon opportunities for AI Rogue without disturbing the already-wired G4 system-object frames or the G8 runtime status path. It is next because the analysis script reports Phase 37 as current, no active session, Session 01 complete, and Session 02 as the first unfinished current-phase candidate. The work is presentation-only. The session may add G4 crop decisions, atlas frames, typed equipment and tier frame contracts, equipment/status mapping helpers, HUD descriptor frame choices, React atlas-icon usage, tests, docs, and browser proof, but it must not add new equipment mechanics, statuses, remote loading, public-demo bridge calls, analytics, hosted writes, or save-schema changes. The product outcome must be visible in the real AI Rogue HUD and supporting React surfaces. Updated frame names, atlas JSON, or docs are insufficient unless equipment, reward, loadout, ledger, and applicable settings/status surfaces render stable icons with accessible labels, clear fallback behavior, and focused coverage. *** ## 2. Objectives 1. Extend the crop manifest with accepted and rejected G4 status/equipment icon decisions while preserving existing system-object and G8 status frames. 2. Add typed equipment-slot and material-tier icon contracts to the UI atlas and required-frame validation. 3. Wire G4 icons into runtime HUD descriptors and React surfaces that already expose equipment, rewards, loadout, ledger, settings, or status state. 4. Prove icon visibility, accessibility labels, fallback behavior, asset-size policy, and product-surface cleanliness through focused tests and browser checks. *** ## 3. Prerequisites ### Required Sessions * [x] `phase37-session01-g8-runtime-fx` - Provides completed G8 status pips, overlays, atlas regeneration baseline, visual-asset docs, validation evidence, and no unresolved atlas-contract blocker. ### Required Tools Or Knowledge * Python visual packer: `scripts/extensions/ai-rogue/pack-visual-assets.py`. * G4 source and alpha derivative: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/source/ai-rogue-status-equipment-systems-source.png` and `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/alpha/ai-rogue-status-equipment-systems-alpha.png`. * Current crop manifest: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json`. * AI Rogue atlas contracts in `src/extensions/ai-rogue/runtime/types-assets.ts` and `src/extensions/ai-rogue/runtime/assets.ts`. * Existing equipment, status, HUD, and React atlas-icon surfaces under `src/extensions/ai-rogue/runtime/` and `src/extensions/ai-rogue/views/`. ### Environment Requirements * Dependencies installed with Bun. * Python environment can run the visual packer and Pillow dependency already used by the repo. * Playwright Chromium is available through the repo test setup. * Local browser checks can run AI Rogue Play, Ledger, Loadout, and Settings at desktop and mobile viewport sizes. *** ## 4. Scope ### In Scope (MVP) * Player can recognize equipped `kernel`, `guard`, and `payload` items in HUD descriptors and related product surfaces through stable G4 UI atlas icons. * Player can distinguish patched, compiled, vectorized, and kernel-grade equipment tiers without relying only on hue. * Operator can review accepted and rejected G4 candidates in `crop-manifest.json`, including abstract cross, lock, keyhole, and text-like candidates rejected where they do not improve product clarity. * Maintainer can rely on typed frame names, required UI frame tests, and helper functions to keep equipment/status icon mappings exhaustive. * User-facing React surfaces continue to use product-facing copy only; visual diagnostics remain in tests, screenshots, docs, or implementation notes. ### Out Of Scope (Deferred) * Reworking already-wired G4 system-object frames - Reason: vault, terminal, cache, key, crash dump, and objective lock/unlock frames already shipped in the first G4 runtime pass. * Replacing the G8 active status pip and overlay runtime path - Reason: Session 01 completed typed G8 status pips and overlays; G4 may only add targeted supplemental icon mappings where existing product surfaces still use generic fallback frames. * Adding new equipment, status, reward, loadout, ledger, settings, or save mechanics - Reason: this session changes presentation mappings only. * Adding separate board equipment pickups unless an existing snapshot path already exposes them - Reason: current equipment rewards are earned through existing vault cache flow, not a new board item family. * Replacing familiar standard controls with themed icons where clarity drops - Reason: Phase 37 keeps generated icons only where they improve domain readability. * Remote game-content loading, collectors, hosted writes, analytics, Pages Functions, public-demo bridge calls, WebGPU-only behavior, or new third-party data transfers - Reason: AI Rogue safety posture remains local-only and static-demo-safe. *** ## 5. Technical Approach ### Architecture Use the existing manifest-first asset pipeline. Add reviewed G4 crop decisions to `crop-manifest.json`, run the packer to refresh `src/assets/ai-rogue/gameplay-atlas.png/json`, `src/assets/ai-rogue/ui-atlas.png/json`, and the docs preview, then update TypeScript frame contracts and required-frame lists. Keep mappings near their owning domain. Equipment slot, tier, and equipped-item icon helpers belong in `equipment.ts`; supplemental status icon choices belong in `status.ts` only where they do not replace the G8 status path; HUD descriptor and sprite choices belong in `render-hud.ts`; React atlas rendering and labels belong in `reward-icon.tsx` and its consumers. The simulation, persistence, claim, and save-schema layers remain unchanged except for tests that prove they still expose the same browser-local data. ### Design Patterns * Manifest-first asset acceptance: every shipped or rejected G4 icon candidate is recorded with source rectangle, target size, category, notes, and status. * Typed frame contract: equipment, tier, and supplemental status icon frame names are union types and required UI frames, not ad hoc strings. * Presentation boundary: convert existing equipment, status, reward, ledger, loadout, and settings facts into icon frames without mutating state. * Accessible icon rendering: React icon uses must provide labels for meaningful icons and mark repeated decorative instances as hidden. * Product-surface discipline: browser proof belongs in tests and notes, not debug copy mounted into normal routes. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | ---------------------------------------------------------------------------------- | ------------------------------------------------------------ | ---------- | | `.spec_system/specs/phase37-session02-g4-status-equipment/implementation-notes.md` | G4 candidate review, validation ledger, and browser evidence | \~180 | ### Files To Modify | File | Changes | Est. Lines | | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- | | `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json` | Accepted/rejected G4 equipment, tier, reward, and supplemental status icon decisions | \~160 | | `src/assets/ai-rogue/gameplay-atlas.png` | Regenerated gameplay atlas if accepted G4 gameplay/icon candidates are retained | Binary | | `src/assets/ai-rogue/gameplay-atlas.json` | Regenerated gameplay atlas metadata | \~0-80 | | `src/assets/ai-rogue/ui-atlas.png` | Regenerated UI atlas containing accepted G4 UI icon frames | Binary | | `src/assets/ai-rogue/ui-atlas.json` | Regenerated UI atlas metadata | \~80-160 | | `docs/extensions/ai-rogue/generated/ai-rogue-production-atlas-preview.png` | Regenerated docs-only atlas preview | Binary | | `src/extensions/ai-rogue/runtime/types-assets.ts` | Equipment-slot, material-tier, and supplemental G4 icon frame-name unions and constants | \~80 | | `src/extensions/ai-rogue/runtime/assets.ts` | Required UI/gameplay frame names and atlas validation expectations for accepted G4 icons | \~60 | | `src/extensions/ai-rogue/runtime/equipment.ts` | Typed equipment and material-tier icon mapping helpers | \~90 | | `src/extensions/ai-rogue/runtime/status.ts` | Supplemental G4 status icon/fallback mappings where existing fallback frames remain | \~40 | | `src/extensions/ai-rogue/runtime/render-hud.ts` | Runtime HUD equipment/status descriptor frames and labels | \~80 | | `src/extensions/ai-rogue/views/reward-icon.tsx` | React UI atlas icon type and accessible label expansion | \~70 | | `src/extensions/ai-rogue/views/loadout-view.tsx` | Loadout wallet/upgrade/tier icon usage where it improves domain readability | \~80 | | `src/extensions/ai-rogue/views/ledger-view.tsx` | Claim, source-state, and reward icon usage with decorative/meaningful label discipline | \~70 | | `src/extensions/ai-rogue/views/settings-view.tsx` | Settings readiness/storage icon usage only where G4 candidates beat generic controls | \~60 | | `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts` | Required-frame, atlas count, and TexturePacker metadata coverage | \~50 | | `src/extensions/ai-rogue/runtime/__tests__/equipment.test.ts` | Equipment slot/tier icon mapping coverage | \~70 | | `src/extensions/ai-rogue/runtime/__tests__/status-expanded.test.ts` | Supplemental status icon/fallback mapping coverage | \~40 | | `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts` | HUD descriptor coverage for equipment/status icon mappings | \~80 | | `src/extensions/ai-rogue/__tests__/client.test.tsx` | React icon rendering, labels, loadout, ledger, and settings surface coverage | \~100 | | `tests/e2e/ai-rogue-runtime.spec.ts` | Desktop browser proof for HUD equipment/status icon visibility | \~40 | | `tests/e2e/ai-rogue-mobile.spec.ts` | Mobile browser proof for responsive HUD/readability after icon additions | \~40 | | `tests/e2e/ai-rogue-ledger.spec.ts` | Browser proof for Ledger icon accessibility and product-facing copy | \~40 | | `docs/extensions/ai-rogue/visual-assets.md` | Current atlas counts, accepted/rejected G4 decisions, validation evidence, and caveats | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] G4 accepted and rejected candidates are recorded in `crop-manifest.json` with no unresolved placeholder entries. * [ ] Runtime atlases regenerate successfully and every accepted G4 icon frame is available through typed frame contracts. * [ ] Equipment-slot and material-tier helpers map every existing equipment slot, equipment ID, and material tier to stable icon frames. * [ ] HUD descriptors and React surfaces render recognizable icons without relying only on hue and without replacing standard controls where the themed icon is less clear. * [ ] AI Rogue Play, Ledger, Loadout, and Settings product surfaces remain product-facing and render without overlapping text or layout shifts on desktop and mobile. ### Testing Requirements * [ ] `python3 scripts/extensions/ai-rogue/pack-visual-assets.py` runs successfully. * [ ] `bun run typecheck` passes. * [ ] `bash scripts/check-asset-sizes.sh` passes. * [ ] Focused assets, equipment, status-expanded, render-model, and client tests pass for touched behavior. * [ ] `bunx playwright test tests/e2e/ai-rogue-runtime.spec.ts` passes or records a concrete environment blocker. * [ ] `bunx playwright test tests/e2e/ai-rogue-mobile.spec.ts` passes or records a concrete environment blocker. * [ ] `bunx playwright test tests/e2e/ai-rogue-ledger.spec.ts` passes or records a concrete environment blocker. ### Non-Functional Requirements * [ ] No simulation rule, equipment math, status behavior, persistence schema, ledger storage, public-demo, or hosted-runtime behavior changes. * [ ] AI Rogue production default-enabled posture and explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path are preserved. * [ ] No remote loading, hosted write, collector, analytics, public-demo bridge call, WebGPU-only behavior, or new third-party data transfer is introduced. * [ ] Committed runtime image assets remain within media-policy caps. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] Primary user-facing surfaces contain product-facing copy only. * [ ] `git diff --check` passes. *** ## 8. Implementation Notes ### Working Assumptions * Session 02 is the next executable session: the analysis script reports Phase 37 as current, no active session, Session 01 completed, and `phase37-session02-g4-status-equipment` as the first unfinished candidate; the phase PRD also recommends G4 after G8. * G4 equipment/tier icon work should target UI atlas frames first: the existing React and HUD surfaces consume UI icons, while current equipment rewards are earned through the vault cache flow rather than a separate board pickup item. Planning can proceed because `equipment.ts` already defines the complete slot, ID, and tier vocabulary. * G8 status pips and overlays remain authoritative for active runtime statuses: Session 01 completed typed G8 status visuals and docs list them as shipped. G4 may add supplemental mappings only where existing surfaces still use generic fallback icons. ### Conflict Resolutions * Master PRD status versus phase state: `.spec_system/PRD/PRD.md` still lists Phase 37 as "Not Started", while the analysis output, phase PRD progress tracker, and session history show Phase 37 in progress with Session 01 complete. The analysis output and phase PRD are the best-supported current sources, so Session 02 planning proceeds. * G4 stub status-pip scope versus completed G8 status visuals: the Session 02 stub mentions status pips, but Session 01 artifacts and `docs/extensions/ai-rogue/visual-assets.md` show G8 status pips and overlays already shipped. The best-supported interpretation is to preserve those G8 mappings and use G4 only for remaining equipment, tier, reward/loadout, ledger/settings, and supplemental fallback icon opportunities. ### Key Considerations * Existing system-object frames from G4 must stay stable. * Asset growth must preserve the two-atlas model unless validation evidence forces a later reviewed expansion. * Icon choices must avoid baked text, letters, readable numbers, and punctuation-like symbols. * Meaningful icons require accessible labels; decorative repeats should be hidden from assistive technology. ### Potential Challenges * G4 source candidates may be ambiguous at small sizes: mitigate by accepting fewer high-confidence icons and documenting rejected candidates. * Tier icons may over-rely on color: mitigate with shape differences and tests that assert distinct frame names across all tiers. * React icon additions can shift compact layouts: mitigate with fixed icon dimensions, responsive checks, and mobile Playwright coverage. * Atlas counts can drift: mitigate through required-frame tests and asset-size checks after packing. ### Relevant Considerations * \[P34-P36] **AI Rogue is production default-enabled**: Visual changes must preserve Production Go and the explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` opt-out path. * \[P31-P36] **Public-demo and AI Rogue gates stay bundled**: Runtime visual changes need asset-size, private-runtime, browser, route smoke, and playthrough-style gates where touched. * \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade and avoid broad runtime ownership leaks. * \[P30/P34-P35] **Visibility gates catch real issues**: Pair focused tests, asset budgets, browser checks, screenshots, and docs before treating visual work as done. * \[P30/P32/P34-P36] **Do not widen AI Rogue capabilities without review**: This phase adds visual assets only; collectors, WebGPU, workers, remote loading, hosted writes, analytics, and expanded content stay out of scope. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Icon mappings can drift from typed contracts and silently render null frames. * React product surfaces can gain inaccessible or duplicate icon labels. * Runtime HUD and mobile layouts can shift or overlap after new fixed-size icons are added. *** ## 9. Testing Strategy ### Unit Tests * Assert accepted G4 icon frames exist in the relevant atlas metadata and are compact, unrotated TexturePacker frames. * Assert equipment-slot, equipment-ID, and material-tier icon helpers cover all current values exhaustively. * Assert supplemental status fallback mappings do not replace G8 status pips or overlays. * Assert HUD descriptors use equipment/status icon frames derived from existing snapshots. * Assert `RewardIcon` renders meaningful labels, decorative variants, and null fallback behavior correctly. ### Integration Tests * Render Loadout, Ledger, and Settings through existing client tests and verify G4 icon labels or decorative usage remain product-facing and accessible. * Run focused runtime render-model tests to prove HUD descriptor frame choices remain deterministic and bounded. ### Runtime Verification * Run desktop AI Rogue Play and confirm equipment/status HUD visuals render after acquiring equipment or using a seeded test scenario. * Run AI Rogue Ledger and Loadout and confirm reward/tier icons render without text overlap or diagnostic copy. * Run mobile AI Rogue Play and Ledger checks for responsive icon sizing and no horizontal overflow. ### Edge Cases * Missing UI atlas frame returns a null icon instead of throwing in React. * Storage unavailable, denied, offline, loading, and error states keep explicit non-icon text labels. * Empty equipment state renders no misleading equipment icon. * Multiple equipment tiers use distinct non-hue-only frame names. * Existing G8 status pips remain present after G4 atlas additions. *** ## 10. Dependencies ### Other Sessions * Depends on: `phase37-session01-g8-runtime-fx` * Depended by: `phase37-session03-g5-boss-presentation`, `phase37-session05-g6-ui-cinematics`, and `phase37-session06-g7-player-animation` *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # 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://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase37-session02-g4-status-equipment/spec.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.