# ============================================
# TIER 1: CRITICAL CONTEXT (Always Loaded)
# ============================================
@PROJECT_CONTEXT.md
@TODO.md
@README.md

# ============================================
# TIER 2: TECHNICAL REFERENCE (Always Loaded)
# ============================================
@doc/HOWTO.md
@doc/CONTRIBUTING.md
@doc/AI_RULES.md
@doc/EFFECT_WORKFLOW.md

# ============================================
# TIER 3: DESIGN DOCS (Load On-Demand)
# ============================================
# Load these only when working on specific subsystems:
#
# Audio & Tracker:
#   doc/SPECTRAL_BRUSH_EDITOR.md - Spectral editor design
#   doc/TRACKER.md - Audio tracker system
#
# 3D & Graphics:
#   doc/3D.md - 3D rendering architecture
#   doc/PROCEDURAL.md - Procedural generation
#
# Build & Assets:
#   doc/ASSET_SYSTEM.md - Asset pipeline details
#   doc/BUILD.md - Build system details
#   doc/FETCH_DEPS.md - Dependency management
#
# Testing & Tools:
#   doc/test_demo_README.md - test_demo tool documentation
#
# Architecture & Reference:
#   doc/ARCHITECTURE.md - Detailed system architecture
#   doc/CODING_STYLE.md - Code style examples
#   doc/BACKLOG.md - Untriaged future goals
#   doc/TOOLS_REFERENCE.md - Developer tools reference

# ============================================
# TIER 4: HISTORICAL ARCHIVE (Load Rarely)
# ============================================
# Load these only for historical context or debugging:
#
# Completion History:
#   Use: "read @doc/COMPLETED.md" for detailed history
#
# Technical Investigations:
#   doc/GPU_EFFECTS_TEST_ANALYSIS.md
#   doc/PLATFORM_ANALYSIS.md
#   doc/PLATFORM_SIDE_QUEST_SUMMARY.md
#   doc/PEAK_FIX_SUMMARY.md
#   doc/CNN_DEBUG.md - CNN post-processing binding bug resolution
#
# Agent Handoffs:
#   doc/HANDOFF_CLAUDE.md
#   doc/HANDOFF.md
#   doc/HANDOFF_2026-02-04.md
#
# Task Tracking:
#   doc/TASKS_SUMMARY.md

# ============================================
# PROJECT RULES (IMPORTANT)
# ============================================

IMPORTANT:
- Follow all rules in doc/AI_RULES.md
- This repository is shared with Claude-Code
- You are working in turns with another AI agent
- Work only on tasks explicitly requested by the user
- Do NOT modify files outside the current scope
- Do NOT perform refactors or cleanups unless explicitly asked
- Concise answers only
- No explanations unless asked
- Max 100 tokens per reply

# Context Maintenance:
- See @doc/CONTEXT_MAINTENANCE.md for keeping context clean
- Archive completed work to doc/COMPLETED.md regularly
- Keep PROJECT_CONTEXT.md focused on current status
- Keep TODO.md focused on active/next tasks only

# ============================================
# CURRENT STATE SNAPSHOT (Gemini-Specific)
# ============================================
<state_snapshot>
    <overall_goal>
        Produce a cross-platform (Windows, macOS, Linux) 64-kilobyte demoscene production. This is achieved through a C++ codebase utilizing WebGPU for graphics (with a hybrid SDF/rasterization pipeline) and a real-time procedural audio engine for sound, with a heavy focus on size-optimization at all stages.
    </overall_goal>

    <active_constraints>
        - All tests passing (36/36 - 100%).
        - Strict 64k final binary size target.
        - Adherence to project coding style and contribution guidelines is mandatory.
    </active_constraints>

    <key_knowledge>
        - **Workspace System:** The project is organized into self-contained workspaces (e.g., `workspaces/main`, `workspaces/test`) managed by a `workspace.cfg` file, separating demo-specific content from a `common/` directory that holds shared shaders and resources. Selection is done at build time with `-DDEMO_WORKSPACE=<name>`.
        - **Build & Asset Pipeline:** A modular CMake system orchestrates the build. It uses host-native tools (`asset_packer`, `seq_compiler`, `tracker_compiler`) to parse manifest files (`assets.txt`, `timeline.seq`, `music.track`) and compile assets directly into the binary as C++ data, including procedural asset generation.
        - **Audio Engine:** A real-time, sample-accurate audio engine with a tracker system for sequencing patterns from `.track` files. It features procedural synthesis from spectrograms (FFT-based IDCT), variable tempo that is decoupled from visual timing, and an abstracted backend for testing and offline rendering (`WavDumpBackend`).
        - **Graphics & Rendering:** The renderer uses WebGPU (wgpu-native) and WGSL shaders. It employs a hybrid technique, rasterizing proxy geometry (cubes) and then performing SDF raymarching within the fragment shader. The 3D system supports BVH acceleration, and there's a pipeline for importing OBJ models.
        - **Sequence & Timing:** Visuals are defined in `.seq` files using a beat-based timeline that is compiled into physical seconds. Shaders receive a `CommonPostProcessUniforms` buffer containing both physical time (`time`) for constant-speed animations and musical time (`beat_time`, `beat_phase`) for syncing with the audio playback clock.
        - **CNN Post-Processing:** The project features a sophisticated CNN post-processing pipeline (CNNv2) for visual stylization. This includes a full Python/PyTorch training toolchain, a binary weight format, and a WebGPU-based validation tool. The network uses 7D parametric static features (RGBD, UV, sin, bias) for rich, position-aware effects.
        - **Development Workflow:** There is a strong emphasis on tooling and process, including a visual timeline editor, audio analysis tools, a web-based CNN debugger, strict coding standards enforced by `clang-format`, and a comprehensive pre-commit script (`./scripts/check_all.sh`).
    </key_knowledge>

    <artifact_trail>
        - `GEMINI.md`: This file, synchronized with CLAUDE.md structure
        - `PROJECT_CONTEXT.md`: Current system status
        - `TODO.md`: Active priorities (Task #5 in progress)
    </artifact_trail>

    <recent_actions>
        - **File Hierarchy Cleanup:** Major reorganization of the project structure, establishing the `workspaces/` and `common/` directories and eliminating ~100 redundant files (especially shaders).
        - **CNNv2 Training Pipeline:** Fixed critical checkpointing bugs and streamlined the output of the training scripts for faster iteration.
        - **Effect Render API Refactor:** Simplified the `Effect::render` API and fixed uniform initialization bugs across 19 effects.
        - **CNN Shader Testing Tool:** Implemented `tools/cnn_test` for offline GPU-accelerated validation of trained CNN models.
    </recent_actions>

    <task_state>
        1. [IN PROGRESS] Task #5: Spectral Brush Editor (Priority 1)
        2. [PENDING] Task #18: 3D System Enhancements (Priority 4)
        3. [RECURRENT] Task #50: WGSL Modularization (Priority 4)
        4. [PENDING] Tracker Humanization & Sample Offset (Priority 3)
    </task_state>
</state_snapshot>