> 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/docs/extensions/ai-rogue/implementation-baseline.md).

# AI Rogue Implementation Baseline

**Status**: Production default enablement supersedes Session 10 release closeout **Session**: `phase30-session01-direction-and-asset-readiness` **Checked**: 2026-06-27

This document is the implementation handoff for Phase 30 Sessions 02 through 10. It records the product, scope, economy, renderer, asset, privacy, and deferred-system decisions that are already supported by the Phase 30 PRD, the AI Rogue extension plan, the AI Rogue visual-assets record, package manifests, and committed runtime assets.

Session 10 validated the implemented slice as safe for opt-in. Phase 34 later fixed the audited default-enable blockers, reran the gate bundle, and the current source production-enables AI Rogue by default. The final closeout decision lives in [`enablement-decision.md`](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/enablement-decision.md).

Historical plan text that describes optional audio, no audio, or default enablement as a future decision is superseded by current Web Audio behavior, the reviewed AI Rogue music cap, and the Phase 34 production default-enable decision. Browser-local state, no collector, no remote content loading, and no hosted write remain live boundaries.

## Source Documents

| Source                                                                  | Purpose                                                                                                |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `.spec_system/PRD/phase_30/PRD_phase_30.md`                             | Phase objective, prerequisites, session list, quality gates, and risks.                                |
| `.spec_system/PRD/phase_30/session_01_direction_and_asset_readiness.md` | Session 01 scope, out-of-scope boundaries, and deliverables.                                           |
| `docs/extensions/ai-rogue/plan-2026-06-21.md`                           | Historical product shape, architecture, runtime boundary, economy rules, quality gates, and non-goals. |
| `docs/extensions/ai-rogue/visual-assets.md`                             | First-batch pixel-art direction, palette, atlas grouping, provenance, and acceptance checklist.        |
| `docs/extensions/ai-rogue/game-feel.md`                                 | Current HUD text, effects, motion, run arc, audio runtime, and asset contracts.                        |
| `package.json` and `bun.lock`                                           | Installed renderer dependency state.                                                                   |
| `src/assets/ai-rogue/`                                                  | Committed runtime atlas, audio, TexturePacker-style metadata, and audio provenance files.              |

## Locked Product Shape

| Decision         | Baseline                                                                   |
| ---------------- | -------------------------------------------------------------------------- |
| Product name     | `AI Rogue`                                                                 |
| Extension ID     | `ai-rogue`                                                                 |
| Primary route    | `/extensions/ai-rogue/play`                                                |
| Primary currency | `Insight Shards`                                                           |
| Initial stance   | Production default-enabled repo-local extension after Phase 34 remediation |
| First screen     | Playable roguelike surface, not a dashboard or marketing page              |

Initial user-facing surfaces:

| Surface  | Purpose                                                                              |
| -------- | ------------------------------------------------------------------------------------ |
| Play     | Canvas-first roguelike run with concise surrounding controls.                        |
| Ledger   | Manual claims, daily earning caps, and compact provenance for `Insight Shards`.      |
| Loadout  | Persistent upgrades, relics, classes, and skill-linked modifiers.                    |
| Settings | Accessibility, reduced motion, input remapping, save reset, and debug seed controls. |

The first implementation can use this document as the product naming source of truth. Later sessions should update this file only when a validated implementation changes a locked decision.

## Extension Boundary And Capabilities

AI Rogue uses the accepted static extension platform:

* Register through reviewed source code, not dynamic plugin loading.
* Keep the extension production-enabled by default in the browser registry.
* Use `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` only as an explicit build-time disable path.
* Keep PixiJS and runtime code out of `src/extensions/registry.ts`, app shell chunks, and other routes.
* Keep the first version client-only unless a later session proves a browser-safe generated-content collector is required.

Initial capability posture:

```ts
capabilities: [
  {
    kind: "readGeneratedData",
    reason: "Reads browser-safe AI Rogue content and economy projections from LiveData",
  },
  {
    kind: "localStorage",
    reason: "Stores local game preferences and small save metadata in this browser",
  },
  {
    kind: "indexedDB",
    reason: "Stores browser-local wallet, ledger, run history, and save slots",
  },
];
```

