docs: ui plan

CLAUDE.md

@@ -30,19 +30,29 @@ This repository hosts the Galaxy Game project.
 
 - `galaxy/<service>/PLAN.md` — staged implementation plan for the service.
   May be already complete and resides for historical reasons.
-- `galaxy/<service>/docs/` — per-stage decision records
-  (one file per decision, re-organized after full implementation
-  of `PLAN.md`).
+- `galaxy/<service>/docs/` — live topic-based documentation that's
+  deeper than what fits in `README.md` (per-feature design notes,
+  protocol specs, runbooks). Not stage-by-stage history.
 
-## Decision records when implementing stages from PLAN.md
+## Decisions during stage implementation
 
-- Stage-related discussion and decisions do NOT live in `README.md` or
-  `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
-  the code must be captured — either as a decision record or as an entry in
-  the module's README.
+Stages from `PLAN.md` produce decisions. Those decisions never live in a
+separate per-decision history file. Instead, every non-obvious decision is
+baked back into the live state in three places:
+
+1. **The plan itself.** Update the relevant stage's text, acceptance
+   criteria, or targeted tests so it reflects what was decided. If
+   earlier already-implemented stages need to follow the new agreement,
+   correct their code, tests, and live docs in the same patch.
+2. **Later, not-yet-implemented stages.** When a decision affects later
+   stages — scope, dependencies, deliverables, or tests — update those
+   stages now, do not leave the future to re-derive them.
+3. **Live documentation.** Module `README.md`, project
+   `docs/ARCHITECTURE.md`, `docs/FUNCTIONAL.md` (with its
+   `docs/FUNCTIONAL_ru.md` mirror), the affected service `openapi.yaml`
+   or `*.proto`, and any topic doc under `galaxy/<service>/docs/` that
+   the decision touches. `README.md` and `ARCHITECTURE.md` always
+   describe current state, not the history of how it was reached.
 
 ## Scope of PLAN.md changes
 
@@ -82,8 +92,8 @@ details.
 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.
+relevant `openapi.yaml` or `*.proto`, and the topic-based docs 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
@@ -103,6 +113,22 @@ records under `galaxy/<service>/docs/`. They must never disagree.
   `docs/FUNCTIONAL_ru.md` (translate only the touched paragraphs).
   Skipping the mirror is treated as an incomplete patch.
 
+## Code compactness
+
+- Prefer compact code over speculative universality. Three similar
+  occurrences are not yet a pattern — wait for the third real caller
+  before extracting an abstraction.
+- Do not add seams, hooks, or configuration knobs for hypothetical
+  future requirements. If the next stage of `PLAN.md` will need
+  something, the next stage will add it.
+- A bug fix does not need surrounding cleanup; a one-shot operation
+  does not need a helper function; a single concrete value does not
+  need a parameter.
+- When the plan can be satisfied by reusing an existing function or
+  type, do that instead of introducing a new one.
+- This rule is about scope, not laziness — well-named identifiers,
+  precise types, and full test coverage stay non-negotiable.
+
 ## Dependencies
 
 - Before adding a new module, check its upstream repository for the latest