docs: streamline and align AI context files

Synchronized GEMINI.md and CLAUDE.md to provide a consistent
and comprehensive context-loading structure for both AI agents.

- Consolidated the Tier 3 (Design Docs) and Tier 4 (Archive)
  sections to include a detailed, verified list of all relevant
  documentation.
- Standardized the use of the '@' prefix for all file paths,
  assuming a common loader directive.
- Ensured project rules and maintenance guidelines are identical
  between both files.

2 files changed, 50 insertions, 59 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 5e987bd..e525708 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,35 +1,50 @@
-# TIER 1: CRITICAL (Always Loaded)
+# ============================================
+# TIER 1: CRITICAL CONTEXT (Always Loaded)
+# ============================================
 @PROJECT_CONTEXT.md
 @TODO.md
 @README.md
 
-# TIER 2: REFERENCE (Always Loaded)
+# ============================================
+# 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 by Subsystem)
+# ============================================
 #
-# Audio: SPECTRAL_BRUSH_EDITOR.md, TRACKER.md, BEAT_TIMING.md
-# CNN: cnn_v1/docs/CNN_V1_EFFECT.md, cnn_v2/docs/CNN_V2*.md
-# 3D/Graphics: 3D.md, GPU_PROCEDURAL_PHASE4.md, MASKING_SYSTEM.md, SDF_EFFECT_GUIDE.md
-# Scene: SCENE_FORMAT.md, SEQUENCE.md, WORKSPACE_SYSTEM.md
-# Build: ASSET_SYSTEM.md, BUILD.md, CMAKE_MODULES.md, SIZE_MEASUREMENT.md
-# Rendering: GEOM_BUFFER.md, SHADER_REUSE_INVESTIGATION.md, UNIFORM_BUFFER_GUIDELINES.md, WGPU_HELPERS.md, AUXILIARY_TEXTURE_INIT.md
-# Tools: test_demo_README.md, HOT_RELOAD.md, HEADLESS_MODE.md, RECIPE.md
-# Arch: ARCHITECTURE.md, CODING_STYLE.md, BACKLOG.md, TOOLS_REFERENCE.md, CONTEXT_MAINTENANCE.md
+# Audio: @doc/SPECTRAL_BRUSH_EDITOR.md, @doc/TRACKER.md, @doc/BEAT_TIMING.md
+# CNN: @cnn_v1/docs/CNN_V1_EFFECT.md, @cnn_v2/docs/CNN_V2.md, @cnn_v2/docs/CNN_V2_BINARY_FORMAT.md
+# 3D/Graphics: @doc/3D.md, @doc/GPU_PROCEDURAL_PHASE4.md, @doc/MASKING_SYSTEM.md, @doc/SDF_EFFECT_GUIDE.md
+# Scene: @doc/SCENE_FORMAT.md, @doc/SEQUENCE.md, @doc/WORKSPACE_SYSTEM.md
+# Build: @doc/ASSET_SYSTEM.md, @doc/BUILD.md, @doc/CMAKE_MODULES.md, @doc/SIZE_MEASUREMENT.md
+# Rendering: @doc/GEOM_BUFFER.md, @doc/SHADER_REUSE_INVESTIGATION.md, @doc/UNIFORM_BUFFER_GUIDELINES.md, @doc/WGPU_HELPERS.md, @doc/AUXILIARY_TEXTURE_INIT.md
+# Tools: @doc/test_demo_README.md, @doc/HOT_RELOAD.md, @doc/HEADLESS_MODE.md, @doc/RECIPE.md, @doc/TOOLS_REFERENCE.md
+# Arch: @doc/ARCHITECTURE.md, @doc/CODING_STYLE.md, @doc/BACKLOG.md, @doc/CONTEXT_MAINTENANCE.md
 
-# TIER 4: ARCHIVE (Historical/Debugging Only)
-# Active: COMPLETED.md, CNN_DEBUG.md
-# Archived: doc/archive/* (handoffs, analyses, build proposals, cleanups)
+# ============================================
+# TIER 4: HISTORICAL ARCHIVE (Load Rarely)
+# ============================================
+#
+# Active History: @doc/COMPLETED.md
+# Debugging Docs: @cnn_v1/docs/CNN_DEBUG.md
+# Archived Docs: @doc/archive/*
+#
+# Past Investigations:
+#   @cnn_v1/docs/CNN_BIAS_FIX_2026-02.md
+#   @cnn_v1/docs/CNN_FLATTEN_ANALYSIS.md
+#   @cnn_v1/docs/CNN_RGBD_GRAYSCALE_SUMMARY.md
 
 # ============================================
 # PROJECT RULES (IMPORTANT)
 # ============================================
 
 IMPORTANT:
