> 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-session03-g5-boss-presentation/spec.md).

# Session Specification

**Session ID**: `phase37-session03-g5-boss-presentation` **Phase**: 37 - AI Rogue Visual Asset Finishing **Status**: Not Started **Created**: 2026-06-29

***

## 1. Session Overview

This session upgrades the Kernel Sentinel and final-defense presentation for AI Rogue using the generated G5 source sheet. It is next because the analysis script reports Phase 37 as current, no active session, Sessions 01 and 02 complete, and Session 03 as the first unfinished current-phase candidate.

The work is presentation-only. The session may add G5 crop decisions, refreshed atlas frames, typed boss and final-defense frame contracts, render-model frame selection, transient effects, cinematics, tests, docs, and browser proof, but it must not change boss footprint, collision, pathing, objective rules, win conditions, balance, audio cues, persistence, remote loading, or public-demo boundaries.

The product outcome must be visible in real AI Rogue gameplay. Updated manifest entries, atlas JSON, or docs are insufficient unless charge, attack, shield, hit, shutdown, payload compile, and final-defense states can be seen in runtime evidence while existing combat and final-defense tests continue to prove logic stability.

***

## 2. Objectives

1. Extend the crop manifest with accepted and rejected G5 boss and final-defense frame decisions that are readable at runtime scale.
2. Regenerate the gameplay/UI atlas outputs and add typed G5 boss, final-defense, and marker frame contracts.
3. Wire event-driven boss and final-defense visual overrides for charge, attack, shield, hit, death, payload activation, objective progress, and win unlock windows without changing simulation rules.
4. Prove the presentation through focused atlas, boss-presentation, combat, final-defense, render, asset-size, typecheck, and desktop/mobile browser validation.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase37-session01-g8-runtime-fx` - Provides completed runtime FX, status overlays, atlas regeneration baseline, and visual proof workflow.
* [x] `phase37-session02-g4-status-equipment` - Provides stable UI icon contracts, atlas counts, React/HUD icon patterns, and completed validation evidence.

### Required Tools Or Knowledge

* Python visual packer: `scripts/extensions/ai-rogue/pack-visual-assets.py`.
* G5 source and alpha derivative: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/source/ai-rogue-boss-final-defense-source.png` and `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/alpha/ai-rogue-boss-final-defense-alpha.png`.
* Current crop manifest: `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json`.
* Existing boss, final-defense, render, effects, and atlas contracts under `src/extensions/ai-rogue/runtime/`.
* Existing final-defense tests in `src/extensions/ai-rogue/runtime/__tests__/biome-final.test.ts`.

### 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 at desktop and mobile viewport sizes with deterministic boss/final-defense scenarios.

***

## 4. Scope

### In Scope (MVP)

* Player can read Kernel Sentinel idle, charge, telegraph, line-fire, shielded, hit, and shutdown presentation during runtime play.
* Player can identify arena, compile payload, final-defense target, objective progress, payload activation, and win unlock presentation states without relying on debug copy.
* Maintainer can rely on typed frame names, required-frame tests, and focused boss-presentation tests to catch missing G5 atlas output or event mapping drift.
* Existing combat and final-defense rules remain stable while presentation derives from current snapshots, combat log events, pending threats, status, and audio metadata.
* User-facing Play route remains product-facing; diagnostics and evidence stay in tests, screenshots, docs, or implementation notes.

### Out Of Scope (Deferred)

* Boss footprint, collision, pathing, range, speed, stats, shield-piercing behavior, objective rules, or win conditions - Reason: Session 03 is presentation-only.
* New boss attacks, phases, rewards, relics, status effects, or balance changes
  * Reason: the phase objective is visual finishing, not gameplay expansion.
* Audio boss cue changes - Reason: Phase 36 owns audio and already shipped boss and final-defense cues.
* G3 sector decals, G6 UI cinematics, and G7 player animation - Reason: these are later Phase 37 sessions.
* Remote game-content loading, collectors, hosted writes, analytics, Pages Functions, public-demo bridge calls, WebGPU-only behavior, save-schema changes, 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 G5 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` if final-defense UI markers require the UI atlas, and the docs preview, then update TypeScript frame contracts and required-frame lists.

Keep mapping logic at the presentation boundary. Add a small typed boss presentation helper so render-model, transient effects, and tests share the same event-to-frame rules. Render-model should project boss frame overrides and final-defense markers from existing snapshot facts and combat log events. Effects should react to existing boss and payload audio cues. Renderer-sprites should preserve idle animation while respecting override frames. Cinematics should use the accepted payload and win-unlock frames without baking gameplay text into images.

### Design Patterns

* Manifest-first asset acceptance: every accepted or rejected G5 candidate is recorded with source rectangle, target size, atlas, category, status, and notes.
* Typed frame contract: boss state frames and final-defense marker frames are union types and required atlas frames, not ad hoc strings.
* Presentation boundary: derive visuals from existing snapshots, pending threats, events, status, and audio metadata without mutating simulation.
* Event-driven override window: charge, attack, shield, hit, and shutdown frames use deterministic event and time windows with stable fallback to idle.
* 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-session03-g5-boss-presentation/implementation-notes.md` | G5 candidate review, validation ledger, and browser evidence      | \~180      |
| `src/extensions/ai-rogue/runtime/boss-presentation.ts`                              | Typed boss/final-defense frame helpers shared by render and tests | \~120      |
| `src/extensions/ai-rogue/runtime/__tests__/boss-presentation.test.ts`               | Focused G5 frame selection and final-defense marker coverage      | \~140      |

