================================================================================
<YOUR PROJECT NAME> — RULES OF ENGAGEMENT
(how your coding assistant / AI agent should behave in this workspace)
================================================================================

================================================================================
0) THE THREE-FILE SYSTEM
================================================================================
These three files are the working instructions for the AI assistant while it
works in this workspace. They cross-reference each other — treat them as ONE
system. This file is the RULES file. Its companions:

  notes.txt        general text / session notes (what this project is,
                   ongoing topics)
  rules.txt        THIS FILE — the rules the assistant follows (read first)
  errors.txt       every error encountered + its cause + the fix that worked

Division of labor:
  - notes / general text    -> notes.txt
  - behavior / conventions  -> rules.txt (this file)
  - failures / fixes        -> errors.txt
When something breaks, log it in errors.txt using the template at its end.
When an open topic changes, update the session notes in notes.txt.

================================================================================
1) WHO I AM
================================================================================
- Name: <YOUR ASSISTANT NAME>. Runs inside <YOUR PRODUCT / CLI>.
- I work inside this repo and only edit files here unless the user
  explicitly asks otherwise.

================================================================================
2) HOW I WORK
================================================================================
- ERROR-HANDLING PROTOCOL (MANDATORY): when you encounter an error, do NOT
  fix it immediately. FIRST log it in errors.txt (template at its end).
  ONLY after it is logged are you allowed to fix it. Log first, fix after —
  always, no exceptions.
  Tooling: `python check_errors.py` validates the log; `--has-entry "<AREA>"`
  gates a fix (exit 0 only if the error is already logged); `--add` scaffolds
  a new entry in the template format; `--archive-days N` archives old FIXED
  entries (preview only unless --apply).
  Git gate: this folder is a git repo; the commit-msg hook
  (git-commitmsg-hook.sh, installed as .git/hooks/commit-msg) blocks code
  commits whose message lacks an "AREA: <text>" marker matching a logged
  entry — write: git commit -m "... (AREA: <what broke>)".
- SESSION START: at the beginning of every session, run `python start.py`
  (Windows: double-click start.bat) to print the reading order, the mandatory
  rules, the open errors and the latest session note.
- CHECK-BEFORE-CODING PROTOCOL (MANDATORY): before writing or modifying ANY
  code, review errors.txt FIRST so you do not repeat past mistakes. Read the
  log, note the errors relevant to what you are about to write, and avoid
  them.
- Follow existing project conventions. Read the surrounding code, tests, and
  config BEFORE writing anything. Never invent conventions of your own.
- Make the SMALLEST change that satisfies the request. No gold-plating, no
  speculative refactors, no unrequested cleanup.
- Reuse existing helpers/functions instead of reimplementing them.
- If a library or service is needed, verify it exists in the project
  (requirements, package.json, imports) or research it before using it.
- When you change an exported symbol, update every reference to it.
- Don't surprise the user: no destructive commands, no production changes,
  no committing/pushing unless explicitly asked.
- Ask for clarification when the request is ambiguous or the options are
  meaningfully different.

================================================================================
3) CODE RULES
================================================================================
- Match the existing style: plain, dependency-light, stdlib-first. No pip
  packages unless required.
- UTF-8 everywhere; Windows consoles get reconfigured to UTF-8 in scripts.
- Keep tool descriptions / system prompts short and factual — LLMs narrate
  intent instead of calling tools when prompts get verbose.
- Validate changes: run tests / typechecks / a quick run of the touched
  script when practical. Review with a second pass (code review agent).
- Before writing code, review errors.txt (CHECK-BEFORE-CODING PROTOCOL,
  section 2) so past mistakes are not repeated.

================================================================================
4) YOUR PROJECT — NOTES FOR THE ASSISTANT
================================================================================
<Describe your stack, key files, and known constraints here. Delete this
placeholder section or expand it to map your repo:
  - Stack / frameworks / entry points
  - Key files and what they do
  - Known constraints and limitations
  - How to run tests and lint>

================================================================================
5) CURRENT OPEN TOPICS
================================================================================
<List open decisions / discussions here so any session can pick them up.
Delete this section if you have none.>

================================================================================
6) NON-NEGOTIABLES
================================================================================
- LOG BEFORE FIXING: never fix an error before logging it in errors.txt.
  Log first, fix after — no exceptions.
- Be honest about what you did and did not do. No claiming success without
  verification.
- If a command is risky or hard to undo, say so before running it.
- Final summaries stay short: a few words per change.
- The user is the boss: if their instruction conflicts with a rule here,
  their instruction wins.
================================================================================

================================================================================
7) LESSONS LEARNED FROM THE ERROR LOG
================================================================================
Distilled from the error log by: python check_errors.py --lessons [--apply]
Generated: 2026-08-09  |  source: 19 error log entrie(s).

1. amount
   1 entrie(s): payment webhook parser
   Common cause keywords: amount, payload, webhook
   Action: re-read the CAUSE fields of these entries before touching
   related code, so the same mistake is not repeated.

2. resize
   1 entrie(s): image resize service timeouts
   Common cause keywords: full, image, resize
   Action: re-read the CAUSE fields of these entries before touching
   related code, so the same mistake is not repeated.

3. back
   1 entrie(s): search API rate limit
   Common cause keywords: back, gaps, requests
   Action: re-read the CAUSE fields of these entries before touching
   related code, so the same mistake is not repeated.

4. readme
   15 entrie(s): CI commit-message gate missing; README CI badges missing; README stale test count; README missing PR-workflow docs; one-command --init adoption missing; community polish missing; code of conduct missing; permanent visitor counter missing; README companion cross-link; README companion badge; AGENTS.md missing CI gate note; README test-count drift guard missing; _extract_area marker mismatch with hooks (review); badge count artifact in live-page verification; rules.txt missing LESSONS section
   Common cause keywords: added, area, badge, command, community, companion, count, enabling, gate, hook, hooks, missing, never, polish, readme, section
   Action: re-read the CAUSE fields of these entries before touching
   related code, so the same mistake is not repeated.

5. verify
   1 entrie(s): harness blocker install friction
   Common cause keywords: blockers, hooks, verify
   Action: re-read the CAUSE fields of these entries before touching
   related code, so the same mistake is not repeated.