Do not add `networkAccess`, script collectors, admin writes, hosted storage, remote loading, auth flows, realtime services, or database dependencies in the initial extension shell. Any later capability must be matched to behavior that exists in that session and documented in the relevant implementation notes.

## Privacy Boundary

Browser-visible game data must stay bounded and explainable:

* Allowed: counts, dates, categories, status labels, source labels, capped token or spend signals, readiness labels, streak labels, and aggregate provenance summaries.
* Not allowed: raw prompts, transcripts, command bodies, command output, private file paths, credentials, secrets, logs, or raw private telemetry.
* Missing pricing, unknown tokens, example data, and unavailable provider telemetry reduce only their unavailable source contribution. They do not become penalties against the rest of the claim.
* Preference state remains browser-local in `localStorage`; wallet, ledger, save-slot, and run-history state remains browser-local in IndexedDB. Normal play state does not write to `src/data/live-data.json`.

## Insight Shards Economy Baseline

The first implementation uses one primary currency: `Insight Shards`.

AI OS activity creates a claimable daily shard pool from browser-safe `LiveData`. Wallet changes require a manual claim action. The Ledger must show a compact "why did I earn this?" breakdown before or immediately after the claim.

Locked earning blend:

| Source                            | Weight | Rule                                                                   |
| --------------------------------- | ------ | ---------------------------------------------------------------------- |
| Completed agent runs and sessions | 40%    | Prefer completed, non-error work when status data exists.              |
| Skill usage diversity             | 25%    | Reward meaningful skill use across categories.                         |
| Tool-class diversity              | 20%    | Reward varied productive workflows without reading command bodies.     |
| Capped token or spend signal      | 10%    | Count only browser-safe priced spend or token metadata when available. |
| Provider readiness and streaks    | 5%     | Small bonus for healthy local setup and consistent use.                |

Manual claim behavior:

* Daily earnings can be detected from the latest browser-safe `LiveData`, but wallet mutation happens only through an explicit claim action.
* Repeated claims must be idempotent. Stable redemption keys should include date plus provider, activity run ID, or another available browser-safe source identifier.
* Daily caps must prevent raw spend or token burn from dominating progression.
* Unknown pricing, unavailable tokens, example data, and missing telemetry leave only their source contribution unavailable.

Provenance expectations:

* Ledger entries explain the contribution categories and caps without exposing prompts, transcripts, command bodies, private paths, credentials, or logs.
* `Insight Shards` appear in two gameplay contexts: in-run pickup feedback and post-run or claim rewards that bank into the wallet.
* In-run pickups are feedback and run rewards; the authoritative wallet balance comes from the claim, post-run banking, and local persistence contracts added in later sessions.

## PixiJS Renderer Baseline

Checked package state on 2026-06-22:

| Package       | Status                                                  |
| ------------- | ------------------------------------------------------- |
| `pixi.js`     | Installed as `8.19.0` in `package.json` and `bun.lock`. |
| `@pixi/react` | Not installed in `package.json` or `bun.lock`.          |

Runtime rules:

* Lazy import the local AI Rogue Pixi facade only from the mounted Play view or from runtime modules that are loaded after the Play view mounts.
* Do not import PixiJS from the extension registry, app shell, route index, or non-game views.
* Use imperative PixiJS ownership for canvas, renderer, textures, sprites, containers, ticker/frame loop, input sampling, particles, and disposal.
* React owns routing, menus, forms, accessibility UI, settings, and coarse state updates. Per-frame simulation does not move through React state.
* Pin the first slice to WebGL with `preserveDrawingBuffer: true` so the existing canvas-pixel verification pattern can read pixels. WebGPU remains deferred because it changes the canvas verification strategy.
* Measure the lazy runtime chunk when PixiJS enters the route. Update bundle budget classification only if the measured PixiJS chunk requires the watched vendor allowance.
* Session 10 moved AI Rogue view modules out of the static entry chunk and added a local Pixi facade so the broad Pixi namespace import does not inflate total client JS. `bun run budget:check` passes at 1442 KB / 1500 KB total client JS gzip. Phase 34 later applied production default enablement after the blocker and gate closeout.
* Do not add `@pixi/react` unless a later session proves a declarative Pixi UI layer is useful enough to justify the dependency and chunk cost.