### Files To Modify

| File                                                                              | Changes                                                                                 | Est. Lines |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------- |
| `docs/ongoing-projects/generated/ai-rogue-visual-audio-assets/crop-manifest.json` | Accepted/rejected G5 boss, arena, payload, objective, and win-unlock frame decisions    | \~160      |
| `src/assets/ai-rogue/gameplay-atlas.png`                                          | Regenerated gameplay atlas containing accepted G5 boss/final-defense frames             | Binary     |
| `src/assets/ai-rogue/gameplay-atlas.json`                                         | Regenerated gameplay atlas metadata                                                     | \~120      |
| `src/assets/ai-rogue/ui-atlas.png`                                                | Regenerated UI atlas if objective or result marker frames belong in UI                  | Binary     |
| `src/assets/ai-rogue/ui-atlas.json`                                               | Regenerated UI atlas metadata if UI frames change                                       | \~0-80     |
| `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`                                 | G5 boss state, final-defense marker, and payload frame-name unions and constants        | \~90       |
| `src/extensions/ai-rogue/runtime/assets.ts`                                       | Required gameplay/UI frame names and atlas validation expectations for accepted G5 work | \~60       |
| `src/extensions/ai-rogue/runtime/render-model.ts`                                 | Boss frame overrides, final-defense markers, payload progress sprites, and proof labels | \~140      |
| `src/extensions/ai-rogue/runtime/render-hud.ts`                                   | Objective progress pips or descriptors for final-defense state if HUD-owned             | \~70       |
| `src/extensions/ai-rogue/runtime/effects.ts`                                      | Boss charge/fire/hit/shutdown and payload activation transient visual routing           | \~120      |
| `src/extensions/ai-rogue/runtime/effects-cinematics.ts`                           | Final-defense activation and win-unlock presentation using accepted frames              | \~80       |
| `src/extensions/ai-rogue/runtime/renderer-sprites.ts`                             | Idle animation and override-frame handling for expanded Kernel Sentinel state frames    | \~70       |
| `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts`                        | Required-frame, atlas count, and TexturePacker metadata coverage for G5 frames          | \~50       |
| `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts`                  | Boss override, final-defense marker, and deterministic sprite ordering coverage         | \~100      |
| `src/extensions/ai-rogue/runtime/__tests__/combat.test.ts`                        | Boss attack, threat, shield-piercing, and metadata stability coverage                   | \~50       |
| `src/extensions/ai-rogue/runtime/__tests__/biome-final.test.ts`                   | Final-defense compile/win/loss logic stability and presentation marker coverage         | \~70       |
| `tests/e2e/ai-rogue-runtime.spec.ts`                                              | Desktop browser proof for charge, attack, shield, hit, shutdown, and final-defense view | \~70       |
| `tests/e2e/ai-rogue-mobile.spec.ts`                                               | Mobile browser proof for boss/final-defense readability and no layout overlap           | \~50       |
| `docs/extensions/ai-rogue/visual-assets.md`                                       | Current atlas counts, accepted/rejected G5 decisions, validation evidence, and caveats  | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] G5 accepted and rejected candidates are recorded in `crop-manifest.json` with no unresolved placeholder entries.
* [ ] Runtime atlases regenerate successfully and every accepted G5 frame is available through typed frame contracts.
* [ ] Kernel Sentinel frame selection shows idle, charge, attack, shield, hit, and shutdown states from existing event/snapshot facts.
* [ ] Final-defense target, compile payload, objective progress, payload activation, and win unlock presentation render in real runtime play.
* [ ] Boss footprint, pathing, collision, objective rules, win conditions, and combat math remain unchanged.

### 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, boss-presentation, render-model, combat, and biome-final 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.

### Non-Functional Requirements

