AGENTS.MD

# Agent guidance
 
Use these rules throughout this repository. More specific instructions closer to
the code being changed take precedence.
 
## Sources of truth
 
- Read the relevant code, configuration, and project documentation before
  editing. Do not rely on remembered framework behaviour when the installed
  version can answer the question.
- For Next.js work, read the relevant guide in
  `node_modules/next/dist/docs/` before writing code. The installed version may
  contain breaking API, convention, or file-structure changes. Heed
  deprecation notices.
- When a task references Figma or another design source, inspect that source and
  match its copy, layout, styles, and assets. Do not invent missing design
  decisions.
- Preserve explicit product constraints such as privacy, indexing, security,
  and public visibility unless the task changes them.
 
## Change discipline
 
- Keep changes small, local, and directly related to the feature or bug.
- Preserve unrelated work in a dirty worktree.
- Reuse existing primitives, tokens, and patterns before introducing a new
  abstraction.
- Verify changes with the narrowest useful tests, type checks, lint checks, or
  build steps for the affected area.
 
## Structure and naming
 
- Prefer cute, neat names and logical domain boundaries. Use
  `commerce/readiness/medusa.ts`, not `commerce-readiness.medusa.ts`.
- Keep one clear responsibility per module and place it beside the domain that
  owns it.
- Prefer functional factories and functions over classes when they make
  dependency injection and testing simpler.
- Quote route-segment paths in shell commands so characters such as `[]` and
  `()` are not expanded by the shell.
 
## Types and boundaries
 
- Do not introduce `any`, `as any`, `@ts-ignore`, or broad double casts when a
  practical typed alternative exists.
- Prefer generated types, schema-inferred types, `unknown` with narrowing, or a
  small explicit interface.
- If an escape hatch is unavoidable, keep it at the untyped boundary and
  explain why it is needed.
- Keep input validation and authorization checks close to the API, data, or
  service boundary they protect.
 
## Interface work
 
- In localized surfaces, keep user-facing copy in the localization system.
  Preserve German as a first-class locale, update both English and German
  messages, and prefer message interpolation over string concatenation.
- Use the existing design system and component primitives instead of ad-hoc
  colours, typography, spacing, or controls.
- For technologies, AI models, and integrations, use the service's
  `domain.com/favicon.ico` when a recognizable brand mark is needed and no
  canonical local asset exists.