another step

CLAUDE.md

@@ -65,8 +65,22 @@ The two communicate over **HTTP/JSON** (optionally gRPC). The client reads the A
    intentionally removed. Don't add them back.
 6. **Never commit secrets.** Use `.env` (client) and `appsettings.*.json` / user-secrets (server).
    Real connection strings, keys, and tokens never enter git.
-7. **Keep docs honest.** If you change how something works, update the `CLAUDE.md` that describes it
-   in the same change. Stale instructions are worse than none.
+7. **Keep docs honest, and keep the architecture map current.** If you change how something works,
+   update the `CLAUDE.md` that describes it in the same change. Each level documents its architecture
+   in one canonical place — **this file's "Repository layout"** (repo), **client/CLAUDE.md "Project
+   Structure"** (frontend), **server/CLAUDE.md "Project map"** (backend). When a change alters that
+   structure — adds, removes, or renames a project, layer, route group, provider, or major folder, or
+   changes a cross-project / cross-layer boundary — update the matching architecture section in the
+   same change. Stale instructions are worse than none.
+8. **Write clean, self-documenting code.**
+   - **No dead code.** Remove unused variables, imports/usings, parameters, and private members —
+     don't leave them behind and don't suppress the warning. The client enforces this with ESLint
+     (`@typescript-eslint/no-unused-vars` as an *error*); on the server they are build warnings and
+     the gate is zero new warnings. Per-project specifics live in each project's `CLAUDE.md` /
+     `CONVENTIONS.md`.
+   - **Comment the *why*, not the *what*.** Don't write verbose comments that restate what the code
+     already says. Add a comment only where a non-obvious decision, constraint, business rule, or
+     trade-off isn't evident from the code itself. Prefer a clearer name over a comment.
 
 ---