-- Follow all rules in doc/AI_RULES.md
+- Follow all rules in @doc/AI_RULES.md
 - This repository is shared with Gemini-CLI
 - You are working in turns with another AI agent
 - Work only on tasks explicitly requested by the user
@@ -40,7 +55,7 @@ IMPORTANT:
 - Max 100 tokens per reply
 
 # Context Maintenance:
-- See doc/CONTEXT_MAINTENANCE.md for keeping context clean
-- Archive completed work to doc/COMPLETED.md regularly
+- 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
diff --git a/GEMINI.md b/GEMINI.md
index 5c47b07..25e92a7 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -14,61 +14,37 @@
 @doc/EFFECT_WORKFLOW.md
 
 # ============================================
-# TIER 3: DESIGN DOCS (Load On-Demand)
+# TIER 3: DESIGN DOCS (Load On-Demand by Subsystem)
 # ============================================
-# 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
+# Audio: @doc/SPECTRAL_BRUSH_EDITOR.md, @doc/TRACKER.md, @doc/BEAT_TIMING.md
+# CNN: @cnn_v1/docs/CNN_V1_EFFECT.md, @cnn_v2/docs/CNN_V2.md, @cnn_v2/docs/CNN_V2_BINARY_FORMAT.md
+# 3D/Graphics: @doc/3D.md, @doc/GPU_PROCEDURAL_PHASE4.md, @doc/MASKING_SYSTEM.md, @doc/SDF_EFFECT_GUIDE.md
+# Scene: @doc/SCENE_FORMAT.md, @doc/SEQUENCE.md, @doc/WORKSPACE_SYSTEM.md
+# Build: @doc/ASSET_SYSTEM.md, @doc/BUILD.md, @doc/CMAKE_MODULES.md, @doc/SIZE_MEASUREMENT.md
+# Rendering: @doc/GEOM_BUFFER.md, @doc/SHADER_REUSE_INVESTIGATION.md, @doc/UNIFORM_BUFFER_GUIDELINES.md, @doc/WGPU_HELPERS.md, @doc/AUXILIARY_TEXTURE_INIT.md
+# Tools: @doc/test_demo_README.md, @doc/HOT_RELOAD.md, @doc/HEADLESS_MODE.md, @doc/RECIPE.md, @doc/TOOLS_REFERENCE.md
+# Arch: @doc/ARCHITECTURE.md, @doc/CODING_STYLE.md, @doc/BACKLOG.md, @doc/CONTEXT_MAINTENANCE.md
 
 # ============================================
 # 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
+# Active History: @doc/COMPLETED.md
+# Debugging Docs: @cnn_v1/docs/CNN_DEBUG.md
+# Archived Docs: @doc/archive/*
 #
-# Task Tracking:
-#   doc/TASKS_SUMMARY.md
+# Past Investigations:
+#   @cnn_v1/docs/CNN_BIAS_FIX_2026-02.md
+#   @cnn_v1/docs/CNN_FLATTEN_ANALYSIS.md
+#   @cnn_v1/docs/CNN_RGBD_GRAYSCALE_SUMMARY.md
 
 # ============================================
 # PROJECT RULES (IMPORTANT)
 # ============================================
 
 IMPORTANT:
-- Follow all rules in doc/AI_RULES.md
+- 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
@@ -80,7 +56,7 @@ IMPORTANT:
 
 # Context Maintenance:
 - See @doc/CONTEXT_MAINTENANCE.md for keeping context clean
-- Archive completed work to doc/COMPLETED.md regularly
+- 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
 
@@ -95,7 +71,7 @@ IMPORTANT:
 ## Technical Preferences
 - **C++ Standards:** Default to C++20/C++23 unless specified otherwise.
 - **Style:** Prefer Modern C++ (RAII, templates, constexpr, STL) over C-style patterns.
-- **Nomenclature:** Use standard engineering terminology (e.g., "O(n) complexity," "pointer aliasing," "cache miss") without defining the terms.
+-Nomenclature:** Use standard engineering terminology (e.g., "O(n) complexity," "pointer aliasing," "cache miss") without defining the terms.
 
 ## Interaction Protocol
 - If a query is ambiguous, provide the most likely technical solution rather than asking for clarification.