> 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/phase39-session07-real-content-expansion-path/spec.md).

# Session Specification

**Session ID**: `phase39-session07-real-content-expansion-path` **Phase**: 39 - AI Rogue Level Authoring Infrastructure **Status**: Not Started **Created**: 2026-07-01

***

## 1. Session Overview

This session proves the first real AI Rogue content expansion on top of the Phase 39 authored level workflow. Sessions 01 through 06 established the level registry, routed depth decisions through specs, added validation and save parity, proved a reused-media fourth floor, moved enemy media requirements into metadata, and generalized boss/finale contracts.

The next executable slice is to promote one prepared standard enemy into actual authored level content without adding a second content track, new media, a new audio family, remote loading, or a save-schema version bump. The selected content path is `insight-beetle` on the existing depth-4 `firewall-gauntlet` floor because the candidate is already cataloged, has committed five-frame visuals, uses the existing `corruption` audio family, has persisted-ID parity, and exercises the method-based death reward path that is not yet represented in authored floor content.

The implementation should be catalog/spec work plus focused tests. It should avoid broad runtime archaeology by changing the authored level spec and nearby content, generation, combat, render, asset, audio, and save tests only where needed to prove the new content path.

***

## 2. Objectives

1. Activate one prepared standard enemy as real authored content through the level registry and a floor guarantee.
2. Prove the enemy's spawn, frame, audio, combat effect, death reward, render model, and save parse behavior with focused tests.
3. Preserve browser-local save boundaries, authored max-depth behavior, and route-lazy renderer ownership without a schema version bump.
4. Record implementation evidence that future real content can be added through catalogs, specs, and tests rather than scattered depth branches.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase39-session04-existing-media-floor-four` - Adds and validates the depth-4 `firewall-gauntlet` floor with deterministic generation, route safety, final-floor behavior, and save hydration evidence.
* [x] `phase39-session05-enemy-metadata-and-derived-asset-checks` - Adds enemy audio-family and frame-set metadata plus derived asset/audio validation for prepared standard enemies.
* [x] `phase39-session06-boss-and-finale-contracts` - Generalizes Kernel Sentinel boss/finale presentation and keeps depth 4 as the authored finale path.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Authored level specs in `src/extensions/ai-rogue/runtime/content/levels.ts`.
* Prepared enemy templates in `src/extensions/ai-rogue/runtime/entities.ts`.
* Save parity arrays and parsers in `src/extensions/ai-rogue/save-schema.ts`.
* Generation, simulation, render model, asset, audio, and save Vitest suites under `src/extensions/ai-rogue/`.
* Phase 39 media guidance in `docs/ongoing-projects/ai-rogue-phase-39-asset-generation-plan.md`.

### Environment Requirements

* Local repository checkout with dependencies installed or installable through `bun install`.
* Focused validation available through `bunx vitest run`.
* Type validation available through `bun run typecheck`.
* Asset-size validation available through `bash scripts/check-asset-sizes.sh` if asset manifests or media references change.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue players can encounter `insight-beetle` in authored content through the `firewall-gauntlet` level spec and one explicit floor guarantee.
* AI Rogue content validation continues to prove the selected enemy has known frame metadata, known audio-family metadata, persisted-ID parity, and safe product-facing labels.
* AI Rogue deterministic generation tests prove the guaranteed enemy appears on depth 4 without breaking exit reachability, guard adjacency, prefab, terminal, objective, or finale behavior.
* AI Rogue combat/effect tests prove `insight-beetle` still repairs the operator only through the existing Strike death reward path.
* AI Rogue render, asset, and audio tests prove the selected enemy projects existing committed frames and existing audio-family cues.
* AI Rogue save tests prove persisted snapshots containing `insight-beetle` parse and hydrate under `AI_ROGUE_SAVE_SCHEMA_VERSION` 1.

### Out Of Scope (Deferred)

* Adding another enemy, terminal, objective, protocol, status, theme, music track, ambience loop, boss, miniboss, or floor - Reason: the session must prove one real content path before widening content scope.
* Generating new runtime media - Reason: the Phase 39 asset plan says prepared enemy sets can complete the low-risk Session 07 content proof without new generated assets.
* Adding a new persisted enemy ID or bumping `AI_ROGUE_SAVE_SCHEMA_VERSION` - Reason: `insight-beetle` is already present in runtime templates and persisted enemy-kind parity arrays.
* Route-visible UI, controls, audio unlock changes, PixiJS renderer redesign, remote loading, collectors, hosted writes, telemetry, analytics, workers, dynamic plugins, or public demo behavior - Reason: this is local runtime content activation and test coverage only.

***

## 5. Technical Approach

### Architecture

Update the authored `firewall-gauntlet` level spec so `insight-beetle` becomes a guaranteed enemy on depth 4. Keep reusable enemy data in `AI_ROGUE_ENEMY_TEMPLATES`; do not add a second catalog or a new depth branch. The level spec remains the place that decides when the enemy appears, while the existing template supplies behavior, stats, audio family, frame set, and death reward metadata.

Preserve save boundaries by relying on the existing parser-owned persisted enemy-kind arrays and save-schema parity tests. If implementation discovers a missing persisted ID, add the ID deliberately to the parser-owned arrays and keep `AI_ROGUE_SAVE_SCHEMA_VERSION` unchanged unless a real migration is required. Current repo evidence indicates no schema edit should be required.

Update focused tests close to the behavior they protect: content registry and baseline tests for authored expectations, world/golden tests for deterministic spawn behavior, ecology/enemy-effects or simulation tests for the death reward, render-model tests for frame projection, audio/assets tests for metadata-backed media coverage, and save-schema tests for parse/hydrate behavior.

### Design Patterns

* Spec-owned activation: Add the enemy through one authored level spec and guarantee, not through scattered resolver branches.
* Catalog reuse: Use the existing `insight-beetle` template, frame set, audio family, and death reward metadata instead of introducing new runtime systems.
* Behavior-preserving regression gates: Update deterministic expectations only where the new guaranteed enemy intentionally changes depth-4 content.
* Parser-owned persistence: Keep save compatibility in `save-schema.ts` and prove parity through tests rather than inferring safety from runtime enums.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                                                          | Est. Lines |
| ---- | -------------------------------------------------------------------------------- | ---------- |
| None | Existing AI Rogue content, runtime, docs, and test owners can hold this session. | 0          |

### Files To Modify

| File                                                                   | Changes                                                                                              | Est. Lines |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/content/levels.ts`                    | Add `insight-beetle` to the depth-4 authored content path and keep product-facing level copy safe.   | \~12       |
| `src/extensions/ai-rogue/runtime/content/__tests__/levels.test.ts`     | Assert the level registry activates the selected enemy and keeps validation passing.                 | \~35       |
| `src/extensions/ai-rogue/runtime/__tests__/content-baseline.test.ts`   | Update authored depth-4 baseline expectations for the new guaranteed enemy.                          | \~25       |
| `src/extensions/ai-rogue/runtime/__tests__/world.test.ts`              | Prove depth-4 generation includes the guaranteed enemy while route safety remains intact.            | \~35       |
| `src/extensions/ai-rogue/runtime/__tests__/golden-determinism.test.ts` | Regenerate the intentional depth-4 deterministic summaries after the new spawn path lands.           | \~90       |
| `src/extensions/ai-rogue/runtime/__tests__/ecology.test.ts`            | Keep template behavior coverage aligned with authored activation and death reward expectations.      | \~35       |
| `src/extensions/ai-rogue/runtime/__tests__/enemy-effects.test.ts`      | Add focused death reward coverage if existing ecology coverage is not sufficient.                    | \~35       |
| `src/extensions/ai-rogue/runtime/__tests__/render-model.test.ts`       | Prove `insight-beetle` projects committed enemy frames through the render model.                     | \~35       |
| `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts`             | Prove derived gameplay frames include the selected enemy's five-frame set.                           | \~25       |
| `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts`              | Prove the selected enemy uses the existing `corruption` audio family without new audio maps.         | \~25       |
| `src/extensions/ai-rogue/__tests__/save-schema-parity.test.ts`         | Keep persisted enemy-kind parity explicit for the activated enemy.                                   | \~20       |
| `src/extensions/ai-rogue/__tests__/save-schema.test.ts`                | Prove snapshots containing `insight-beetle` parse and hydrate without a schema version bump.         | \~45       |
| `docs/ongoing-projects/ai-rogue-phase-39-asset-generation-plan.md`     | Record that Session 07 selected the prepared `insight-beetle` path and needs no new generated media. | \~20       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `firewall-gauntlet` includes `insight-beetle` as the single newly activated real-content enemy.
* [ ] Depth-4 generation deterministically places `insight-beetle` through the authored guarantee while keeping the exit reachable and guarded.
* [ ] `insight-beetle` uses existing behavior, existing `corruption` audio, and committed five-frame metadata.
* [ ] Strike-kill death reward behavior remains deterministic and covered by tests.
* [ ] Save parsing and hydration accept `insight-beetle` under the current save schema version.

