D3-TUI Proto-Run Research Note

Date: 2026-05-11

Agent: researcher

Stage: T0 Intake → T1 Review / Research (Read-Only Proto-Run)

Executive Summary

This research note summarizes findings from the initial read-only proto-run of the D3-TUI project. The goal was to understand the current state of the codebase, identify contradictions, unknowns, and toolchain blockers.

1. Authoritative Documentation Review

REALIGNMENT_BRIEF.md

• Key Points:
• Previous work drifted from canonical D3-TUI Forgejo repo
• Visual target drifted from W/A/R/P subset to full D2 title menu
• Build-image work carried contradictory assumptions (CDI, ISO, raw IP.BIN, MIL-CD, physical hardware)
• Correct Focus: Forgejo repo, RG40XXV/Knulli FlycastVL validation, D2 Disc 1 title menu
• Private assets location: /mnt/kitchen/from-house/assets/private/d2-title

D2_TITLE_MENU_TARGET.md

• Target Visual: Snowy mountain background, animated snow flecks, translucent red D2 logo, menu stack, WARP copyright
• Validation Context: RG40XXV/FlycastVL with specific RetroArch command line
• Important: Old W/A/R/P proof screen is insufficient - it's only decoder evidence

ASSET_EXTRACTION_MAP.md

• Private Source: /mnt/kitchen/from-house/assets/private/d2-title
• High-Priority Candidates: NLOGO.PVM, Q_TITLEBGMT.PVM, Q_TITLEMENU.PVM, Q_TITLE2D.PVM, Q_DMTITLE.PVM, Q_DJSNOW.PVM, SAKA_MNSNOW.PVM, P_COMTIT*.PVR
• Extraction Path:
• Prefer FlycastVL texture dumps from RG40XXV
• Extract from private D2 material using file map
• Keep raw/extracted assets out of git
• Commit only tooling, metadata, manifests, original source

BUILD_TARGET_POLICY.md

• Active Target: RG40XXV/Knulli FlycastVL emulator validation
• Accepted Artifacts: KOS ELF for Flycast, GDI/CHD for disc-image
• Out of Scope: MIL-CD exploit, CDI-first, physical hardware, raw IP.BIN concatenation
• Build Commands: make d2-assets, make flycast-image
• Visual Proof: Must match D2_TITLE_MENU_TARGET.md, not old W/A/R/P screen

AGENT_PROTOCOL.md

• Required Loop: Read AGENTS.md, pick small step, work in mounted repo, no secrets, commit changes, comment on issues, write journal entries
• No Deletion Policy: Don't delete archives, images, containers, private assets, or build evidence
• Blocked Validation: Continue with review, tests, docs, contradiction removal, issue grooming

2. Repository Structure Analysis

Key Directories and Files

/work/repo/
├── AGENTS.md                  # Team contract
├── Makefile                   # Build pipeline (d2-assets, flycast-image)
├── docs/                      # Authoritative documentation
├── src/                      # Source code
│   ├── d3tui/                # Main D3-TUI implementation
│   │   ├── assets/           # Asset management
│   │   │   ├── d2_menu_assets.c  # Generated asset data (1.7MB)
│   │   │   ├── d2_menu_assets.h  # Generated asset headers
│   │   │   ├── asset_metadata.c  # Asset metadata
│   │   │   └── asset_metadata.h  # Asset metadata headers
│   │   ├── render/           # Rendering system
│   │   ├── terminal/         # Terminal core
│   │   ├── font/             # Font system
│   │   ├── input/            # Input system
│   │   └── ...               # Other subsystems
│   ├── d3tui_main.c          # Main entry point
│   ├── d3tui_kos_stubs.c     # KOS stubs
│   └── IP.BIN                # Dreamcast IP.BIN (32KB)
├── tools/                    # Build tools
│   ├── extract_d2_menu_assets.py  # Asset extraction tool
│   └── title_menu_manifest.json   # Asset manifest
├── scripts/                  # Build scripts
│   ├── build-dreamcast.sh    # Main build script
│   ├── verify-flycast.sh    # Flycast verification
│   └── ...                   # Other scripts
├── tests/                    # Test suite
│   └── python/              # Python tests
│       └── test_extraction.py  # Extraction tool tests
├── asset-staging/            # Asset staging (metadata-only)
│   └── d2/                  # D2 assets (empty - private material)
└── workspace/                # Workspace directory