## Asset Baseline

Current maintained runtime image-atlas inventory:

| File                                      | Size         | Role                                                     |
| ----------------------------------------- | ------------ | -------------------------------------------------------- |
| `src/assets/ai-rogue/gameplay-atlas.png`  | 43,901 bytes | Runtime image atlas for gameplay sprites and tiles.      |
| `src/assets/ai-rogue/gameplay-atlas.json` | 65,769 bytes | TexturePacker-style frame metadata for gameplay atlas.   |
| `src/assets/ai-rogue/ui-atlas.png`        | 14,191 bytes | Runtime image atlas for HUD, reward, pip, and frame art. |
| `src/assets/ai-rogue/ui-atlas.json`       | 32,799 bytes | TexturePacker-style frame metadata for UI atlas.         |

Frame inventory:

| Atlas            | Frames | Groups                                                                                                                                                     |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gameplay-atlas` | 161    | Player directions, enemy ecology, Kernel Sentinel, protocol FX, system objects, FX, telegraph frames, tiles, pickups, hazards, fog, and projectile frames. |
| `ui-atlas`       | 82     | Bitmap font glyphs, icons, pips, frame/panel pieces, result glyphs, and result grid tiles.                                                                 |

Scale and animation:

* Use 16x16 source pixels for normal tiles, player, standard enemies, pickups, hazards, and compact icons.
* Use nearest-neighbor scaling. The baseline display scale is 2x, so one tile renders as 32 CSS pixels. Treat 3x as a roomy-desktop option only.
* Player frame budget is 1 idle frame plus 2 move frames per direction across four directions.
* Standard enemies use 1 idle frame plus 1 attack or hit frame. The Kernel Sentinel boss uses a deliberate 32x32 source footprint.
* Animation frames must not resize or shift the tile footprint.

Palette semantics:

| Role                         | Semantics                                                         |
| ---------------------------- | ----------------------------------------------------------------- |
| Dark neutral base            | Dungeon floor, walls, void, and machine shell.                    |
| Cyan                         | `Insight Shards`, reward cache, shard HUD, and currency feedback. |
| Green                        | Health pickup and positive survivability signals.                 |
| Orange/red                   | Hostile cores, enemy danger, and attack telegraph emphasis.       |
| Magenta or acid yellow-green | Hazards and environmental damage.                                 |

Provenance and acceptance:

* First-batch runtime art is AI-generated project art refined locally through cropping, chroma-key cleanup, resizing, palette reduction, hard-alpha cleanup, and compact atlas packing.
* Runtime image art must remain under the `src/assets/` 200 KB per-file non-logo media limit. AI Rogue music tracks are audio assets governed by the reviewed 900 KB cap in [`docs/media-policy.md`](/ai-os-and-trend-finder-docs/docs/media-policy.md), not the image-atlas cap.
* No gameplay sprites include baked text.
* Player, enemy, wall, floor, hazard, pickup, and fog silhouettes must remain distinct at intended in-game scale.
* Transparent sprites must have clean alpha with no chroma-key fringe.
* Atlas names and frame names are stable inputs for later runtime imports.
* Future asset expansions must update `docs/extensions/ai-rogue/visual-assets.md` with prompt/provenance notes and rerun the media-policy check.

## Game-Feel And Audio Baseline

The current Play route includes a clock-driven presentation layer in `runtime/effects.ts`. Keep `render-model.ts` as the pure turn-snapshot projection and keep transient HUD text, floating numbers, impact effects, particles, shake, hit-stop, camera/entity tweening, damage flash, sector intro, relic moment, descend fade, and end screen behavior in the runtime effects layer.

Reduced motion is a hard contract. Animation, camera glide, shake, and decorative motion must gate on the runtime reduced-motion flag and fall back to readable static or instant feedback.

Audio is implemented directly with Web Audio in `runtime/audio.ts`:

* Music: six Ogg Opus tracks under `src/assets/ai-rogue/audio/music/`, with provenance in `src/assets/ai-rogue/audio/music/provenance.json`.
* SFX: 57 Ogg Opus effects under `src/assets/ai-rogue/audio/sfx/`, with provenance in `src/assets/ai-rogue/audio/sfx/provenance.json`.
* The engine unlocks on first user gesture, lazily decodes and caches buffers, crossfades music by title/sector/result state, maps simulation events to one-shots, runs the low-HP heartbeat loop, and degrades to silent no-op when Web Audio is unavailable.
* Typed enemy metadata routes fast, thief, corruption, sentry, and Kernel Sentinel encounters to local identity SFX while retaining generic enemy, missing-asset, and invalid-metadata fallback behavior.
* Preferences are persisted as `audioMuted`, `musicVolume`, and `sfxVolume`.
* The current audio engine does not implement sidechain or event-based music ducking.

Current game-feel contracts live in [`game-feel.md`](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/game-feel.md). Source art and atlas provenance live in [`visual-assets.md`](/ai-os-and-trend-finder-docs/docs/extensions/ai-rogue/visual-assets.md).

## Session Handoff Map

| Session                                     | Must Reuse From This Baseline                                                                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Session 02 - Extension Shell And Routes     | `AI Rogue`, `ai-rogue`, `/extensions/ai-rogue/play`, Play/Ledger/Loadout/Settings surfaces, production browser visibility, and initial capabilities.           |
| Session 03 - PixiJS Runtime Boundary        | `pixi.js@8.19.0`, lazy runtime import, no `@pixi/react`, WebGL with `preserveDrawingBuffer: true`, route cleanup, and chunk measurement.                       |
| Session 04 - Economy And Ledger             | `Insight Shards`, manual claim, 40/25/20/10/5 source weights, daily caps, idempotent redemption keys, and privacy-safe provenance.                             |
| Session 05 - Persistence And Save Contracts | Browser-local wallet, ledger, preferences, run history, save state, versioned parsing, and reset boundaries.                                                   |
| Session 06 - Dungeon Simulation Core        | Pure TypeScript simulation, deterministic seeded rules, 16x16 tile semantics, no PixiJS dependency in simulation modules, and no worker by default.            |
| Session 07 - Play Runtime Integration       | Committed atlas paths, tile scale, palette semantics, frame budgets, shard pickup/reward distinction, and acceptance gates.                                    |
| Session 08 - Progression Depth              | Counts, categories, labels, capped signals, and skill/source readiness signals only; no raw private telemetry or unbounded spend progression.                  |
| Session 09 - Content Polish And Mobile      | Compact atlas policy, media-policy size limit, provenance update requirement, and mobile playable-space baseline.                                              |
| Session 10 - Quality Gates And Enablement   | Historical opt-in approval, privacy boundary, no remote loading, asset-size gate, runtime private-data gate, build/budget checks, and final enablement record. |

Deferred-system anchors:

* Worker simulation remains deferred until profiling shows main-thread simulation blocks input or rendering.
* Audio is direct Web Audio with generated project-owned assets and persisted mute/music/SFX preferences. An external audio wrapper remains deferred until sound complexity justifies the dependency.
* Gamepad, pointer lock, generated content packs, script collectors, remote loading, and large media packs remain out of scope for the first slice.
* Any session that changes a deferred-system anchor must update this baseline, the relevant implementation notes, and the docs that own the source decision.

## Deferred Non-Goals

These systems are out of scope for the first implementation slice unless a later accepted session explicitly changes the baseline with evidence:

* External audio wrapper dependencies.
* Web Worker simulation, OffscreenCanvas, or worker renderer ownership.
* Gamepad support, pointer lock, physics engines, multiplayer, NPC systems, inventory trees, crafting systems, large meta-progression trees, procedural biomes, or large asset packs.
* Generated content packs or script collectors.
* Remote executable packages, marketplace installs, iframe-wrapped games, or a separate embedded game app.
* Unbounded token-burn rewards or raw dollar-spend dominant progression.
* Unreviewed third-party art, unoptimized generated media, or assets above the committed media-policy limits.


---

# 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/docs/extensions/ai-rogue/implementation-baseline.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.