### Testing Requirements

* [ ] Content registry, content baseline, world, and golden determinism tests pass for the updated authored floor.
* [ ] Ecology or enemy-effect tests pass for `insight-beetle` combat and death reward behavior.
* [ ] Asset, audio, render-model, save-schema, and save-schema-parity tests pass.
* [ ] `bun run typecheck` passes.
* [ ] `bash scripts/check-asset-sizes.sh` passes if asset docs, manifests, or media references change.

### Non-Functional Requirements

* [ ] No new remote loading, collectors, hosted writes, telemetry, analytics, workers, dynamic plugins, browser bridge calls, or public demo live behavior are introduced.
* [ ] `AI_ROGUE_SAVE_SCHEMA_VERSION` remains unchanged unless a real migration is discovered and justified.
* [ ] Added product-facing labels and docs avoid private paths, command bodies, credentials, raw prompts, transcripts, tokens, and local usernames.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.

***

## 8. Implementation Notes

### Working Assumptions

* Activate `insight-beetle` instead of creating a brand-new enemy ID: repo evidence shows the template, five-frame set, `corruption` audio family, death reward metadata, atlas frames, and persisted-ID parity already exist. This is safe because the Session 07 goal is a real content path, and the Phase 39 asset plan explicitly recommends prepared enemy promotion for low-risk completion.
* Target `firewall-gauntlet` for the first real content proof: Session 04 validated depth 4 with route safety, deterministic generation, objective, finale, and save evidence; Session 06 validated the boss/finale contract for that same floor. Planning can proceed without a new floor.
* Do not require browser proof at planning time: the expected source changes are runtime content and focused tests, not route-visible UI, controls, audio unlock behavior, or PixiJS mount logic. Browser proof becomes required if implementation touches those surfaces.

