# AGENT.md

**Purpose:**  
This file defines how AI coding assistants (Cursor, Copilot, ChatGPT, etc.) should interact with this project.  
Follow these rules when generating, editing, or refactoring code.  
Return **diffs/patches only**, unless explicitly asked for full files.

---

## 0. AHK v2 Policy (MANDATORY)
- All new and updated code MUST be written in **AutoHotkey v2** syntax. No v1 syntax is allowed.
- Always select/use an agent that is specialized in **AHK v2** when generating code.
- When unsure about syntax, consult AHK v2 docs and prefer modern patterns.
- If existing legacy code is encountered, propose a minimal, safe v2 migration in small edits.

### AHK v2 Coding Guidelines
- Use expressions everywhere; `:=` for assignment, `.` for concatenation, `()` for calls.
- Prefer `Array` (`[]`) and `Map()` over pseudo-arrays or dynamic variable names.
- GUI: `Gui()` + `Add()`; hook events with `Control.OnEvent()` and `Gui.OnEvent()`.
- File I/O: `FileRead()`, `FileWrite()`, `FileCopy()`, `DirCreate()`, etc. Use full paths.
- Error handling: wrap file and parsing operations in `try/catch` blocks; report actionable errors.
- Globals: keep minimal; pass values via parameters; use `static` sparingly inside functions.
- Strings/paths: use `A_ScriptDir` for repo-relative paths; prefer `A_...` built-ins.
- Performance: avoid tight loops with heavy GUI updates; batch updates, then render.
- Images: set `Picture.Value := path`; for scaling, compute target size from control `.Pos`.
- Testing: after edits, run the script with the AHK v2 interpreter and exercise key UI flows.

Supersedence: The sections below are general engineering guidance. For this repo, the AHK v2 Policy above takes precedence. Ignore web-only or SQL-only guidance when not applicable.

---

## 1. File & Structure
- Organize by **feature** (component, service, tests, styles grouped together).  
- Keep modules **cohesive**.  
- Enforce limits with ESLint/Stylelint, not arbitrary hard caps:
  - Warn: ~400 lines per file  
  - Error: >600 lines per file  
  - Functions ≤ 80 lines, cyclomatic complexity ≤ 10  
- No cyclical imports.

---

## 2. Paradigm
- **Composition first**: prefer functions, modules, and hooks.  
- Classes only when modeling true objects with state/behavior.  
- Avoid “everything in a class” (OOP-first is **not** mandatory).  
- Follow **SRP (Single Responsibility Principle)** pragmatically: split when complexity or concerns diverge.

---

## 3. Separation of Concerns
- **UI (AHK v2):** Build GUI with `Gui()` and `Add()`. Keep event handlers small; delegate to functions.
- **Business logic:** Separate file I/O, parsing, and list management into functions/modules.
- **Data layer:** Store documents and list options in text files; parse into Arrays/Maps.
- **State:** Keep UI state in memory (Arrays/Maps); avoid global sprawl.
- **Do not mix GUI updates with parsing logic unnecessarily.**

---

## 4. Design & Scalability
- Modules should be **reusable, testable, isolated**.  
- Avoid god components/classes/services.  
- Add extension points **only when a second real use case arises (YAGNI rule)**.  
- Dependency injection or factories preferred over tight coupling.

---

## 5. Naming & Readability
- Use **descriptive, intention-revealing names**.  
- Ban vague names: `data`, `info`, `helper`, `tmp`.  
- Align with `CONVENTIONS.md`.

---

## 6. Assets & CSS/HTML
- N/A for AHK v2. Images are loaded from `images/` via `Picture` controls.
- Ensure image paths are valid and avoid blocking UI during file operations.

---

## 7. SQL
- N/A for this project. Data is stored in flat files.

---

## 8. Testing
- Unit tests near modules.  
- Integration tests for services/DAO.  
- Minimal e2e for core flows.  

---

## 9. Error Handling & Security (AHK v2)
- Validate file paths and existence before operations; wrap in `try/catch`.
- Sanitize text fields when writing to disk to preserve delimiter integrity.
- Prefer absolute paths via `A_ScriptDir` to avoid cwd issues.

---

## 10. Other Instructions
- **Return unified diffs** (`git patch` style) unless explicitly asked for full file.  
- **Do not rename** files or public symbols unless instructed.  
- Keep `ARCHITECTURE.md`, `CONTRIBUTING.md`, `CONVENTIONS.md` updated after meaningful changes.  
- Implement changes in **small, reviewable steps**.

AHK v2 specifics:
- Do not introduce v1 syntax.
- Prefer Arrays/Maps over dynamic var names.
- Use `OnEvent()` for all GUI event wiring.

**Documentation References:**
- `ARCHITECTURE.md` - System design, module dependencies, data flow
- `CONTRIBUTING.md` - Development workflow, testing guidelines, service development
- `CONVENTIONS.md` - Code style, naming conventions, error handling patterns

**Development Environment:**
- AHK v2 interpreter is required to run the app. Suggested path:
  - `C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe`
- Run the app:
  - `AutoHotkey64.exe "E:\GDRIVE\...\CATALOGUE\catalogue-documentaire.ahk"`
- Test checklist (minimum):
  - App opens, lists load, selection updates preview
  - Filters work and auto-select first result
  - Full-size image opens on preview click

---