another step

server/CLAUDE.md

@@ -63,14 +63,21 @@ Server is required to start.
 
 ## Quality gates — run before declaring work done
 
-1. `dotnet build Baya.sln` — zero new warnings introduced.
+1. `dotnet build Baya.sln` — zero new warnings introduced. Unused `using`s, locals, parameters,
+   private fields, or members count as failures — delete them, don't suppress them
+   ([CONVENTIONS.md](CONVENTIONS.md) §2 "No unused code").
 2. `dotnet test Baya.sln` — all tests pass.
 3. Read your own diff as if reviewing a PR: would a senior engineer approve it without comment?
+4. If the change alters the architecture, update the **Project map** below in the same change
+   (see "Keeping the Project map current").
 
 ---
 
 ## Project map
 
+This tree is the **canonical description of the server's architecture** — the authoritative list of
+projects/assemblies, Clean-Architecture layers, and cross-layer dependencies.
+
 ```
 src/
 ├── Core/
@@ -95,6 +102,12 @@ src/
 Domain. Infrastructure and API implement/consume Application contracts. Never make Domain or
 Application reference Infrastructure or the API — this is a hard rule.
 
+**Keeping the Project map current.** When a change touches the architecture — adds, removes, or
+renames a project/assembly, a Clean-Architecture layer, or a major folder, or changes a cross-layer
+dependency — you **must** update this Project map (and the dependency rule above, if affected) in the
+**same** change. This is the server-specific form of the root "Keep docs honest" rule: the map is
+only canonical if it stays accurate.
+
 ---
 
 ## Startup wiring
@@ -179,6 +192,8 @@ Full rules in [CONVENTIONS.md](CONVENTIONS.md). The essentials:
 - `async`/`await` all the way; pass `CancellationToken` through every async call; never `.Result`/`.Wait()`/`async void`.
 - Mapster for mapping; FluentValidation for validation (validate at the boundary).
 - Package versions live **only** in `Directory.Packages.props` — never `Version=` in a `.csproj`.
+- No unused code (usings, locals, parameters, private fields/members) and no *what*-comments — explain *why*, prefer self-documenting names (§2).
+- Architecture changes (a project/layer/major folder or a cross-layer dependency) must update the **Project map** in the same change.
 - The `Baya.*` namespace is project naming — do not rename without explicit instruction.
 
 ---

server/CONVENTIONS.md

@@ -94,6 +94,32 @@ List<string> tags = ["new", "sale"];
 
 No abbreviations unless universally understood (`dto`, `id`, `url`). No Hungarian notation (`strName`, `intCount`).
 
+### No unused code
+
+Leave nothing dead behind. Remove unused `using` directives, local variables, parameters, private fields, and private members rather than letting them accumulate.
+
+- These already surface as compiler/analyzer signals — `CS0168` (variable declared, never used), `CS0219` (variable assigned, value never used), `CS0169` (private field never used), `IDE0005` (unnecessary `using`). The quality gate is **zero new warnings**, so treat unused code as a gate failure.
+- **Delete it — don't silence it.** Do not add `#pragma warning disable`, throwaway discards, or `_ =` assignments just to quiet the analyzer.
+- The one exception: a parameter that must exist to satisfy an interface or delegate signature but is genuinely unused. Keep it, name it conventionally, and add a one-line `// why` only if the reason isn't obvious.
+
+### Comments — explain *why*, never *what*
+
+Code that needs a comment to be understood usually needs a better name instead. Prefer self-documenting names over prose.
+
+- **Do not** write comments that restate what the code already says — no `// constructor`, `// loop over users`, or XML-doc that merely echoes the method name.
+- **Do** add a comment only where a non-obvious decision, constraint, business rule, workaround, or trade-off is *not* evident from the code — explain the reasoning, not the mechanics.
+- Keep any necessary comment tight, and delete comments that no longer match the code.
+
+```csharp
+// ❌ restates the obvious
+// increment the retry counter
+retryCount++;
+
+// ✅ captures a non-obvious constraint the code can't express on its own
+// Payment gateway rejects amounts above 50M IRR per call; split larger settlements upstream.
+if (amount > MaxPerCallRial) ...
+```
+
 ---
 
 ## 3. Async / await