v1.18.0

Agent-native repository documentation

Adds CLAUDE.md, a single instruction file that tells AI coding agents how to work in this
repository, plus AGENTS.md as a symlink to it so tools that look for either filename find the same
content. The document is deliberately vendor-neutral — no assistant-specific syntax, commands or
configuration — so any agent can consume it.

What it covers

• Makefile-first workflow. A per-task table mapping each job to its make target, and the flags
  you silently lose by calling the underlying tool directly (make test adds -race -covermode atomic; make swag-v1 passes --parseDependency -g internal/controller/restapi/router.go;
  make format runs go fix, gofumpt and gci with the repo's import grouping).
• Layer boundaries. The dependency direction across entity → usecase → repo →
  controller, the rule that pkg/ never imports internal/, and that wiring happens only in
  internal/app/app.go.
• Where new code goes. A decision table keyed on what the code knows about — a domain
  invariant, SQL, an HTTP status, a reusable server — plus file, package and constructor naming
  conventions.
• The handler contract. The six steps every controller method follows on all four transports:
  identify the caller, decode into a transport-local DTO, validate, call the use case with the
  request context, map sentinel errors to a transport status, encode the response.
• Checklists. Adding a use case to an existing domain, and adding a whole domain end to end
  from entity and migration through repository, use case, mocks, wiring, transports, docs and
  integration test.
• Translation upkeep. README.md is canonical; README_RU.md and README_CN.md mirror it
  section for section, with a trigger table for which change requires which README edit and rules
  for localized anchors.
• Generated artifacts. Which files come from make swag-v1, make proto-v1 and make mock,
  and must never be hand-edited.

Documented pitfalls

• make integration-test runs on the host and always fails; make compose-up-integration-test is
  the real entry point.
• make migrate-create <name> prints No rule to make target after succeeding — a side effect of
  reading the name from MAKECMDGOALS.
• make run and make pre-commit require swag and protoc on PATH; make bin-deps does not
  install protoc.
• Fiber handlers must use ctx.UserContext(), never ctx.Context(), or the trace is dropped.
• Every use-case and repository constructor returns the interface wrapped by newTraced, so a new
  contract method must be implemented in three places — interface, struct and tracing decorator.
• internal/repo/persistent/translation/ declares package persistent while its siblings use the
  directory name; new packages should follow task/ and user/.

What's Changed

• chore(deps): security updates by @soltanoff in #475
• feat: AI native docs for agents by @soltanoff in #476

Full Changelog: v1.17.2...v1.18.0