From bc3973ef1525f92b10def6974e854f9d18cbec69 Mon Sep 17 00:00:00 2001
From: omigamedev <omarator@gmail.com>
Date: Thu, 4 Jun 2026 15:31:53 +0200
Subject: [PATCH] Document agent modernization handoff

---
 AGENTS.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7843989
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,95 @@
+# AGENTS.md
+
+This file is the quick-start map for agents working in this repository. Keep it
+small and point to the live docs instead of duplicating the whole plan.
+
+## Current Modernization Goal
+
+PanoPainter is being incrementally modernized into independently testable C++23
+components while preserving current behavior. OpenGL remains the working backend
+until the renderer boundary is proven; Vulkan/Metal/WebGPU work waits behind that
+boundary.
+
+Read these first:
+
+- `docs/modernization/roadmap.md` - live phase roadmap, recent results, and next
+  work queue.
+- `docs/modernization/debt.md` - required debt log. Every temporary adapter,
+  retained legacy dependency, skipped platform, fallback, or shortcut needs an
+  entry with validation and removal conditions.
+- `docs/modernization/capability-map.md` - behavior that must be preserved.
+- `docs/modernization/build-inventory.md` - current build/component inventory.
+- `docs/adr/0001-modernization-boundaries.md` - component boundary decisions.
+
+## Working Rules
+
+- Work on `codex/modernization-cmake-foundation` unless the user says otherwise.
+- Commit and push each verified successful progress slice.
+- Prefer larger coherent slices over tiny checkpoints, but keep docs/debt updated
+  with each slice.
+- Do not revert user changes. Unrelated untracked notes, such as
+  `docs/human-review-notes.md`, should be left alone unless explicitly requested.
+- Use CMake as the source of truth. Legacy Visual Studio project files are not the
+  modernization path.
+- Use `apply_patch` for manual source/doc edits.
+
+## Build And Test
+
+Primary Windows configure/build:
+
+```powershell
+cmake --preset windows-msvc-default
+cmake --build --preset windows-msvc-default --config Debug --target PanoPainter pano_cli
+```
+
+Focused fast validation:
+
+```powershell
+ctest --preset desktop-fast --build-config Debug --output-on-failure
+```
+
+Useful targeted pattern:
+
+```powershell
+ctest --preset desktop-fast --build-config Debug -R "pp_app_core|pano_cli_plan" --output-on-failure
+```
+
+If MSVC reports corrupt debug information or stale PDB/object errors, clean the
+generated build tree target before judging source changes:
+
+```powershell
+cmake --build --preset windows-msvc-default --config Debug --target clean
+```
+
+## Current Architecture Direction
+
+The desired component split is documented in the roadmap. Current extracted or
+in-progress boundaries include:
+
+- `pp_foundation`
+- `pp_assets`
+- `pp_paint`
+- `pp_document`
+- `pp_renderer_api`
+- `pp_renderer_gl`
+- `pp_paint_renderer`
+- `pp_app_core`
+- `pp_panopainter_ui`
+- `pp_platform_*`
+- `panopainter_app`
+
+Legacy UI/app code still exists and is being reduced through pure planners,
+service interfaces, CLI automation, and CTest coverage. When moving behavior out
+of a legacy node, preserve current behavior first, add focused tests, document
+remaining shortcuts in `docs/modernization/debt.md`, then wire the live adapter.
+
+## Legacy Context
+
+PanoPainter started as a flat C++17 OpenGL panoramic painting app centered on
+singletons such as `App::I`, `Canvas::I`, `Settings`, and `WacomTablet::I`.
+Rendering uses GLAD/OpenGL and shaders in `data/shaders/`. UI is XML/Yoga based
+with many `Node*` subclasses. Project files are PPI, brush packages are PPBR,
+and Photoshop brushes import through ABR support.
+
+Exceptions are disabled in app code. Public modernization APIs should return
+explicit status/result objects.