### Conflict Resolutions

* The Session 07 stub says "Add one standard enemy," while the current code already contains several dormant prepared standard enemy templates. The chosen interpretation is to activate one existing cataloged enemy through an authored level guarantee rather than invent a new saved ID. This better matches the Phase 39 asset plan and keeps the session to one content type.
* The stub allows adding a terminal, objective, protocol, status, miniboss, or music only after the enemy path is stable. The chosen scope excludes those additions entirely because one enemy plus verification is sufficient for the 2-4 hour session contract.

### Key Considerations

* Preserve AI Rogue compatibility exports; do not remove runtime barrel or migration re-exports while activating content.
* Keep browser-local save data schema-backed and parser-owned.
* Maintain static/public-demo boundaries; this session must not create a hosted runtime or collector path.
* Keep validation messages deterministic and privacy-safe.

### Potential Challenges

* Updating guaranteed enemies can shift golden outputs: regenerate only the intentional depth-4 summaries and keep other authored floors unchanged.
* Death reward behavior may already be covered in ecology tests: add the smallest missing regression rather than duplicating broad combat coverage.
* Save parity may already include `insight-beetle`: verify explicitly and avoid no-op schema churn.
* Route-visible presentation may be indirectly affected through render projection: cover committed frames in render-model tests and use browser proof only if route or renderer ownership changes.

### Relevant Considerations

* \[P35] **AI Rogue compatibility exports remain**: Keep migration exports and runtime boundaries stable while touching content tests.
* \[P30/P32/P34-P35] **Schema-backed browser-local state works**: Save parsing and hydration must remain parser-owned and non-throwing.
* \[P30/P34-P38] **Visibility gates catch real issues**: Pair focused runtime, asset, audio, save, and type gates before claiming content proof.
* \[P31-P38] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Avoid public-demo, hosted, bridge, or collector changes in this local content session.
* \[P30/P32/P34-P38] **Do not widen AI Rogue capabilities without review**: Avoid remote content loading, workers, WebGPU changes, hosted writes, or new direct media reuse outside reviewed assets.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Authored level changes accidentally break deterministic generation or route safety.
* Persisted enemy snapshots accept runtime IDs only by accident rather than through parser-owned parity.
* New product-facing enemy/floor copy leaks diagnostics, private paths, or implementation language.

***

## 9. Testing Strategy

### Unit Tests

* `content/__tests__/levels.test.ts` for registry activation, validation, and safe text.
* `content-baseline.test.ts` for depth helper expectations and authored guarantee routing.
* `world.test.ts` and `golden-determinism.test.ts` for deterministic generated floor behavior.
* `ecology.test.ts` and/or `enemy-effects.test.ts` for the selected enemy's death reward behavior.
* `assets.test.ts`, `audio.test.ts`, and `render-model.test.ts` for committed frame, audio-family, and projection coverage.
* `save-schema.test.ts` and `save-schema-parity.test.ts` for parser-owned persisted ID coverage.

### Integration Tests

* Focused AI Rogue runtime suite covering world generation, simulation, content registry, render model, audio, assets, and save parser behavior.
* `bun run typecheck` after source edits.
* `bash scripts/check-asset-sizes.sh` if docs, manifests, or media references change.

### Runtime Verification

* No browser runtime proof is required unless implementation touches route-visible UI, controls, audio unlock behavior, PixiJS mount code, or renderer import shape.
* If those surfaces change, run the relevant AI Rogue Playwright desktop and mobile checks before validation.

### Edge Cases

* Save payload with `insight-beetle` parses and hydrates without a schema version bump.
* Depth 4 still has reachable exit, adjacent Kernel Sentinel guard, expected terminal/prefab, objective lock, and finale behavior.
* The selected enemy's death reward does not fire for the wrong kill source.
* Derived frame and audio checks remain deterministic and deduplicated.
* Product-facing level and enemy labels stay safe and diagnostic-free.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase39-session04-existing-media-floor-four`, `phase39-session05-enemy-metadata-and-derived-asset-checks`, `phase39-session06-boss-and-finale-contracts`
* Depended by: `phase39-session08-validation-and-documentation-hardening`

***

## 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/phase39-session07-real-content-expansion-path/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.