docs: reorder & testing

CLAUDE.md

@@ -4,10 +4,27 @@ This repository hosts the Galaxy Game project.
 
 ## Sources of truth
 
-- `ARCHITECTURE.md` — global architecture, project-wide rules
-  and links to the implemented services.
-- `galaxy/<service>/README.md` - service conventions and agreements
-  for the implemented or planned to be implemented service.
+- `docs/ARCHITECTURE.md` — global architecture, security model,
+  cross-service contracts, and project-wide rules.
+- `docs/FUNCTIONAL.md` — per-domain user stories that describe what each
+  user-visible operation does, with the exact gateway and backend logic
+  for it. Starting point for any change request that touches behaviour.
+- `docs/FUNCTIONAL_ru.md` — Russian translation of `docs/FUNCTIONAL.md`,
+  maintained as a convenience for the project owner. **Not a source of
+  truth** — when the two files disagree, the English version wins.
+  Every point edit applied to `docs/FUNCTIONAL.md` must also be
+  mirrored into `docs/FUNCTIONAL_ru.md` in the same patch (translate
+  the changed paragraphs only, do not re-translate the whole file).
+  A full re-translation only happens on explicit owner request.
+- `docs/TESTING.md` — testing layers (unit / integration), the
+  integration runbook, and the principles every test must follow
+  (no-op observability for testcontainers, `t.Fatal` on
+  infrastructure breakages, label-driven preclean). Read before
+  adding tests or modifying the integration harness.
+- `galaxy/<service>/README.md` — service conventions, layout,
+  configuration, and operations for an implemented or planned service.
+- `galaxy/<service>/openapi.yaml` and `*.proto` files — exact wire
+  contracts for REST and gRPC surfaces.
 
 ## Planning of service implementation and Implementing Plan
 
@@ -20,7 +37,7 @@ This repository hosts the Galaxy Game project.
 ## Decision records when implementing stages from PLAN.md
 
 - Stage-related discussion and decisions do NOT live in `README.md` or
-  `ARCHITECTURE.md`. Those files describe the current state, not the history.
+  `docs/ARCHITECTURE.md`. Those files describe the current state, not the history.
 - Each non-trivial decision gets its own `.md` under the module's `docs/`,
   referenced from the relevant `README.md`.
 - Any agreement reached during interactive planning that is not obvious from
@@ -33,6 +50,19 @@ The existing codebase of `galaxy/<service>` may be modified or extended when a
 plan stage requires it. All such changes must be covered by new or updated tests
 and reflected in documentation when they affect documented behavior.
 
+## Pre-production migration rule
+
+The platform is not yet in production. Schema changes for `backend` go
+into the existing `backend/internal/postgres/migrations/00001_init.sql`
+file rather than into new `00002_*`-prefixed files. Local databases and
+integration test harnesses are recreated from scratch on every pull.
+
+**This rule is removed before the first production deployment.** From
+that point on every schema change becomes a new migration file with a
+monotonically increasing prefix, and `00001_init.sql` becomes immutable
+history. See `backend/internal/postgres/migrations/README.md` for
+details.
+
 ## Documentation discipline
 
 - Code and docs are kept in sync. If an implementation changes behavior
@@ -45,7 +75,33 @@ and reflected in documentation when they affect documented behavior.
   doc with a reference kept.
 - Cross-module impact: if a new agreement requires changes in
   already-implemented modules, make those changes — code, tests, docs — in
-  the same patch, and record the new rule in `ARCHITECTURE.md`.
+  the same patch, and record the new rule in `docs/ARCHITECTURE.md`.
+
+## Documentation synchronisation
+
+The same behaviour is described in several parallel sources: code,
+`docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (with its Russian mirror
+`docs/FUNCTIONAL_ru.md`), the affected service `README.md`, the
+relevant `openapi.yaml` or `*.proto`, and the per-stage decision
+records under `galaxy/<service>/docs/`. They must never disagree.
+
+- Any patch that changes user-visible behaviour, an API contract, or a
+  cross-service flow updates every affected source in the same change
+  set — never one source in this patch and another later.
+- Before declaring a change complete, read the relevant sections of
+  `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md`, the affected service
+  README, the relevant `openapi.yaml` or `*.proto`, and the implementing
+  code; confirm they describe the same behaviour.
+- When two sources disagree about existing behaviour, do not pick one
+  silently. Decide which one is authoritative, fix the contradiction in
+  the same patch, and call out the change in the response. If the
+  resolution is non-obvious, escalate to the user before proceeding.
+- When touching code, also re-read inline package and Go Doc Comments in
+  the affected packages and update them when they no longer match the
+  code.
+- When `docs/FUNCTIONAL.md` changes, mirror the same change into
+  `docs/FUNCTIONAL_ru.md` (translate only the touched paragraphs).
+  Skipping the mirror is treated as an incomplete patch.
 
 ## Dependencies