> 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/phase30-session02-extension-shell-and-routes/spec.md).

# Session Specification

**Session ID**: `phase30-session02-extension-shell-and-routes` **Phase**: 30 - AI Rogue Game Extension **Status**: Not Started **Created**: 2026-06-22

***

## 1. Session Overview

This session adds the disabled-first `ai-rogue` client extension shell to the existing AI OS compile-time extension platform. It registers AI Rogue, exposes the primary Play surface plus Ledger, Loadout, and Settings surfaces, and keeps the first screen canvas-first without mounting PixiJS or game runtime code.

It is next because Session 01 ratified the product name, extension ID, route, capability posture, asset constraints, privacy boundary, and deferred systems. The shell must exist before Session 03 can prove the lazy PixiJS runtime boundary and before later economy, persistence, simulation, and gameplay work has routes to attach to.

The implementation should reuse the existing dynamic extension host instead of creating bespoke TanStack route files. AI Rogue should be visible in the registered extension index, appear in navigation only when enabled through `VITE_CLAUDE_OS_ENABLED_EXTENSIONS`, and render honest disabled, missing-data, warning, and error states when runtime data is absent or unavailable.

***

## 2. Objectives

1. Register `ai-rogue` as a static client extension with `play` as the default view and no PixiJS, browser-only, or game-runtime imports in registry code.
2. Create accessible Play, Ledger, Loadout, and Settings shell views that communicate disabled-first and missing-data states without implementing game logic.
3. Declare only the initial `readGeneratedData` and `localStorage` capabilities with reasons that match Session 01.
4. Add focused registry, route, view, and import-boundary tests for AI Rogue registration, env gating, default routing, disabled behavior, and capability declarations.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase30-session01-direction-and-asset-readiness` - Ratified AI Rogue naming, route, surfaces, capability posture, asset baseline, PixiJS lazy boundary, privacy boundary, and deferred-system anchors.

### Required Tools Or Knowledge

* Existing extension platform in `src/extensions/registry.ts`, `src/extensions/types.ts`, `src/extensions/use-extension-data.ts`, and `src/components/extensions/extension-host.tsx`.
* Existing route and registry tests in `src/routes/__tests__/extensions-routes.test.tsx` and `src/lib/__tests__/extension-registry.test.ts`.
* Phase 30 baseline docs in `docs/extensions/ai-rogue/implementation-baseline.md` and `docs/extensions/ai-rogue/visual-assets.md`.

### Environment Requirements

* Bun 1.3.14 project tooling.
* React 19, TanStack Router/Start, Vite 8, Tailwind CSS 4, Vitest, and happy-dom test environment.
* `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` remains the extension visibility gate for sidebar navigation and enabled-extension lists.

***

## 4. Scope

### In Scope (MVP)

* AI OS operator can see `AI Rogue` as a registered extension in the Extensions index - implemented through a static client extension entry.
* AI OS operator can open `/extensions/ai-rogue/play` and the default `/extensions/ai-rogue` redirect path - implemented by the existing dynamic extension routes.
* AI OS operator can switch between Play, Ledger, Loadout, and Settings shell views - implemented as lightweight React view modules.
* AI OS operator gets honest disabled, missing-data, warning, and error states
  * implemented through shared AI Rogue view-state presentation fed by `ExtensionViewProps`.
* AI OS maintainer can verify initial capabilities - implemented as exactly `readGeneratedData` and `localStorage` declarations.
* AI OS maintainer can verify runtime isolation - implemented with tests and source checks showing no `pixi.js` or AI Rogue game runtime import in the registry, client metadata, or shell views.

### Out Of Scope (Deferred)

* PixiJS runtime mounting, ticker loop, renderer lifecycle, canvas nonblank checks, and route-away cleanup - Reason: Session 03 owns the lazy runtime boundary.
* Economy transforms, wallet state, manual claims, and ledger mutations - Reason: Session 04 owns Insight Shards derivation and claim behavior.
* Browser persistence, IndexedDB, save contracts, and reset behavior - Reason: Session 05 owns local persistence.
* Dungeon simulation, input commands, combat, FOV, world generation, and progression - Reason: Sessions 06 through 08 own gameplay logic.
* New collectors, admin writes, network access, remote loading, hosted storage, auth flows, or database dependencies - Reason: Phase 30 keeps the first slice local-first and disabled-first.

***

## 5. Technical Approach

### Architecture

Create `src/extensions/ai-rogue/` as a client-only extension package that mirrors the established Trend Finder extension shape at a smaller scale. The extension exports one `ClientExtension` from `client.tsx`, uses a dedicated `capabilities.ts` for the two initial declarations, and places view modules under `views/`.

The existing extension host already resolves `/extensions/$extensionId/$viewId`, renders shared view navigation, fetches extension runtime state through `useExtensionData()`, and passes `ExtensionViewProps` to each view. Session 02 should compose with that host rather than adding new route files or editing `src/routeTree.gen.ts`.

The Play view should reserve first-screen space for the future game surface and skip a promotional hero. Because `ExtensionHost` renders a hero only when the extension declares one, AI Rogue should omit `hero` and `renderHero` in this session. The Play shell should use stable layout constraints informed by the visual-assets E2E baseline, but it must not import PixiJS or allocate a canvas runtime yet.

### Design Patterns

* Static registry: AI Rogue is imported by `src/extensions/registry.ts` and filtered through existing env parsing for enabled navigation.
* View shell composition: Common status, warning, and section framing live in a small AI Rogue view helper so all four views treat disabled and missing data consistently.
* Data honesty: Missing runtime data is shown as a disabled or unavailable shell state, not as fake gameplay data.
* Import-boundary testing: Source-level tests assert registry and shell files do not import `pixi.js` or runtime modules before Session 03.

***

## 6. Deliverables

### Files To Create

| File                                                | Purpose                                                                                | Est. Lines |
| --------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/capabilities.ts`           | Initial capability declarations for read-generated-data and local storage.             | \~25       |
| `src/extensions/ai-rogue/client.tsx`                | `aiRogueExtension` metadata, view list, nav item, default view, and capability wiring. | \~90       |
| `src/extensions/ai-rogue/views/view-shell.tsx`      | Shared AI Rogue status, warning, missing-data, and panel framing helper.               | \~150      |
| `src/extensions/ai-rogue/views/play-view.tsx`       | Canvas-first Play shell without PixiJS or game runtime mounting.                       | \~130      |
| `src/extensions/ai-rogue/views/ledger-view.tsx`     | Ledger shell for future Insight Shards claims without mutation behavior.               | \~95       |
| `src/extensions/ai-rogue/views/loadout-view.tsx`    | Loadout shell for future upgrades, relics, and classes without persistence.            | \~95       |
| `src/extensions/ai-rogue/views/settings-view.tsx`   | Settings shell for future accessibility, controls, reset, and seed options.            | \~105      |
| `src/extensions/ai-rogue/__tests__/client.test.tsx` | AI Rogue client metadata, view rendering, capabilities, and import-boundary tests.     | \~170      |

