<!--
  ─────────────────────────────────────────────────────────────────────────────
  .github/copilot-instructions.md  ·  repository-wide Copilot instructions
  QRefAI AI Coding Field Guide, Part 3 (Q3.1)

  This file is ALWAYS applied, repo-wide, across the Copilot coding agent, code
  review, and IDE chat.

  ┌── THE 4,000-CHARACTER RULE ────────────────────────────────────────────────┐
  │ Copilot CODE REVIEW only reads the FIRST ~4,000 characters of this file.     │
  │ The coding agent and Chat have no such limit — but if you care about review  │
  │ behavior, every rule that must influence review MUST live above the marker   │
  │ below. Treat the first 4,000 chars as prime real estate: dense, rule-first,  │
  │ no preamble.                                                                  │
  └─────────────────────────────────────────────────────────────────────────────┘

  Priority across Copilot's instruction layers: Personal > Repository > Organization.
  Keep org-wide context in AGENTS.md (the cross-vendor standard) and reference or
  restate it here for Copilot's repo-wide layer.
  ─────────────────────────────────────────────────────────────────────────────
-->

# <PROJECT NAME> — Copilot Instructions

<!-- ============================================================ -->
<!-- ▼▼▼  CRITICAL RULES — FRONT-LOAD ZONE (first ~4,000 chars)  ▼▼▼ -->
<!-- Everything ABOVE the end marker is read by Copilot code review. -->
<!-- Put your hard, must-enforce-in-review rules here, rule-first.   -->
<!-- ============================================================ -->

## Hard rules (enforced in review)
<!-- Replace with YOUR non-negotiables. Keep each to one line. Examples: -->
- All monetary values are int64 minor units; never floats.
- Every transaction mutation must call `audit.Emit()`.
- No secrets, tokens, or credentials in source — ever.
- Every external call goes through `internal/clients/`; never inline an HTTP client.
- New public endpoints require an entry in `docs/api-changelog.md`.

## Stack (with versions)
- <LANGUAGE + VERSION, e.g. Go 1.23> · <DATASTORE + VERSION> · <FRAMEWORK> · <DEPLOY TARGET>

## Commands Copilot can't guess
- Build: `<cmd>` · Test: `<cmd>` (must pass before PR) · Lint: `<cmd>` (CI-enforced)

## Conventions that differ from defaults
<!-- Only things the agent would NOT infer from the code. The linter rules do
     not belong here — don't restate them. -->
- <e.g. Business logic in `internal/domain/`; handlers stay thin.>
- <e.g. Never write code that deletes from `audit_events`.>

<!-- ============================================================ -->
<!-- ▲▲▲  END FRONT-LOAD ZONE — keep everything above ≤ 4,000 chars  ▲▲▲ -->
<!-- Content BELOW is still used by the coding agent and Chat, but    -->
<!-- may be TRUNCATED away from Copilot code review. Put nice-to-have -->
<!-- context, longer explanations, and orientation here.             -->
<!-- ============================================================ -->

## Project structure (orientation — agent can discover detail itself)
- <e.g. `internal/domain/` — business logic>
- <e.g. `internal/transport/` — HTTP/gRPC handlers>
- <e.g. `internal/store/` — DB access>

## Testing notes
- <how to run a focused test, coverage expectations, test naming, etc.>

## Background / rationale
- <longer-form context that helps Chat and the coding agent but isn't a review rule>

<!--
  TIP: To check you're under budget, the front-load zone should end before the
  4,000th character. As a rough guide that's ~600–650 words of dense Markdown.
  Snapshot of mid-2026 behavior — re-verify the limit before relying on it.
-->
