Save this content to: AGENTS.md

# Agent Instructions

This file is the entrypoint. The single source of truth for project context lives in `.agents/rules/` — read these before working:

- `.agents/rules/project-context.md` — overview, stack, repo map
- `.agents/rules/architecture.md` — config-driven CRUD, MCP, exporters
- `.agents/rules/commands.md` — test / analyse / format / artisan commands
- `.agents/rules/coding-standards.md` — conventions, testing, tooling quirks
- `.agents/rules/clef-auto-triage.md` — automated error triage and severity classification (P0–P3) via Clef

## Working Rules
- Follow existing patterns in the repo; prefer minimal changes and small diffs.
- Run the relevant command from `.agents/rules/commands.md` after changes.
- Maintain backward compatibility unless explicitly asked to break.
- Do not add secrets, tokens, or private keys to code or logs.
- If unsure about architecture or product requirements, ask before implementing.
- For module/feature context, read `docs/guide/*` first (saves tokens), then open `src/` only for implementation detail.
- When changing core behaviour or adding a module/feature, update the matching `docs/guide/*` page (see `.agents/rules/coding-standards.md`).

<!-- trail:start -->
## Trail — repo context graph

This repo is indexed in `.trail/cache/`: small linked markdown nodes that explain each
system and carry exact file:line spans, kept in sync with the code through git.

For ANY task here — understanding how something works, finding where code lives,
or scoping a change — get context from the graph before grepping or opening
source files. Re-ask freely (it's cheap) and reuse literal identifiers you
already have (symbol, error string, file name) as the query. New to this repo?
Run `trail map` first — a token-budgeted orientation (dir clusters, hubs,
hotspots), no LLM, no key.

- Run `trail ask "<your question>" --source` → ranked nodes with the relevant
  code spans inlined (each hit's ≤8-line crux by default; `--full` for whole
  definitions when the crux isn't enough). Match the tool to the task shape:
  for understanding or editing, the top node IS the answer — cite its
  `covers:` file:line spans and edit straight from `--source`. For
  exhaustive tasks ("every occurrence / every caller of this pattern"), ranked
  results are top-N, not complete — run `trail grep "<literal>"` instead
  (exhaustive over indexed files, grouped by enclosing symbol), falling back
  to raw `grep -rn` only for unindexed files.
- `trail skeleton <file>` → every definition's signature + span, ~10× cheaper
  than reading the file; use it to skim an API surface.
- `trail callers <symbol>` gives precomputed, exact edges — who calls this.
  Add `--direction out` for what it calls, or `--depth N` to walk
  transitively for the full blast radius. For structural questions, skip
  ranking and use this directly.
- Or browse: `.trail/cache/INDEX.md` lists every node; follow the links.
- Monorepos and folders of multiple repos rank fairly across sub-projects —
  hits carry `[scope/]` labels naming which one they're from. Narrow with
  `trail ask "<task>" --in <scope>/` once you know where you're working.

If a returned span is truncated ("+N more lines"), open the file at that exact
range before finalizing. Only open source files when a node genuinely lacks a
needed detail, and then at the exact file:line the node points to — never
re-read whole files.

After big code changes, refresh the graph with `trail build` (deterministic,
no API key, $0).
<!-- trail:end -->