### Files To Modify

| File                                                | Changes                                                                               | Est. Lines |
| --------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/registry.ts`                        | Register `aiRogueExtension` next to Trend Finder while preserving env gating.         | \~5        |
| `src/lib/__tests__/extension-registry.test.ts`      | Cover `ai-rogue` registration, env enablement, default view, views, and capabilities. | \~55       |
| `src/routes/__tests__/extensions-routes.test.tsx`   | Cover the Extensions index card and AI Rogue dynamic route rendering.                 | \~60       |
| `src/lib/__tests__/setup-config-extensions.test.ts` | Include `ai-rogue` in registered-ID parsing cases where useful.                       | \~20       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `getExtension("ai-rogue")` returns a registered `ClientExtension` named `AI Rogue` with `defaultViewId` set to `play`.
* [ ] `/extensions/ai-rogue/play` renders the Play shell through the existing dynamic extension route.
* [ ] `/extensions/ai-rogue` redirects to `/extensions/ai-rogue/play` through the existing layout behavior.
* [ ] The extension has Play, Ledger, Loadout, and Settings views and a sidebar nav entry pointing to Play when enabled.
* [ ] `getEnabledExtensions()` includes AI Rogue only when `VITE_CLAUDE_OS_ENABLED_EXTENSIONS` includes `ai-rogue` or `all`.
* [ ] AI Rogue capability declarations contain only `readGeneratedData` and `localStorage` with reasons matching the baseline.
* [ ] Registry, client metadata, and shell views do not import `pixi.js` or game runtime modules.

### Testing Requirements

* [ ] Registry tests cover AI Rogue metadata, default view, env enablement, and capability declarations.
* [ ] Route tests cover the extension index card and AI Rogue Play shell route.
* [ ] AI Rogue client tests cover all four view shells and import-boundary constraints.
* [ ] Focused Vitest suites pass.

### Non-Functional Requirements

* [ ] The Play shell reserves first-screen game space without a promotional hero.
* [ ] Disabled, missing-data, warning, and error states are explicit and accessible.
* [ ] Initial shell code adds no network, admin write, hosted storage, database, collector, or remote-loading surface.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] Focused TypeScript and Vitest checks pass for touched areas

***

## 8. Implementation Notes

### Working Assumptions

* AI Rogue is planned as a single-repo extension rather than a monorepo package: the analysis script reports `monorepo` as `null` and monorepo detection as false, and the phase PRD places new code under `src/extensions/ai-rogue/`. Planning can proceed with repo-root-relative paths.
* Session 02 should not add an `ai-rogue` branch to `src/data/live-data.example.json`: the phase sequence assigns economy data shape and persistence to Sessions 04 and 05, while the existing `useExtensionData()` fallback already lets shell views handle absent runtime data safely.
* AI Rogue should omit extension hero metadata in this session: the Session 02 stub and visual-assets baseline require the Play route to skip a promotional hero and reserve the first screen for the game surface.

### Key Considerations

* Keep the extension disabled-first through the existing env gate.
* Do not create new route files unless the dynamic extension routes prove insufficient.
* Do not add `pixi.js` imports, game runtime modules, browser persistence, or state mutation during this shell session.
* Keep visible copy honest about unavailable runtime data and future gameplay systems.

### Potential Challenges

* Distinguishing disabled and missing runtime data: use the existing `ExtensionViewProps` status, warnings, error, and `data` values, then phrase the shell state as unavailable without claiming generated game data exists.
* Play surface sizing before renderer work: reserve a stable frame based on the locked 32 CSS px tile baseline without creating a Pixi canvas lifecycle.
* Static import drift: enforce source checks so Session 03 is the first place PixiJS can enter the Play route runtime.

### Relevant Considerations

* \[P02] **Static extension registry requires code changes**: Register AI Rogue by editing reviewed source; do not add marketplace, dynamic loading, eval, or remote code.
* \[P02] **Extension payloads and labels stay bounded**: The shell must preserve explicit disabled, fallback, unavailable, warning, and error labels.
* \[P00] **Stack conventions**: React 19, TanStack Start, Vite 8, Bun, and Cloudflare Worker compatibility shape the shell and test approach.
* \[P23] **Do not hand-edit generated route trees**: Use existing dynamic route files and let route generation remain a tooling concern if future route files are added.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Disabled or absent runtime data could look like a working game if shell copy is too optimistic.
* Future game controls could cause layout shift if the Play placeholder does not reserve stable dimensions.
* A stray PixiJS import in the registry or client metadata could move runtime weight into shared chunks before Session 03.

***

## 9. Testing Strategy

### Unit Tests

* Extend `src/lib/__tests__/extension-registry.test.ts` for AI Rogue metadata, `getExtension()`, `getExtensionView()`, `getEnabledExtensions()`, and capability assertions.
* Add `src/extensions/ai-rogue/__tests__/client.test.tsx` for view rendering, status/warning/error display, and static source import-boundary checks.
* Extend `src/lib/__tests__/setup-config-extensions.test.ts` to include `ai-rogue` in parsing examples.

### Integration Tests

* Extend `src/routes/__tests__/extensions-routes.test.tsx` to prove the Extensions index includes AI Rogue and the dynamic route renders the Play shell.

### Runtime Verification

* Run focused Vitest suites for registry, setup config, extension routes, and AI Rogue client tests.
* Run `bun run typecheck` or a focused type check if the implementation touches shared extension types.

### Edge Cases

* Env unset, empty, `none`, explicit `ai-rogue`, mixed `trend-finder,ai-rogue`, and `all`.
* Unknown extension and unknown view still use existing not-found behavior.
* Missing `liveData.extensions.items["ai-rogue"]` renders a safe unavailable state.
* Runtime warnings and errors render without exposing private data.
* Source checks fail if `pixi.js`, `@pixi/react`, `game/`, `renderer`, or runtime modules are imported by shell files.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase30-session01-direction-and-asset-readiness`
* Depended by: `phase30-session03-pixijs-runtime-boundary`, `phase30-session04-economy-and-ledger`, `phase30-session05-persistence-and-save-contracts`, `phase30-session07-play-runtime-integration`

***

## 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/phase30-session02-extension-shell-and-routes/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.