Build Pipeline

1. Asset Extraction: make d2-assets
2. Runs tools/extract_d2_menu_assets.py with title_menu_manifest.json
3. Generates src/d3tui/assets/d2_menu_assets.[ch]

4. Currently uses placeholder data (no private assets available in repo)

5. ELF Build: make elf or make flycast-image

6. Runs scripts/build-dreamcast.sh
7. Compiles source files with KOS toolchain
8. Produces ELF executable for Flycast validation

9. Validates ELF entry point (must be in Dreamcast RAM at 0x8c...)

10. Verification: make verify-flycast

11. Runs scripts/verify-flycast.sh
12. Launches Flycast emulator with generated ELF
13. Captures screenshot after 10 seconds

Current Build Status

• Asset Extraction: Partially implemented
• Extraction tool exists and has comprehensive test coverage
• Manifest defines 11 required assets for title menu
• Generated asset files exist but likely contain placeholder data

• No private D2 assets in repo (as expected per ASSET_EXTRACTION_MAP.md)

• Build System: Complete

• Makefile with proper targets
• Build scripts with KOS detection and validation

• Manifest generation for build artifacts

• Test Coverage: Comprehensive

• Unit tests for extraction tool (test_extraction.py)
• Tests cover Morton index, RGB conversion, PVRT parsing, PVM entry parsing, manifest loading
• 12 test classes with good coverage of edge cases

3. Code Analysis

Asset Extraction Tool (tools/extract_d2_menu_assets.py)

Capabilities: - Supports PVRT format decoding (RGB565, ARGB4444, ARGB1555) - Handles multiple data formats (square twiddled, VQ, smallVQ) - Parses PVM containers with multiple entries - Auto-detects PVRT format and dispatches to appropriate decoder - Generates C header/source files with asset data - Preserves existing placeholders in generated headers

Supported Formats: - Pixel formats: RGB565 (0x01), ARGB4444 (0x02), ARGB1555 (0x03) - Data formats: Square Twiddled (0x01), VQ (0x03), SmallVQ (0x10)

Manifest-Driven Extraction: - Loads assets from JSON manifest - Supports both PVM entries and standalone PVR files - Handles missing files gracefully (skips with error message) - Validates asset roles and symbols

Build Script (scripts/build-dreamcast.sh)

Features: - KOS toolchain detection (multiple fallback paths) - Proper environment setup for Dreamcast cross-compilation - Source file validation (checks all sources exist) - ELF validation (entry point must be in Dreamcast RAM) - Manifest generation with build metadata

Source Files Compiled: - Main: d3tui_main.c, d3tui_kos_stubs.c - Assets: d2_menu_assets.c, asset_metadata.c - Terminal: terminal_core.c, terminal_state.c, ansi_parser.c - Render: render_system.c - Font: font_system.c, font_atlas.c - Input: input_system.c - VMU: vmu_integration.c - Spectre: spectre_integration.c - Memory: memory_management.c - Debug: debug_system.c, debug_menu.c - Test: test_framework.c

Test Suite (tests/python/test_extraction.py)

Test Coverage: - Morton index calculation (identity, range, uniqueness) - RGB conversion (ARGB4444, ARGB1555, RGB565) - PVRT header parsing - Square twiddled RGB565 decoding - VQ RGB565 decoding - Auto-decoder dispatch - PVM entry parsing - Manifest loading and skipping logic - Existing placeholder preservation - Title menu manifest coverage validation - Header declarations coverage

Test Quality: - Comprehensive unit tests with good edge case coverage - Synthetic data generation for isolated testing - No dependency on private D2 assets - Validates manifest schema and asset requirements

4. Contradictions and Issues

No Major Contradictions Found

The codebase appears well-aligned with the authoritative documentation:

• ✅ Build targets match BUILD_TARGET_POLICY.md (Flycast ELF validation)
• ✅ Asset extraction follows ASSET_EXTRACTION_MAP.md (manifest-driven, private assets out of git)
• ✅ Visual target aligns with D2_TITLE_MENU_TARGET.md (title menu assets in manifest)
• ✅ No MIL-CD, CDI, or physical hardware assumptions in build scripts

Minor Observations

1. Python Dependency: The extraction tool and tests require Python, but Python is not available in the current environment. This is likely a container setup issue.

2. Private Assets: The asset-staging/d2 directory is empty (as expected), but this means the extraction tool cannot produce real asset data without access to /mnt/kitchen/from-house/assets/private/d2-title.

3. Generated Files: The d2_menu_assets.c file is 1.7MB, suggesting it contains placeholder data rather than real extracted assets.

4. Test Execution: Cannot run Python tests due to missing Python runtime, but test code appears comprehensive and well-written.

5. Unknowns and Blockers

Toolchain Blockers

1. Python Runtime Missing:
2. Extraction tool and tests require Python 3
3. Python is not installed in the current environment
4. Dockerfile specifies Python 3 should be installed, but it's missing
5. Impact: Cannot run asset extraction or tests
6. Workaround: Install Python or use pre-generated assets

Asset Blockers

1. Private D2 Assets Unavailable:
2. Extraction tool requires access to /mnt/kitchen/from-house/assets/private/d2-title
3. This path is not accessible in the current environment
4. Impact: Cannot extract real D2 title menu assets
5. Workaround: Use placeholder data for development, extract on system with access to private assets

Validation Blockers

1. Flycast Emulator:
2. Verification script assumes Flycast is available at /Applications/Flycast.app/Contents/MacOS/Flycast
3. This is a macOS path, unlikely to work in current environment
4. Impact: Cannot run automated Flycast verification
5. Workaround: Manual verification or configure Flycast path for current environment

6. Recommendations

Immediate Next Steps

1. Resolve Python Dependency:
2. Install Python 3 in the environment
3. Verify test suite runs successfully

4. Document Python version requirement

5. Asset Extraction Strategy:

6. Document the two-phase approach:
   • Phase 1: Develop with placeholder assets (current state)
   • Phase 2: Extract real assets on system with private D2 access

7. Create script to generate placeholder assets for development

8. Build Verification:

9. Test ELF build without asset extraction
10. Verify KOS toolchain detection works in current environment

11. Document build prerequisites clearly

12. Test Coverage:

13. Once Python is available, run full test suite
14. Add integration tests for end-to-end asset extraction
15. Consider adding mock private assets for CI testing

Longer-Term Recommendations

1. Container Setup:
2. Ensure Dockerfile provisions all required dependencies
3. Add health checks for Python and other tools

4. Document container setup process

5. Asset Pipeline:

6. Create documentation for asset extraction workflow
7. Add validation that extracted assets match expected formats

8. Consider adding asset preview generation

9. Build Validation:

10. Add automated checks for ELF entry point
11. Validate generated manifest contains expected metadata
12. Consider adding size/performance metrics

7. Conclusion

The D3-TUI project is well-structured and aligned with its documentation. The main blockers are environmental:

1. Missing Python runtime prevents running extraction tool and tests
2. Private D2 assets are not accessible in current environment
3. Flycast emulator path is macOS-specific

These are solvable issues. The codebase itself is in good shape with: - Clear architecture and separation of concerns - Comprehensive test coverage - Well-documented build pipeline - Proper handling of private assets (out of git)

Once the environmental blockers are resolved, the project should be able to proceed with: - Asset extraction from private D2 material - Full build and validation pipeline - Automated testing

8. References

• Authoritative Docs: /work/repo/docs/
• Build Scripts: /work/repo/scripts/
• Extraction Tool: /work/repo/tools/extract_d2_menu_assets.py
• Test Suite: /work/repo/tests/python/test_extraction.py
• Asset Manifest: /work/repo/tools/title_menu_manifest.json
• Generated Assets: /work/repo/src/d3tui/assets/d2_menu_assets.[ch]