feat: refactor for ai first development

Author: martins-itc

CLAUDE.md

@@ -154,6 +154,16 @@ NEVER use `synchronize: true` in production.
 
 All private pages: `SectionContainer` + `PageHeader` + `<div className="p-4 lg:p-12">`
 
+### Routes & i18n (typed)
+
+- **NEVER hardcode internal route strings.** Use the typed `routes` from `~/lib/routes`
+  in every `href` / `router.push` / `redirect` — `routes.adminUsers`, `routes.adminUser(id)`.
+  A renamed/removed route then becomes a compile error at every call site, not a dead link.
+  Add new routes to `~/lib/routes.ts`.
+- **Translation keys are typed** (next-intl `AppConfig` augmentation in `src/global.ts`).
+  `useTranslations('ns')` + `t('key')` are checked against the real messages — a missing
+  key is a compile error. Add keys to `messages/<locale>/<ns>.json` (same key in every locale).
+
 ### Server Actions
 
 - Call orval-generated functions (e.g. `usersQueryControllerFindAll(params, cfg)`)
@@ -166,6 +176,24 @@ All private pages: `SectionContainer` + `PageHeader` + `<div className="p-4 lg:p
 - Place in `_actions/` folders (excluded from routing); `revalidatePath()` after a
   successful mutation.
 
+### Runtime Validation (boundary)
+
+Validate API responses at the boundary on **data-bearing** endpoints — the ones
+whose `.data` you actually read in a component. That's where malformed data crashes
+the UI, and those schemas are accurate.
+
+- **Server Actions**: pass the generated `*Response` schema as `safeAction`'s 2nd arg
+  → `safeAction(fn, UsersCommandControllerUpdateResponse)`. On drift it returns a 502
+  envelope (never throws).
+- **Server Component page fetches**: `SchemaResponse.parse(response)` right after the
+  call → a drift throws and is caught by `error.tsx`.
+- Schemas come from `@myorg/api-client/zod` (generated — never hand-write them).
+- **Do NOT validate no-data endpoints** (delete, logout, change-password): nothing to
+  dereference (no UI-crash risk) and their `null`/void `data` would false-positive.
+- If a real, valid response ever fails validation, the backend `@ApiProperty` is
+  wrong (e.g. missing `type`/`nullable`) — **fix the DTO so the schema is accurate
+  and regenerate; never disable the check.**
+
 ### Testing
 
 - **Vitest** for unit/component tests (`*.spec.ts` backend, `*.test.tsx` web),
@@ -249,3 +277,5 @@ app/[locale]/(main)/
 ---
 
 **Reference Module:** `apps/backend/src/modules/users/`
+
+**Design system:** all generated UI MUST follow `docs/design-system.md` (tokens + component rules, generated by `/studio`).

apps/backend/src/modules/users/dto/user-response.dto.ts

@@ -32,6 +32,8 @@ export class UserResponseDto {
   emailVerified!: boolean;
 
   @ApiPropertyOptional({
+    type: String,
+    nullable: true,
     example: '2024-01-15T10:30:00.000Z',
     description: 'Last login timestamp',
   })

apps/web/scripts/studio-init.ts

@@ -0,0 +1,38 @@
+// One-off: migrate globals.css (add studio markers + status tokens) and write the
+// initial docs/design-system.md + CLAUDE.md pointer using the real Studio engine.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseGlobalsCss } from '../src/lib/studio/parse-globals';
+import { applyTokensToCss } from '../src/lib/studio/serialize-tokens';
+import {
+  generateDesignRules,
+  DESIGN_RULES_POINTER,
+} from '../src/lib/studio/generate-rules';
+import { withStatusDefaults } from '../src/lib/studio/theme-config';
+
+const root = join(process.cwd(), '..', '..');
+const globalsPath = join(root, 'packages/design/src/styles/globals.css');
+
+const css = readFileSync(globalsPath, 'utf-8');
+const config = withStatusDefaults(parseGlobalsCss(css));
+
+writeFileSync(globalsPath, applyTokensToCss(css, config), 'utf-8');
+writeFileSync(
+  join(root, 'docs/design-system.md'),
+  generateDesignRules(config),
+  'utf-8',
+);
+
+const claudePath = join(root, 'CLAUDE.md');
+const claude = readFileSync(claudePath, 'utf-8');
+if (!claude.includes('docs/design-system.md')) {
+  writeFileSync(
+    claudePath,
+    `${claude.trimEnd()}\n\n${DESIGN_RULES_POINTER}\n`,
+    'utf-8',
+  );
+}
+
+console.log(
+  'Studio init complete: globals.css migrated, design-system.md + CLAUDE pointer written.',
+);