* [ ] No simulation rule, boss stats, pathing, final-defense objective, persistence schema, public-demo, hosted-runtime, or audio 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 03 is the next executable session: the analysis script reports Phase 37 as current, no active session, Sessions 01 and 02 completed, and `phase37-session03-g5-boss-presentation` as the first unfinished candidate; the phase PRD also recommends G5 after G8 and G4.
* G5 work can proceed from existing source inputs: the repo contains the G5 source sheet, alpha derivative, crop manifest, gameplay/UI atlases, and visual packer, so planning does not need user arbitration.
* Boss presentation should be derived from current event metadata and snapshot state rather than combat math changes: `combat.ts` already emits boss-specific actor metadata and cues, while `biome-final.test.ts` already proves compile/win/loss behavior.
* A small `boss-presentation.ts` helper is warranted: the session needs the same boss/final-defense frame rules in render-model, effects, and tests, and a typed helper keeps those mappings exhaustive and reusable.

### Conflict Resolutions

* Master PRD status versus phase state: `.spec_system/PRD/PRD.md` still lists Phase 37 as "Not Started", while the analysis output and `.spec_system/PRD/phase_37/PRD_phase_37.md` show Phase 37 in progress with Sessions 01 and 02 complete. The analysis output is authoritative for workflow state, so Session 03 planning proceeds.
* Existing baseline boss frames versus G5 refresh scope: `assets.ts` already requires baseline `boss_kernel_sentinel_*` frames, but the Session 03 stub calls for richer idle, charge, telegraph, line-fire, shielded, hit, and shutdown presentation plus final-defense markers. The best-supported interpretation is to preserve baseline frame compatibility while adding typed G5 frame groups and mappings for the expanded presentation.

### Key Considerations

* Boss size must continue to read as a 2x entity without changing logical footprint or collision.
* Event-driven overrides need deterministic fallbacks so idle animation still works when no recent boss event is active.
* Final-defense visuals must communicate progress and victory without baked text or debug-only labels.
* Browser proof must cover visible boss and final-defense states, not only atlas or unit-test success.

### Potential Challenges

* G5 source candidates may be strong as stills but weak at runtime scale: mitigate by accepting fewer high-confidence frames and documenting rejected candidates.
* Boss event windows can become timing-sensitive in browser tests: mitigate with deterministic scenario setup and stable canvas-pixel assertions.
* Final-defense presentation can accidentally imply new mechanics: mitigate by keeping compile and win/loss rules covered in `biome-final.test.ts`.
* Atlas growth can exceed media policy caps: mitigate through selective frame acceptance and immediate asset-size validation after packing.

### Relevant Considerations

* \[P34-P36] **AI Rogue is production default-enabled**: Keep production visibility and the explicit disable path intact while changing only local presentation.
* \[P31-P36] **Public-demo and AI Rogue gates stay bundled**: Media/runtime work must keep private-runtime, asset-size, provenance, browser, Pages, no-bridge, and playthrough evidence together.
* \[P30/P34-P36] **Visibility gates catch real issues**: Pair focused unit tests, browser checks, asset-size validation, and product-visible proof before widening confidence in visual changes.
* \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi changes behind the Play route/runtime boundary and avoid widening hosted or remote capability.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Boss presentation changing perceived or actual gameplay footprint.
* Event-driven override frames persisting after their intended window or hiding active combat feedback.
* Final-defense visuals suggesting progress, failure, or victory states that diverge from simulation status.

***

## 9. Testing Strategy

### Unit Tests

* Atlas contract tests for all accepted G5 gameplay/UI frames and compact, unrotated TexturePacker metadata.
* Boss-presentation helper tests for idle, charge, attack, shield, hit, shutdown, final-defense marker, and fallback selection.
* Render-model tests for deterministic sprite ordering, marker projection, and final-defense progress descriptors.
* Combat tests proving boss metadata, shield-piercing behavior, and cue routing remain stable.
* Biome-final tests proving compile payload, final-defense win, and failure outcomes remain unchanged.

### Integration Tests

* Focused AI Rogue runtime tests that mount the Play surface with deterministic boss and final-defense states.
* Existing runtime and mobile Playwright suites for desktop/mobile product visibility, no layout overlap, and product-facing copy only.

### Runtime Verification

* Desktop browser proof for Kernel Sentinel charge, attack, shield, hit, and shutdown states.
* Desktop browser proof for compile payload activation, final-defense target, objective progress, and win unlock.
* Mobile browser proof for the same presentation states at compact viewport scale without horizontal overflow.

### Edge Cases

* Reduced-motion mode keeps static readable boss/final-defense feedback without shaking or timing-dependent animation.
* High-contrast mode keeps boss, target, and objective markers readable.
* Missing optional G5 UI marker frames fall back to existing gameplay markers without throwing.
* No recent boss events fall back to idle animation.
* Boss defeated and final-defense won/lost states do not leave stale override sprites in the renderer.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase37-session01-g8-runtime-fx`, `phase37-session02-g4-status-equipment`.
* Depended by: `phase37-session04-g3-theme-decals`, `phase37-session05-g6-ui-cinematics`, `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-session03-g5-boss-presentation/spec.md?ask=<question>&goal=<endgoal>
```

`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.