From 419ac64f62ba481677a236676e14d694fb27dacb Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 2 Oct 2026 17:54:47 -0300
Subject: [PATCH 01/30] feat(admin): register a served person under Pessoas
 (#154)

Adds the "Nova pessoa" form (/pessoas/nova) to the admin panel. It posts to
POST /api/v1/clients and registers the person together with guardians and
reference contacts.

- Navigation: the "Clientes" destination becomes "Pessoas" (/pessoas) and is no
  longer "Em breve"; the page is a small hub with a "Nova pessoa" link until
  the list arrives with #155.
- features/clients: model (CPF check digits and mask, dd/mm/aaaa birth date and
  calculated age, the minor-needs-a-guardian rule in America/Sao_Paulo, the Zod
  schema that normalizes what the backend receives), repository, and a
  full-page form with field arrays. Field errors from the backend stay on the
  field they belong to (indexed keys such as Guardians[1].Name included) and
  the typed values are kept.
- A CPF conflict reads the existing person's id from the typed FieldError.meta
  and offers "Abrir cadastro existente" (/pessoas/{id}, opened in a new tab so
  the form survives; that page arrives with #155).
- Usability: focus moves to "Adicionar responsavel" when only the guardian is
  missing; the general error banner sits right above the buttons; adding more
  than 10 contacts of a kind is not offered.
- shared: MaskedField (CPF and birth date), CheckboxGroup, toFormErrors for
  indexed keys, shared/format/date.ts (todayInSaoPaulo).

Docs: ARCHITECTURE.md (decision row and sections 1 and 6), the UI foundation
spec (Clientes -> Pessoas) and the agenza-form-field / agenza-api-contract
skills.

Tests: 561 unit tests (coverage 97%) and e2e/clients.spec.ts (create by name
only, minor needing a guardian, duplicate CPF offering the existing record).

Depends on the backend change (feat/154-clients-backend): the OpenAPI types
file below is the same file that change commits and drops out of this diff once
it is merged. The unit tests, tsc, lint and build do not need the backend;
api-contract-check and the e2e only pass after it is merged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .../agenza-api-contract/references/errors.md  |  12 +-
 .claude/skills/agenza-form-field/SKILL.md     |  17 +-
 apps/admin-frontend/docs/ARCHITECTURE.md      |  21 +-
 apps/admin-frontend/e2e/clients.spec.ts       | 105 +++
 .../specs/002-ui-foundation/spec.md           |  11 +-
 .../src/app/pages/Clients.test.tsx            |  20 +
 apps/admin-frontend/src/app/pages/Clients.tsx |  24 +-
 .../src/app/pages/ComingSoonPages.test.tsx    |   2 -
 apps/admin-frontend/src/app/routes.tsx        |  14 +-
 .../src/app/shell/BottomNav.test.tsx          |   4 +-
 .../src/app/shell/BottomNav.tsx               |   2 +-
 .../src/app/shell/navigation.ts               |   2 +-
 .../clients/api/clientsRepository.test.ts     |  58 ++
 .../features/clients/api/clientsRepository.ts |   9 +
 .../clients/api/existingClientId.test.ts      |  63 ++
 .../features/clients/api/existingClientId.ts  |  16 +
 .../src/features/clients/index.ts             |   1 +
 .../features/clients/model/birthDate.test.ts  | 116 +++
 .../src/features/clients/model/birthDate.ts   |  72 ++
 .../src/features/clients/model/client.ts      |  57 ++
 .../features/clients/model/clientForm.test.ts | 338 +++++++++
 .../src/features/clients/model/clientForm.ts  | 184 +++++
 .../clients/model/contactFormats.test.ts      |  52 ++
 .../features/clients/model/contactFormats.ts  |  17 +
 .../src/features/clients/model/cpf.test.ts    |  56 ++
 .../src/features/clients/model/cpf.ts         |  34 +
 .../ClientFormPage/ClientFormPage.test.tsx    | 671 ++++++++++++++++++
 .../pages/ClientFormPage/ClientFormPage.tsx   |  49 ++
 .../components/ClientFormFooter.tsx           |  28 +
 .../components/ClientFormHeader.tsx           |  22 +
 .../components/ClientFormSection.tsx          |  32 +
 .../components/ClientGuardianItem.tsx         |  82 +++
 .../components/ClientGuardiansSection.tsx     |  73 ++
 .../components/ClientPersonSection.tsx        | 108 +++
 .../components/ClientReferenceContactItem.tsx |  93 +++
 .../ClientReferenceContactsSection.tsx        |  62 ++
 .../pages/ClientFormPage/useClientFormPage.ts | 113 +++
 .../ClientFormPage/useClientFormPage.types.ts |  17 +
 .../src/shared/api/formErrors.test.ts         |  24 +
 .../src/shared/api/formErrors.ts              |   4 +-
 .../shared/api/generated/services-api.d.ts    | 167 +++++
 .../fields/components/masked-field.test.tsx   |  55 ++
 .../form/fields/components/masked-field.tsx   |  28 +
 .../src/shared/form/fields/fields.types.ts    |   5 +
 .../src/shared/form/fields/index.tsx          |   2 +
 .../src/shared/format/date.test.ts            |  17 +
 apps/admin-frontend/src/shared/format/date.ts |  13 +
 .../ui/checkbox-group/checkbox-group.test.tsx | 131 ++++
 .../src/shared/ui/checkbox-group/index.tsx    |  61 ++
 49 files changed, 3131 insertions(+), 33 deletions(-)
 create mode 100644 apps/admin-frontend/e2e/clients.spec.ts
 create mode 100644 apps/admin-frontend/src/app/pages/Clients.test.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts
 create mode 100644 apps/admin-frontend/src/features/clients/api/clientsRepository.ts
 create mode 100644 apps/admin-frontend/src/features/clients/api/existingClientId.test.ts
 create mode 100644 apps/admin-frontend/src/features/clients/api/existingClientId.ts
 create mode 100644 apps/admin-frontend/src/features/clients/index.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/birthDate.test.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/birthDate.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/client.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/clientForm.test.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/clientForm.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/contactFormats.test.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/contactFormats.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/cpf.test.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/cpf.ts
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
 create mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/masked-field.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/masked-field.tsx
 create mode 100644 apps/admin-frontend/src/shared/format/date.test.ts
 create mode 100644 apps/admin-frontend/src/shared/format/date.ts
 create mode 100644 apps/admin-frontend/src/shared/ui/checkbox-group/checkbox-group.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/checkbox-group/index.tsx

diff --git a/.claude/skills/agenza-api-contract/references/errors.md b/.claude/skills/agenza-api-contract/references/errors.md
index 8071abcf..328d9f50 100644
--- a/.claude/skills/agenza-api-contract/references/errors.md
+++ b/.claude/skills/agenza-api-contract/references/errors.md
@@ -52,17 +52,23 @@ not read as "sem conexão", because the user's actual next step is entirely diff
 
 ## `errors` is not always field errors
 
-This is the trap. `errors` is `Record<string, { code?, message? }[]>` and gets filled **two
+This is the trap. `errors` is `Record<string, { code?, message?, meta? }[]>` and gets filled **two
 different ways** (`ApiProblemDetailsFactory`):
 
 1. **Validation (400).** Keys come from FluentValidation's `PropertyName`, grouped in
    `Dispatcher.cs` — so they are **PascalCase C# property names** (`Name`, `DurationMinutes`), not
    the camelCase your JSON body and form fields use. A cross-field rule can be re-keyed onto one
    field with `OverridePropertyName` (see `CreateServiceCommandValidator.cs`), so the key set is not
-   mechanically the command's properties either.
+   mechanically the command's properties either. An item of a list inside the command carries its
+   index: `Guardians[1].Name` (`toFormErrors` turns that into `guardians.1.name`).
 2. **Any other application error** (Conflict, NotFound, Failure). `CreateSingleErrorDictionary`
    puts the error itself under the **empty-string key `""`**. So a 409 arrives with a populated
-   `errors` that maps to no field at all.
+   `errors` that maps to no field at all. The exception: a handler may build the `Error` with its own
+   `FieldErrors`, and then the 409 is keyed by field (`Cpf`, `Email` in `CreateClient`).
+
+`meta` is an optional string map on one entry, absent when empty. It carries context for the client,
+never prose: the CPF conflict puts `clientId` there (and only when that record can be opened), read in
+`features/clients/api/existingClientId.ts`. Branch on the entry's `code` before trusting a `meta` key.
 
 Authorization and unexpected problems carry an empty `errors` object, never `null` in practice —
 but the type says nullable, so guard anyway.
diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index 72d86139..12fa5eb2 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -5,12 +5,21 @@ description: Use when building or changing a form in admin-frontend — wiring R
 
 # Forms — React Hook Form + Zod + `shared/form/fields/`
 
-`TagFormPage` (`src/features/tags/ui/pages/TagFormPage/`) is the reference implementation and, as of
-this writing, the **only** consumer of everything described here. Read
+`TagFormPage` (`src/features/tags/ui/pages/TagFormPage/`) is the reference implementation for a
+dialog form. `ClientFormPage` (`src/features/clients/ui/pages/ClientFormPage/`) is the second
+consumer and the reference for a full-page form with **field arrays** (`useFieldArray`, nested paths
+such as `guardians.${number}.name`), masked inputs (`MaskedField`) and a custom multi-value control
+(`CheckboxGroup` through a `ControlledField` render function). Read
 [`docs/ARCHITECTURE.md` §5](../../../apps/admin-frontend/docs/ARCHITECTURE.md) (the "Tag create/edit
 UI reintroduced on React Hook Form + Zod" row and the row right after it) for the decision history
 and the two gotchas below in their original context, and §6's "Provisional" section for what's still
-unproven with only one consumer.
+unproven.
+
+Backend errors on a list item arrive keyed `Guardians[1].Name`; `toFormErrors` normalizes that to
+`guardians.1.name`, so the hook passes it the **current** field paths (top-level plus one per item),
+not a static list — see `useClientFormPage.ts`'s `fieldPathsOf`. A field-array root error (e.g.
+"informe ao menos um responsável") lives at `errors.guardians.message` / `errors.guardians.root.message`
+and has no input to attach to: render it in the section.
 
 ## The three layers, one job each
 
@@ -18,7 +27,7 @@ unproven with only one consumer.
 | --- | --- | --- |
 | Error mapping | `shared/api/formErrors.ts` | `toFormErrors<F>(problem, fields)` — `ApiProblem` → `{fieldErrors, formError}`. Knows `ApiProblem`, nothing about RHF. |
 | RHF bridge | `shared/form/applyApiProblem.ts` | `applyApiProblem<T>(problem, fields, setError)` — calls the above, then `setError` per field plus `setError('root.serverError', …)`. Knows both shapes; the only file that does. |
-| Field components | `shared/form/fields/` | `TextField`/`TextareaField`, `ControlledField`, `ColorField`, `FormErrorBanner` — RHF wiring, zero domain knowledge. They render into `shared/ui/form-field/`'s `FormField` (label, hint, error, the `aria-*` wiring), which stays presentational and RHF-free like the rest of `shared/ui/` (`agenza-ui-primitive`). |
+| Field components | `shared/form/fields/` | `TextField`/`TextareaField`, `MaskedField`, `ControlledField`, `ColorField`, `FormErrorBanner` — RHF wiring, zero domain knowledge. They render into `shared/ui/form-field/`'s `FormField` (label, hint, error, the `aria-*` wiring), which stays presentational and RHF-free like the rest of `shared/ui/` (`agenza-ui-primitive`). |
 
 Never let a field component or `shared/form/` read `problem.errors` directly — that parsing (PascalCase
 keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See `agenza-api-contract`'s
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index e5751e82..b16837f6 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -24,7 +24,7 @@ src/
 │   ├── shell/               AppShell chrome: responsive nav (sidebar/rail/bottom), header,
 │   │                        command palette
 │   └── pages/               One stub per route (§6) — not feature slices; no model, no api
-├── features/<slice>/        One vertical slice per user-facing capability (auth, tags, …)
+├── features/<slice>/        One vertical slice per user-facing capability (auth, tags, clients, …)
 │   ├── model/               Types + rules. No React. ( = domain + application )
 │   ├── api/                 Backend gateway — repositories. ( = infrastructure )
 │   ├── ui/                  Everything that imports React
@@ -382,6 +382,7 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | Review fixes on the tag dialogs (PR #125) | Two defects, one line of reasoning each. (1) `useRouteScrollReset` keys on the **section** (first path segment), not the whole `pathname`: `new`, `:id/edit` and `:id/delete` are child routes of `/tags`, so every dialog open/close used to reset `<main>`'s scroll and throw the list back to the top. (2) `useTagFormPage.onValid` and `ConfirmDialog.handleConfirm` skip closing when the dialog already unmounted mid-request (browser Back): react-router's `useNavigate` stays live after unmount, so the stale `navigate(-1)` used to pop one entry too many — out of the app, when `/tags` was the tab's first entry. FR-018 still does not block browser Back; no `useBlocker`, since the request finishes anyway and the toast still reports it. Deliberately left as is, both judged not worth the code: a row someone else already removed stays listed after its `Tag.NotFound` until the next reload or search — the spec's edge case only asks for the "não encontrada" message, which already shows; and `TagDeletePage` keeps its loaded tag if `:id` changed without a remount, because no UI path goes from `/tags/A/delete` straight to `/tags/B/delete` — the modal blocks the list, and closing it goes back to `/tags` first. A `key={id}` on the confirmation is the fix if a flow like "excluir a próxima" ever appears. |
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
+| `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayInSaoPaulo()` for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict reads the existing record's id from the typed `FieldError.meta` and links to `/pessoas/{id}` in a new tab, so the typed values survive; that page arrives with #155. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
@@ -407,19 +408,21 @@ because it didn't need to be yet. This is the compiled view across the whole app
   `specs/002-ui-foundation/`'s explicit scope (D6) — chrome, theme, routing and "Em breve" stubs
   first. Retirement trigger, per page: **the first real feature slice replaces the stub it
   corresponds to** (e.g. a `features/services/` slice replaces `app/pages/Services.tsx` and moves
-  under `ui/pages/<Page>/` per §1), once its backend exists.
+  under `ui/pages/<Page>/` per §1), once its backend exists. `app/pages/Clients.tsx` is already
+  half-way: it is the Pessoas hub (title plus a **Nova pessoa** link), no longer an "Em breve" screen,
+  while the registration form lives in `features/clients`; the list from issue #155 replaces its body.
 - **The API layer (`servicesApi`, `apiClient`, `unwrap`, `servicesFacade`, the generated types) stood
   with zero call sites for a while, on purpose — not dead code.** `features/tags/api/tagsRepository.ts`
   is its first real consumer (`specs/003-tags-crud/`); see
   [ADR 0038](../../../docs/adr/0038-admin-frontend-remove-categories-harness.md) for why the layer
   was kept standing in the meantime.
-- **`shared/form/fields/`'s genericity is asserted, not yet proven by a second caller.**
-  `TextField`/`TextareaField`/`ControlledField` are written generic over any RHF `FieldValues`, and
-  `ColorField` was deliberately kept as a specialization of `ControlledField` rather than the only
-  shape the family supports — but `TagFormPage` is still the one consumer exercising any of it.
-  Whether the family's actual shape holds (in particular whether `ControlledField`'s render-function
-  escape hatch is what the next custom control needs, or whether it wants its own specialization
-  immediately) is untested until the next entity's form is built — see `agenza-form-field`.
+- **`shared/form/fields/`'s genericity now has a second caller.** `ClientFormPage` uses
+  `TextField`/`TextareaField`/`ControlledField` over a different schema, including nested field-array
+  paths (`guardians.${number}.name`), and it is what justified `MaskedField` as the second
+  specialization of `ControlledField` (three call sites) while the purposes checkboxes stay a plain
+  `ControlledField` render function (one call site) — see `agenza-form-field`. Still unproven: a form
+  that loads an existing record in a page rather than a dialog (Tags covers edit; Clients is
+  create-only until issue #156).
 
 ### Deliberately not built — no need yet
 
diff --git a/apps/admin-frontend/e2e/clients.spec.ts b/apps/admin-frontend/e2e/clients.spec.ts
new file mode 100644
index 00000000..b519903d
--- /dev/null
+++ b/apps/admin-frontend/e2e/clients.spec.ts
@@ -0,0 +1,105 @@
+import { test, expect, type Page } from '@playwright/test';
+import { loginAsDemoUser } from './helpers';
+
+function validCpf(): string {
+  const checkDigit = (digits: number[]) => {
+    const weightStart = digits.length + 1;
+    const sum = digits.reduce((total, digit, index) => total + digit * (weightStart - index), 0);
+    const remainder = (sum * 10) % 11;
+    return remainder === 10 ? 0 : remainder;
+  };
+
+  const base = Array.from({ length: 9 }, () => Math.floor(Math.random() * 10));
+  const first = checkDigit(base);
+  const second = checkDigit([...base, first]);
+  return [...base, first, second].join('');
+}
+
+function uniqueName(prefix: string): string {
+  return `${prefix} ${Date.now()}${Math.floor(Math.random() * 1000)}`;
+}
+
+async function openNewPersonForm(page: Page) {
+  await page.getByRole('link', { name: 'Pessoas' }).click();
+  await expect(page).toHaveURL(/\/pessoas$/);
+  await page.getByRole('link', { name: 'Nova pessoa' }).click();
+  await expect(page).toHaveURL(/\/pessoas\/nova$/);
+  await expect(page.getByRole('heading', { name: 'Nova pessoa' })).toBeVisible();
+}
+
+test.describe('Register a person', () => {
+  test.beforeEach(async ({ page }) => {
+    await loginAsDemoUser(page);
+  });
+
+  test('reaches the form from the Pessoas area and saves a person described only by the name', async ({
+    page,
+  }) => {
+    await openNewPersonForm(page);
+
+    await page.getByLabel('Nome completo').fill(uniqueName('Pessoa E2E'));
+    await page.getByRole('button', { name: 'Salvar' }).click();
+
+    await expect(page).toHaveURL(/\/pessoas$/);
+    await expect(page.getByText('Pessoa cadastrada')).toBeVisible();
+  });
+
+  test('asks for a guardian only when the birth date indicates a minor, then saves with one', async ({
+    page,
+  }) => {
+    await openNewPersonForm(page);
+    const person = page.getByRole('region', { name: 'Dados da pessoa' });
+    const tenYearsAgo = new Date().getFullYear() - 10;
+
+    await person.getByLabel('Nome completo').fill(uniqueName('Menor E2E'));
+    await expect(page.getByRole('status')).toHaveCount(0);
+    await person.getByLabel('Data de nascimento').fill(`15/06/${tenYearsAgo}`);
+    await expect(page.getByRole('status')).toContainText('Informe ao menos um responsável');
+
+    await page.getByRole('button', { name: 'Salvar' }).click();
+    await expect(page.getByRole('alert')).toContainText(
+      'Informe ao menos um responsável para pessoas menores de 18 anos.',
+    );
+    await expect(page).toHaveURL(/\/pessoas\/nova$/);
+
+    await page.getByRole('button', { name: 'Adicionar responsável' }).click();
+    const guardian = page.getByRole('group', { name: 'Responsável 1' });
+    await guardian.getByLabel('Nome').fill('Responsável E2E');
+    await guardian.getByLabel('Vínculo').fill('Mãe');
+    await page.getByRole('button', { name: 'Adicionar pessoa de referência' }).click();
+    const reference = page.getByRole('group', { name: 'Pessoa de referência 1' });
+    await reference.getByLabel('Nome').fill('Contato E2E');
+    await reference.getByLabel('Vínculo').fill('Tio');
+    await reference.getByRole('checkbox', { name: 'Emergência' }).click();
+    await page.getByRole('button', { name: 'Salvar' }).click();
+
+    await expect(page).toHaveURL(/\/pessoas$/);
+    await expect(page.getByText('Pessoa cadastrada')).toBeVisible();
+  });
+
+  test('refuses a CPF that already belongs to someone and offers the existing record', async ({
+    page,
+  }) => {
+    const cpf = validCpf();
+    await openNewPersonForm(page);
+    await page.getByLabel('Nome completo').fill(uniqueName('Primeira E2E'));
+    await page.getByRole('region', { name: 'Dados da pessoa' }).getByLabel('CPF').fill(cpf);
+    await page.getByRole('button', { name: 'Salvar' }).click();
+    await expect(page).toHaveURL(/\/pessoas$/);
+
+    await page.getByRole('link', { name: 'Nova pessoa' }).click();
+    const person = page.getByRole('region', { name: 'Dados da pessoa' });
+    const secondName = uniqueName('Segunda E2E');
+    await person.getByLabel('Nome completo').fill(secondName);
+    await person.getByLabel('CPF').fill(cpf);
+    await page.getByRole('button', { name: 'Salvar' }).click();
+
+    await expect(person.getByText('Já existe uma pessoa cadastrada com este CPF.')).toBeVisible();
+    await expect(person.getByLabel('Nome completo')).toHaveValue(secondName);
+    await expect(page).toHaveURL(/\/pessoas\/nova$/);
+    await expect(person.getByRole('link', { name: /Abrir cadastro existente/ })).toHaveAttribute(
+      'href',
+      /\/pessoas\/[0-9a-f-]{36}$/,
+    );
+  });
+});
diff --git a/apps/admin-frontend/specs/002-ui-foundation/spec.md b/apps/admin-frontend/specs/002-ui-foundation/spec.md
index 0a993202..77da28d9 100644
--- a/apps/admin-frontend/specs/002-ui-foundation/spec.md
+++ b/apps/admin-frontend/specs/002-ui-foundation/spec.md
@@ -27,6 +27,14 @@ A interface atual pode ser inteiramente descartada, mantendo apenas o esqueleto
   "Em breve" honesta.
 - Q: Aprovar o visual antes de escrever código? → A: **Sim**, protótipo clicável primeiro. Concluído.
 
+### Session 2026-10-02
+
+- Q: O destino "Clientes" mantém o nome quando o cadastro de pessoas atendidas chega (issues #139 e
+  #154)? → A: **Não.** O destino passa a se chamar **"Pessoas"**, na rota `/pessoas`, e deixa de ser
+  "Em breve" porque já tem backend (`POST /api/v1/clients`) e o formulário de cadastro em
+  `/pessoas/nova`. O identificador de código continua em inglês (`clients`). A lista e o detalhe
+  chegam com a issue #155.
+
 ## User Scenarios & Testing *(mandatory)*
 
 ### User Story 1 — A pessoa escolhe como o painel se apresenta, e o painel obedece (Priority: P1)
@@ -128,7 +136,8 @@ próprio escopo, sem texto genérico repetido.
 - **FR-004**: A preferência de tema **DEVE** ser compartilhada com o identity-service, de modo que a
   página de credenciais abra no mesmo tema (fecha a lacuna da ADR 0020).
 - **FR-005**: A navegação **DEVE** expor seis destinos — Início, Agenda, Clientes, Conversas,
-  Serviços, Ajustes — desde a primeira entrega.
+  Serviços, Ajustes — desde a primeira entrega. _(Desde 2026-10-02 o destino "Clientes" chama-se
+  "Pessoas"; ver Clarifications.)_
 - **FR-006**: Destinos sem backend **DEVEM** renderizar uma explicação específica do destino, e
   **NÃO DEVEM** ser apresentados como funcionais.
 - **FR-007**: O shell **DEVE** apresentar barra lateral em telas largas e barra inferior em telas
diff --git a/apps/admin-frontend/src/app/pages/Clients.test.tsx b/apps/admin-frontend/src/app/pages/Clients.test.tsx
new file mode 100644
index 00000000..731b2bb0
--- /dev/null
+++ b/apps/admin-frontend/src/app/pages/Clients.test.tsx
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import { Clients } from './Clients';
+
+describe('Clients', () => {
+  it('renders the Pessoas title and a way to register a new person', () => {
+    render(
+      <MemoryRouter>
+        <Clients />
+      </MemoryRouter>,
+    );
+
+    expect(screen.getByRole('heading', { name: 'Pessoas' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Nova pessoa' })).toHaveAttribute(
+      'href',
+      '/pessoas/nova',
+    );
+  });
+});
diff --git a/apps/admin-frontend/src/app/pages/Clients.tsx b/apps/admin-frontend/src/app/pages/Clients.tsx
index bbedd8ba..0f835354 100644
--- a/apps/admin-frontend/src/app/pages/Clients.tsx
+++ b/apps/admin-frontend/src/app/pages/Clients.tsx
@@ -1,12 +1,22 @@
-import { Users } from 'lucide-react';
-import { ComingSoon } from './ComingSoon';
+import { Plus } from 'lucide-react';
+import { Link } from 'react-router';
+import { buttonVariants } from '@/shared/ui/button';
 
 export function Clients() {
   return (
-    <ComingSoon
-      icon={Users}
-      title="Clientes"
-      description="O cadastro de clientes vai reunir aqui o histórico, o contato e as preferências de cada um."
-    />
+    <div className="space-y-4">
+      <div className="flex items-start justify-between gap-4">
+        <div className="space-y-1.5">
+          <h1 className="text-2xl font-semibold tracking-tight">Pessoas</h1>
+          <p className="text-sm text-muted-foreground">
+            A lista das pessoas atendidas vai aparecer aqui.
+          </p>
+        </div>
+        <Link to="/pessoas/nova" className={buttonVariants()}>
+          <Plus aria-hidden="true" />
+          Nova pessoa
+        </Link>
+      </div>
+    </div>
   );
 }
diff --git a/apps/admin-frontend/src/app/pages/ComingSoonPages.test.tsx b/apps/admin-frontend/src/app/pages/ComingSoonPages.test.tsx
index 2edca2db..106cfe9e 100644
--- a/apps/admin-frontend/src/app/pages/ComingSoonPages.test.tsx
+++ b/apps/admin-frontend/src/app/pages/ComingSoonPages.test.tsx
@@ -3,12 +3,10 @@ import { render } from '@testing-library/react';
 import { MemoryRouter } from 'react-router';
 import { Schedule } from './Schedule';
 import { Settings } from './Settings';
-import { Clients } from './Clients';
 import { Conversations } from './Conversations';
 
 const PAGES = [
   { name: 'Agenda', Component: Schedule },
-  { name: 'Clientes', Component: Clients },
   { name: 'Conversas', Component: Conversations },
   { name: 'Ajustes', Component: Settings },
 ];
diff --git a/apps/admin-frontend/src/app/routes.tsx b/apps/admin-frontend/src/app/routes.tsx
index 98b9d2ce..d3b9ec02 100644
--- a/apps/admin-frontend/src/app/routes.tsx
+++ b/apps/admin-frontend/src/app/routes.tsx
@@ -23,8 +23,18 @@ export const router = createBrowserRouter([
             lazy: () => import('./pages/Schedule').then((m) => ({ Component: m.Schedule })),
           },
           {
-            path: 'clientes',
-            lazy: () => import('./pages/Clients').then((m) => ({ Component: m.Clients })),
+            path: 'pessoas',
+            children: [
+              {
+                index: true,
+                lazy: () => import('./pages/Clients').then((m) => ({ Component: m.Clients })),
+              },
+              {
+                path: 'nova',
+                lazy: () =>
+                  import('@/features/clients').then((m) => ({ Component: m.ClientFormPage })),
+              },
+            ],
           },
           {
             path: 'conversas',
diff --git a/apps/admin-frontend/src/app/shell/BottomNav.test.tsx b/apps/admin-frontend/src/app/shell/BottomNav.test.tsx
index b0c72d1c..db620ce0 100644
--- a/apps/admin-frontend/src/app/shell/BottomNav.test.tsx
+++ b/apps/admin-frontend/src/app/shell/BottomNav.test.tsx
@@ -7,13 +7,13 @@ import { BottomNav } from './BottomNav';
 describe('BottomNav', () => {
   it('shows the four primary destinations directly and marks the active one', () => {
     render(
-      <MemoryRouter initialEntries={['/clientes']}>
+      <MemoryRouter initialEntries={['/pessoas']}>
         <BottomNav />
       </MemoryRouter>,
     );
 
     expect(screen.getByRole('link', { name: /Início/ })).toBeInTheDocument();
-    expect(screen.getByRole('link', { name: /Clientes/ })).toHaveAttribute('aria-current', 'page');
+    expect(screen.getByRole('link', { name: 'Pessoas' })).toHaveAttribute('aria-current', 'page');
     expect(screen.getByRole('button', { name: 'Mais' })).toBeInTheDocument();
   });
 
diff --git a/apps/admin-frontend/src/app/shell/BottomNav.tsx b/apps/admin-frontend/src/app/shell/BottomNav.tsx
index 1b13e7c4..41661dea 100644
--- a/apps/admin-frontend/src/app/shell/BottomNav.tsx
+++ b/apps/admin-frontend/src/app/shell/BottomNav.tsx
@@ -5,7 +5,7 @@ import { cn } from '@/shared/lib/utils';
 import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '@/shared/ui/sheet';
 import { NAV_DESTINATIONS } from './navigation';
 
-const PRIMARY_HREFS = ['/', '/agenda', '/clientes', '/servicos'];
+const PRIMARY_HREFS = ['/', '/agenda', '/pessoas', '/servicos'];
 
 const TAB_CLASS =
   'flex min-h-11 flex-1 flex-col items-center justify-center gap-0.5 py-1 text-xs text-muted-foreground';
diff --git a/apps/admin-frontend/src/app/shell/navigation.ts b/apps/admin-frontend/src/app/shell/navigation.ts
index 41957240..9c1c55fd 100644
--- a/apps/admin-frontend/src/app/shell/navigation.ts
+++ b/apps/admin-frontend/src/app/shell/navigation.ts
@@ -11,7 +11,7 @@ export interface NavDestination {
 export const NAV_DESTINATIONS: NavDestination[] = [
   { label: 'Início', href: '/', icon: Home, comingSoon: false },
   { label: 'Agenda', href: '/agenda', icon: CalendarDays, comingSoon: true },
-  { label: 'Clientes', href: '/clientes', icon: Users, comingSoon: true },
+  { label: 'Pessoas', href: '/pessoas', icon: Users, comingSoon: false },
   { label: 'Conversas', href: '/conversas', icon: MessageCircle, comingSoon: true },
   { label: 'Serviços', href: '/servicos', icon: Wrench, comingSoon: false },
   { label: 'Etiquetas', href: '/tags', icon: Tag, comingSoon: false },
diff --git a/apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts b/apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts
new file mode 100644
index 00000000..d0bf17b1
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ClientInput } from '../model/client';
+import { clientsRepository } from './clientsRepository';
+
+const { mockPost } = vi.hoisted(() => ({ mockPost: vi.fn() }));
+
+vi.mock('@/shared/api/servicesApi', () => ({
+  servicesApi: { post: mockPost },
+}));
+
+const INPUT: ClientInput = {
+  fullName: 'Maria Souza',
+  birthDate: '2015-03-10',
+  phone: null,
+  email: 'maria@example.com',
+  cpf: '52998224725',
+  administrativeNotes: null,
+  guardians: [{ name: 'Ana Souza', relationship: 'Mãe', phone: null, cpf: null }],
+  referenceContacts: [
+    { name: 'Carlos Lima', relationship: 'Tio', phone: null, purposes: ['emergency'] },
+  ],
+};
+
+describe('clientsRepository.create', () => {
+  it('posts the whole person with its contacts to POST /clients and forwards the result verbatim', async () => {
+    const client = { id: 'abc', ...INPUT, status: 'active' };
+    mockPost.mockResolvedValue({ ok: true, data: client });
+
+    const result = await clientsRepository.create(INPUT);
+
+    expect(mockPost).toHaveBeenCalledWith('/api/v{version}/clients', { body: INPUT });
+    expect(result).toEqual({ ok: true, data: client });
+  });
+
+  it('never sends a tenant, only what the person typed', async () => {
+    mockPost.mockResolvedValue({ ok: true, data: {} });
+
+    await clientsRepository.create(INPUT);
+
+    const [, options] = mockPost.mock.calls.at(-1) as [string, { body: Record<string, unknown> }];
+    expect(Object.keys(options.body).some((key) => key.toLowerCase().includes('tenant'))).toBe(
+      false,
+    );
+  });
+
+  it('forwards a failed result verbatim, without throwing (e.g. duplicate CPF)', async () => {
+    const error = {
+      status: 409,
+      code: 'Client.DuplicateCpf',
+      title: 'Já existe uma pessoa cadastrada com este CPF.',
+    };
+    mockPost.mockResolvedValue({ ok: false, error });
+
+    const result = await clientsRepository.create(INPUT);
+
+    expect(result).toEqual({ ok: false, error });
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/api/clientsRepository.ts b/apps/admin-frontend/src/features/clients/api/clientsRepository.ts
new file mode 100644
index 00000000..1db9bc71
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/api/clientsRepository.ts
@@ -0,0 +1,9 @@
+import { servicesApi } from '@/shared/api/servicesApi';
+import type { ApiResult } from '@/shared/api/servicesFacade';
+import type { Client, ClientInput } from '../model/client';
+
+function create(input: ClientInput): Promise<ApiResult<Client>> {
+  return servicesApi.post('/api/v{version}/clients', { body: input });
+}
+
+export const clientsRepository = { create };
diff --git a/apps/admin-frontend/src/features/clients/api/existingClientId.test.ts b/apps/admin-frontend/src/features/clients/api/existingClientId.test.ts
new file mode 100644
index 00000000..8508bff9
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/api/existingClientId.test.ts
@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import type { ApiProblem } from '@/shared/api/servicesFacade';
+import { existingClientIdFrom } from './existingClientId';
+
+const EXISTING_ID = '0197f2a0-0000-7000-8000-000000000001';
+
+describe('existingClientIdFrom', () => {
+  it('reads the id of the client that already owns the CPF', () => {
+    const problem: ApiProblem = {
+      status: 409,
+      code: 'Client.DuplicateCpf',
+      errors: {
+        Cpf: [
+          {
+            code: 'Client.DuplicateCpf',
+            message: 'Já existe uma pessoa cadastrada com este CPF.',
+            meta: { clientId: EXISTING_ID },
+          },
+        ],
+      },
+    };
+
+    expect(existingClientIdFrom(problem)).toBe(EXISTING_ID);
+  });
+
+  it('has nothing to open when the CPF belongs to a deleted client', () => {
+    const problem: ApiProblem = {
+      status: 409,
+      code: 'Client.DuplicateCpf',
+      errors: {
+        Cpf: [
+          { code: 'Client.DuplicateCpf', message: 'Este CPF pertence a um cadastro excluído.' },
+        ],
+      },
+    };
+
+    expect(existingClientIdFrom(problem)).toBeNull();
+  });
+
+  it('ignores a conflict that is not about the CPF', () => {
+    const problem: ApiProblem = {
+      status: 409,
+      code: 'Client.DuplicateEmail',
+      errors: {
+        Email: [
+          { code: 'Client.DuplicateEmail', message: 'Já existe.', meta: { clientId: EXISTING_ID } },
+        ],
+      },
+    };
+
+    expect(existingClientIdFrom(problem)).toBeNull();
+  });
+
+  it.each([
+    ['no errors at all', { status: 0, title: 'Sem conexão.' } satisfies ApiProblem],
+    [
+      'a form-level error',
+      { status: 409, errors: { '': [{ message: 'Conflito.' }] } } satisfies ApiProblem,
+    ],
+  ])('returns null for %s', (_name, problem) => {
+    expect(existingClientIdFrom(problem)).toBeNull();
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/api/existingClientId.ts b/apps/admin-frontend/src/features/clients/api/existingClientId.ts
new file mode 100644
index 00000000..53a77001
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/api/existingClientId.ts
@@ -0,0 +1,16 @@
+import type { ApiProblem } from '@/shared/api/servicesFacade';
+
+const DUPLICATE_CPF_CODE = 'Client.DuplicateCpf';
+const CPF_FIELD = 'cpf';
+const CLIENT_ID_KEY = 'clientId';
+
+export function existingClientIdFrom(problem: ApiProblem): string | null {
+  for (const [field, errors] of Object.entries(problem.errors ?? {})) {
+    if (field.toLowerCase() !== CPF_FIELD) continue;
+
+    const conflict = errors.find((error) => error.code === DUPLICATE_CPF_CODE);
+    return conflict?.meta?.[CLIENT_ID_KEY] ?? null;
+  }
+
+  return null;
+}
diff --git a/apps/admin-frontend/src/features/clients/index.ts b/apps/admin-frontend/src/features/clients/index.ts
new file mode 100644
index 00000000..323d4b58
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/index.ts
@@ -0,0 +1 @@
+export { ClientFormPage } from './ui/pages/ClientFormPage/ClientFormPage';
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
new file mode 100644
index 00000000..095dafec
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it } from 'vitest';
+import {
+  calculateAge,
+  formatAge,
+  isInThePast,
+  isMinorOn,
+  isWithinMaxAge,
+  maskBirthDate,
+  parseBirthDate,
+} from './birthDate';
+
+const TODAY = '2026-10-02';
+
+describe('maskBirthDate', () => {
+  it.each([
+    ['', ''],
+    ['1', '1'],
+    ['10', '10'],
+    ['103', '10/3'],
+    ['1003', '10/03'],
+    ['10032', '10/03/2'],
+    ['10032015', '10/03/2015'],
+    ['100320159999', '10/03/2015'],
+    ['10/03/2015', '10/03/2015'],
+    ['ab10-03', '10/03'],
+  ] as const)('masks %j as %j while typing', (typed, expected) => {
+    expect(maskBirthDate(typed)).toBe(expected);
+  });
+});
+
+describe('parseBirthDate', () => {
+  it.each([
+    ['10/03/2015', '2015-03-10'],
+    ['01/01/1900', '1900-01-01'],
+    ['29/02/2000', '2000-02-29'],
+    [' 05/12/1990 ', '1990-12-05'],
+  ] as const)('reads %j as %s', (masked, expected) => {
+    expect(parseBirthDate(masked)).toBe(expected);
+  });
+
+  it.each([
+    '',
+    '10/03',
+    '10/03/15',
+    '31/02/2020',
+    '29/02/2001',
+    '00/10/2020',
+    '10/00/2020',
+    '10/13/2020',
+    '32/01/2020',
+    '10/03/0999',
+    'aa/bb/cccc',
+    '10-03-2015',
+  ])('rejects %j', (masked) => {
+    expect(parseBirthDate(masked)).toBeNull();
+  });
+});
+
+describe('calculateAge', () => {
+  it.each([
+    ['2008-10-02', 18],
+    ['2008-10-03', 17],
+    ['2008-10-01', 18],
+    ['2026-10-01', 0],
+    ['2000-02-29', 26],
+    ['1906-10-02', 120],
+    ['1906-10-03', 119],
+    ['1905-10-02', 121],
+  ] as const)('counts completed years for %s as %i', (birthDate, expected) => {
+    expect(calculateAge(birthDate, TODAY)).toBe(expected);
+  });
+
+  it('treats a leap-day birthday as February 28 in common years, like the backend', () => {
+    expect(calculateAge('2008-02-29', '2026-02-27')).toBe(17);
+    expect(calculateAge('2008-02-29', '2026-02-28')).toBe(18);
+    expect(calculateAge('2008-02-29', '2028-02-28')).toBe(19);
+    expect(calculateAge('2008-02-29', '2028-02-29')).toBe(20);
+  });
+});
+
+describe('birth date rules', () => {
+  it('requires a date strictly in the past', () => {
+    expect(isInThePast('2026-10-01', TODAY)).toBe(true);
+    expect(isInThePast('2026-10-02', TODAY)).toBe(false);
+    expect(isInThePast('2026-10-03', TODAY)).toBe(false);
+  });
+
+  it('accepts up to 120 years and rejects 121', () => {
+    expect(isWithinMaxAge('1906-10-02', TODAY)).toBe(true);
+    expect(isWithinMaxAge('1905-10-02', TODAY)).toBe(false);
+  });
+
+  it('is a minor until the eighteenth birthday', () => {
+    expect(isMinorOn('2008-10-03', TODAY)).toBe(true);
+    expect(isMinorOn('2008-10-02', TODAY)).toBe(false);
+    expect(isMinorOn('2026-10-01', TODAY)).toBe(true);
+    expect(isMinorOn('1990-01-01', TODAY)).toBe(false);
+  });
+
+  it('is never a minor on a date that is not in the past', () => {
+    expect(isMinorOn('2026-10-03', TODAY)).toBe(false);
+    expect(isMinorOn('2026-10-02', TODAY)).toBe(false);
+  });
+});
+
+describe('formatAge', () => {
+  it.each([
+    [0, 'menos de 1 ano'],
+    [1, '1 ano'],
+    [2, '2 anos'],
+    [17, '17 anos'],
+    [120, '120 anos'],
+  ] as const)('writes %i as %j', (age, expected) => {
+    expect(formatAge(age)).toBe(expected);
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.ts b/apps/admin-frontend/src/features/clients/model/birthDate.ts
new file mode 100644
index 00000000..f2e72191
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.ts
@@ -0,0 +1,72 @@
+export const ADULT_AGE_IN_YEARS = 18;
+export const MAX_AGE_IN_YEARS = 120;
+
+const MASKED_LENGTH = 10;
+
+export function maskBirthDate(value: string): string {
+  const digits = value.replace(/\D/g, '').slice(0, 8);
+
+  if (digits.length <= 2) return digits;
+  if (digits.length <= 4) return `${digits.slice(0, 2)}/${digits.slice(2)}`;
+  return `${digits.slice(0, 2)}/${digits.slice(2, 4)}/${digits.slice(4)}`;
+}
+
+export function parseBirthDate(masked: string): string | null {
+  const value = masked.trim();
+  if (value.length !== MASKED_LENGTH) return null;
+
+  const [day, month, year] = value.split('/').map(Number);
+  if (day === undefined || month === undefined || year === undefined) return null;
+  if (!Number.isInteger(day) || !Number.isInteger(month) || !Number.isInteger(year)) return null;
+  if (year < 1000 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
+    return null;
+  }
+
+  return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+
+export function calculateAge(birthDate: string, today: string): number {
+  const birth = toParts(birthDate);
+  const current = toParts(today);
+
+  const age = current.year - birth.year;
+  const birthdayThisYear = {
+    month: birth.month,
+    day: Math.min(birth.day, daysInMonth(current.year, birth.month)),
+  };
+  const hadBirthday =
+    current.month > birthdayThisYear.month ||
+    (current.month === birthdayThisYear.month && current.day >= birthdayThisYear.day);
+
+  return hadBirthday ? age : age - 1;
+}
+
+export function isInThePast(birthDate: string, today: string): boolean {
+  return birthDate < today;
+}
+
+export function isWithinMaxAge(birthDate: string, today: string): boolean {
+  return calculateAge(birthDate, today) <= MAX_AGE_IN_YEARS;
+}
+
+export function isMinorOn(birthDate: string, today: string): boolean {
+  return isInThePast(birthDate, today) && calculateAge(birthDate, today) < ADULT_AGE_IN_YEARS;
+}
+
+export function formatAge(age: number): string {
+  if (age < 1) return 'menos de 1 ano';
+  return age === 1 ? '1 ano' : `${age} anos`;
+}
+
+function toParts(isoDate: string): { year: number; month: number; day: number } {
+  const [year = 0, month = 0, day = 0] = isoDate.split('-').map(Number);
+  return { year, month, day };
+}
+
+function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function pad(value: number, length: number): string {
+  return String(value).padStart(length, '0');
+}
diff --git a/apps/admin-frontend/src/features/clients/model/client.ts b/apps/admin-frontend/src/features/clients/model/client.ts
new file mode 100644
index 00000000..7dd0156a
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/client.ts
@@ -0,0 +1,57 @@
+export interface ClientGuardian {
+  id: string;
+  name: string;
+  relationship: string;
+  phone: string | null;
+  cpf: string | null;
+}
+
+export interface ClientReferenceContact {
+  id: string;
+  name: string;
+  relationship: string;
+  phone: string | null;
+  purposes: string[];
+}
+
+export interface Client {
+  id: string;
+  fullName: string;
+  birthDate: string | null;
+  phone: string | null;
+  email: string | null;
+  cpf: string | null;
+  administrativeNotes: string | null;
+  status: string;
+  guardians: ClientGuardian[];
+  referenceContacts: ClientReferenceContact[];
+}
+
+export type GuardianInput = Pick<ClientGuardian, 'name' | 'relationship' | 'phone' | 'cpf'>;
+
+export type ReferenceContactInput = Pick<
+  ClientReferenceContact,
+  'name' | 'relationship' | 'phone' | 'purposes'
+>;
+
+export interface ClientInput {
+  fullName: string;
+  birthDate: string | null;
+  phone: string | null;
+  email: string | null;
+  cpf: string | null;
+  administrativeNotes: string | null;
+  guardians: GuardianInput[];
+  referenceContacts: ReferenceContactInput[];
+}
+
+export interface ContactPurposeOption {
+  value: string;
+  label: string;
+}
+
+export const CONTACT_PURPOSE_OPTIONS: readonly ContactPurposeOption[] = [
+  { value: 'emergency', label: 'Emergência' },
+  { value: 'operationalSupport', label: 'Apoio operacional' },
+  { value: 'dailyCommunication', label: 'Comunicação cotidiana' },
+];
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
new file mode 100644
index 00000000..f356c2fa
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
@@ -0,0 +1,338 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  CLIENT_FORM_FIELDS,
+  GUARDIAN_FORM_FIELDS,
+  REFERENCE_CONTACT_FORM_FIELDS,
+  ageFromBirthDate,
+  clientFormSchema,
+  emptyGuardian,
+  emptyReferenceContact,
+  toClientFormFieldValues,
+  type ClientFormFieldValues,
+} from './clientForm';
+
+const NOON_IN_SAO_PAULO = new Date('2026-10-02T15:00:00Z');
+
+function values(overrides: Partial<ClientFormFieldValues> = {}): ClientFormFieldValues {
+  return { ...toClientFormFieldValues(), fullName: 'Maria Souza', ...overrides };
+}
+
+function guardian(overrides: Partial<ReturnType<typeof emptyGuardian>> = {}) {
+  return { ...emptyGuardian(), name: 'Ana Souza', relationship: 'Mãe', ...overrides };
+}
+
+function reference(overrides: Partial<ReturnType<typeof emptyReferenceContact>> = {}) {
+  return {
+    ...emptyReferenceContact(),
+    name: 'Carlos Lima',
+    relationship: 'Tio',
+    purposes: ['emergency'],
+    ...overrides,
+  };
+}
+
+function issuesOf(input: ClientFormFieldValues): Record<string, string> {
+  const result = clientFormSchema.safeParse(input);
+  const firstMessageByPath: Record<string, string> = {};
+  if (result.success) return firstMessageByPath;
+
+  for (const issue of result.error.issues) {
+    firstMessageByPath[issue.path.join('.')] ??= issue.message;
+  }
+  return firstMessageByPath;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ now: NOON_IN_SAO_PAULO, toFake: ['Date'] });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('clientFormSchema', () => {
+  it('accepts a person described only by the full name', () => {
+    const result = clientFormSchema.safeParse(values());
+
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({
+      fullName: 'Maria Souza',
+      birthDate: null,
+      phone: null,
+      email: null,
+      cpf: null,
+      administrativeNotes: null,
+      guardians: [],
+      referenceContacts: [],
+    });
+  });
+
+  it('trims and normalizes every field to the shape the backend takes', () => {
+    const result = clientFormSchema.safeParse(
+      values({
+        fullName: '  Maria Souza  ',
+        birthDate: '20/05/1990',
+        phone: '  (11) 99999-0000 ',
+        email: '  Maria.Souza@Example.COM ',
+        cpf: '529.982.247-25',
+        administrativeNotes: '  Prefere contato pela manhã.  ',
+        guardians: [
+          guardian({ name: ' Ana Souza ', phone: ' 11 98888-0000', cpf: '123.456.789-09' }),
+        ],
+        referenceContacts: [reference({ purposes: ['emergency', 'dailyCommunication'] })],
+      }),
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.data).toEqual({
+      fullName: 'Maria Souza',
+      birthDate: '1990-05-20',
+      phone: '(11) 99999-0000',
+      email: 'maria.souza@example.com',
+      cpf: '52998224725',
+      administrativeNotes: 'Prefere contato pela manhã.',
+      guardians: [
+        { name: 'Ana Souza', relationship: 'Mãe', phone: '11 98888-0000', cpf: '12345678909' },
+      ],
+      referenceContacts: [
+        {
+          name: 'Carlos Lima',
+          relationship: 'Tio',
+          phone: null,
+          purposes: ['emergency', 'dailyCommunication'],
+        },
+      ],
+    });
+  });
+
+  it('turns blank optional fields into null', () => {
+    const result = clientFormSchema.safeParse(
+      values({ birthDate: '  ', phone: '   ', email: '  ', cpf: ' ', administrativeNotes: '   ' }),
+    );
+
+    expect(result.data).toMatchObject({
+      birthDate: null,
+      phone: null,
+      email: null,
+      cpf: null,
+      administrativeNotes: null,
+    });
+  });
+
+  describe('full name', () => {
+    it('is required', () => {
+      expect(issuesOf(values({ fullName: '   ' }))['fullName']).toBe(
+        'O nome completo é obrigatório.',
+      );
+    });
+
+    it('needs at least two characters after trimming', () => {
+      expect(issuesOf(values({ fullName: ' A ' }))['fullName']).toBe(
+        'O nome completo deve ter pelo menos 2 caracteres.',
+      );
+    });
+
+    it('allows up to 150 characters after trimming', () => {
+      expect(issuesOf(values({ fullName: ` ${'a'.repeat(150)} ` }))).toEqual({});
+      expect(issuesOf(values({ fullName: 'a'.repeat(151) }))['fullName']).toBe(
+        'O nome completo deve ter no máximo 150 caracteres.',
+      );
+    });
+  });
+
+  describe('birth date', () => {
+    it.each([
+      ['10/03', 'Informe uma data válida no formato dd/mm/aaaa.'],
+      ['31/02/2020', 'Informe uma data válida no formato dd/mm/aaaa.'],
+      ['02/10/2026', 'A data de nascimento deve estar no passado.'],
+      ['03/10/2026', 'A data de nascimento deve estar no passado.'],
+      ['01/01/2030', 'A data de nascimento deve estar no passado.'],
+      ['02/10/1905', 'A data de nascimento não pode indicar idade superior a 120 anos.'],
+    ] as const)('rejects %j', (birthDate, message) => {
+      expect(issuesOf(values({ birthDate, guardians: [guardian()] }))['birthDate']).toBe(message);
+    });
+
+    it('accepts a date in the past within 120 years', () => {
+      expect(issuesOf(values({ birthDate: '01/10/2026', guardians: [guardian()] }))).toEqual({});
+      expect(issuesOf(values({ birthDate: '02/10/1906' }))).toEqual({});
+    });
+  });
+
+  describe('guardian required for minors', () => {
+    it('does not ask anything when there is no birth date', () => {
+      expect(issuesOf(values({ birthDate: '', guardians: [] }))).toEqual({});
+    });
+
+    it('requires a guardian when the birth date indicates a minor', () => {
+      expect(issuesOf(values({ birthDate: '10/03/2015', guardians: [] }))['guardians']).toBe(
+        'Informe ao menos um responsável para pessoas menores de 18 anos.',
+      );
+    });
+
+    it('is satisfied by a guardian', () => {
+      expect(issuesOf(values({ birthDate: '10/03/2015', guardians: [guardian()] }))).toEqual({});
+    });
+
+    it('is not required for adults, including on the eighteenth birthday', () => {
+      expect(issuesOf(values({ birthDate: '20/05/1990', guardians: [] }))).toEqual({});
+      expect(issuesOf(values({ birthDate: '02/10/2008', guardians: [] }))).toEqual({});
+    });
+
+    it('still requires one the day before the eighteenth birthday', () => {
+      expect(
+        issuesOf(values({ birthDate: '03/10/2008', guardians: [] }))['guardians'],
+      ).toBeDefined();
+    });
+
+    it('does not require one when the birth date itself is invalid', () => {
+      expect(
+        issuesOf(values({ birthDate: '01/01/2030', guardians: [] }))['guardians'],
+      ).toBeUndefined();
+    });
+
+    it('counts the São Paulo day, not the UTC day', () => {
+      vi.setSystemTime(new Date('2026-10-03T01:00:00Z'));
+
+      expect(
+        issuesOf(values({ birthDate: '03/10/2008', guardians: [] }))['guardians'],
+      ).toBeDefined();
+    });
+  });
+
+  describe('contact details', () => {
+    it('rejects an invalid phone', () => {
+      expect(issuesOf(values({ phone: 'telefone' }))['phone']).toContain(
+        'Informe um telefone válido',
+      );
+      expect(issuesOf(values({ phone: '1'.repeat(21) }))['phone']).toContain(
+        'Informe um telefone válido',
+      );
+    });
+
+    it('rejects an invalid e-mail', () => {
+      expect(issuesOf(values({ email: 'maria@example' }))['email']).toBe(
+        'Informe um e-mail válido.',
+      );
+    });
+
+    it('rejects an e-mail longer than 254 characters', () => {
+      expect(issuesOf(values({ email: `${'a'.repeat(250)}@example.com` }))['email']).toBe(
+        'O e-mail deve ter no máximo 254 caracteres.',
+      );
+    });
+
+    it('rejects an invalid CPF', () => {
+      expect(issuesOf(values({ cpf: '529.982.247-24' }))['cpf']).toBe('Informe um CPF válido.');
+    });
+
+    it('limits the administrative notes to 500 characters', () => {
+      expect(issuesOf(values({ administrativeNotes: 'n'.repeat(500) }))).toEqual({});
+      expect(
+        issuesOf(values({ administrativeNotes: 'n'.repeat(501) }))['administrativeNotes'],
+      ).toBe('As observações administrativas devem ter no máximo 500 caracteres.');
+    });
+  });
+
+  describe('linked contacts', () => {
+    it('reports guardian problems on the guardian field', () => {
+      const issues = issuesOf(
+        values({
+          guardians: [
+            guardian(),
+            guardian({ name: '', relationship: '', phone: 'tel', cpf: '123' }),
+          ],
+        }),
+      );
+
+      expect(issues['guardians.1.name']).toBe('O nome do responsável é obrigatório.');
+      expect(issues['guardians.1.relationship']).toBe('O vínculo do responsável é obrigatório.');
+      expect(issues['guardians.1.phone']).toContain('Informe um telefone válido');
+      expect(issues['guardians.1.cpf']).toBe('Informe um CPF válido.');
+      expect(Object.keys(issues).some((path) => path.startsWith('guardians.0'))).toBe(false);
+    });
+
+    it('requires at least one purpose on a reference contact', () => {
+      const issues = issuesOf(values({ referenceContacts: [reference({ purposes: [] })] }));
+
+      expect(issues['referenceContacts.0.purposes']).toBe(
+        'Informe ao menos uma finalidade para a pessoa de referência.',
+      );
+    });
+
+    it('reports reference contact problems on the contact field', () => {
+      const issues = issuesOf(
+        values({ referenceContacts: [reference({ name: ' ', relationship: ' ', phone: 'tel' })] }),
+      );
+
+      expect(issues['referenceContacts.0.name']).toBe(
+        'O nome da pessoa de referência é obrigatório.',
+      );
+      expect(issues['referenceContacts.0.relationship']).toBe(
+        'O vínculo da pessoa de referência é obrigatório.',
+      );
+      expect(issues['referenceContacts.0.phone']).toContain('Informe um telefone válido');
+    });
+
+    it('limits how many contacts can be added', () => {
+      const issues = issuesOf(
+        values({
+          guardians: Array.from({ length: 11 }, () => guardian()),
+          referenceContacts: Array.from({ length: 11 }, () => reference()),
+        }),
+      );
+
+      expect(issues['guardians']).toBe('Informe no máximo 10 responsáveis.');
+      expect(issues['referenceContacts']).toBe('Informe no máximo 10 pessoas de referência.');
+    });
+  });
+});
+
+describe('ageFromBirthDate', () => {
+  it.each([
+    ['10/03/2015', 11],
+    ['03/10/2008', 17],
+    ['02/10/2008', 18],
+    ['20/05/1990', 36],
+    ['01/10/2026', 0],
+    ['02/10/1906', 120],
+  ] as const)('reads %j as %i years old today', (birthDate, expected) => {
+    expect(ageFromBirthDate(birthDate)).toBe(expected);
+  });
+
+  it.each(['', '10/03', '31/02/2020', '02/10/2026', '01/01/2030', '02/10/1905'])(
+    'has no age for %j',
+    (birthDate) => {
+      expect(ageFromBirthDate(birthDate)).toBeNull();
+    },
+  );
+});
+
+describe('form field lists', () => {
+  it('names every field the backend can report on', () => {
+    expect(CLIENT_FORM_FIELDS).toEqual([
+      'fullName',
+      'birthDate',
+      'phone',
+      'email',
+      'cpf',
+      'administrativeNotes',
+      'guardians',
+      'referenceContacts',
+    ]);
+    expect(GUARDIAN_FORM_FIELDS).toEqual(['name', 'relationship', 'phone', 'cpf']);
+    expect(REFERENCE_CONTACT_FORM_FIELDS).toEqual(['name', 'relationship', 'phone', 'purposes']);
+  });
+
+  it('starts empty so nothing is asked up front', () => {
+    expect(toClientFormFieldValues()).toEqual({
+      fullName: '',
+      birthDate: '',
+      phone: '',
+      email: '',
+      cpf: '',
+      administrativeNotes: '',
+      guardians: [],
+      referenceContacts: [],
+    });
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
new file mode 100644
index 00000000..3e54fbcc
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { todayInSaoPaulo } from '@/shared/format/date';
+import {
+  ADULT_AGE_IN_YEARS,
+  MAX_AGE_IN_YEARS,
+  calculateAge,
+  isInThePast,
+  isMinorOn,
+  isWithinMaxAge,
+  parseBirthDate,
+} from './birthDate';
+import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH, isValidEmail, isValidPhone } from './contactFormats';
+import { isValidCpf, stripCpfMask } from './cpf';
+
+// Mirrors the backend limits (ServicesService.Domain.Entities.Client / ClientContact). UX pre-check
+// only - the backend response stays the source of truth.
+export const CLIENT_NAME_MIN_LENGTH = 2;
+export const CLIENT_NAME_MAX_LENGTH = 150;
+export const CLIENT_NOTES_MAX_LENGTH = 500;
+export const CONTACT_RELATIONSHIP_MAX_LENGTH = 60;
+export const MAX_GUARDIANS = 10;
+export const MAX_REFERENCE_CONTACTS = 10;
+
+const nameField = (subject: string) =>
+  z
+    .string()
+    .trim()
+    .min(1, `O nome ${subject} é obrigatório.`)
+    .min(
+      CLIENT_NAME_MIN_LENGTH,
+      `O nome ${subject} deve ter pelo menos ${CLIENT_NAME_MIN_LENGTH} caracteres.`,
+    )
+    .max(
+      CLIENT_NAME_MAX_LENGTH,
+      `O nome ${subject} deve ter no máximo ${CLIENT_NAME_MAX_LENGTH} caracteres.`,
+    );
+
+const relationshipField = (subject: string) =>
+  z
+    .string()
+    .trim()
+    .min(1, `O vínculo ${subject} é obrigatório.`)
+    .max(
+      CONTACT_RELATIONSHIP_MAX_LENGTH,
+      `O vínculo ${subject} deve ter no máximo ${CONTACT_RELATIONSHIP_MAX_LENGTH} caracteres.`,
+    );
+
+const phoneField = z
+  .string()
+  .trim()
+  .refine(
+    (value) => value === '' || isValidPhone(value),
+    `Informe um telefone válido, com até ${PHONE_MAX_LENGTH} caracteres entre dígitos, espaços, +, parênteses e hífen.`,
+  )
+  .transform((value) => value || null);
+
+const cpfField = z
+  .string()
+  .trim()
+  .refine((value) => value === '' || isValidCpf(value), 'Informe um CPF válido.')
+  .transform((value) => (value ? stripCpfMask(value) : null));
+
+const emailField = z
+  .string()
+  .trim()
+  .toLowerCase()
+  .max(EMAIL_MAX_LENGTH, `O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`)
+  .refine((value) => value === '' || isValidEmail(value), 'Informe um e-mail válido.')
+  .transform((value) => value || null);
+
+const birthDateField = z.string().transform((value, ctx) => {
+  if (value.trim() === '') return null;
+
+  const fail = (message: string) => {
+    ctx.addIssue({ code: 'custom', message });
+    return z.NEVER;
+  };
+
+  const birthDate = parseBirthDate(value);
+  if (birthDate === null) return fail('Informe uma data válida no formato dd/mm/aaaa.');
+
+  const today = todayInSaoPaulo();
+  if (!isInThePast(birthDate, today)) return fail('A data de nascimento deve estar no passado.');
+  if (!isWithinMaxAge(birthDate, today)) {
+    return fail(`A data de nascimento não pode indicar idade superior a ${MAX_AGE_IN_YEARS} anos.`);
+  }
+
+  return birthDate;
+});
+
+const guardianSchema = z.object({
+  name: nameField('do responsável'),
+  relationship: relationshipField('do responsável'),
+  phone: phoneField,
+  cpf: cpfField,
+});
+
+const referenceContactSchema = z.object({
+  name: nameField('da pessoa de referência'),
+  relationship: relationshipField('da pessoa de referência'),
+  phone: phoneField,
+  purposes: z
+    .array(z.string())
+    .min(1, 'Informe ao menos uma finalidade para a pessoa de referência.'),
+});
+
+const clientFormObject = z.object({
+  fullName: nameField('completo'),
+  birthDate: birthDateField,
+  phone: phoneField,
+  email: emailField,
+  cpf: cpfField,
+  administrativeNotes: z
+    .string()
+    .trim()
+    .max(
+      CLIENT_NOTES_MAX_LENGTH,
+      `As observações administrativas devem ter no máximo ${CLIENT_NOTES_MAX_LENGTH} caracteres.`,
+    )
+    .transform((value) => value || null),
+  guardians: z
+    .array(guardianSchema)
+    .max(MAX_GUARDIANS, `Informe no máximo ${MAX_GUARDIANS} responsáveis.`),
+  referenceContacts: z
+    .array(referenceContactSchema)
+    .max(
+      MAX_REFERENCE_CONTACTS,
+      `Informe no máximo ${MAX_REFERENCE_CONTACTS} pessoas de referência.`,
+    ),
+});
+
+export const clientFormSchema = clientFormObject.superRefine((value, ctx) => {
+  if (
+    value.birthDate &&
+    isMinorOn(value.birthDate, todayInSaoPaulo()) &&
+    value.guardians.length === 0
+  ) {
+    ctx.addIssue({
+      code: 'custom',
+      path: ['guardians'],
+      message: `Informe ao menos um responsável para pessoas menores de ${ADULT_AGE_IN_YEARS} anos.`,
+    });
+  }
+});
+
+export type ClientFormFieldValues = z.input<typeof clientFormSchema>;
+export type ClientFormValues = z.output<typeof clientFormSchema>;
+export type GuardianFormFieldValues = ClientFormFieldValues['guardians'][number];
+export type ReferenceContactFormFieldValues = ClientFormFieldValues['referenceContacts'][number];
+
+export const CLIENT_FORM_FIELDS = clientFormObject.keyof().options;
+export const GUARDIAN_FORM_FIELDS = guardianSchema.keyof().options;
+export const REFERENCE_CONTACT_FORM_FIELDS = referenceContactSchema.keyof().options;
+
+export function toClientFormFieldValues(): ClientFormFieldValues {
+  return {
+    fullName: '',
+    birthDate: '',
+    phone: '',
+    email: '',
+    cpf: '',
+    administrativeNotes: '',
+    guardians: [],
+    referenceContacts: [],
+  };
+}
+
+export function emptyGuardian(): GuardianFormFieldValues {
+  return { name: '', relationship: '', phone: '', cpf: '' };
+}
+
+export function emptyReferenceContact(): ReferenceContactFormFieldValues {
+  return { name: '', relationship: '', phone: '', purposes: [] };
+}
+
+export function ageFromBirthDate(masked: string): number | null {
+  const birthDate = parseBirthDate(masked);
+  const today = todayInSaoPaulo();
+  if (birthDate === null || !isInThePast(birthDate, today) || !isWithinMaxAge(birthDate, today)) {
+    return null;
+  }
+
+  return calculateAge(birthDate, today);
+}
diff --git a/apps/admin-frontend/src/features/clients/model/contactFormats.test.ts b/apps/admin-frontend/src/features/clients/model/contactFormats.test.ts
new file mode 100644
index 00000000..54751921
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/contactFormats.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { isValidEmail, isValidPhone } from './contactFormats';
+
+describe('isValidPhone', () => {
+  it.each([
+    '11999990000',
+    '(11) 99999-0000',
+    '+55 (11) 99999-0000',
+    '11 9999-0000',
+    '1'.repeat(20),
+  ])('accepts %j', (phone) => {
+    expect(isValidPhone(phone)).toBe(true);
+  });
+
+  it.each([
+    '',
+    '1'.repeat(21),
+    '(11) 99999-0000 ramal 12',
+    '11.99999.0000',
+    '11/99999',
+    'telefone',
+    '+-() ',
+    '---',
+  ])('rejects %j', (phone) => {
+    expect(isValidPhone(phone)).toBe(false);
+  });
+});
+
+describe('isValidEmail', () => {
+  it.each(['maria@example.com', 'maria.souza+agenda@mail.example.com.br', 'a@b.co'])(
+    'accepts %j',
+    (email) => {
+      expect(isValidEmail(email)).toBe(true);
+    },
+  );
+
+  it.each([
+    '',
+    'maria',
+    'maria@',
+    '@example.com',
+    'maria@example',
+    'maria@@example.com',
+    'maria@example..com',
+    'maria@.example.com',
+    'maria@example.com.',
+    'maria souza@example.com',
+    `${'a'.repeat(250)}@example.com`,
+  ])('rejects %j', (email) => {
+    expect(isValidEmail(email)).toBe(false);
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/model/contactFormats.ts b/apps/admin-frontend/src/features/clients/model/contactFormats.ts
new file mode 100644
index 00000000..1f36492c
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/contactFormats.ts
@@ -0,0 +1,17 @@
+export const PHONE_MAX_LENGTH = 20;
+export const EMAIL_MAX_LENGTH = 254;
+
+export function isValidPhone(value: string): boolean {
+  return value.length <= PHONE_MAX_LENGTH && /\d/.test(value) && /^[\d +()-]+$/.test(value);
+}
+
+export function isValidEmail(value: string): boolean {
+  if (value.length > EMAIL_MAX_LENGTH || /\s/.test(value)) return false;
+
+  const parts = value.split('@');
+  if (parts.length !== 2) return false;
+
+  const [local = '', domain = ''] = parts;
+  const labels = domain.split('.');
+  return local.length > 0 && labels.length >= 2 && labels.every((label) => label.length > 0);
+}
diff --git a/apps/admin-frontend/src/features/clients/model/cpf.test.ts b/apps/admin-frontend/src/features/clients/model/cpf.test.ts
new file mode 100644
index 00000000..c38d698c
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/cpf.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { formatCpf, isValidCpf, stripCpfMask } from './cpf';
+
+describe('isValidCpf', () => {
+  it.each([
+    '529.982.247-25',
+    '52998224725',
+    ' 529.982.247-25 ',
+    '123.456.789-09',
+    '111.444.777-35',
+  ])('accepts %s', (cpf) => {
+    expect(isValidCpf(cpf)).toBe(true);
+  });
+
+  it.each([
+    '',
+    '529.982.247-24',
+    '529.982.247-52',
+    '123.456.789-00',
+    '5299822472',
+    '529982247255',
+    '000.000.000-00',
+    '111.111.111-11',
+    '999.999.999-99',
+    'abc.def.ghi-jk',
+    '529.982.247-2a',
+  ])('rejects %j', (cpf) => {
+    expect(isValidCpf(cpf)).toBe(false);
+  });
+});
+
+describe('stripCpfMask', () => {
+  it('removes dots, hyphens and spaces only', () => {
+    expect(stripCpfMask(' 529.982.247-25 ')).toBe('52998224725');
+    expect(stripCpfMask('529 982 247 25')).toBe('52998224725');
+  });
+});
+
+describe('formatCpf', () => {
+  it.each([
+    ['', ''],
+    ['5', '5'],
+    ['529', '529'],
+    ['5299', '529.9'],
+    ['529982', '529.982'],
+    ['5299822', '529.982.2'],
+    ['529982247', '529.982.247'],
+    ['5299822472', '529.982.247-2'],
+    ['52998224725', '529.982.247-25'],
+    ['529982247259999', '529.982.247-25'],
+    ['529.982.247-25', '529.982.247-25'],
+    ['abc529x', '529'],
+  ] as const)('formats %j as %j while typing', (typed, expected) => {
+    expect(formatCpf(typed)).toBe(expected);
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/model/cpf.ts b/apps/admin-frontend/src/features/clients/model/cpf.ts
new file mode 100644
index 00000000..57abdb4c
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/cpf.ts
@@ -0,0 +1,34 @@
+const CPF_LENGTH = 11;
+
+export function stripCpfMask(value: string): string {
+  return value.replace(/[.\-\s]/g, '');
+}
+
+export function isValidCpf(value: string): boolean {
+  const digits = stripCpfMask(value);
+  if (!/^\d{11}$/.test(digits) || /^(\d)\1{10}$/.test(digits)) return false;
+
+  return (
+    checkDigit(digits, 9) === Number(digits.charAt(9)) &&
+    checkDigit(digits, 10) === Number(digits.charAt(10))
+  );
+}
+
+export function formatCpf(value: string): string {
+  const digits = value.replace(/\D/g, '').slice(0, CPF_LENGTH);
+
+  if (digits.length <= 3) return digits;
+  if (digits.length <= 6) return `${digits.slice(0, 3)}.${digits.slice(3)}`;
+  if (digits.length <= 9) return `${digits.slice(0, 3)}.${digits.slice(3, 6)}.${digits.slice(6)}`;
+  return `${digits.slice(0, 3)}.${digits.slice(3, 6)}.${digits.slice(6, 9)}-${digits.slice(9)}`;
+}
+
+function checkDigit(digits: string, length: number): number {
+  let sum = 0;
+  for (let index = 0; index < length; index += 1) {
+    sum += Number(digits.charAt(index)) * (length + 1 - index);
+  }
+
+  const remainder = (sum * 10) % 11;
+  return remainder === 10 ? 0 : remainder;
+}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
new file mode 100644
index 00000000..0a33a147
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -0,0 +1,671 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen, waitFor, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter, Route, Routes, useLocation } from 'react-router';
+import { toast } from '@/shared/ui/toast';
+import type { ApiProblem } from '@/shared/api/servicesFacade';
+import type { Client } from '../../../model/client';
+import { ClientFormPage } from './ClientFormPage';
+
+const { mockCreate } = vi.hoisted(() => ({ mockCreate: vi.fn() }));
+
+vi.mock('../../../api/clientsRepository', () => ({
+  clientsRepository: { create: mockCreate },
+}));
+
+const EXISTING_ID = '0197f2a0-0000-7000-8000-000000000001';
+
+const CREATED: Client = {
+  id: '0197f2a0-0000-7000-8000-0000000000aa',
+  fullName: 'Maria Souza',
+  birthDate: null,
+  phone: null,
+  email: null,
+  cpf: null,
+  administrativeNotes: null,
+  status: 'active',
+  guardians: [],
+  referenceContacts: [],
+};
+
+function LocationProbe() {
+  const location = useLocation();
+  return <div data-testid="location">{location.pathname}</div>;
+}
+
+function renderPage() {
+  return render(
+    <MemoryRouter initialEntries={['/pessoas/nova']}>
+      <Routes>
+        <Route path="/pessoas/nova" element={<ClientFormPage />} />
+        <Route path="/pessoas" element={<h1>Lista de pessoas</h1>} />
+      </Routes>
+      <LocationProbe />
+    </MemoryRouter>,
+  );
+}
+
+function problem(overrides: Partial<ApiProblem>): { ok: false; error: ApiProblem } {
+  return {
+    ok: false,
+    error: { status: 400, title: 'Ocorreram erros de validação.', ...overrides },
+  };
+}
+
+function lastPayload() {
+  return mockCreate.mock.calls.at(-1)?.[0] as Record<string, unknown>;
+}
+
+describe('ClientFormPage', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.useFakeTimers({ now: new Date('2026-10-02T15:00:00Z'), toFake: ['Date'] });
+    mockCreate.mockResolvedValue({ ok: true, data: CREATED });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('layout', () => {
+    it('opens as a full page with the person fields and both contact sections', () => {
+      renderPage();
+
+      expect(screen.getByRole('heading', { name: 'Nova pessoa' })).toBeInTheDocument();
+      for (const label of [
+        'Nome completo',
+        'Data de nascimento',
+        'Telefone',
+        'E-mail',
+        'CPF',
+        'Observações administrativas',
+      ]) {
+        expect(screen.getByLabelText(label)).toBeInTheDocument();
+      }
+      expect(screen.getByRole('heading', { name: 'Responsáveis' })).toBeInTheDocument();
+      expect(screen.getByRole('heading', { name: 'Pessoas de referência' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Adicionar responsável' })).toBeInTheDocument();
+      expect(
+        screen.getByRole('button', { name: 'Adicionar pessoa de referência' }),
+      ).toBeInTheDocument();
+      expect(screen.getByRole('link', { name: 'Cancelar' })).toHaveAttribute('href', '/pessoas');
+      expect(screen.getByRole('link', { name: 'Voltar para Pessoas' })).toHaveAttribute(
+        'href',
+        '/pessoas',
+      );
+    });
+
+    it('warns that notes are administrative only', () => {
+      renderPage();
+
+      expect(screen.getByText(/Não registre prontuário, diagnóstico/)).toBeInTheDocument();
+    });
+
+    it('starts with no contacts and never asks whether the person is a minor', () => {
+      renderPage();
+
+      expect(screen.getByText('Nenhum responsável adicionado ainda.')).toBeInTheDocument();
+      expect(
+        screen.getByText('Nenhuma pessoa de referência adicionada ainda.'),
+      ).toBeInTheDocument();
+      expect(screen.queryByRole('status')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('registering an adult or a person without a birth date', () => {
+    it('saves a person described only by the name, then returns to the Pessoas area', async () => {
+      const user = userEvent.setup();
+      const toastAdd = vi.spyOn(toast, 'add');
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), '  Maria Souza  ');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(screen.getByTestId('location')).toHaveTextContent('/pessoas'));
+      expect(mockCreate).toHaveBeenCalledTimes(1);
+      expect(lastPayload()).toEqual({
+        fullName: 'Maria Souza',
+        birthDate: null,
+        phone: null,
+        email: null,
+        cpf: null,
+        administrativeNotes: null,
+        guardians: [],
+        referenceContacts: [],
+      });
+      expect(toastAdd).toHaveBeenCalledWith(
+        expect.objectContaining({ title: 'Pessoa cadastrada', type: 'success' }),
+      );
+      expect(await screen.findByRole('heading', { name: 'Lista de pessoas' })).toBeInTheDocument();
+    });
+
+    it('sends every field normalized: ISO birth date, CPF without mask, lowercase e-mail', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
+      await user.type(screen.getByLabelText('Telefone'), '(11) 99999-0000');
+      await user.type(screen.getByLabelText('E-mail'), 'Maria.Souza@Example.COM');
+      await user.type(screen.getByLabelText('CPF'), '52998224725');
+      await user.type(
+        screen.getByLabelText('Observações administrativas'),
+        'Prefere contato pela manhã.',
+      );
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
+      expect(lastPayload()).toEqual({
+        fullName: 'Maria Souza',
+        birthDate: '1990-05-20',
+        phone: '(11) 99999-0000',
+        email: 'maria.souza@example.com',
+        cpf: '52998224725',
+        administrativeNotes: 'Prefere contato pela manhã.',
+        guardians: [],
+        referenceContacts: [],
+      });
+    });
+
+    it('masks the CPF and the birth date while they are typed and shows the calculated age', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('CPF'), '52998224725');
+      await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
+
+      expect(screen.getByLabelText('CPF')).toHaveValue('529.982.247-25');
+      expect(screen.getByLabelText('Data de nascimento')).toHaveValue('20/05/1990');
+      expect(screen.getByText('36 anos')).toBeInTheDocument();
+    });
+
+    it('does not demand a guardian for an adult', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.type(screen.getByLabelText('Data de nascimento'), '02102008');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
+      expect(screen.queryByRole('status')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('local validation', () => {
+    it('blocks the submit and explains the missing name', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(await screen.findByText('O nome completo é obrigatório.')).toBeInTheDocument();
+      expect(screen.getByLabelText('Nome completo')).toHaveAttribute('aria-invalid', 'true');
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+
+    it('keeps what was typed while reporting field errors in pt-BR', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.type(screen.getByLabelText('Telefone'), 'telefone');
+      await user.type(screen.getByLabelText('E-mail'), 'maria@example');
+      await user.type(screen.getByLabelText('CPF'), '52998224724');
+      await user.type(screen.getByLabelText('Data de nascimento'), '31022020');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(await screen.findByText('Informe um e-mail válido.')).toBeInTheDocument();
+      expect(screen.getByText('Informe um CPF válido.')).toBeInTheDocument();
+      expect(screen.getByText(/Informe um telefone válido/)).toBeInTheDocument();
+      expect(
+        screen.getByText('Informe uma data válida no formato dd/mm/aaaa.'),
+      ).toBeInTheDocument();
+      expect(screen.getByLabelText('Nome completo')).toHaveValue('Maria Souza');
+      expect(screen.getByLabelText('E-mail')).toHaveValue('maria@example');
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+
+    it.each([
+      ['02102026', 'A data de nascimento deve estar no passado.'],
+      ['01011905', 'A data de nascimento não pode indicar idade superior a 120 anos.'],
+    ])('rejects the birth date %s', async (digits, message) => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.type(screen.getByLabelText('Data de nascimento'), digits);
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(await screen.findByText(message)).toBeInTheDocument();
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('minors and their guardians', () => {
+    it('says a guardian is needed as soon as the birth date indicates a minor', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Data de nascimento'), '10032015');
+
+      expect(screen.getByRole('status')).toHaveTextContent(
+        'Esta pessoa tem menos de 18 anos. Informe ao menos um responsável.',
+      );
+    });
+
+    it('refuses to save a minor without a guardian and keeps the form', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Joana Souza');
+      await user.type(screen.getByLabelText('Data de nascimento'), '10032015');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(await screen.findByRole('alert')).toHaveTextContent(
+        'Informe ao menos um responsável para pessoas menores de 18 anos.',
+      );
+      expect(mockCreate).not.toHaveBeenCalled();
+      expect(screen.getByLabelText('Nome completo')).toHaveValue('Joana Souza');
+    });
+
+    it('moves focus to the way out of the problem when only the guardian is missing', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Joana Souza');
+      await user.type(screen.getByLabelText('Data de nascimento'), '10032015');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await screen.findByRole('alert');
+      expect(screen.getByRole('button', { name: 'Adicionar responsável' })).toHaveFocus();
+    });
+
+    it('keeps focus on the first invalid field when something else is wrong too', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Data de nascimento'), '10032015');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await screen.findByText('O nome completo é obrigatório.');
+      expect(screen.getByLabelText('Nome completo')).toHaveFocus();
+    });
+
+    it('stops offering more guardians at the limit', async () => {
+      const user = userEvent.setup();
+      renderPage();
+      const add = screen.getByRole('button', { name: 'Adicionar responsável' });
+
+      for (let count = 0; count < 10; count += 1) await user.click(add);
+
+      expect(screen.getAllByRole('group', { name: /^Responsável \d+$/ })).toHaveLength(10);
+      expect(add).toBeDisabled();
+    });
+
+    it('saves a minor once a valid guardian is informed', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Joana Souza');
+      await user.type(screen.getByLabelText('Data de nascimento'), '10032015');
+      await user.click(screen.getByRole('button', { name: 'Adicionar responsável' }));
+
+      const guardian = within(screen.getByRole('group', { name: 'Responsável 1' }));
+      await user.type(guardian.getByLabelText('Nome'), 'Ana Souza');
+      await user.type(guardian.getByLabelText('Vínculo'), 'Mãe');
+      await user.type(guardian.getByLabelText('Telefone'), '11 98888-0000');
+      await user.type(guardian.getByLabelText('CPF'), '12345678909');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
+      expect(lastPayload()).toMatchObject({
+        birthDate: '2015-03-10',
+        guardians: [
+          { name: 'Ana Souza', relationship: 'Mãe', phone: '11 98888-0000', cpf: '12345678909' },
+        ],
+      });
+      expect(screen.queryByRole('status')).not.toBeInTheDocument();
+    });
+
+    it('reports a guardian missing name and relationship on that guardian', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Joana Souza');
+      await user.click(screen.getByRole('button', { name: 'Adicionar responsável' }));
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      const guardian = within(await screen.findByRole('group', { name: 'Responsável 1' }));
+      expect(await guardian.findByText('O nome do responsável é obrigatório.')).toBeInTheDocument();
+      expect(guardian.getByText('O vínculo do responsável é obrigatório.')).toBeInTheDocument();
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+
+    it('lets a guardian be removed from the form', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.click(screen.getByRole('button', { name: 'Adicionar responsável' }));
+      await user.click(screen.getByRole('button', { name: 'Adicionar responsável' }));
+      expect(screen.getAllByRole('group', { name: /^Responsável \d$/ })).toHaveLength(2);
+
+      await user.click(screen.getByRole('button', { name: 'Remover responsável 1' }));
+
+      expect(screen.getAllByRole('group', { name: /^Responsável \d$/ })).toHaveLength(1);
+      await user.click(screen.getByRole('button', { name: 'Remover responsável 1' }));
+      expect(screen.getByText('Nenhum responsável adicionado ainda.')).toBeInTheDocument();
+
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+      await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
+      expect(lastPayload()).toMatchObject({ guardians: [] });
+    });
+  });
+
+  describe('reference contacts', () => {
+    async function addReferenceContact(user: ReturnType<typeof userEvent.setup>) {
+      await user.click(screen.getByRole('button', { name: 'Adicionar pessoa de referência' }));
+      return within(screen.getByRole('group', { name: 'Pessoa de referência 1' }));
+    }
+
+    it('requires at least one purpose', async () => {
+      const user = userEvent.setup();
+      renderPage();
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      const contact = await addReferenceContact(user);
+      await user.type(contact.getByLabelText('Nome'), 'Carlos Lima');
+      await user.type(contact.getByLabelText('Vínculo'), 'Tio');
+
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(
+        await contact.findByText('Informe ao menos uma finalidade para a pessoa de referência.'),
+      ).toBeInTheDocument();
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+
+    it('offers the three purposes and sends the chosen ones', async () => {
+      const user = userEvent.setup();
+      renderPage();
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      const contact = await addReferenceContact(user);
+      await user.type(contact.getByLabelText('Nome'), 'Carlos Lima');
+      await user.type(contact.getByLabelText('Vínculo'), 'Tio');
+      await user.type(contact.getByLabelText('Telefone'), '11 4000-1000');
+
+      expect(
+        contact.getAllByRole('checkbox').map((box) => box.getAttribute('aria-checked')),
+      ).toEqual(['false', 'false', 'false']);
+      await user.click(contact.getByRole('checkbox', { name: 'Emergência' }));
+      await user.click(contact.getByRole('checkbox', { name: 'Comunicação cotidiana' }));
+      expect(contact.getByRole('checkbox', { name: 'Apoio operacional' })).not.toBeChecked();
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
+      expect(lastPayload()).toMatchObject({
+        guardians: [],
+        referenceContacts: [
+          {
+            name: 'Carlos Lima',
+            relationship: 'Tio',
+            phone: '11 4000-1000',
+            purposes: ['emergency', 'dailyCommunication'],
+          },
+        ],
+      });
+    });
+
+    it('keeps the contact separate from the person: it never becomes a guardian', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await addReferenceContact(user);
+
+      expect(screen.getByText('Nenhum responsável adicionado ainda.')).toBeInTheDocument();
+      expect(screen.queryByRole('group', { name: 'Responsável 1' })).not.toBeInTheDocument();
+    });
+
+    it('lets a reference contact be removed', async () => {
+      const user = userEvent.setup();
+      renderPage();
+      await addReferenceContact(user);
+
+      await user.click(screen.getByRole('button', { name: 'Remover pessoa de referência 1' }));
+
+      expect(
+        screen.getByText('Nenhuma pessoa de referência adicionada ainda.'),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('backend responses', () => {
+    async function fillAndSubmit(user: ReturnType<typeof userEvent.setup>) {
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.type(screen.getByLabelText('CPF'), '52998224725');
+      await user.type(screen.getByLabelText('E-mail'), 'maria@example.com');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+    }
+
+    it('shows the duplicate CPF message on the CPF field, focuses it and offers the existing record', async () => {
+      const user = userEvent.setup();
+      mockCreate.mockResolvedValue(
+        problem({
+          status: 409,
+          code: 'Client.DuplicateCpf',
+          title: 'Já existe uma pessoa cadastrada com este CPF.',
+          errors: {
+            Cpf: [
+              {
+                code: 'Client.DuplicateCpf',
+                message: 'Já existe uma pessoa cadastrada com este CPF.',
+                meta: { clientId: EXISTING_ID },
+              },
+            ],
+          },
+        }),
+      );
+      renderPage();
+
+      await fillAndSubmit(user);
+
+      expect(
+        await screen.findByText('Já existe uma pessoa cadastrada com este CPF.'),
+      ).toBeInTheDocument();
+      expect(screen.getByLabelText('CPF')).toHaveAttribute('aria-invalid', 'true');
+      await waitFor(() => expect(screen.getByLabelText('CPF')).toHaveFocus());
+      const link = screen.getByRole('link', { name: /Abrir cadastro existente/ });
+      expect(link).toHaveAttribute('href', `/pessoas/${EXISTING_ID}`);
+      expect(link).toHaveAttribute('target', '_blank');
+      expect(screen.getByLabelText('Nome completo')).toHaveValue('Maria Souza');
+      expect(screen.getByLabelText('E-mail')).toHaveValue('maria@example.com');
+      expect(screen.getByTestId('location')).toHaveTextContent('/pessoas/nova');
+    });
+
+    it('stops offering the existing record once the CPF is changed', async () => {
+      const user = userEvent.setup();
+      mockCreate.mockResolvedValue(
+        problem({
+          status: 409,
+          code: 'Client.DuplicateCpf',
+          errors: {
+            Cpf: [
+              {
+                code: 'Client.DuplicateCpf',
+                message: 'Já existe uma pessoa cadastrada com este CPF.',
+                meta: { clientId: EXISTING_ID },
+              },
+            ],
+          },
+        }),
+      );
+      renderPage();
+      await fillAndSubmit(user);
+      await screen.findByRole('link', { name: /Abrir cadastro existente/ });
+
+      await user.type(screen.getByLabelText('CPF'), '{Backspace}');
+
+      expect(
+        screen.queryByRole('link', { name: /Abrir cadastro existente/ }),
+      ).not.toBeInTheDocument();
+    });
+
+    it('explains a CPF that belongs to a deleted record, with nothing to open', async () => {
+      const user = userEvent.setup();
+      mockCreate.mockResolvedValue(
+        problem({
+          status: 409,
+          code: 'Client.DuplicateCpf',
+          errors: {
+            Cpf: [
+              {
+                code: 'Client.DuplicateCpf',
+                message:
+                  'Este CPF pertence a um cadastro excluído e não pode ser usado em um novo cadastro.',
+              },
+            ],
+          },
+        }),
+      );
+      renderPage();
+
+      await fillAndSubmit(user);
+
+      expect(await screen.findByText(/pertence a um cadastro excluído/)).toBeInTheDocument();
+      expect(
+        screen.queryByRole('link', { name: /Abrir cadastro existente/ }),
+      ).not.toBeInTheDocument();
+    });
+
+    it('shows a duplicate e-mail on the e-mail field and keeps everything typed', async () => {
+      const user = userEvent.setup();
+      mockCreate.mockResolvedValue(
+        problem({
+          status: 409,
+          code: 'Client.DuplicateEmail',
+          errors: {
+            Email: [
+              {
+                code: 'Client.DuplicateEmail',
+                message: 'Já existe uma pessoa ativa cadastrada com este e-mail.',
+              },
+            ],
+          },
+        }),
+      );
+      renderPage();
+
+      await fillAndSubmit(user);
+
+      expect(
+        await screen.findByText('Já existe uma pessoa ativa cadastrada com este e-mail.'),
+      ).toBeInTheDocument();
+      expect(screen.getByLabelText('E-mail')).toHaveAttribute('aria-invalid', 'true');
+      expect(screen.getByLabelText('CPF')).toHaveValue('529.982.247-25');
+    });
+
+    it('maps indexed backend errors to the matching contact field', async () => {
+      const user = userEvent.setup();
+      mockCreate.mockResolvedValue(
+        problem({
+          code: 'Validation.Failed',
+          errors: {
+            'Guardians[0].Name': [{ message: 'O nome do responsável é obrigatório.' }],
+            'ReferenceContacts[0].Purposes': [{ message: 'Informe ao menos uma finalidade.' }],
+          },
+        }),
+      );
+      renderPage();
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.click(screen.getByRole('button', { name: 'Adicionar responsável' }));
+      const guardian = within(screen.getByRole('group', { name: 'Responsável 1' }));
+      await user.type(guardian.getByLabelText('Nome'), 'Ana');
+      await user.type(guardian.getByLabelText('Vínculo'), 'Mãe');
+      await user.click(screen.getByRole('button', { name: 'Adicionar pessoa de referência' }));
+      const contact = within(screen.getByRole('group', { name: 'Pessoa de referência 1' }));
+      await user.type(contact.getByLabelText('Nome'), 'Carlos');
+      await user.type(contact.getByLabelText('Vínculo'), 'Tio');
+      await user.click(contact.getByRole('checkbox', { name: 'Emergência' }));
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(await guardian.findByText('O nome do responsável é obrigatório.')).toBeInTheDocument();
+      expect(guardian.getByLabelText('Nome')).toHaveAttribute('aria-invalid', 'true');
+      expect(contact.getByText('Informe ao menos uma finalidade.')).toBeInTheDocument();
+      expect(guardian.getByLabelText('Nome')).toHaveValue('Ana');
+    });
+
+    it('shows an error with no field in a banner and keeps the form', async () => {
+      const user = userEvent.setup();
+      mockCreate.mockResolvedValue(
+        problem({
+          status: 0,
+          code: 'Network.Unreachable',
+          title: 'Sem conexão com o servidor. Tente novamente.',
+        }),
+      );
+      renderPage();
+
+      await fillAndSubmit(user);
+
+      const banner = await screen.findByRole('alert');
+      expect(banner).toHaveTextContent('Sem conexão com o servidor. Tente novamente.');
+      expect(
+        banner.compareDocumentPosition(screen.getByRole('button', { name: 'Salvar' })) &
+          Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+      expect(
+        screen
+          .getByRole('heading', { name: 'Pessoas de referência' })
+          .compareDocumentPosition(banner) & Node.DOCUMENT_POSITION_FOLLOWING,
+      ).toBeTruthy();
+      expect(screen.getByLabelText('Nome completo')).toHaveValue('Maria Souza');
+      expect(screen.getByTestId('location')).toHaveTextContent('/pessoas/nova');
+    });
+
+    it('can be submitted again after fixing the problem', async () => {
+      const user = userEvent.setup();
+      mockCreate.mockResolvedValueOnce(
+        problem({
+          status: 409,
+          code: 'Client.DuplicateEmail',
+          errors: {
+            Email: [{ message: 'Já existe uma pessoa ativa cadastrada com este e-mail.' }],
+          },
+        }),
+      );
+      renderPage();
+      await fillAndSubmit(user);
+      await screen.findByText('Já existe uma pessoa ativa cadastrada com este e-mail.');
+
+      await user.clear(screen.getByLabelText('E-mail'));
+      await user.type(screen.getByLabelText('E-mail'), 'outro@example.com');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(screen.getByTestId('location')).toHaveTextContent('/pessoas'));
+      expect(mockCreate).toHaveBeenCalledTimes(2);
+      expect(lastPayload()).toMatchObject({ email: 'outro@example.com' });
+    });
+  });
+
+  describe('while saving', () => {
+    it('shows progress, locks the exits and sends the request only once', async () => {
+      const user = userEvent.setup();
+      let resolveCreate!: (value: unknown) => void;
+      mockCreate.mockReturnValue(new Promise((resolve) => (resolveCreate = resolve)));
+      renderPage();
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      const saving = await screen.findByRole('button', { name: 'Salvando…' });
+      expect(saving).toHaveAttribute('aria-disabled', 'true');
+      expect(screen.getByRole('button', { name: 'Cancelar' })).toBeDisabled();
+      expect(screen.queryByRole('link', { name: 'Cancelar' })).not.toBeInTheDocument();
+      await user.click(saving);
+      expect(mockCreate).toHaveBeenCalledTimes(1);
+
+      resolveCreate({ ok: true, data: CREATED });
+      await waitFor(() => expect(screen.getByTestId('location')).toHaveTextContent('/pessoas'));
+    });
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
new file mode 100644
index 00000000..0065e377
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -0,0 +1,49 @@
+import { FormProvider } from 'react-hook-form';
+import { FormErrorBanner } from '@/shared/form/fields';
+import { ClientFormFooter } from './components/ClientFormFooter';
+import { ClientFormHeader } from './components/ClientFormHeader';
+import { ClientGuardiansSection } from './components/ClientGuardiansSection';
+import { ClientPersonSection } from './components/ClientPersonSection';
+import { ClientReferenceContactsSection } from './components/ClientReferenceContactsSection';
+import { useClientFormPage } from './useClientFormPage';
+
+export function ClientFormPage() {
+  const {
+    methods,
+    guardians,
+    referenceContacts,
+    age,
+    isMinor,
+    existingClientId,
+    isSaving,
+    addGuardianButtonRef,
+    onSubmit,
+    addGuardian,
+    addReferenceContact,
+  } = useClientFormPage();
+
+  return (
+    <div className="mx-auto w-full max-w-3xl space-y-6">
+      <ClientFormHeader />
+      <FormProvider {...methods}>
+        <form onSubmit={onSubmit} noValidate className="space-y-6">
+          <ClientPersonSection age={age} existingClientId={existingClientId} />
+          <ClientGuardiansSection
+            fieldIds={guardians.fields.map((field) => field.id)}
+            isMinor={isMinor}
+            addButtonRef={addGuardianButtonRef}
+            onAdd={addGuardian}
+            onRemove={guardians.remove}
+          />
+          <ClientReferenceContactsSection
+            fieldIds={referenceContacts.fields.map((field) => field.id)}
+            onAdd={addReferenceContact}
+            onRemove={referenceContacts.remove}
+          />
+          <FormErrorBanner />
+          <ClientFormFooter isSaving={isSaving} />
+        </form>
+      </FormProvider>
+    </div>
+  );
+}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx
new file mode 100644
index 00000000..617684ac
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx
@@ -0,0 +1,28 @@
+import { Link } from 'react-router';
+import { ActionButton } from '@/shared/ui/action-button';
+import { Button, buttonVariants } from '@/shared/ui/button';
+
+interface ClientFormFooterProps {
+  isSaving: boolean;
+}
+
+function ClientFormFooter({ isSaving }: ClientFormFooterProps) {
+  return (
+    <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+      {isSaving ? (
+        <Button type="button" variant="outline" disabled>
+          Cancelar
+        </Button>
+      ) : (
+        <Link to="/pessoas" className={buttonVariants({ variant: 'outline' })}>
+          Cancelar
+        </Link>
+      )}
+      <ActionButton type="submit" pending={isSaving}>
+        {isSaving ? 'Salvando…' : 'Salvar'}
+      </ActionButton>
+    </div>
+  );
+}
+
+export { ClientFormFooter };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
new file mode 100644
index 00000000..5ec9bf47
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
@@ -0,0 +1,22 @@
+import { ArrowLeftIcon } from 'lucide-react';
+import { Link } from 'react-router';
+import { buttonVariants } from '@/shared/ui/button';
+
+function ClientFormHeader() {
+  return (
+    <header className="space-y-3">
+      <Link to="/pessoas" className={buttonVariants({ variant: 'ghost', size: 'sm' })}>
+        <ArrowLeftIcon aria-hidden="true" />
+        Voltar para Pessoas
+      </Link>
+      <div className="space-y-1.5">
+        <h1 className="text-2xl font-semibold tracking-tight">Nova pessoa</h1>
+        <p className="text-sm text-muted-foreground">
+          Cadastre a pessoa atendida e, se precisar, seus responsáveis e pessoas de referência.
+        </p>
+      </div>
+    </header>
+  );
+}
+
+export { ClientFormHeader };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
new file mode 100644
index 00000000..51b1d9ba
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
@@ -0,0 +1,32 @@
+import { useId, type ReactNode } from 'react';
+
+interface ClientFormSectionProps {
+  title: string;
+  description: string;
+  action?: ReactNode;
+  children: ReactNode;
+}
+
+function ClientFormSection({ title, description, action, children }: ClientFormSectionProps) {
+  const headingId = useId();
+
+  return (
+    <section
+      aria-labelledby={headingId}
+      className="space-y-4 rounded-xl border border-border bg-card p-4 text-card-foreground md:p-6"
+    >
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+        <div className="min-w-0 space-y-1">
+          <h2 id={headingId} className="text-base font-semibold">
+            {title}
+          </h2>
+          <p className="text-sm text-muted-foreground">{description}</p>
+        </div>
+        {action && <div className="shrink-0">{action}</div>}
+      </div>
+      {children}
+    </section>
+  );
+}
+
+export { ClientFormSection };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
new file mode 100644
index 00000000..91c5d7ee
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -0,0 +1,82 @@
+import { useId } from 'react';
+import { XIcon } from 'lucide-react';
+import { MaskedField, TextField } from '@/shared/form/fields';
+import { Button } from '@/shared/ui/button';
+import {
+  CLIENT_NAME_MAX_LENGTH,
+  CONTACT_RELATIONSHIP_MAX_LENGTH,
+  type ClientFormFieldValues,
+} from '../../../../model/clientForm';
+import { PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
+import { formatCpf } from '../../../../model/cpf';
+
+interface ClientGuardianItemProps {
+  index: number;
+  onRemove: () => void;
+}
+
+function ClientGuardianItem({ index, onRemove }: ClientGuardianItemProps) {
+  const headingId = useId();
+  const position = index + 1;
+
+  return (
+    <div
+      role="group"
+      aria-labelledby={headingId}
+      className="space-y-3 rounded-lg border border-border p-3"
+    >
+      <div className="flex items-center justify-between gap-2">
+        <h3 id={headingId} className="text-sm font-medium">
+          Responsável {position}
+        </h3>
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={onRemove}
+          aria-label={`Remover responsável ${position}`}
+        >
+          <XIcon aria-hidden="true" />
+          Remover
+        </Button>
+      </div>
+
+      <div className="grid gap-3 md:grid-cols-2">
+        <TextField<ClientFormFieldValues>
+          name={`guardians.${index}.name`}
+          label="Nome"
+          hint="obrigatório"
+          maxLength={CLIENT_NAME_MAX_LENGTH}
+          autoComplete="off"
+        />
+        <TextField<ClientFormFieldValues>
+          name={`guardians.${index}.relationship`}
+          label="Vínculo"
+          hint="obrigatório"
+          maxLength={CONTACT_RELATIONSHIP_MAX_LENGTH}
+          placeholder="Ex.: mãe, pai, tutor legal"
+          autoComplete="off"
+        />
+        <TextField<ClientFormFieldValues>
+          name={`guardians.${index}.phone`}
+          label="Telefone"
+          hint="opcional"
+          type="tel"
+          maxLength={PHONE_MAX_LENGTH}
+          autoComplete="off"
+        />
+        <MaskedField<ClientFormFieldValues>
+          name={`guardians.${index}.cpf`}
+          label="CPF"
+          hint="opcional"
+          mask={formatCpf}
+          inputMode="numeric"
+          placeholder="000.000.000-00"
+          autoComplete="off"
+        />
+      </div>
+    </div>
+  );
+}
+
+export { ClientGuardianItem };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
new file mode 100644
index 00000000..6623ac5a
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -0,0 +1,73 @@
+import type { RefObject } from 'react';
+import { PlusIcon } from 'lucide-react';
+import { useFormContext } from 'react-hook-form';
+import { Button } from '@/shared/ui/button';
+import { ADULT_AGE_IN_YEARS } from '../../../../model/birthDate';
+import { MAX_GUARDIANS, type ClientFormFieldValues } from '../../../../model/clientForm';
+import { ClientFormSection } from './ClientFormSection';
+import { ClientGuardianItem } from './ClientGuardianItem';
+
+interface ClientGuardiansSectionProps {
+  fieldIds: string[];
+  isMinor: boolean;
+  addButtonRef: RefObject<HTMLButtonElement | null>;
+  onAdd: () => void;
+  onRemove: (index: number) => void;
+}
+
+function ClientGuardiansSection({
+  fieldIds,
+  isMinor,
+  addButtonRef,
+  onAdd,
+  onRemove,
+}: ClientGuardiansSectionProps) {
+  const {
+    formState: { errors },
+  } = useFormContext<ClientFormFieldValues>();
+  const listError = errors.guardians?.root?.message ?? errors.guardians?.message;
+
+  return (
+    <ClientFormSection
+      title="Responsáveis"
+      description={`Quem responde pela pessoa. É obrigatório ter ao menos um quando a data de nascimento indicar menos de ${ADULT_AGE_IN_YEARS} anos.`}
+      action={
+        <Button
+          ref={addButtonRef}
+          type="button"
+          variant="outline"
+          size="sm"
+          disabled={fieldIds.length >= MAX_GUARDIANS}
+          onClick={onAdd}
+        >
+          <PlusIcon aria-hidden="true" />
+          Adicionar responsável
+        </Button>
+      }
+    >
+      {isMinor && fieldIds.length === 0 && (
+        <p role="status" className="rounded-md border border-border bg-muted p-3 text-sm">
+          Esta pessoa tem menos de {ADULT_AGE_IN_YEARS} anos. Informe ao menos um responsável.
+        </p>
+      )}
+
+      {fieldIds.length === 0 ? (
+        <p className="text-sm text-muted-foreground">Nenhum responsável adicionado ainda.</p>
+      ) : (
+        <div className="space-y-3">
+          {fieldIds.map((id, index) => (
+            <ClientGuardianItem key={id} index={index} onRemove={() => onRemove(index)} />
+          ))}
+        </div>
+      )}
+
+      {listError && (
+        <p role="alert" className="text-sm text-destructive">
+          {listError}
+        </p>
+      )}
+    </ClientFormSection>
+  );
+}
+
+export { ClientGuardiansSection };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
new file mode 100644
index 00000000..0a54998f
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -0,0 +1,108 @@
+import { Link } from 'react-router';
+import { MaskedField, TextField, TextareaField } from '@/shared/form/fields';
+import { buttonVariants } from '@/shared/ui/button';
+import { formatAge, maskBirthDate } from '../../../../model/birthDate';
+import {
+  CLIENT_NAME_MAX_LENGTH,
+  CLIENT_NOTES_MAX_LENGTH,
+  type ClientFormFieldValues,
+} from '../../../../model/clientForm';
+import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
+import { formatCpf } from '../../../../model/cpf';
+import { ClientFormSection } from './ClientFormSection';
+
+interface ClientPersonSectionProps {
+  age: number | null;
+  existingClientId: string | null;
+}
+
+function ClientPersonSection({ age, existingClientId }: ClientPersonSectionProps) {
+  return (
+    <ClientFormSection
+      title="Dados da pessoa"
+      description="Só o nome é obrigatório. Complete o restante quando precisar."
+    >
+      <div className="grid gap-4 md:grid-cols-2">
+        <div className="md:col-span-2">
+          <TextField<ClientFormFieldValues>
+            name="fullName"
+            label="Nome completo"
+            hint="obrigatório"
+            maxLength={CLIENT_NAME_MAX_LENGTH}
+            autoComplete="off"
+            autoFocus
+          />
+        </div>
+
+        <MaskedField<ClientFormFieldValues>
+          name="birthDate"
+          label="Data de nascimento"
+          hint={age === null ? 'opcional' : formatAge(age)}
+          mask={maskBirthDate}
+          inputMode="numeric"
+          placeholder="dd/mm/aaaa"
+          autoComplete="off"
+        />
+
+        <TextField<ClientFormFieldValues>
+          name="phone"
+          label="Telefone"
+          hint="opcional"
+          type="tel"
+          maxLength={PHONE_MAX_LENGTH}
+          placeholder="(11) 91234-5678"
+          autoComplete="off"
+        />
+
+        <TextField<ClientFormFieldValues>
+          name="email"
+          label="E-mail"
+          hint="opcional"
+          type="email"
+          maxLength={EMAIL_MAX_LENGTH}
+          placeholder="nome@exemplo.com"
+          autoComplete="off"
+        />
+
+        <div className="space-y-1.5">
+          <MaskedField<ClientFormFieldValues>
+            name="cpf"
+            label="CPF"
+            hint="opcional"
+            mask={formatCpf}
+            inputMode="numeric"
+            placeholder="000.000.000-00"
+            autoComplete="off"
+          />
+          {existingClientId && (
+            <Link
+              to={`/pessoas/${existingClientId}`}
+              target="_blank"
+              rel="noreferrer"
+              className={buttonVariants({ variant: 'link', size: 'sm' })}
+            >
+              Abrir cadastro existente
+              <span className="sr-only"> (abre em outra aba)</span>
+            </Link>
+          )}
+        </div>
+
+        <div className="space-y-1.5 md:col-span-2">
+          <TextareaField<ClientFormFieldValues>
+            name="administrativeNotes"
+            label="Observações administrativas"
+            hint={`opcional · até ${CLIENT_NOTES_MAX_LENGTH} caracteres`}
+            maxLength={CLIENT_NOTES_MAX_LENGTH}
+            placeholder="Ex.: prefere contato por WhatsApp pela manhã."
+          />
+          <p className="text-xs text-muted-foreground">
+            Use só para informações administrativas. Não registre prontuário, diagnóstico ou outros
+            dados clínicos.
+          </p>
+        </div>
+      </div>
+    </ClientFormSection>
+  );
+}
+
+export { ClientPersonSection };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
new file mode 100644
index 00000000..fc2ec1ce
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -0,0 +1,93 @@
+import { useId } from 'react';
+import { XIcon } from 'lucide-react';
+import { ControlledField, TextField } from '@/shared/form/fields';
+import { Button } from '@/shared/ui/button';
+import { CheckboxGroup } from '@/shared/ui/checkbox-group';
+import { CONTACT_PURPOSE_OPTIONS } from '../../../../model/client';
+import {
+  CLIENT_NAME_MAX_LENGTH,
+  CONTACT_RELATIONSHIP_MAX_LENGTH,
+  type ClientFormFieldValues,
+} from '../../../../model/clientForm';
+import { PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
+
+interface ClientReferenceContactItemProps {
+  index: number;
+  onRemove: () => void;
+}
+
+function ClientReferenceContactItem({ index, onRemove }: ClientReferenceContactItemProps) {
+  const headingId = useId();
+  const position = index + 1;
+
+  return (
+    <div
+      role="group"
+      aria-labelledby={headingId}
+      className="space-y-3 rounded-lg border border-border p-3"
+    >
+      <div className="flex items-center justify-between gap-2">
+        <h3 id={headingId} className="text-sm font-medium">
+          Pessoa de referência {position}
+        </h3>
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={onRemove}
+          aria-label={`Remover pessoa de referência ${position}`}
+        >
+          <XIcon aria-hidden="true" />
+          Remover
+        </Button>
+      </div>
+
+      <div className="grid gap-3 md:grid-cols-2">
+        <TextField<ClientFormFieldValues>
+          name={`referenceContacts.${index}.name`}
+          label="Nome"
+          hint="obrigatório"
+          maxLength={CLIENT_NAME_MAX_LENGTH}
+          autoComplete="off"
+        />
+        <TextField<ClientFormFieldValues>
+          name={`referenceContacts.${index}.relationship`}
+          label="Vínculo"
+          hint="obrigatório"
+          maxLength={CONTACT_RELATIONSHIP_MAX_LENGTH}
+          placeholder="Ex.: tio, vizinha, amigo"
+          autoComplete="off"
+        />
+        <TextField<ClientFormFieldValues>
+          name={`referenceContacts.${index}.phone`}
+          label="Telefone"
+          hint="opcional"
+          type="tel"
+          maxLength={PHONE_MAX_LENGTH}
+          autoComplete="off"
+        />
+        <ControlledField<ClientFormFieldValues>
+          name={`referenceContacts.${index}.purposes`}
+          label="Finalidades"
+          hint="escolha ao menos uma"
+          labelHtmlFor={false}
+        >
+          {(field, controlProps) => (
+            <CheckboxGroup
+              ref={field.ref}
+              options={CONTACT_PURPOSE_OPTIONS}
+              value={Array.isArray(field.value) ? (field.value as string[]) : []}
+              onValueChange={field.onChange}
+              onBlur={field.onBlur}
+              aria-label={`Finalidades da pessoa de referência ${position}`}
+              aria-invalid={controlProps['aria-invalid']}
+              aria-describedby={controlProps['aria-describedby']}
+            />
+          )}
+        </ControlledField>
+      </div>
+    </div>
+  );
+}
+
+export { ClientReferenceContactItem };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
new file mode 100644
index 00000000..76845db1
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -0,0 +1,62 @@
+import { PlusIcon } from 'lucide-react';
+import { useFormContext } from 'react-hook-form';
+import { Button } from '@/shared/ui/button';
+import { MAX_REFERENCE_CONTACTS, type ClientFormFieldValues } from '../../../../model/clientForm';
+import { ClientFormSection } from './ClientFormSection';
+import { ClientReferenceContactItem } from './ClientReferenceContactItem';
+
+interface ClientReferenceContactsSectionProps {
+  fieldIds: string[];
+  onAdd: () => void;
+  onRemove: (index: number) => void;
+}
+
+function ClientReferenceContactsSection({
+  fieldIds,
+  onAdd,
+  onRemove,
+}: ClientReferenceContactsSectionProps) {
+  const {
+    formState: { errors },
+  } = useFormContext<ClientFormFieldValues>();
+  const listError = errors.referenceContacts?.root?.message ?? errors.referenceContacts?.message;
+
+  return (
+    <ClientFormSection
+      title="Pessoas de referência"
+      description="Familiares, amigos ou outras pessoas de apoio. Não são cadastros de pessoas atendidas: registrar um contato não dá acesso aos dados da pessoa nem envia mensagens."
+      action={
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          disabled={fieldIds.length >= MAX_REFERENCE_CONTACTS}
+          onClick={onAdd}
+        >
+          <PlusIcon aria-hidden="true" />
+          Adicionar pessoa de referência
+        </Button>
+      }
+    >
+      {fieldIds.length === 0 ? (
+        <p className="text-sm text-muted-foreground">
+          Nenhuma pessoa de referência adicionada ainda.
+        </p>
+      ) : (
+        <div className="space-y-3">
+          {fieldIds.map((id, index) => (
+            <ClientReferenceContactItem key={id} index={index} onRemove={() => onRemove(index)} />
+          ))}
+        </div>
+      )}
+
+      {listError && (
+        <p role="alert" className="text-sm text-destructive">
+          {listError}
+        </p>
+      )}
+    </ClientFormSection>
+  );
+}
+
+export { ClientReferenceContactsSection };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
new file mode 100644
index 00000000..9c20d4ee
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -0,0 +1,113 @@
+import { useEffect, useRef, useState, type SubmitEvent } from 'react';
+import { useNavigate } from 'react-router';
+import { useFieldArray, useForm, useWatch, type FieldErrors, type Path } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { toFormErrors } from '@/shared/api/formErrors';
+import { applyApiProblem } from '@/shared/form/applyApiProblem';
+import { toast } from '@/shared/ui/toast';
+import { clientsRepository } from '../../../api/clientsRepository';
+import { existingClientIdFrom } from '../../../api/existingClientId';
+import { ADULT_AGE_IN_YEARS } from '../../../model/birthDate';
+import {
+  CLIENT_FORM_FIELDS,
+  GUARDIAN_FORM_FIELDS,
+  REFERENCE_CONTACT_FORM_FIELDS,
+  ageFromBirthDate,
+  clientFormSchema,
+  emptyGuardian,
+  emptyReferenceContact,
+  toClientFormFieldValues,
+  type ClientFormFieldValues,
+  type ClientFormValues,
+} from '../../../model/clientForm';
+import type { UseClientFormPageResult } from './useClientFormPage.types';
+
+const CLIENTS_PATH = '/pessoas';
+
+function fieldPathsOf(values: ClientFormFieldValues): Path<ClientFormFieldValues>[] {
+  return [
+    ...CLIENT_FORM_FIELDS,
+    ...values.guardians.flatMap((_, index) =>
+      GUARDIAN_FORM_FIELDS.map((field) => `guardians.${index}.${field}` as const),
+    ),
+    ...values.referenceContacts.flatMap((_, index) =>
+      REFERENCE_CONTACT_FORM_FIELDS.map((field) => `referenceContacts.${index}.${field}` as const),
+    ),
+  ];
+}
+
+export function useClientFormPage(): UseClientFormPageResult {
+  const navigate = useNavigate();
+  const isMountedRef = useRef(true);
+  const addGuardianButtonRef = useRef<HTMLButtonElement>(null);
+  const [conflict, setConflict] = useState<{ cpf: string; clientId: string } | null>(null);
+
+  const methods = useForm<ClientFormFieldValues, unknown, ClientFormValues>({
+    resolver: zodResolver(clientFormSchema),
+    defaultValues: toClientFormFieldValues(),
+  });
+  const guardians = useFieldArray({ control: methods.control, name: 'guardians' });
+  const referenceContacts = useFieldArray({ control: methods.control, name: 'referenceContacts' });
+  const birthDate = useWatch({ control: methods.control, name: 'birthDate' });
+  const cpf = useWatch({ control: methods.control, name: 'cpf' });
+
+  const isSaving = methods.formState.isSubmitting;
+  const age = ageFromBirthDate(birthDate);
+  const isMinor = age !== null && age < ADULT_AGE_IN_YEARS;
+  const existingClientId = conflict?.cpf === cpf ? conflict.clientId : null;
+
+  useEffect(() => {
+    isMountedRef.current = true;
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  async function onValid(values: ClientFormValues) {
+    const result = await clientsRepository.create(values);
+
+    if (result.ok) {
+      toast.add({
+        title: 'Pessoa cadastrada',
+        description: `${result.data.fullName} foi cadastrada.`,
+        type: 'success',
+      });
+      if (isMountedRef.current) void navigate(CLIENTS_PATH);
+      return;
+    }
+
+    const paths = fieldPathsOf(methods.getValues());
+    applyApiProblem<ClientFormFieldValues>(result.error, paths, methods.setError);
+
+    const clientId = existingClientIdFrom(result.error);
+    setConflict(clientId ? { cpf: methods.getValues('cpf'), clientId } : null);
+
+    const { fieldErrors } = toFormErrors(result.error, paths);
+    const firstInvalid = paths.find((path) => fieldErrors[path]);
+    if (firstInvalid) methods.setFocus(firstInvalid);
+  }
+
+  function onInvalid(errors: FieldErrors<ClientFormFieldValues>) {
+    const onlyGuardianMissing = Object.keys(errors).join() === 'guardians';
+    if (onlyGuardianMissing) addGuardianButtonRef.current?.focus();
+  }
+
+  function submit(event: SubmitEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (!isSaving) void methods.handleSubmit(onValid, onInvalid)(event);
+  }
+
+  return {
+    methods,
+    guardians,
+    referenceContacts,
+    age,
+    isMinor,
+    existingClientId,
+    isSaving,
+    addGuardianButtonRef,
+    onSubmit: submit,
+    addGuardian: () => guardians.append(emptyGuardian()),
+    addReferenceContact: () => referenceContacts.append(emptyReferenceContact()),
+  };
+}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
new file mode 100644
index 00000000..39d10767
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
@@ -0,0 +1,17 @@
+import type { RefObject, SubmitEvent } from 'react';
+import type { UseFieldArrayReturn, UseFormReturn } from 'react-hook-form';
+import type { ClientFormFieldValues, ClientFormValues } from '../../../model/clientForm';
+
+export interface UseClientFormPageResult {
+  methods: UseFormReturn<ClientFormFieldValues, unknown, ClientFormValues>;
+  guardians: UseFieldArrayReturn<ClientFormFieldValues, 'guardians'>;
+  referenceContacts: UseFieldArrayReturn<ClientFormFieldValues, 'referenceContacts'>;
+  age: number | null;
+  isMinor: boolean;
+  existingClientId: string | null;
+  isSaving: boolean;
+  addGuardianButtonRef: RefObject<HTMLButtonElement | null>;
+  onSubmit: (event: SubmitEvent<HTMLFormElement>) => void;
+  addGuardian: () => void;
+  addReferenceContact: () => void;
+}
diff --git a/apps/admin-frontend/src/shared/api/formErrors.test.ts b/apps/admin-frontend/src/shared/api/formErrors.test.ts
index e7ead42a..babc2f59 100644
--- a/apps/admin-frontend/src/shared/api/formErrors.test.ts
+++ b/apps/admin-frontend/src/shared/api/formErrors.test.ts
@@ -75,6 +75,30 @@ describe('toFormErrors', () => {
     );
   });
 
+  it('maps an indexed FluentValidation key to the matching nested field path', () => {
+    const problem: ApiProblem = {
+      status: 400,
+      title: 'Ocorreram erros de validação.',
+      errors: {
+        'Guardians[1].Name': [{ message: 'O nome do responsável é obrigatório.' }],
+        'ReferenceContacts[0].Purposes': [{ message: 'Informe ao menos uma finalidade.' }],
+        'Guardians[7].Name': [{ message: 'Um índice que o formulário não tem.' }],
+      },
+    };
+
+    const { fieldErrors, formError } = toFormErrors(problem, [
+      'guardians.0.name',
+      'guardians.1.name',
+      'referenceContacts.0.purposes',
+    ] as const);
+
+    expect(fieldErrors).toEqual({
+      'guardians.1.name': 'O nome do responsável é obrigatório.',
+      'referenceContacts.0.purposes': 'Informe ao menos uma finalidade.',
+    });
+    expect(formError).toBe('Um índice que o formulário não tem.');
+  });
+
   it('ignores an error entry with no message', () => {
     const problem: ApiProblem = {
       status: 400,
diff --git a/apps/admin-frontend/src/shared/api/formErrors.ts b/apps/admin-frontend/src/shared/api/formErrors.ts
index 273b0bc9..ffe75ecd 100644
--- a/apps/admin-frontend/src/shared/api/formErrors.ts
+++ b/apps/admin-frontend/src/shared/api/formErrors.ts
@@ -1,5 +1,7 @@
 import type { ApiProblem } from './servicesFacade';
 
+const toFieldPath = (key: string) => key.replace(/\[(\d+)\]/g, '.$1').toLowerCase();
+
 export function toFormErrors<F extends string>(
   problem: ApiProblem,
   fields: readonly F[],
@@ -11,7 +13,7 @@ export function toFormErrors<F extends string>(
   for (const [key, entries] of Object.entries(problem.errors ?? {})) {
     const message = entries[0]?.message;
     if (!message) continue;
-    const field = byField.get(key.toLowerCase());
+    const field = byField.get(toFieldPath(key));
     if (field) fieldErrors[field] = message;
     else formLevel.push(message);
   }
diff --git a/apps/admin-frontend/src/shared/api/generated/services-api.d.ts b/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
index b1e998d6..87108d7f 100644
--- a/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
+++ b/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
@@ -452,6 +452,109 @@ export interface paths {
     patch?: never;
     trace?: never;
   };
+  '/api/v{version}/clients': {
+    parameters: {
+      query?: never;
+      header?: never;
+      path?: never;
+      cookie?: never;
+    };
+    get?: never;
+    put?: never;
+    post: {
+      parameters: {
+        query?: never;
+        header?: never;
+        path: {
+          version: string;
+        };
+        cookie?: never;
+      };
+      requestBody: {
+        content: {
+          'application/json': components['schemas']['CreateClientCommand'];
+          'text/json': components['schemas']['CreateClientCommand'];
+          'application/*+json': components['schemas']['CreateClientCommand'];
+        };
+      };
+      responses: {
+        /** @description Created */
+        201: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'text/plain': components['schemas']['ApiResponseOfClientResponse'];
+            'application/json': components['schemas']['ApiResponseOfClientResponse'];
+            'text/json': components['schemas']['ApiResponseOfClientResponse'];
+          };
+        };
+        /** @description Bad Request */
+        400: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'text/plain': components['schemas']['ApiProblemDetails'];
+            'application/json': components['schemas']['ApiProblemDetails'];
+            'text/json': components['schemas']['ApiProblemDetails'];
+          };
+        };
+        /** @description Unauthorized */
+        401: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'application/problem+json': components['schemas']['ApiProblemDetails'];
+          };
+        };
+        /** @description Forbidden */
+        403: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'application/problem+json': components['schemas']['ApiProblemDetails'];
+          };
+        };
+        /** @description Not Found */
+        404: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'application/problem+json': components['schemas']['ApiProblemDetails'];
+          };
+        };
+        /** @description Conflict */
+        409: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'text/plain': components['schemas']['ApiProblemDetails'];
+            'application/json': components['schemas']['ApiProblemDetails'];
+            'text/json': components['schemas']['ApiProblemDetails'];
+          };
+        };
+        /** @description Internal Server Error */
+        500: {
+          headers: {
+            [name: string]: unknown;
+          };
+          content: {
+            'application/problem+json': components['schemas']['ApiProblemDetails'];
+          };
+        };
+      };
+    };
+    delete?: never;
+    options?: never;
+    head?: never;
+    patch?: never;
+    trace?: never;
+  };
   '/api/v{version}/services': {
     parameters: {
       query?: never;
@@ -1298,6 +1401,14 @@ export interface components {
       traceId?: null | string;
       correlationId?: null | string;
     };
+    ApiResponseOfClientResponse: {
+      data: null | components['schemas']['ClientResponse'];
+      success?: boolean;
+      /** Format: date-time */
+      timestamp?: string;
+      traceId?: null | string;
+      correlationId?: null | string;
+    };
     ApiResponseOfIReadOnlyListOfCategoryResponse: {
       data: null | components['schemas']['CategoryResponse'][];
       success?: boolean;
@@ -1343,9 +1454,34 @@ export interface components {
       id: string;
       name: string;
     };
+    ClientResponse: {
+      /** Format: uuid */
+      id: string;
+      fullName: string;
+      /** Format: date */
+      birthDate: null | string;
+      phone: null | string;
+      email: null | string;
+      cpf: null | string;
+      administrativeNotes: null | string;
+      status: string;
+      guardians: components['schemas']['GuardianResponse'][];
+      referenceContacts: components['schemas']['ReferenceContactResponse'][];
+    };
     CreateCategoryCommand: {
       name: string;
     };
+    CreateClientCommand: {
+      fullName: string;
+      /** Format: date */
+      birthDate: null | string;
+      phone: null | string;
+      email: null | string;
+      cpf: null | string;
+      administrativeNotes: null | string;
+      guardians: null | components['schemas']['GuardianInput'][];
+      referenceContacts: null | components['schemas']['ReferenceContactInput'][];
+    };
     CreateServiceCommand: {
       name: string;
       description: null | string;
@@ -1371,6 +1507,23 @@ export interface components {
     FieldError: {
       code?: string;
       message?: string;
+      meta?: null | {
+        [key: string]: string;
+      };
+    };
+    GuardianInput: {
+      name: string;
+      relationship: string;
+      phone: null | string;
+      cpf: null | string;
+    };
+    GuardianResponse: {
+      /** Format: uuid */
+      id: string;
+      name: string;
+      relationship: string;
+      phone: null | string;
+      cpf: null | string;
     };
     PagedResultOfServiceResponse: {
       items: components['schemas']['ServiceResponse'][];
@@ -1381,6 +1534,20 @@ export interface components {
       /** Format: int32 */
       pageSize: number | string;
     };
+    ReferenceContactInput: {
+      name: string;
+      relationship: string;
+      phone: null | string;
+      purposes: null | string[];
+    };
+    ReferenceContactResponse: {
+      /** Format: uuid */
+      id: string;
+      name: string;
+      relationship: string;
+      phone: null | string;
+      purposes: string[];
+    };
     ServiceResponse: {
       /** Format: uuid */
       id: string;
diff --git a/apps/admin-frontend/src/shared/form/fields/components/masked-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/masked-field.test.tsx
new file mode 100644
index 00000000..6571263e
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/masked-field.test.tsx
@@ -0,0 +1,55 @@
+import { useEffect } from 'react';
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FormProvider, useForm, useFormContext, useWatch } from 'react-hook-form';
+import { MaskedField } from './masked-field';
+
+interface DummyValues {
+  code: string;
+}
+
+const dashAfterTwo = (value: string) => {
+  const digits = value.replace(/\D/g, '').slice(0, 4);
+  return digits.length > 2 ? `${digits.slice(0, 2)}-${digits.slice(2)}` : digits;
+};
+
+function Harness({ withError = false }: { withError?: boolean }) {
+  const methods = useForm<DummyValues>({ defaultValues: { code: '' } });
+
+  useEffect(() => {
+    if (withError) methods.setError('code', { type: 'test', message: 'Erro de teste' });
+  }, [withError, methods]);
+
+  return (
+    <FormProvider {...methods}>
+      <MaskedField<DummyValues> name="code" label="Código" hint="opcional" mask={dashAfterTwo} />
+      <CurrentValue />
+    </FormProvider>
+  );
+}
+
+function CurrentValue() {
+  const { control } = useFormContext<DummyValues>();
+  const code = useWatch({ control, name: 'code' });
+  return <output aria-label="valor do formulário">{code}</output>;
+}
+
+describe('MaskedField', () => {
+  it('formats what is typed with the mask and stores the masked text in the form', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    await user.type(screen.getByLabelText('Código'), 'a1b2c3d4e5');
+
+    expect(screen.getByLabelText('Código')).toHaveValue('12-34');
+    expect(screen.getByLabelText('valor do formulário')).toHaveTextContent('12-34');
+  });
+
+  it('shows the hint and the field error tied to the input', () => {
+    render(<Harness withError />);
+
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+    expect(screen.getByLabelText('Código')).toHaveAccessibleDescription(/Erro de teste/);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/masked-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/masked-field.tsx
new file mode 100644
index 00000000..f7149f29
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/masked-field.tsx
@@ -0,0 +1,28 @@
+import type { FieldValues } from 'react-hook-form';
+import { Input } from '@/shared/ui/input';
+import type { MaskedFieldProps } from '../fields.types';
+import { ControlledField } from './controlled-field';
+
+export function MaskedField<T extends FieldValues>({
+  name,
+  label,
+  hint,
+  mask,
+  ...inputProps
+}: MaskedFieldProps<T>) {
+  return (
+    <ControlledField<T> name={name} label={label} hint={hint}>
+      {(field, controlProps) => (
+        <Input
+          {...controlProps}
+          {...inputProps}
+          ref={field.ref}
+          name={field.name}
+          value={typeof field.value === 'string' ? field.value : ''}
+          onBlur={field.onBlur}
+          onChange={(event) => field.onChange(mask(event.target.value))}
+        />
+      )}
+    </ControlledField>
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/fields.types.ts b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
index dcd49319..9ea6b78d 100644
--- a/apps/admin-frontend/src/shared/form/fields/fields.types.ts
+++ b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
@@ -20,6 +20,11 @@ export type TextFieldProps<T extends FieldValues> = BaseFieldProps<T> &
 export type TextareaFieldProps<T extends FieldValues> = BaseFieldProps<T> &
   Omit<ComponentProps<typeof Textarea>, RegisterOwnedProps | FormFieldOwnedProps>;
 
+export type MaskedFieldProps<T extends FieldValues> = BaseFieldProps<T> &
+  Omit<ComponentProps<typeof Input>, RegisterOwnedProps | FormFieldOwnedProps | 'value'> & {
+    mask: (value: string) => string;
+  };
+
 export interface ControlledFieldProps<T extends FieldValues> {
   name: Path<T>;
   label: string;
diff --git a/apps/admin-frontend/src/shared/form/fields/index.tsx b/apps/admin-frontend/src/shared/form/fields/index.tsx
index e8cfebe6..26923ac7 100644
--- a/apps/admin-frontend/src/shared/form/fields/index.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/index.tsx
@@ -1,10 +1,12 @@
 export { TextField, TextareaField } from './components/text-fields';
+export { MaskedField } from './components/masked-field';
 export { ControlledField } from './components/controlled-field';
 export { ColorField } from './components/color-field';
 export { FormErrorBanner } from './components/form-error-banner';
 export type {
   TextFieldProps,
   TextareaFieldProps,
+  MaskedFieldProps,
   ControlledFieldProps,
   ColorFieldProps,
 } from './fields.types';
diff --git a/apps/admin-frontend/src/shared/format/date.test.ts b/apps/admin-frontend/src/shared/format/date.test.ts
new file mode 100644
index 00000000..e9bdb2bd
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/date.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+import { todayInSaoPaulo } from './date';
+
+describe('todayInSaoPaulo', () => {
+  it.each([
+    ['2026-10-02T15:00:00Z', '2026-10-02'],
+    ['2026-10-03T02:59:59Z', '2026-10-02'],
+    ['2026-10-03T03:00:00Z', '2026-10-03'],
+    ['2026-01-01T02:00:00Z', '2025-12-31'],
+  ] as const)('reads %s as the São Paulo calendar day %s', (instant, expected) => {
+    expect(todayInSaoPaulo(new Date(instant))).toBe(expected);
+  });
+
+  it('defaults to the current instant', () => {
+    expect(todayInSaoPaulo()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/format/date.ts b/apps/admin-frontend/src/shared/format/date.ts
new file mode 100644
index 00000000..3ee6d153
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/date.ts
@@ -0,0 +1,13 @@
+const dateParts = new Intl.DateTimeFormat('pt-BR', {
+  timeZone: 'America/Sao_Paulo',
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+});
+
+export function todayInSaoPaulo(now: Date = new Date()): string {
+  const parts = Object.fromEntries(
+    dateParts.formatToParts(now).map((part) => [part.type, part.value]),
+  );
+  return `${parts['year']}-${parts['month']}-${parts['day']}`;
+}
diff --git a/apps/admin-frontend/src/shared/ui/checkbox-group/checkbox-group.test.tsx b/apps/admin-frontend/src/shared/ui/checkbox-group/checkbox-group.test.tsx
new file mode 100644
index 00000000..02193714
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/checkbox-group/checkbox-group.test.tsx
@@ -0,0 +1,131 @@
+import { createRef } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { CheckboxGroup } from './index';
+
+const OPTIONS = [
+  { value: 'emergency', label: 'Emergência' },
+  { value: 'operationalSupport', label: 'Apoio operacional' },
+  { value: 'dailyCommunication', label: 'Comunicação cotidiana' },
+];
+
+describe('CheckboxGroup', () => {
+  it('renders a named group with one checkbox per option', () => {
+    render(
+      <CheckboxGroup
+        options={OPTIONS}
+        value={[]}
+        onValueChange={vi.fn()}
+        aria-label="Finalidades do contato"
+      />,
+    );
+
+    expect(screen.getByRole('group', { name: 'Finalidades do contato' })).toBeInTheDocument();
+    expect(screen.getAllByRole('checkbox')).toHaveLength(3);
+    expect(screen.getByRole('checkbox', { name: 'Apoio operacional' })).toBeInTheDocument();
+  });
+
+  it('checks only the options present in value', () => {
+    render(
+      <CheckboxGroup
+        options={OPTIONS}
+        value={['emergency', 'dailyCommunication']}
+        onValueChange={vi.fn()}
+        aria-label="Finalidades do contato"
+      />,
+    );
+
+    expect(screen.getByRole('checkbox', { name: 'Emergência' })).toBeChecked();
+    expect(screen.getByRole('checkbox', { name: 'Apoio operacional' })).not.toBeChecked();
+    expect(screen.getByRole('checkbox', { name: 'Comunicação cotidiana' })).toBeChecked();
+  });
+
+  it('reports the whole new selection when one option is toggled on', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <CheckboxGroup
+        options={OPTIONS}
+        value={['emergency']}
+        onValueChange={onValueChange}
+        aria-label="Finalidades do contato"
+      />,
+    );
+
+    await userEvent.setup().click(screen.getByRole('checkbox', { name: 'Apoio operacional' }));
+
+    expect(onValueChange).toHaveBeenCalledWith(
+      ['emergency', 'operationalSupport'],
+      expect.anything(),
+    );
+  });
+
+  it('reports the remaining selection when one option is toggled off', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <CheckboxGroup
+        options={OPTIONS}
+        value={['emergency', 'operationalSupport']}
+        onValueChange={onValueChange}
+        aria-label="Finalidades do contato"
+      />,
+    );
+
+    await userEvent.setup().click(screen.getByRole('checkbox', { name: 'Emergência' }));
+
+    expect(onValueChange).toHaveBeenCalledWith(['operationalSupport'], expect.anything());
+  });
+
+  it('toggles from the visible label text too', async () => {
+    const onValueChange = vi.fn();
+    render(
+      <CheckboxGroup
+        options={OPTIONS}
+        value={[]}
+        onValueChange={onValueChange}
+        aria-label="Finalidades do contato"
+      />,
+    );
+
+    await userEvent.setup().click(screen.getByText('Comunicação cotidiana'));
+
+    expect(onValueChange).toHaveBeenCalledWith(['dailyCommunication'], expect.anything());
+  });
+
+  it('forwards the ref to the first checkbox so a form can focus it on error', () => {
+    const ref = createRef<HTMLElement>();
+    render(
+      <CheckboxGroup
+        ref={ref}
+        options={OPTIONS}
+        value={[]}
+        onValueChange={vi.fn()}
+        aria-label="Finalidades do contato"
+      />,
+    );
+
+    expect(ref.current).toBe(screen.getByRole('checkbox', { name: 'Emergência' }));
+  });
+
+  it('describes the group and flags each checkbox as invalid', () => {
+    render(
+      <>
+        <p id="hint">Escolha ao menos uma.</p>
+        <CheckboxGroup
+          options={OPTIONS}
+          value={[]}
+          onValueChange={vi.fn()}
+          aria-label="Finalidades do contato"
+          aria-invalid
+          aria-describedby="hint"
+        />
+      </>,
+    );
+
+    const group = screen.getByRole('group', { name: 'Finalidades do contato' });
+    expect(group).toHaveAccessibleDescription('Escolha ao menos uma.');
+    for (const checkbox of screen.getAllByRole('checkbox')) {
+      expect(checkbox).toHaveAttribute('aria-invalid', 'true');
+    }
+  });
+});
diff --git a/apps/admin-frontend/src/shared/ui/checkbox-group/index.tsx b/apps/admin-frontend/src/shared/ui/checkbox-group/index.tsx
new file mode 100644
index 00000000..40ca080b
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/checkbox-group/index.tsx
@@ -0,0 +1,61 @@
+import type { FocusEventHandler, Ref } from 'react';
+import { Checkbox } from '@base-ui/react/checkbox';
+import { CheckboxGroup as CheckboxGroupPrimitive } from '@base-ui/react/checkbox-group';
+import { CheckIcon } from 'lucide-react';
+
+interface CheckboxGroupOption {
+  value: string;
+  label: string;
+}
+
+interface CheckboxGroupProps {
+  options: readonly CheckboxGroupOption[];
+  value: readonly string[];
+  onValueChange: (value: string[]) => void;
+  onBlur?: FocusEventHandler<HTMLDivElement> | undefined;
+  ref?: Ref<HTMLElement> | undefined;
+  'aria-label': string;
+  'aria-invalid'?: boolean | undefined;
+  'aria-describedby'?: string | undefined;
+}
+
+function CheckboxGroup({
+  options,
+  value,
+  onValueChange,
+  onBlur,
+  ref,
+  'aria-label': ariaLabel,
+  'aria-invalid': ariaInvalid,
+  'aria-describedby': ariaDescribedBy,
+}: CheckboxGroupProps) {
+  return (
+    <CheckboxGroupPrimitive
+      aria-label={ariaLabel}
+      aria-describedby={ariaDescribedBy}
+      value={[...value]}
+      onValueChange={onValueChange}
+      onBlur={onBlur}
+      className="flex flex-col gap-2 sm:flex-row sm:flex-wrap sm:gap-x-6"
+    >
+      {options.map((option, index) => (
+        <label key={option.value} className="flex w-fit cursor-pointer items-center gap-2 text-sm">
+          <Checkbox.Root
+            ref={index === 0 ? ref : undefined}
+            value={option.value}
+            aria-invalid={ariaInvalid}
+            className="flex size-4 shrink-0 items-center justify-center rounded-[4px] border border-input bg-transparent outline-none transition-colors focus-visible:border-ring focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background data-[checked]:border-primary data-[checked]:bg-primary data-[checked]:text-primary-foreground aria-invalid:border-destructive dark:bg-input/30"
+          >
+            <Checkbox.Indicator className="flex items-center justify-center text-current">
+              <CheckIcon aria-hidden="true" className="size-3.5" />
+            </Checkbox.Indicator>
+          </Checkbox.Root>
+          {option.label}
+        </label>
+      ))}
+    </CheckboxGroupPrimitive>
+  );
+}
+
+export { CheckboxGroup };
+export type { CheckboxGroupOption, CheckboxGroupProps };

From 4dab19caff003cd9b909c66bccef3aac939b682e Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 5 Oct 2026 19:52:59 -0300
Subject: [PATCH 02/30] asd

---
 .../features/clients/model/clientForm.test.ts |  28 +++++
 .../src/features/clients/model/clientForm.ts  |  26 ++--
 .../ClientFormPage/ClientFormPage.test.tsx    |  20 +++-
 .../pages/ClientFormPage/useClientFormPage.ts |   2 +-
 ...regate-uniqueness-and-conflict-contract.md | 112 ++++++++++++++++++
 5 files changed, 173 insertions(+), 15 deletions(-)
 create mode 100644 docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md

diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
index f356c2fa..f1766eb2 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
@@ -190,6 +190,34 @@ describe('clientFormSchema', () => {
       ).toBeUndefined();
     });
 
+    it('reports the missing guardian together with errors on other fields', () => {
+      const issues = issuesOf(
+        values({
+          fullName: '',
+          email: 'invalido',
+          birthDate: '10/03/2015',
+          guardians: [],
+          referenceContacts: [reference({ purposes: [] })],
+        }),
+      );
+
+      expect(issues['fullName']).toBe('O nome completo é obrigatório.');
+      expect(issues['email']).toBe('Informe um e-mail válido.');
+      expect(issues['referenceContacts.0.purposes']).toBeDefined();
+      expect(issues['guardians']).toBe(
+        'Informe ao menos um responsável para pessoas menores de 18 anos.',
+      );
+    });
+
+    it('still counts a guardian whose own fields are invalid', () => {
+      const issues = issuesOf(
+        values({ birthDate: '10/03/2015', guardians: [guardian({ name: '' })] }),
+      );
+
+      expect(issues['guardians.0.name']).toBe('O nome do responsável é obrigatório.');
+      expect(issues['guardians']).toBeUndefined();
+    });
+
     it('counts the São Paulo day, not the UTC day', () => {
       vi.setSystemTime(new Date('2026-10-03T01:00:00Z'));
 
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index 3e54fbcc..3b1985e1 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -129,19 +129,19 @@ const clientFormObject = z.object({
     ),
 });
 
-export const clientFormSchema = clientFormObject.superRefine((value, ctx) => {
-  if (
-    value.birthDate &&
-    isMinorOn(value.birthDate, todayInSaoPaulo()) &&
-    value.guardians.length === 0
-  ) {
-    ctx.addIssue({
-      code: 'custom',
-      path: ['guardians'],
-      message: `Informe ao menos um responsável para pessoas menores de ${ADULT_AGE_IN_YEARS} anos.`,
-    });
-  }
-});
+export const clientFormSchema = clientFormObject.refine(
+  (value) =>
+    !value.birthDate ||
+    !isMinorOn(value.birthDate, todayInSaoPaulo()) ||
+    value.guardians.length > 0,
+  {
+    path: ['guardians'],
+    message: `Informe ao menos um responsável para pessoas menores de ${ADULT_AGE_IN_YEARS} anos.`,
+    // Zod skips object refinements once any field fails; the person would only learn about the
+    // missing guardian on a second submit. Only an invalid birth date makes the rule meaningless.
+    when: (payload) => payload.issues.every((issue) => issue.path?.[0] !== 'birthDate'),
+  },
+);
 
 export type ClientFormFieldValues = z.input<typeof clientFormSchema>;
 export type ClientFormValues = z.output<typeof clientFormSchema>;
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 0a33a147..88bfb0b2 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -134,7 +134,11 @@ describe('ClientFormPage', () => {
         referenceContacts: [],
       });
       expect(toastAdd).toHaveBeenCalledWith(
-        expect.objectContaining({ title: 'Pessoa cadastrada', type: 'success' }),
+        expect.objectContaining({
+          title: 'Pessoa cadastrada',
+          description: 'O cadastro de Maria Souza foi criado.',
+          type: 'success',
+        }),
       );
       expect(await screen.findByRole('heading', { name: 'Lista de pessoas' })).toBeInTheDocument();
     });
@@ -292,6 +296,20 @@ describe('ClientFormPage', () => {
       expect(screen.getByLabelText('Nome completo')).toHaveFocus();
     });
 
+    it('reports the missing guardian on the same submit as the other errors', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Data de nascimento'), '10032015');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(await screen.findByText('O nome completo é obrigatório.')).toBeInTheDocument();
+      expect(
+        screen.getByText('Informe ao menos um responsável para pessoas menores de 18 anos.'),
+      ).toBeInTheDocument();
+      expect(mockCreate).not.toHaveBeenCalled();
+    });
+
     it('stops offering more guardians at the limit', async () => {
       const user = userEvent.setup();
       renderPage();
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index 9c20d4ee..0b824905 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -69,7 +69,7 @@ export function useClientFormPage(): UseClientFormPageResult {
     if (result.ok) {
       toast.add({
         title: 'Pessoa cadastrada',
-        description: `${result.data.fullName} foi cadastrada.`,
+        description: `O cadastro de ${result.data.fullName} foi criado.`,
         type: 'success',
       });
       if (isMountedRef.current) void navigate(CLIENTS_PATH);
diff --git a/docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md b/docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md
new file mode 100644
index 00000000..be1f3d75
--- /dev/null
+++ b/docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md
@@ -0,0 +1,112 @@
+# ADR 0044 — Clients: person aggregate, uniqueness rules and conflict contract
+
+Status: accepted (2026-10)
+
+## Context
+
+Issue #139 introduces the "pessoa atendida" (served person, `Client` in code, `/api/v1/clients`, the
+**Pessoas** area in the UI). #154 is the first slice of that work: it creates the persisted model and the
+contract that #155 (query), #156 (update), #157 (deactivate), #158 (reactivate) and #159 (delete) build on.
+The rules that shape the model are stricter than anything Tags, Categories or Services needed:
+
+- CPF is unique per tenant across **every** situation — active, inactive and deleted — and must never be
+  reused; e-mail is unique only among **active** persons of the tenant. Both must hold under concurrent
+  writes ([ADR 0012](0012-revert-cross-aggregate-checks-to-handlers-and-domain.md) already says the database,
+  not a pre-check, is the final authority).
+- A person owns two kinds of linked contacts (guardians and reference contacts) that are not persons
+  themselves, and the person and its contacts must be written atomically.
+- A birth date that indicates a minor requires a guardian, on the backend and in the form.
+- A CPF conflict must let the user open the existing record, so the error has to carry that record's id.
+
+## Decision
+
+**Aggregate.** `Client` is a `TenantOwnedEntity` root; `ClientGuardian` and `ClientReferenceContact` are tenant-owned
+children (`ClientContact` is an unmapped abstract base for the shared name/relationship/phone). Two tables, not one
+with a discriminator: the two contact kinds have different required data (guardian CPF vs. purposes) and the issue
+insists they are separate records. Children reference the root through the composite key
+`(TenantId, ClientId) → Clients(TenantId, Id)` ([ADR 0024](0024-database-enforced-data-ownership.md)). One
+`SaveChanges` is one transaction, so a failure leaves no partial person.
+
+**Situation.** `ClientStatus { Active, Inactive, Deleted }`, stored as text with a `CHECK`. Creation sets `Active`;
+the transitions belong to #157–#159. A person that becomes `Deleted` must **also** be soft-deleted through the
+existing `BaseEntity` mechanism (`Remove` → `DeletedAt`), because the global query filter is what makes a deleted
+record invisible — and answer 404 — in every read path by default. The e-mail index ignores a row that is either
+not `Active` or soft-deleted, so it stays correct whichever of the two a future operation sets.
+
+**Normalized storage.** The domain stores CPF as 11 digits, e-mail trimmed and lowercase, and phone trimmed, so the
+unique indexes compare plain stored values (no generated column for them). `FullNameNormalized` (`lower("FullName")`,
+the convention of ADR 0012) exists for #155's stable ordering.
+
+**Uniqueness.**
+
+| Rule | Index (all `UNIQUE`, tenant-scoped) |
+| --- | --- |
+| CPF, any situation | `IX_Clients_TenantId_Cpf` on `(TenantId, Cpf) WHERE Cpf IS NOT NULL` |
+| E-mail, active persons | `IX_Clients_TenantId_Email` on `(TenantId, Email) WHERE Email IS NOT NULL AND Status = 'Active' AND DeletedAt IS NULL` |
+
+A guardian's CPF is deliberately not constrained. The handler pre-checks both rules for a friendly answer; the
+indexes decide races, and `UnitOfWork` already turns SQLSTATE `23505` into a `PersistenceError` carrying the
+constraint name.
+
+**The one `IgnoreQueryFilters()`.** `ClientRepository.FindByCpfAsync` must see soft-deleted and deleted rows, which the
+global filter hides, and `IgnoreQueryFilters()` drops the tenant scope with them. The method re-applies the tenant by
+hand from `ServicesDataContext.CurrentTenantId` (`Guid.Empty` — matching nothing — with no tenant). This is the only
+bypass in the repository layer and is pinned by persistence tests that put the same CPF in two tenants, one of them
+soft-deleted. A new read path must not copy it.
+
+**Conflict contract.** A duplicate answers `409` with the errors keyed by field (`Cpf`, `Email`, PascalCase like
+validation keys), so a form can show each under its input. `FieldError` gained an optional `Meta` string map
+(omitted from the JSON when null, so no existing response changes). The CPF conflict puts `clientId` there — and
+only when the existing person is not deleted, since a deleted record cannot be opened; the message already tells the
+user why. A client reads it from the typed OpenAPI schema (`errors.Cpf[0].meta.clientId`); the id is the one
+`GET /api/v1/clients/{id}` will serve once #155 lands.
+
+**Validation layers.** Per-field pt-BR messages come from FluentValidation (the only place that can name the field);
+the domain re-checks the same invariants and its messages are not meant to reach the user. List sizes are capped
+(10 guardians, 10 reference contacts) because the issue sets no bound and an unbounded array in a body is an abuse
+vector. Reference-contact purposes are strings (`emergency`, `operationalSupport`, `dailyCommunication`) validated
+like `TagColor`, not a JSON enum: a bad enum value fails in the framework's binder with an English message and no code.
+
+**"Today".** The minor rule needs a calendar day, so `TimeProvider.GetBusinessToday()` converts to
+`America/Sao_Paulo` (Windows id, then a fixed UTC−3, because Brazil has had no DST since 2019). Age is completed years
+(a leap-day birthday counts on February 28 in common years), "in the past" is strictly before today, and "more than
+120 years" means an age of 121 or more. A client that pre-validates must use the same day and the same age rule.
+
+**Tenant.** Neither the command nor its nested inputs has a tenant member; the tenant is assigned on save from the
+validated token ([ADR 0008](0008-automatic-tenant-assignment-on-save.md)), and a `tenantId` smuggled into the body
+is ignored by the binder (tested at the DTO and verified against the running API).
+
+## Consequences
+
+What #155–#159 can rely on:
+
+- Read paths go through `ServicesDataContext`'s filter: deleted persons never appear and unknown ids answer 404 with no
+  extra predicate. Only the CPF lookup bypasses it.
+- Wire shape: camelCase English fields; `status` is `active | inactive | deleted`; dates are `yyyy-MM-dd`; CPF is
+  returned as digits (masking lists is #155's job).
+- Deleting must go through `Remove` (soft delete) **and** set `Status = Deleted`; reactivating must re-check the e-mail
+  rule with `ActiveEmailExistsAsync` (it will need an exclusion for the person itself, which Create does not).
+- `Client.Create`/`ClientGuardian.Create` are the factories to extend with `Update` for #156; the contact-id rules
+  are theirs to add.
+- This change is deliverable on its own: it commits the regenerated OpenAPI types
+  (`apps/admin-frontend/src/shared/api/generated/services-api.d.ts`) because `generate:api-types:check` compares them
+  with the live document, and it adds no consumer. The admin-frontend form is a separate change that depends on it.
+
+Accepted costs and limits: the Postgres-only guarantees (unique indexes, composite FK, `CHECK`s, the race) have no
+automated proof, per [ADR 0026](0026-remove-dedicated-runtime-tests.md). They were exercised by hand against a
+disposable PostgreSQL 18 with the real services and a real login — 8 and 10 parallel creates yielded exactly one
+`201` and no orphan contacts, and the schema rules were driven with SQL in a rolled-back transaction. Persistence
+tests cover the EF side (tenant assignment across the graph, isolation, the filters' bypass and the index definitions).
+
+## Considered and rejected
+
+- **One contacts table with a discriminator** — nullable columns that only apply to one kind, and a purposes column
+  that is meaningless for guardians.
+- **Deletion as a status only (no `DeletedAt`)** — every read path would need its own `Status <> Deleted` predicate;
+  one forgotten predicate exposes deleted people. The soft-delete filter is already the default everywhere.
+- **Named query filters / changing `ApplyAuditableConventions` to split tenant from soft delete** — would remove the
+  hand-written tenant predicate, but touches the highest-consequence mechanism ([ADR 0006](0006-tenant-header-base-entity-generic-repository.md))
+  for one lookup.
+- **The existing id as a top-level problem extension** — not visible in the generated OpenAPI schema, so untyped.
+- **Sending the user to a CPF search instead of the record** — an extra step, and it depends on #155's search.
+- **JSON enums for purposes and status** — see the validation note above.

From d2b75c5bf21f431026c43cf9dc704c32e431f2de Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 9 Oct 2026 09:20:15 -0300
Subject: [PATCH 03/30] asdasd

---
 .../ui/pages/ClientFormPage/ClientFormPage.test.tsx | 13 ++++++-------
 .../ClientFormPage/components/ClientFormHeader.tsx  | 11 +++++++++--
 .../components/ClientGuardianItem.tsx               |  6 +-----
 .../components/ClientGuardiansSection.tsx           |  8 +++-----
 .../components/ClientReferenceContactItem.tsx       |  6 +-----
 .../components/ClientReferenceContactsSection.tsx   | 10 +++-------
 6 files changed, 23 insertions(+), 31 deletions(-)

diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 88bfb0b2..984af414 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -104,10 +104,10 @@ describe('ClientFormPage', () => {
     it('starts with no contacts and never asks whether the person is a minor', () => {
       renderPage();
 
-      expect(screen.getByText('Nenhum responsável adicionado ainda.')).toBeInTheDocument();
+      expect(screen.queryByRole('group', { name: /^Responsável \d$/ })).not.toBeInTheDocument();
       expect(
-        screen.getByText('Nenhuma pessoa de referência adicionada ainda.'),
-      ).toBeInTheDocument();
+        screen.queryByRole('group', { name: /^Pessoa de referência \d$/ }),
+      ).not.toBeInTheDocument();
       expect(screen.queryByRole('status')).not.toBeInTheDocument();
     });
   });
@@ -373,7 +373,7 @@ describe('ClientFormPage', () => {
 
       expect(screen.getAllByRole('group', { name: /^Responsável \d$/ })).toHaveLength(1);
       await user.click(screen.getByRole('button', { name: 'Remover responsável 1' }));
-      expect(screen.getByText('Nenhum responsável adicionado ainda.')).toBeInTheDocument();
+      expect(screen.queryByRole('group', { name: /^Responsável \d$/ })).not.toBeInTheDocument();
 
       await user.click(screen.getByRole('button', { name: 'Salvar' }));
       await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
@@ -440,7 +440,6 @@ describe('ClientFormPage', () => {
 
       await addReferenceContact(user);
 
-      expect(screen.getByText('Nenhum responsável adicionado ainda.')).toBeInTheDocument();
       expect(screen.queryByRole('group', { name: 'Responsável 1' })).not.toBeInTheDocument();
     });
 
@@ -452,8 +451,8 @@ describe('ClientFormPage', () => {
       await user.click(screen.getByRole('button', { name: 'Remover pessoa de referência 1' }));
 
       expect(
-        screen.getByText('Nenhuma pessoa de referência adicionada ainda.'),
-      ).toBeInTheDocument();
+        screen.queryByRole('group', { name: 'Pessoa de referência 1' }),
+      ).not.toBeInTheDocument();
     });
   });
 
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
index 5ec9bf47..7aefc6ac 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
@@ -4,8 +4,15 @@ import { buttonVariants } from '@/shared/ui/button';
 
 function ClientFormHeader() {
   return (
-    <header className="space-y-3">
-      <Link to="/pessoas" className={buttonVariants({ variant: 'ghost', size: 'sm' })}>
+    <header className="space-y-2">
+      <Link
+        to="/pessoas"
+        className={buttonVariants({
+          variant: 'ghost',
+          size: 'sm',
+          className: '-ml-2.5 text-muted-foreground',
+        })}
+      >
         <ArrowLeftIcon aria-hidden="true" />
         Voltar para Pessoas
       </Link>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
index 91c5d7ee..4a9eeb4d 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -20,11 +20,7 @@ function ClientGuardianItem({ index, onRemove }: ClientGuardianItemProps) {
   const position = index + 1;
 
   return (
-    <div
-      role="group"
-      aria-labelledby={headingId}
-      className="space-y-3 rounded-lg border border-border p-3"
-    >
+    <div role="group" aria-labelledby={headingId} className="space-y-3 py-4 last:pb-0">
       <div className="flex items-center justify-between gap-2">
         <h3 id={headingId} className="text-sm font-medium">
           Responsável {position}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index 6623ac5a..5d10eef1 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -30,7 +30,7 @@ function ClientGuardiansSection({
   return (
     <ClientFormSection
       title="Responsáveis"
-      description={`Quem responde pela pessoa. É obrigatório ter ao menos um quando a data de nascimento indicar menos de ${ADULT_AGE_IN_YEARS} anos.`}
+      description={`Quem responde pela pessoa. Obrigatório para menores de ${ADULT_AGE_IN_YEARS} anos.`}
       action={
         <Button
           ref={addButtonRef}
@@ -51,10 +51,8 @@ function ClientGuardiansSection({
         </p>
       )}
 
-      {fieldIds.length === 0 ? (
-        <p className="text-sm text-muted-foreground">Nenhum responsável adicionado ainda.</p>
-      ) : (
-        <div className="space-y-3">
+      {fieldIds.length > 0 && (
+        <div className="divide-y divide-border border-t border-border">
           {fieldIds.map((id, index) => (
             <ClientGuardianItem key={id} index={index} onRemove={() => onRemove(index)} />
           ))}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index fc2ec1ce..21a3e679 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -21,11 +21,7 @@ function ClientReferenceContactItem({ index, onRemove }: ClientReferenceContactI
   const position = index + 1;
 
   return (
-    <div
-      role="group"
-      aria-labelledby={headingId}
-      className="space-y-3 rounded-lg border border-border p-3"
-    >
+    <div role="group" aria-labelledby={headingId} className="space-y-3 py-4 last:pb-0">
       <div className="flex items-center justify-between gap-2">
         <h3 id={headingId} className="text-sm font-medium">
           Pessoa de referência {position}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
index 76845db1..5bb7eecf 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -24,7 +24,7 @@ function ClientReferenceContactsSection({
   return (
     <ClientFormSection
       title="Pessoas de referência"
-      description="Familiares, amigos ou outras pessoas de apoio. Não são cadastros de pessoas atendidas: registrar um contato não dá acesso aos dados da pessoa nem envia mensagens."
+      description="Familiares, amigos ou pessoas de apoio. Registrar não dá acesso aos dados nem envia mensagens."
       action={
         <Button
           type="button"
@@ -38,12 +38,8 @@ function ClientReferenceContactsSection({
         </Button>
       }
     >
-      {fieldIds.length === 0 ? (
-        <p className="text-sm text-muted-foreground">
-          Nenhuma pessoa de referência adicionada ainda.
-        </p>
-      ) : (
-        <div className="space-y-3">
+      {fieldIds.length > 0 && (
+        <div className="divide-y divide-border border-t border-border">
           {fieldIds.map((id, index) => (
             <ClientReferenceContactItem key={id} index={index} onRemove={() => onRemove(index)} />
           ))}

From 3a9e6aa76ebf65c239e830ce903fc45ed7eebcbe Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 9 Oct 2026 10:17:44 -0300
Subject: [PATCH 04/30] Add breadcrumb-based page header

Introduces a reusable breadcrumb UI and a page-header widget for top-level page context. The client form now uses a breadcrumb trail back to Pessoas and exposes the current page title as the active item.

Also makes form sections accessible without rendering a visible heading by allowing a hidden title with aria labeling, and updates tests and architecture docs to cover the new behavior.
---
 apps/admin-frontend/docs/ARCHITECTURE.md      |  3 +-
 .../ClientFormPage/ClientFormPage.test.tsx    | 23 ++++-
 .../pages/ClientFormPage/ClientFormPage.tsx   |  6 +-
 .../components/ClientFormHeader.tsx           | 29 ------
 .../components/ClientFormSection.tsx          | 40 ++++++---
 .../components/ClientPersonSection.tsx        |  5 +-
 .../src/shared/ui/breadcrumb/index.tsx        | 88 +++++++++++++++++++
 .../src/widgets/page-header/index.tsx         | 45 ++++++++++
 .../widgets/page-header/page-header.test.tsx  | 56 ++++++++++++
 9 files changed, 244 insertions(+), 51 deletions(-)
 delete mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/breadcrumb/index.tsx
 create mode 100644 apps/admin-frontend/src/widgets/page-header/index.tsx
 create mode 100644 apps/admin-frontend/src/widgets/page-header/page-header.test.tsx

diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index b16837f6..d5516fb9 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -32,7 +32,8 @@ src/
 │   │                        state) + route.ts (loader/action), all re-exported by index.ts
 │   └── index.ts             The slice's ONLY public surface
 ├── widgets/                 Generic UI compositions with behaviour but no domain (confirm-dialog,
-│                            list-section); import shared/ only, consumed by features (ADR 0042)
+│                            list-section, page-header); import shared/ only, consumed by features
+│                            (ADR 0042)
 └── shared/                  Cross-cutting, no business logic
     ├── api/                 servicesFacade, servicesApi (its composition), apiClient,
     │                        unwrap (Result → exception at the framework boundary), formErrors
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 984af414..401ed08c 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -89,10 +89,27 @@ describe('ClientFormPage', () => {
         screen.getByRole('button', { name: 'Adicionar pessoa de referência' }),
       ).toBeInTheDocument();
       expect(screen.getByRole('link', { name: 'Cancelar' })).toHaveAttribute('href', '/pessoas');
-      expect(screen.getByRole('link', { name: 'Voltar para Pessoas' })).toHaveAttribute(
-        'href',
-        '/pessoas',
+    });
+
+    it('shows where the page sits with a breadcrumb back to Pessoas', () => {
+      renderPage();
+
+      const trail = within(screen.getByRole('navigation', { name: 'Caminho de navegação' }));
+      expect(trail.getByRole('link', { name: 'Pessoas' })).toHaveAttribute('href', '/pessoas');
+      expect(trail.getByRole('heading', { name: 'Nova pessoa', level: 1 })).toHaveAttribute(
+        'aria-current',
+        'page',
+      );
+    });
+
+    it('names the person section for assistive tech without showing a heading', () => {
+      renderPage();
+
+      const person = screen.getByRole('region', { name: 'Dados da pessoa' });
+      expect(within(person).getByRole('heading', { name: 'Dados da pessoa' })).toHaveClass(
+        'sr-only',
       );
+      expect(screen.queryByText(/Só o nome é obrigatório/)).not.toBeInTheDocument();
     });
 
     it('warns that notes are administrative only', () => {
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
index 0065e377..0156d3da 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -1,12 +1,14 @@
 import { FormProvider } from 'react-hook-form';
 import { FormErrorBanner } from '@/shared/form/fields';
+import { PageHeader } from '@/widgets/page-header';
 import { ClientFormFooter } from './components/ClientFormFooter';
-import { ClientFormHeader } from './components/ClientFormHeader';
 import { ClientGuardiansSection } from './components/ClientGuardiansSection';
 import { ClientPersonSection } from './components/ClientPersonSection';
 import { ClientReferenceContactsSection } from './components/ClientReferenceContactsSection';
 import { useClientFormPage } from './useClientFormPage';
 
+const PAGE_PARENTS = [{ label: 'Pessoas', to: '/pessoas' }];
+
 export function ClientFormPage() {
   const {
     methods,
@@ -24,7 +26,7 @@ export function ClientFormPage() {
 
   return (
     <div className="mx-auto w-full max-w-3xl space-y-6">
-      <ClientFormHeader />
+      <PageHeader parents={PAGE_PARENTS} title="Nova pessoa" />
       <FormProvider {...methods}>
         <form onSubmit={onSubmit} noValidate className="space-y-6">
           <ClientPersonSection age={age} existingClientId={existingClientId} />
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
deleted file mode 100644
index 7aefc6ac..00000000
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormHeader.tsx
+++ /dev/null
@@ -1,29 +0,0 @@
-import { ArrowLeftIcon } from 'lucide-react';
-import { Link } from 'react-router';
-import { buttonVariants } from '@/shared/ui/button';
-
-function ClientFormHeader() {
-  return (
-    <header className="space-y-2">
-      <Link
-        to="/pessoas"
-        className={buttonVariants({
-          variant: 'ghost',
-          size: 'sm',
-          className: '-ml-2.5 text-muted-foreground',
-        })}
-      >
-        <ArrowLeftIcon aria-hidden="true" />
-        Voltar para Pessoas
-      </Link>
-      <div className="space-y-1.5">
-        <h1 className="text-2xl font-semibold tracking-tight">Nova pessoa</h1>
-        <p className="text-sm text-muted-foreground">
-          Cadastre a pessoa atendida e, se precisar, seus responsáveis e pessoas de referência.
-        </p>
-      </div>
-    </header>
-  );
-}
-
-export { ClientFormHeader };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
index 51b1d9ba..6c3be9e1 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
@@ -1,13 +1,23 @@
 import { useId, type ReactNode } from 'react';
 
-interface ClientFormSectionProps {
+interface ClientFormSectionBase {
   title: string;
+  children: ReactNode;
+}
+
+interface ClientFormSectionWithHeader extends ClientFormSectionBase {
+  hideTitle?: false;
   description: string;
   action?: ReactNode;
-  children: ReactNode;
 }
 
-function ClientFormSection({ title, description, action, children }: ClientFormSectionProps) {
+interface ClientFormSectionWithoutHeader extends ClientFormSectionBase {
+  hideTitle: true;
+}
+
+type ClientFormSectionProps = ClientFormSectionWithHeader | ClientFormSectionWithoutHeader;
+
+function ClientFormSection(props: ClientFormSectionProps) {
   const headingId = useId();
 
   return (
@@ -15,16 +25,22 @@ function ClientFormSection({ title, description, action, children }: ClientFormS
       aria-labelledby={headingId}
       className="space-y-4 rounded-xl border border-border bg-card p-4 text-card-foreground md:p-6"
     >
-      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
-        <div className="min-w-0 space-y-1">
-          <h2 id={headingId} className="text-base font-semibold">
-            {title}
-          </h2>
-          <p className="text-sm text-muted-foreground">{description}</p>
+      {props.hideTitle ? (
+        <h2 id={headingId} className="sr-only">
+          {props.title}
+        </h2>
+      ) : (
+        <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+          <div className="min-w-0 space-y-1">
+            <h2 id={headingId} className="text-base font-semibold">
+              {props.title}
+            </h2>
+            <p className="text-sm text-muted-foreground">{props.description}</p>
+          </div>
+          {props.action && <div className="shrink-0">{props.action}</div>}
         </div>
-        {action && <div className="shrink-0">{action}</div>}
-      </div>
-      {children}
+      )}
+      {props.children}
     </section>
   );
 }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 0a54998f..756194ec 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -18,10 +18,7 @@ interface ClientPersonSectionProps {
 
 function ClientPersonSection({ age, existingClientId }: ClientPersonSectionProps) {
   return (
-    <ClientFormSection
-      title="Dados da pessoa"
-      description="Só o nome é obrigatório. Complete o restante quando precisar."
-    >
+    <ClientFormSection title="Dados da pessoa" hideTitle>
       <div className="grid gap-4 md:grid-cols-2">
         <div className="md:col-span-2">
           <TextField<ClientFormFieldValues>
diff --git a/apps/admin-frontend/src/shared/ui/breadcrumb/index.tsx b/apps/admin-frontend/src/shared/ui/breadcrumb/index.tsx
new file mode 100644
index 00000000..3bd863d3
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/breadcrumb/index.tsx
@@ -0,0 +1,88 @@
+import type { ComponentProps } from 'react';
+import { mergeProps } from '@base-ui/react/merge-props';
+import { useRender } from '@base-ui/react/use-render';
+import { ChevronRightIcon } from 'lucide-react';
+import { cn } from '@/shared/lib/utils';
+
+function Breadcrumb({ className, ...props }: ComponentProps<'nav'> & { 'aria-label': string }) {
+  return <nav data-slot="breadcrumb" className={cn(className)} {...props} />;
+}
+
+function BreadcrumbList({ className, ...props }: ComponentProps<'ol'>) {
+  return (
+    <ol
+      data-slot="breadcrumb-list"
+      className={cn(
+        'flex flex-wrap items-center gap-1.5 text-sm wrap-break-word text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbItem({ className, ...props }: ComponentProps<'li'>) {
+  return (
+    <li
+      data-slot="breadcrumb-item"
+      className={cn('inline-flex items-center gap-1', className)}
+      {...props}
+    />
+  );
+}
+
+function BreadcrumbLink({ className, render, ...props }: useRender.ComponentProps<'a'>) {
+  return useRender({
+    defaultTagName: 'a',
+    props: mergeProps<'a'>(
+      {
+        className: cn('transition-colors hover:text-foreground', className),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: 'breadcrumb-link',
+    },
+  });
+}
+
+function BreadcrumbPage({ className, render, ...props }: useRender.ComponentProps<'span'>) {
+  return useRender({
+    defaultTagName: 'span',
+    props: mergeProps<'span'>(
+      {
+        'aria-current': 'page',
+        className: cn('font-normal text-foreground', className),
+      },
+      props,
+    ),
+    render,
+    state: {
+      slot: 'breadcrumb-page',
+    },
+  });
+}
+
+function BreadcrumbSeparator({ children, className, ...props }: ComponentProps<'li'>) {
+  return (
+    <li
+      data-slot="breadcrumb-separator"
+      role="presentation"
+      aria-hidden="true"
+      className={cn('[&>svg]:size-3.5', className)}
+      {...props}
+    >
+      {children ?? <ChevronRightIcon />}
+    </li>
+  );
+}
+
+export {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+};
diff --git a/apps/admin-frontend/src/widgets/page-header/index.tsx b/apps/admin-frontend/src/widgets/page-header/index.tsx
new file mode 100644
index 00000000..8072ddeb
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/page-header/index.tsx
@@ -0,0 +1,45 @@
+import { Fragment } from 'react';
+import { Link } from 'react-router';
+import {
+  Breadcrumb,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '@/shared/ui/breadcrumb';
+
+interface PageHeaderParent {
+  label: string;
+  to: string;
+}
+
+interface PageHeaderProps {
+  parents: readonly PageHeaderParent[];
+  title: string;
+}
+
+function PageHeader({ parents, title }: PageHeaderProps) {
+  return (
+    <Breadcrumb aria-label="Caminho de navegação">
+      <BreadcrumbList className="text-base md:text-lg">
+        {parents.map((parent) => (
+          <Fragment key={parent.to}>
+            <BreadcrumbItem>
+              <BreadcrumbLink render={<Link to={parent.to} />}>{parent.label}</BreadcrumbLink>
+            </BreadcrumbItem>
+            <BreadcrumbSeparator />
+          </Fragment>
+        ))}
+        <BreadcrumbItem>
+          <BreadcrumbPage render={<h1 />} className="text-base font-semibold md:text-lg">
+            {title}
+          </BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  );
+}
+
+export { PageHeader };
+export type { PageHeaderParent, PageHeaderProps };
diff --git a/apps/admin-frontend/src/widgets/page-header/page-header.test.tsx b/apps/admin-frontend/src/widgets/page-header/page-header.test.tsx
new file mode 100644
index 00000000..641bc962
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/page-header/page-header.test.tsx
@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import { MemoryRouter } from 'react-router';
+import { PageHeader, type PageHeaderParent } from './index';
+
+function renderHeader(parents: readonly PageHeaderParent[], title = 'Nova pessoa') {
+  render(
+    <MemoryRouter>
+      <PageHeader parents={parents} title={title} />
+    </MemoryRouter>,
+  );
+  return within(screen.getByRole('navigation', { name: 'Caminho de navegação' }));
+}
+
+describe('PageHeader', () => {
+  it('links each parent to its place and marks the title as the current page', () => {
+    const trail = renderHeader([{ label: 'Pessoas', to: '/pessoas' }]);
+
+    expect(trail.getByRole('link', { name: 'Pessoas' })).toHaveAttribute('href', '/pessoas');
+    expect(trail.getByRole('heading', { name: 'Nova pessoa', level: 1 })).toHaveAttribute(
+      'aria-current',
+      'page',
+    );
+    expect(trail.queryByRole('link', { name: 'Nova pessoa' })).not.toBeInTheDocument();
+  });
+
+  it('keeps every level of a deeper trail reachable, in order', () => {
+    const trail = renderHeader(
+      [
+        { label: 'Pessoas', to: '/pessoas' },
+        { label: 'Maria Souza', to: '/pessoas/42' },
+        { label: 'Responsáveis', to: '/pessoas/42/responsaveis' },
+      ],
+      'Novo responsável',
+    );
+
+    expect(trail.getAllByRole('link').map((link) => link.getAttribute('href'))).toEqual([
+      '/pessoas',
+      '/pessoas/42',
+      '/pessoas/42/responsaveis',
+    ]);
+    expect(trail.getAllByRole('listitem').map((item) => item.textContent)).toEqual([
+      'Pessoas',
+      'Maria Souza',
+      'Responsáveis',
+      'Novo responsável',
+    ]);
+  });
+
+  it('shows only the title when there is no parent', () => {
+    const trail = renderHeader([], 'Início');
+
+    expect(trail.queryByRole('link')).not.toBeInTheDocument();
+    expect(trail.getByRole('heading', { name: 'Início', level: 1 })).toBeInTheDocument();
+  });
+});

From bbdb28fd87115935791d2d68e401722714502c19 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 9 Oct 2026 10:54:47 -0300
Subject: [PATCH 05/30] =?UTF-8?q?feat(admin-frontend):=20calend=C3=A1rio?=
 =?UTF-8?q?=20no=20campo=20de=20data=20de=20nascimento=20(#154)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

O campo agora aceita digitar `dd/mm/aaaa` (com máscara) e também escolher
a data num calendário que abre ao clicar no ícone ou com a seta para baixo.

- DateField em shared/form/fields: InputGroup + Popover + Calendar, com
  dropdown de mês e ano; o valor do formulário continua sendo o texto
  mascarado, então schema, payload e backend não mudam
- shared/ui/popover e shared/ui/calendar (shadcn base-nova sobre Base UI e
  react-day-picker, locale pt-BR, só modo de data única)
- minDate/maxDate vêm da feature: hoje e o futuro ficam desabilitados
- máscara e leitura de data movidas de birthDate.ts para shared/format/date.ts
  (maskDate, parseMaskedDate, formatMaskedDate, conversões ISO <-> Date local)
- todayInSaoPaulo() virou todayLocal(): o dia vem do fuso do navegador (ADR 0045)
- testes que fixam o relógio usam campos locais, independentes do fuso
- dependências: react-day-picker e date-fns (lockfile regerado no Docker)

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .../agenza-ptbr-copy/references/formatting.md |   7 +
 apps/admin-frontend/docs/ARCHITECTURE.md      |   5 +-
 apps/admin-frontend/package.json              |   2 +
 .../features/clients/model/birthDate.test.ts  |  70 +++-----
 .../src/features/clients/model/birthDate.ts   |  45 ++---
 .../features/clients/model/clientForm.test.ts |   8 +-
 .../src/features/clients/model/clientForm.ts  |  15 +-
 .../ClientFormPage/ClientFormPage.test.tsx    |  47 ++++-
 .../components/ClientPersonSection.tsx        |  14 +-
 .../fields/components/date-field.test.tsx     | 166 ++++++++++++++++++
 .../form/fields/components/date-field.tsx     | 130 ++++++++++++++
 .../src/shared/form/fields/fields.types.ts    |   9 +
 .../src/shared/form/fields/index.tsx          |   2 +
 .../src/shared/format/date.test.ts            | 113 +++++++++++-
 apps/admin-frontend/src/shared/format/date.ts |  60 +++++--
 .../components/calendar-day-button.tsx        |  34 ++++
 .../components/calendar-primitives.tsx        |  17 ++
 .../src/shared/ui/calendar/index.tsx          |  97 ++++++++++
 .../ui/popover/components/popover-content.tsx |  35 ++++
 .../popover/components/popover-primitives.tsx |   7 +
 .../src/shared/ui/popover/index.tsx           |  10 ++
 package-lock.json                             |  44 +++++
 22 files changed, 815 insertions(+), 122 deletions(-)
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/calendar/components/calendar-primitives.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/calendar/index.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/popover/components/popover-content.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/popover/components/popover-primitives.tsx
 create mode 100644 apps/admin-frontend/src/shared/ui/popover/index.tsx

diff --git a/.claude/skills/agenza-ptbr-copy/references/formatting.md b/.claude/skills/agenza-ptbr-copy/references/formatting.md
index 82ff85fd..71001b1e 100644
--- a/.claude/skills/agenza-ptbr-copy/references/formatting.md
+++ b/.claude/skills/agenza-ptbr-copy/references/formatting.md
@@ -88,6 +88,13 @@ const [year, month, day] = isoDate.split('-').map(Number);
 const localDate = new Date(year, month - 1, day);
 ```
 
+**"Today" for a form rule is the person's own day, not São Paulo's.** `todayLocal()`
+(`shared/format/date.ts`) reads the browser's calendar day. The pinned zone above is for *rendering
+instants*; it is not the answer to "what is today?" when validating a date the person typed
+([ADR 0045](../../../../docs/adr/0045-backend-works-in-utc.md)). In a test, build the clock with
+`new Date(2026, 9, 2, 12, 0)` (local fields), not an ISO string with `Z`, so it passes on a machine in
+any zone.
+
 Brazil has had no daylight saving since 2019, so the offset itself never moves — which is exactly why
 this bug survives review: the only thing that shifts is a date-only value, and only by one day.
 
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index d5516fb9..44a4875f 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -50,7 +50,7 @@ src/
     │                        feature that owns it, never here
     ├── form/                applyApiProblem — the one place ApiProblem meets React Hook Form's
     │                        setError — and fields/, the RHF-bound TextField/TextareaField/
-    │                        ControlledField/ColorField/FormErrorBanner; no domain knowledge (§5)
+    │                        MaskedField/DateField/ControlledField/ColorField/FormErrorBanner; no domain knowledge (§5)
     ├── ui/                  Base UI primitives (owned source), lib/utils.ts (cn()); form-field/ is
     │                        the presentational label/hint/error frame those fields render into
     ├── env.ts               Fail-fast loader for the six VITE_* vars
@@ -383,7 +383,8 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | Review fixes on the tag dialogs (PR #125) | Two defects, one line of reasoning each. (1) `useRouteScrollReset` keys on the **section** (first path segment), not the whole `pathname`: `new`, `:id/edit` and `:id/delete` are child routes of `/tags`, so every dialog open/close used to reset `<main>`'s scroll and throw the list back to the top. (2) `useTagFormPage.onValid` and `ConfirmDialog.handleConfirm` skip closing when the dialog already unmounted mid-request (browser Back): react-router's `useNavigate` stays live after unmount, so the stale `navigate(-1)` used to pop one entry too many — out of the app, when `/tags` was the tab's first entry. FR-018 still does not block browser Back; no `useBlocker`, since the request finishes anyway and the toast still reports it. Deliberately left as is, both judged not worth the code: a row someone else already removed stays listed after its `Tag.NotFound` until the next reload or search — the spec's edge case only asks for the "não encontrada" message, which already shows; and `TagDeletePage` keeps its loaded tag if `:id` changed without a remount, because no UI path goes from `/tags/A/delete` straight to `/tags/B/delete` — the modal blocks the list, and closing it goes back to `/tags` first. A `key={id}` on the confirmation is the fix if a flow like "excluir a próxima" ever appears. |
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
-| `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayInSaoPaulo()` for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict reads the existing record's id from the typed `FieldError.meta` and links to `/pessoas/{id}` in a new tab, so the typed values survive; that page arrives with #155. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
+| `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict reads the existing record's id from the typed `FieldError.meta` and links to `/pessoas/{id}` in a new tab, so the typed values survive; that page arrives with #155. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
+| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` and `date-fns` added, plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (ISO strings): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date`, so `isoToLocalDate`/`localDateToIso` convert at the edge; the model keeps ISO strings. `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/package.json b/apps/admin-frontend/package.json
index 1c383b43..6ef344ae 100644
--- a/apps/admin-frontend/package.json
+++ b/apps/admin-frontend/package.json
@@ -22,10 +22,12 @@
     "@hookform/resolvers": "^5.9.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "date-fns": "^4.4.0",
     "lucide-react": "^1.41.0",
     "oidc-client-ts": "^3.3.0",
     "openapi-fetch": "^0.17.0",
     "react": "^19.2.7",
+    "react-day-picker": "^10.0.2",
     "react-dom": "^19.2.7",
     "react-hook-form": "^7.88.0",
     "react-router": "^8.3.0",
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
index 095dafec..22e6bfbd 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
@@ -1,61 +1,16 @@
 import { describe, expect, it } from 'vitest';
 import {
   calculateAge,
+  earliestBirthDate,
   formatAge,
   isInThePast,
   isMinorOn,
   isWithinMaxAge,
-  maskBirthDate,
-  parseBirthDate,
+  latestBirthDate,
 } from './birthDate';
 
 const TODAY = '2026-10-02';
 
-describe('maskBirthDate', () => {
-  it.each([
-    ['', ''],
-    ['1', '1'],
-    ['10', '10'],
-    ['103', '10/3'],
-    ['1003', '10/03'],
-    ['10032', '10/03/2'],
-    ['10032015', '10/03/2015'],
-    ['100320159999', '10/03/2015'],
-    ['10/03/2015', '10/03/2015'],
-    ['ab10-03', '10/03'],
-  ] as const)('masks %j as %j while typing', (typed, expected) => {
-    expect(maskBirthDate(typed)).toBe(expected);
-  });
-});
-
-describe('parseBirthDate', () => {
-  it.each([
-    ['10/03/2015', '2015-03-10'],
-    ['01/01/1900', '1900-01-01'],
-    ['29/02/2000', '2000-02-29'],
-    [' 05/12/1990 ', '1990-12-05'],
-  ] as const)('reads %j as %s', (masked, expected) => {
-    expect(parseBirthDate(masked)).toBe(expected);
-  });
-
-  it.each([
-    '',
-    '10/03',
-    '10/03/15',
-    '31/02/2020',
-    '29/02/2001',
-    '00/10/2020',
-    '10/00/2020',
-    '10/13/2020',
-    '32/01/2020',
-    '10/03/0999',
-    'aa/bb/cccc',
-    '10-03-2015',
-  ])('rejects %j', (masked) => {
-    expect(parseBirthDate(masked)).toBeNull();
-  });
-});
-
 describe('calculateAge', () => {
   it.each([
     ['2008-10-02', 18],
@@ -103,6 +58,27 @@ describe('birth date rules', () => {
   });
 });
 
+describe('birth date picker bounds', () => {
+  it('ends the day before today, since a birth date must be in the past', () => {
+    expect(latestBirthDate(TODAY)).toBe('2026-10-01');
+    expect(isInThePast(latestBirthDate(TODAY), TODAY)).toBe(true);
+  });
+
+  it.each([
+    ['2026-03-01', '2026-02-28'],
+    ['2024-03-01', '2024-02-29'],
+    ['2027-01-01', '2026-12-31'],
+  ] as const)('ends the day before %s on %s', (today, expected) => {
+    expect(latestBirthDate(today)).toBe(expected);
+  });
+
+  it('starts on January 1st of the first year that can still be within the maximum age', () => {
+    expect(earliestBirthDate(TODAY)).toBe('1905-01-01');
+    expect(isWithinMaxAge('1905-12-31', '2026-01-01')).toBe(true);
+    expect(isWithinMaxAge('1905-01-01', '2026-12-31')).toBe(false);
+  });
+});
+
 describe('formatAge', () => {
   it.each([
     [0, 'menos de 1 ano'],
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.ts b/apps/admin-frontend/src/features/clients/model/birthDate.ts
index f2e72191..8f6b00fe 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.ts
@@ -1,30 +1,8 @@
+import { daysInMonth, isoToLocalDate, localDateToIso } from '@/shared/format/date';
+
 export const ADULT_AGE_IN_YEARS = 18;
 export const MAX_AGE_IN_YEARS = 120;
 
-const MASKED_LENGTH = 10;
-
-export function maskBirthDate(value: string): string {
-  const digits = value.replace(/\D/g, '').slice(0, 8);
-
-  if (digits.length <= 2) return digits;
-  if (digits.length <= 4) return `${digits.slice(0, 2)}/${digits.slice(2)}`;
-  return `${digits.slice(0, 2)}/${digits.slice(2, 4)}/${digits.slice(4)}`;
-}
-
-export function parseBirthDate(masked: string): string | null {
-  const value = masked.trim();
-  if (value.length !== MASKED_LENGTH) return null;
-
-  const [day, month, year] = value.split('/').map(Number);
-  if (day === undefined || month === undefined || year === undefined) return null;
-  if (!Number.isInteger(day) || !Number.isInteger(month) || !Number.isInteger(year)) return null;
-  if (year < 1000 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
-    return null;
-  }
-
-  return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
-}
-
 export function calculateAge(birthDate: string, today: string): number {
   const birth = toParts(birthDate);
   const current = toParts(today);
@@ -53,6 +31,17 @@ export function isMinorOn(birthDate: string, today: string): boolean {
   return isInThePast(birthDate, today) && calculateAge(birthDate, today) < ADULT_AGE_IN_YEARS;
 }
 
+export function latestBirthDate(today: string): string {
+  const yesterday = isoToLocalDate(today);
+  yesterday.setDate(yesterday.getDate() - 1);
+  return localDateToIso(yesterday);
+}
+
+export function earliestBirthDate(today: string): string {
+  const year = Number(today.slice(0, 4)) - MAX_AGE_IN_YEARS - 1;
+  return `${year}-01-01`;
+}
+
 export function formatAge(age: number): string {
   if (age < 1) return 'menos de 1 ano';
   return age === 1 ? '1 ano' : `${age} anos`;
@@ -62,11 +51,3 @@ function toParts(isoDate: string): { year: number; month: number; day: number }
   const [year = 0, month = 0, day = 0] = isoDate.split('-').map(Number);
   return { year, month, day };
 }
-
-function daysInMonth(year: number, month: number): number {
-  return new Date(Date.UTC(year, month, 0)).getUTCDate();
-}
-
-function pad(value: number, length: number): string {
-  return String(value).padStart(length, '0');
-}
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
index 0a2a2193..f85f419b 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
@@ -11,7 +11,7 @@ import {
   type ClientFormFieldValues,
 } from './clientForm';
 
-const NOON_IN_SAO_PAULO = new Date('2026-10-02T15:00:00Z');
+const LOCAL_NOON = new Date(2026, 9, 2, 12, 0);
 
 function values(overrides: Partial<ClientFormFieldValues> = {}): ClientFormFieldValues {
   return { ...toClientFormFieldValues(), fullName: 'Maria Souza', ...overrides };
@@ -45,7 +45,7 @@ function issuesOf(input: ClientFormFieldValues): Record<string, string> {
 }
 
 beforeEach(() => {
-  vi.useFakeTimers({ now: NOON_IN_SAO_PAULO, toFake: ['Date'] });
+  vi.useFakeTimers({ now: LOCAL_NOON, toFake: ['Date'] });
 });
 
 afterEach(() => {
@@ -220,8 +220,8 @@ describe('clientFormSchema', () => {
       expect(issues['guardians']).toBeUndefined();
     });
 
-    it('counts the São Paulo day, not the UTC day', () => {
-      vi.setSystemTime(new Date('2026-10-03T01:00:00Z'));
+    it('counts the local day late in the evening, before the next day starts', () => {
+      vi.setSystemTime(new Date(2026, 9, 2, 23, 30));
 
       expect(
         issuesOf(values({ birthDate: '03/10/2008', guardians: [] }))['guardians'],
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index 7606c452..0b3536b9 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { todayInSaoPaulo } from '@/shared/format/date';
+import { parseMaskedDate, todayLocal } from '@/shared/format/date';
 import {
   ADULT_AGE_IN_YEARS,
   MAX_AGE_IN_YEARS,
@@ -7,7 +7,6 @@ import {
   isInThePast,
   isMinorOn,
   isWithinMaxAge,
-  parseBirthDate,
 } from './birthDate';
 import { CONTACT_PURPOSES } from './client';
 import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH, isValidEmail, isValidPhone } from './contactFormats';
@@ -77,10 +76,10 @@ const birthDateField = z.string().transform((value, ctx) => {
     return z.NEVER;
   };
 
-  const birthDate = parseBirthDate(value);
+  const birthDate = parseMaskedDate(value);
   if (birthDate === null) return fail('Informe uma data válida no formato dd/mm/aaaa.');
 
-  const today = todayInSaoPaulo();
+  const today = todayLocal();
   if (!isInThePast(birthDate, today)) return fail('A data de nascimento deve estar no passado.');
   if (!isWithinMaxAge(birthDate, today)) {
     return fail(`A data de nascimento não pode indicar idade superior a ${MAX_AGE_IN_YEARS} anos.`);
@@ -132,9 +131,7 @@ const clientFormObject = z.object({
 
 export const clientFormSchema = clientFormObject.refine(
   (value) =>
-    !value.birthDate ||
-    !isMinorOn(value.birthDate, todayInSaoPaulo()) ||
-    value.guardians.length > 0,
+    !value.birthDate || !isMinorOn(value.birthDate, todayLocal()) || value.guardians.length > 0,
   {
     path: ['guardians'],
     message: `Informe ao menos um responsável para pessoas menores de ${ADULT_AGE_IN_YEARS} anos.`,
@@ -175,8 +172,8 @@ export function emptyReferenceContact(): ReferenceContactFormFieldValues {
 }
 
 export function ageFromBirthDate(masked: string): number | null {
-  const birthDate = parseBirthDate(masked);
-  const today = todayInSaoPaulo();
+  const birthDate = parseMaskedDate(masked);
+  const today = todayLocal();
   if (birthDate === null || !isInThePast(birthDate, today) || !isWithinMaxAge(birthDate, today)) {
     return null;
   }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 401ed08c..12d961cc 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -59,7 +59,7 @@ function lastPayload() {
 describe('ClientFormPage', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    vi.useFakeTimers({ now: new Date('2026-10-02T15:00:00Z'), toFake: ['Date'] });
+    vi.useFakeTimers({ now: new Date(2026, 9, 2, 12, 0), toFake: ['Date'] });
     mockCreate.mockResolvedValue({ ok: true, data: CREATED });
   });
 
@@ -200,6 +200,51 @@ describe('ClientFormPage', () => {
       expect(screen.getByText('36 anos')).toBeInTheDocument();
     });
 
+    it('picks the birth date from the calendar, shows the age and sends the ISO date', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.click(
+        screen.getByRole('button', { name: 'Abrir calendário de data de nascimento' }),
+      );
+      const calendar = await screen.findByRole('dialog');
+      await user.selectOptions(
+        within(calendar).getByRole('combobox', { name: 'Escolha o ano' }),
+        '1990',
+      );
+      await user.selectOptions(
+        within(calendar).getByRole('combobox', { name: 'Escolha o mês' }),
+        '4',
+      );
+      await user.click(within(calendar).getByRole('button', { name: /, 20 de maio de 1990/ }));
+
+      expect(screen.getByLabelText('Data de nascimento')).toHaveValue('20/05/1990');
+      expect(screen.getByText('36 anos')).toBeInTheDocument();
+
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
+      expect(lastPayload()).toMatchObject({ birthDate: '1990-05-20' });
+    });
+
+    it('does not let the calendar pick today or later as a birth date', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.click(
+        screen.getByRole('button', { name: 'Abrir calendário de data de nascimento' }),
+      );
+      const calendar = await screen.findByRole('dialog');
+
+      expect(
+        within(calendar).getByRole('button', { name: /, 1 de outubro de 2026/ }),
+      ).toBeEnabled();
+      expect(
+        within(calendar).getByRole('button', { name: /, 2 de outubro de 2026/ }),
+      ).toBeDisabled();
+    });
+
     it('does not demand a guardian for an adult', async () => {
       const user = userEvent.setup();
       renderPage();
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 756194ec..fdfa5aec 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,7 +1,8 @@
 import { Link } from 'react-router';
-import { MaskedField, TextField, TextareaField } from '@/shared/form/fields';
+import { todayLocal } from '@/shared/format/date';
+import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
 import { buttonVariants } from '@/shared/ui/button';
-import { formatAge, maskBirthDate } from '../../../../model/birthDate';
+import { earliestBirthDate, formatAge, latestBirthDate } from '../../../../model/birthDate';
 import {
   CLIENT_NAME_MAX_LENGTH,
   CLIENT_NOTES_MAX_LENGTH,
@@ -17,6 +18,8 @@ interface ClientPersonSectionProps {
 }
 
 function ClientPersonSection({ age, existingClientId }: ClientPersonSectionProps) {
+  const today = todayLocal();
+
   return (
     <ClientFormSection title="Dados da pessoa" hideTitle>
       <div className="grid gap-4 md:grid-cols-2">
@@ -31,13 +34,12 @@ function ClientPersonSection({ age, existingClientId }: ClientPersonSectionProps
           />
         </div>
 
-        <MaskedField<ClientFormFieldValues>
+        <DateField<ClientFormFieldValues>
           name="birthDate"
           label="Data de nascimento"
           hint={age === null ? 'opcional' : formatAge(age)}
-          mask={maskBirthDate}
-          inputMode="numeric"
-          placeholder="dd/mm/aaaa"
+          minDate={earliestBirthDate(today)}
+          maxDate={latestBirthDate(today)}
           autoComplete="off"
         />
 
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
new file mode 100644
index 00000000..7c923608
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
@@ -0,0 +1,166 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FormProvider, useForm, useFormContext, useWatch } from 'react-hook-form';
+import { DateField } from './date-field';
+
+interface DummyValues {
+  birthDate: string;
+}
+
+function Harness({ initial = '' }: { initial?: string }) {
+  const methods = useForm<DummyValues>({ defaultValues: { birthDate: initial } });
+
+  return (
+    <FormProvider {...methods}>
+      <DateField<DummyValues>
+        name="birthDate"
+        label="Data de nascimento"
+        hint="opcional"
+        minDate="1990-01-01"
+        maxDate="2026-10-01"
+      />
+      <CurrentValue />
+    </FormProvider>
+  );
+}
+
+function CurrentValue() {
+  const { control } = useFormContext<DummyValues>();
+  const birthDate = useWatch({ control, name: 'birthDate' });
+  return <output aria-label="valor do formulário">{birthDate}</output>;
+}
+
+function input() {
+  return screen.getByLabelText('Data de nascimento');
+}
+
+async function openCalendar(user: ReturnType<typeof userEvent.setup>) {
+  await user.click(screen.getByRole('button', { name: 'Abrir calendário de data de nascimento' }));
+  return screen.findByRole('dialog');
+}
+
+describe('DateField', () => {
+  it('masks what is typed as dd/mm/aaaa and stores the masked text in the form', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    await user.type(input(), '20051990');
+
+    expect(input()).toHaveValue('20/05/1990');
+    expect(screen.getByLabelText('valor do formulário')).toHaveTextContent('20/05/1990');
+  });
+
+  it('shows the dd/mm/aaaa placeholder and the numeric keyboard hint', () => {
+    render(<Harness />);
+
+    expect(input()).toHaveAttribute('placeholder', 'dd/mm/aaaa');
+    expect(input()).toHaveAttribute('inputmode', 'numeric');
+  });
+
+  it('keeps the calendar closed until it is asked for', () => {
+    render(<Harness />);
+
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  });
+
+  it('opens the calendar from the button on the month of the latest allowed date', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    const calendar = await openCalendar(user);
+
+    expect(within(calendar).getByRole('grid', { name: 'outubro 2026' })).toBeInTheDocument();
+  });
+
+  it('opens the calendar with the arrow down key from the input', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    await user.click(input());
+    await user.keyboard('{ArrowDown}');
+
+    expect(await screen.findByRole('dialog')).toBeInTheDocument();
+  });
+
+  it('fills the field with the picked day and closes the calendar', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    const calendar = await openCalendar(user);
+    await user.click(within(calendar).getByRole('button', { name: /, 1 de outubro de 2026/ }));
+
+    expect(input()).toHaveValue('01/10/2026');
+    expect(screen.getByLabelText('valor do formulário')).toHaveTextContent('01/10/2026');
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+  });
+
+  it('opens on the month of a typed date and marks that day as selected', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    await user.type(input(), '15032000');
+    const calendar = await openCalendar(user);
+
+    expect(within(calendar).getByRole('grid', { name: 'março 2000' })).toBeInTheDocument();
+    expect(
+      within(calendar).getByRole('button', { name: /, 15 de março de 2000, selecionado/ }),
+    ).toBeInTheDocument();
+  });
+
+  it('opens on the month of a date the form already holds', async () => {
+    const user = userEvent.setup();
+    render(<Harness initial="07/08/1995" />);
+
+    const calendar = await openCalendar(user);
+
+    expect(within(calendar).getByRole('grid', { name: 'agosto 1995' })).toBeInTheDocument();
+  });
+
+  it('does not mark a typed date outside the allowed range as selected', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    await user.type(input(), '05102026');
+    const calendar = await openCalendar(user);
+
+    expect(within(calendar).queryByRole('button', { name: /selecionado/ })).not.toBeInTheDocument();
+    expect(within(calendar).getByRole('grid', { name: 'outubro 2026' })).toBeInTheDocument();
+  });
+
+  it('disables the days after the latest allowed date', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    const calendar = await openCalendar(user);
+
+    expect(within(calendar).getByRole('button', { name: /, 2 de outubro de 2026/ })).toBeDisabled();
+    expect(within(calendar).getByRole('button', { name: /, 1 de outubro de 2026/ })).toBeEnabled();
+  });
+
+  it('jumps to another year through the year dropdown', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    const calendar = await openCalendar(user);
+    await user.selectOptions(
+      within(calendar).getByRole('combobox', { name: 'Escolha o ano' }),
+      '2000',
+    );
+
+    expect(within(calendar).getByRole('grid', { name: 'outubro 2000' })).toBeInTheDocument();
+  });
+
+  it('limits the year dropdown to the allowed range', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    const calendar = await openCalendar(user);
+    const years = within(
+      within(calendar).getByRole('combobox', { name: 'Escolha o ano' }),
+    ).getAllByRole('option');
+
+    expect(years[0]).toHaveTextContent('1990');
+    expect(years.at(-1)).toHaveTextContent('2026');
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
new file mode 100644
index 00000000..dc761d23
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
@@ -0,0 +1,130 @@
+import { useState, type KeyboardEvent, type Ref } from 'react';
+import type { FieldValues } from 'react-hook-form';
+import { CalendarIcon } from 'lucide-react';
+import {
+  formatMaskedDate,
+  isoToLocalDate,
+  localDateToIso,
+  maskDate,
+  parseMaskedDate,
+} from '@/shared/format/date';
+import { Calendar } from '@/shared/ui/calendar';
+import type { FormFieldControlProps } from '@/shared/ui/form-field';
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from '@/shared/ui/input-group';
+import { Popover, PopoverContent, PopoverTrigger } from '@/shared/ui/popover';
+import type { DateFieldProps } from '../fields.types';
+import { ControlledField } from './controlled-field';
+
+type DateFieldControlProps = Omit<DateFieldProps<FieldValues>, 'hint'> &
+  FormFieldControlProps & {
+    value: unknown;
+    inputRef: Ref<HTMLInputElement>;
+    onChange: (value: string) => void;
+    onBlur: () => void;
+  };
+
+export function DateField<T extends FieldValues>({
+  name,
+  label,
+  hint,
+  ...rest
+}: DateFieldProps<T>) {
+  return (
+    <ControlledField<T> name={name} label={label} hint={hint}>
+      {(field, controlProps) => (
+        <DateFieldControl
+          {...rest}
+          {...controlProps}
+          label={label}
+          name={field.name}
+          value={field.value}
+          inputRef={field.ref}
+          onChange={field.onChange}
+          onBlur={field.onBlur}
+        />
+      )}
+    </ControlledField>
+  );
+}
+
+function DateFieldControl({
+  label,
+  value: fieldValue,
+  inputRef,
+  onChange,
+  minDate,
+  maxDate,
+  placeholder = 'dd/mm/aaaa',
+  ...inputProps
+}: DateFieldControlProps) {
+  const [open, setOpen] = useState(false);
+
+  const value = typeof fieldValue === 'string' ? fieldValue : '';
+  const typedDate = parseMaskedDate(value);
+  const isSelectable = typedDate !== null && typedDate >= minDate && typedDate <= maxDate;
+  const selected = isSelectable ? isoToLocalDate(typedDate) : undefined;
+
+  function selectDate(date: Date) {
+    onChange(formatMaskedDate(localDateToIso(date)));
+    setOpen(false);
+  }
+
+  function openOnArrowDown(event: KeyboardEvent<HTMLInputElement>) {
+    if (event.key !== 'ArrowDown') return;
+    event.preventDefault();
+    setOpen(true);
+  }
+
+  return (
+    <InputGroup>
+      <Popover open={open} onOpenChange={setOpen}>
+        <InputGroupInput
+          {...inputProps}
+          ref={inputRef}
+          value={value}
+          inputMode="numeric"
+          placeholder={placeholder}
+          onChange={(event) => onChange(maskDate(event.target.value))}
+          onKeyDown={openOnArrowDown}
+        />
+        <InputGroupAddon align="inline-end">
+          <PopoverTrigger
+            render={
+              <InputGroupButton
+                size="icon-xs"
+                aria-label={`Abrir calendário de ${label.toLowerCase()}`}
+              />
+            }
+          >
+            <CalendarIcon aria-hidden="true" />
+          </PopoverTrigger>
+        </InputGroupAddon>
+        <PopoverContent
+          className="w-auto overflow-hidden p-0"
+          align="end"
+          alignOffset={-8}
+          sideOffset={10}
+          initialFocus={false}
+        >
+          <Calendar
+            mode="single"
+            required
+            autoFocus
+            captionLayout="dropdown"
+            selected={selected}
+            defaultMonth={selected ?? isoToLocalDate(maxDate)}
+            startMonth={isoToLocalDate(minDate)}
+            endMonth={isoToLocalDate(maxDate)}
+            disabled={[{ before: isoToLocalDate(minDate) }, { after: isoToLocalDate(maxDate) }]}
+            onSelect={selectDate}
+          />
+        </PopoverContent>
+      </Popover>
+    </InputGroup>
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/fields.types.ts b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
index 9ea6b78d..8c38216a 100644
--- a/apps/admin-frontend/src/shared/form/fields/fields.types.ts
+++ b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
@@ -25,6 +25,15 @@ export type MaskedFieldProps<T extends FieldValues> = BaseFieldProps<T> &
     mask: (value: string) => string;
   };
 
+export type DateFieldProps<T extends FieldValues> = BaseFieldProps<T> &
+  Omit<
+    ComponentProps<typeof Input>,
+    RegisterOwnedProps | FormFieldOwnedProps | 'value' | 'type' | 'inputMode'
+  > & {
+    minDate: string;
+    maxDate: string;
+  };
+
 export interface ControlledFieldProps<T extends FieldValues> {
   name: Path<T>;
   label: string;
diff --git a/apps/admin-frontend/src/shared/form/fields/index.tsx b/apps/admin-frontend/src/shared/form/fields/index.tsx
index 26923ac7..f0cbcefd 100644
--- a/apps/admin-frontend/src/shared/form/fields/index.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/index.tsx
@@ -1,5 +1,6 @@
 export { TextField, TextareaField } from './components/text-fields';
 export { MaskedField } from './components/masked-field';
+export { DateField } from './components/date-field';
 export { ControlledField } from './components/controlled-field';
 export { ColorField } from './components/color-field';
 export { FormErrorBanner } from './components/form-error-banner';
@@ -7,6 +8,7 @@ export type {
   TextFieldProps,
   TextareaFieldProps,
   MaskedFieldProps,
+  DateFieldProps,
   ControlledFieldProps,
   ColorFieldProps,
 } from './fields.types';
diff --git a/apps/admin-frontend/src/shared/format/date.test.ts b/apps/admin-frontend/src/shared/format/date.test.ts
index e9bdb2bd..582a8fd0 100644
--- a/apps/admin-frontend/src/shared/format/date.test.ts
+++ b/apps/admin-frontend/src/shared/format/date.test.ts
@@ -1,17 +1,112 @@
 import { describe, expect, it } from 'vitest';
-import { todayInSaoPaulo } from './date';
+import {
+  daysInMonth,
+  formatMaskedDate,
+  isoToLocalDate,
+  localDateToIso,
+  maskDate,
+  parseMaskedDate,
+  todayLocal,
+} from './date';
 
-describe('todayInSaoPaulo', () => {
+describe('todayLocal', () => {
   it.each([
-    ['2026-10-02T15:00:00Z', '2026-10-02'],
-    ['2026-10-03T02:59:59Z', '2026-10-02'],
-    ['2026-10-03T03:00:00Z', '2026-10-03'],
-    ['2026-01-01T02:00:00Z', '2025-12-31'],
-  ] as const)('reads %s as the São Paulo calendar day %s', (instant, expected) => {
-    expect(todayInSaoPaulo(new Date(instant))).toBe(expected);
+    [new Date(2026, 9, 2, 12, 0), '2026-10-02'],
+    [new Date(2026, 9, 2, 23, 59, 59), '2026-10-02'],
+    [new Date(2026, 9, 3, 0, 0, 0), '2026-10-03'],
+    [new Date(2025, 11, 31, 23, 30), '2025-12-31'],
+    [new Date(2026, 0, 1, 0, 30), '2026-01-01'],
+  ] as const)('reads %s as the calendar day on the device, %s', (instant, expected) => {
+    expect(todayLocal(instant)).toBe(expected);
   });
 
   it('defaults to the current instant', () => {
-    expect(todayInSaoPaulo()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    expect(todayLocal()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+});
+
+describe('maskDate', () => {
+  it.each([
+    ['', ''],
+    ['1', '1'],
+    ['10', '10'],
+    ['103', '10/3'],
+    ['1003', '10/03'],
+    ['10032', '10/03/2'],
+    ['10032015', '10/03/2015'],
+    ['100320159999', '10/03/2015'],
+    ['10/03/2015', '10/03/2015'],
+    ['ab10-03', '10/03'],
+  ] as const)('masks %j as %j while typing', (typed, expected) => {
+    expect(maskDate(typed)).toBe(expected);
+  });
+});
+
+describe('parseMaskedDate', () => {
+  it.each([
+    ['10/03/2015', '2015-03-10'],
+    ['01/01/1900', '1900-01-01'],
+    ['29/02/2000', '2000-02-29'],
+    [' 05/12/1990 ', '1990-12-05'],
+  ] as const)('reads %j as %s', (masked, expected) => {
+    expect(parseMaskedDate(masked)).toBe(expected);
+  });
+
+  it.each([
+    '',
+    '10/03',
+    '10/03/15',
+    '31/02/2020',
+    '29/02/2001',
+    '00/10/2020',
+    '10/00/2020',
+    '10/13/2020',
+    '32/01/2020',
+    '10/03/0999',
+    'aa/bb/cccc',
+    '10-03-2015',
+  ])('rejects %j', (masked) => {
+    expect(parseMaskedDate(masked)).toBeNull();
+  });
+});
+
+describe('formatMaskedDate', () => {
+  it('writes an ISO date as dd/mm/aaaa', () => {
+    expect(formatMaskedDate('2015-03-10')).toBe('10/03/2015');
+    expect(formatMaskedDate('1900-01-01')).toBe('01/01/1900');
+  });
+
+  it('round-trips with parseMaskedDate', () => {
+    expect(parseMaskedDate(formatMaskedDate('2000-02-29'))).toBe('2000-02-29');
+  });
+});
+
+describe('local date conversion', () => {
+  it('turns an ISO date into the same calendar day in local time', () => {
+    const date = isoToLocalDate('1990-05-20');
+
+    expect(date.getFullYear()).toBe(1990);
+    expect(date.getMonth()).toBe(4);
+    expect(date.getDate()).toBe(20);
+  });
+
+  it.each(['1990-05-20', '2000-02-29', '1900-01-01', '2026-12-31'])(
+    'round-trips %s through a local Date',
+    (isoDate) => {
+      expect(localDateToIso(isoToLocalDate(isoDate))).toBe(isoDate);
+    },
+  );
+});
+
+describe('daysInMonth', () => {
+  it.each([
+    [2024, 2, 29],
+    [2025, 2, 28],
+    [1900, 2, 28],
+    [2000, 2, 29],
+    [2026, 4, 30],
+    [2026, 12, 31],
+  ] as const)('counts %i-%i as %i days', (year, month, expected) => {
+    expect(daysInMonth(year, month)).toBe(expected);
   });
 });
diff --git a/apps/admin-frontend/src/shared/format/date.ts b/apps/admin-frontend/src/shared/format/date.ts
index 3ee6d153..4a74908a 100644
--- a/apps/admin-frontend/src/shared/format/date.ts
+++ b/apps/admin-frontend/src/shared/format/date.ts
@@ -1,13 +1,49 @@
-const dateParts = new Intl.DateTimeFormat('pt-BR', {
-  timeZone: 'America/Sao_Paulo',
-  year: 'numeric',
-  month: '2-digit',
-  day: '2-digit',
-});
-
-export function todayInSaoPaulo(now: Date = new Date()): string {
-  const parts = Object.fromEntries(
-    dateParts.formatToParts(now).map((part) => [part.type, part.value]),
-  );
-  return `${parts['year']}-${parts['month']}-${parts['day']}`;
+const MASKED_LENGTH = 10;
+
+export function todayLocal(now: Date = new Date()): string {
+  return localDateToIso(now);
+}
+
+export function maskDate(value: string): string {
+  const digits = value.replace(/\D/g, '').slice(0, 8);
+
+  if (digits.length <= 2) return digits;
+  if (digits.length <= 4) return `${digits.slice(0, 2)}/${digits.slice(2)}`;
+  return `${digits.slice(0, 2)}/${digits.slice(2, 4)}/${digits.slice(4)}`;
+}
+
+export function parseMaskedDate(masked: string): string | null {
+  const value = masked.trim();
+  if (value.length !== MASKED_LENGTH) return null;
+
+  const [day, month, year] = value.split('/').map(Number);
+  if (day === undefined || month === undefined || year === undefined) return null;
+  if (!Number.isInteger(day) || !Number.isInteger(month) || !Number.isInteger(year)) return null;
+  if (year < 1000 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
+    return null;
+  }
+
+  return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
+}
+
+export function formatMaskedDate(isoDate: string): string {
+  const [year, month, day] = isoDate.split('-');
+  return `${day}/${month}/${year}`;
+}
+
+export function isoToLocalDate(isoDate: string): Date {
+  const [year = 0, month = 1, day = 1] = isoDate.split('-').map(Number);
+  return new Date(year, month - 1, day);
+}
+
+export function localDateToIso(date: Date): string {
+  return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1, 2)}-${pad(date.getDate(), 2)}`;
+}
+
+export function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+function pad(value: number, length: number): string {
+  return String(value).padStart(length, '0');
 }
diff --git a/apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx b/apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx
new file mode 100644
index 00000000..afb2afde
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx
@@ -0,0 +1,34 @@
+import * as React from 'react';
+import type { DayButton } from 'react-day-picker';
+import { cn } from '@/shared/lib/utils';
+import { Button } from '@/shared/ui/button';
+
+function CalendarDayButton({
+  className,
+  day,
+  modifiers,
+  ...props
+}: React.ComponentProps<typeof DayButton>) {
+  const ref = React.useRef<HTMLButtonElement>(null);
+
+  React.useEffect(() => {
+    if (modifiers.focused) ref.current?.focus();
+  }, [modifiers.focused]);
+
+  return (
+    <Button
+      ref={ref}
+      variant="ghost"
+      size="icon"
+      data-day={day.isoDate}
+      data-selected-single={modifiers.selected}
+      className={cn(
+        'relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { CalendarDayButton };
diff --git a/apps/admin-frontend/src/shared/ui/calendar/components/calendar-primitives.tsx b/apps/admin-frontend/src/shared/ui/calendar/components/calendar-primitives.tsx
new file mode 100644
index 00000000..dbc9376e
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/calendar/components/calendar-primitives.tsx
@@ -0,0 +1,17 @@
+import type { ChevronProps, RootProps } from 'react-day-picker';
+import { ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon } from 'lucide-react';
+import { cn } from '@/shared/lib/utils';
+
+function CalendarRoot({ className, rootRef, ...props }: RootProps) {
+  return <div data-slot="calendar" ref={rootRef} className={cn(className)} {...props} />;
+}
+
+function CalendarChevron({ className, orientation, ...props }: ChevronProps) {
+  if (orientation === 'left')
+    return <ChevronLeftIcon className={cn('size-4', className)} {...props} />;
+  if (orientation === 'right')
+    return <ChevronRightIcon className={cn('size-4', className)} {...props} />;
+  return <ChevronDownIcon className={cn('size-4', className)} {...props} />;
+}
+
+export { CalendarRoot, CalendarChevron };
diff --git a/apps/admin-frontend/src/shared/ui/calendar/index.tsx b/apps/admin-frontend/src/shared/ui/calendar/index.tsx
new file mode 100644
index 00000000..71360db6
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/calendar/index.tsx
@@ -0,0 +1,97 @@
+import * as React from 'react';
+import { DayPicker, getDefaultClassNames } from 'react-day-picker';
+import { ptBR } from 'react-day-picker/locale';
+import { cn } from '@/shared/lib/utils';
+import { buttonVariants } from '@/shared/ui/button';
+
+import { CalendarDayButton } from './components/calendar-day-button';
+import { CalendarChevron, CalendarRoot } from './components/calendar-primitives';
+
+function Calendar({
+  className,
+  classNames,
+  showOutsideDays = true,
+  captionLayout = 'label',
+  locale = ptBR,
+  ...props
+}: React.ComponentProps<typeof DayPicker>) {
+  const defaultClassNames = getDefaultClassNames();
+
+  return (
+    <DayPicker
+      showOutsideDays={showOutsideDays}
+      className={cn(
+        'group/calendar bg-background p-2 [--cell-radius:var(--radius-md)] [--cell-size:--spacing(7)] in-data-[slot=popover-content]:bg-transparent',
+        className,
+      )}
+      captionLayout={captionLayout}
+      locale={locale}
+      formatters={{
+        formatMonthDropdown: (date) => date.toLocaleString(locale.code, { month: 'short' }),
+      }}
+      classNames={{
+        root: cn('w-fit', defaultClassNames.root),
+        months: cn('relative flex flex-col gap-4 md:flex-row', defaultClassNames.months),
+        month: cn('flex w-full flex-col gap-4', defaultClassNames.month),
+        nav: cn(
+          'absolute inset-x-0 top-0 flex w-full items-center justify-between gap-1',
+          defaultClassNames.nav,
+        ),
+        button_previous: cn(
+          buttonVariants({ variant: 'ghost' }),
+          'size-(--cell-size) p-0 select-none aria-disabled:opacity-50',
+          defaultClassNames.button_previous,
+        ),
+        button_next: cn(
+          buttonVariants({ variant: 'ghost' }),
+          'size-(--cell-size) p-0 select-none aria-disabled:opacity-50',
+          defaultClassNames.button_next,
+        ),
+        month_caption: cn(
+          'flex h-(--cell-size) w-full items-center justify-center px-(--cell-size)',
+          defaultClassNames.month_caption,
+        ),
+        dropdowns: cn(
+          'flex h-(--cell-size) w-full items-center justify-center gap-1.5 text-sm font-medium',
+          defaultClassNames.dropdowns,
+        ),
+        dropdown_root: cn('relative rounded-(--cell-radius)', defaultClassNames.dropdown_root),
+        dropdown: cn('absolute inset-0 bg-popover opacity-0', defaultClassNames.dropdown),
+        caption_label: cn(
+          'font-medium select-none',
+          captionLayout === 'label'
+            ? 'text-sm'
+            : 'flex items-center gap-1 rounded-(--cell-radius) text-sm [&>svg]:size-3.5 [&>svg]:text-muted-foreground',
+          defaultClassNames.caption_label,
+        ),
+        month_grid: cn('w-full border-collapse', defaultClassNames.month_grid),
+        weekdays: cn('flex', defaultClassNames.weekdays),
+        weekday: cn(
+          'flex-1 rounded-(--cell-radius) text-[0.8rem] font-normal text-muted-foreground select-none',
+          defaultClassNames.weekday,
+        ),
+        week: cn('mt-2 flex w-full', defaultClassNames.week),
+        day: cn(
+          'group/day relative aspect-square h-full w-full rounded-(--cell-radius) p-0 text-center select-none',
+          defaultClassNames.day,
+        ),
+        today: cn('rounded-(--cell-radius) bg-muted text-foreground', defaultClassNames.today),
+        outside: cn(
+          'text-muted-foreground aria-selected:text-muted-foreground',
+          defaultClassNames.outside,
+        ),
+        disabled: cn('text-muted-foreground opacity-50', defaultClassNames.disabled),
+        hidden: cn('invisible', defaultClassNames.hidden),
+        ...classNames,
+      }}
+      components={{
+        Root: CalendarRoot,
+        Chevron: CalendarChevron,
+        DayButton: CalendarDayButton,
+      }}
+      {...props}
+    />
+  );
+}
+
+export { Calendar };
diff --git a/apps/admin-frontend/src/shared/ui/popover/components/popover-content.tsx b/apps/admin-frontend/src/shared/ui/popover/components/popover-content.tsx
new file mode 100644
index 00000000..38e7d8e6
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/popover/components/popover-content.tsx
@@ -0,0 +1,35 @@
+import { Popover as PopoverPrimitive } from '@base-ui/react/popover';
+import { cn } from '@/shared/lib/utils';
+
+function PopoverContent({
+  className,
+  align = 'center',
+  alignOffset = 0,
+  side = 'bottom',
+  sideOffset = 4,
+  ...props
+}: PopoverPrimitive.Popup.Props &
+  Pick<PopoverPrimitive.Positioner.Props, 'align' | 'alignOffset' | 'side' | 'sideOffset'>) {
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-50"
+      >
+        <PopoverPrimitive.Popup
+          data-slot="popover-content"
+          className={cn(
+            'z-50 flex w-72 origin-(--transform-origin) flex-col gap-2.5 rounded-lg bg-popover p-2.5 text-sm text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden transition data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0',
+            className,
+          )}
+          {...props}
+        />
+      </PopoverPrimitive.Positioner>
+    </PopoverPrimitive.Portal>
+  );
+}
+
+export { PopoverContent };
diff --git a/apps/admin-frontend/src/shared/ui/popover/components/popover-primitives.tsx b/apps/admin-frontend/src/shared/ui/popover/components/popover-primitives.tsx
new file mode 100644
index 00000000..14a7dfec
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/popover/components/popover-primitives.tsx
@@ -0,0 +1,7 @@
+import { Popover as PopoverPrimitive } from '@base-ui/react/popover';
+
+function PopoverTrigger({ ...props }: PopoverPrimitive.Trigger.Props) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
+}
+
+export { PopoverTrigger };
diff --git a/apps/admin-frontend/src/shared/ui/popover/index.tsx b/apps/admin-frontend/src/shared/ui/popover/index.tsx
new file mode 100644
index 00000000..30935cf1
--- /dev/null
+++ b/apps/admin-frontend/src/shared/ui/popover/index.tsx
@@ -0,0 +1,10 @@
+import { Popover as PopoverPrimitive } from '@base-ui/react/popover';
+
+import { PopoverTrigger } from './components/popover-primitives';
+import { PopoverContent } from './components/popover-content';
+
+function Popover({ ...props }: PopoverPrimitive.Root.Props) {
+  return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+}
+
+export { Popover, PopoverTrigger, PopoverContent };
diff --git a/package-lock.json b/package-lock.json
index f0fd41b5..01871c6b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -30,10 +30,12 @@
         "@hookform/resolvers": "^5.9.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
+        "date-fns": "^4.4.0",
         "lucide-react": "^1.41.0",
         "oidc-client-ts": "^3.3.0",
         "openapi-fetch": "^0.17.0",
         "react": "^19.2.7",
+        "react-day-picker": "^10.0.2",
         "react-dom": "^19.2.7",
         "react-hook-form": "^7.88.0",
         "react-router": "^8.3.0",
@@ -750,6 +752,12 @@
         "node": ">=20.19.0"
       }
     },
+    "node_modules/@date-fns/tz": {
+      "version": "1.5.0",
+      "resolved": "https://registry.npmjs.org/@date-fns/tz/-/tz-1.5.0.tgz",
+      "integrity": "sha512-lwYN/vDPeNRULcepoE/LO2Pgx+7/RV+S9ARfbc9lr2DtGkOD7pAiruHvbR1RX3Qyf6ja47EWJDMsNK5vK08DJg==",
+      "license": "MIT"
+    },
     "node_modules/@eslint-community/eslint-utils": {
       "version": "4.10.1",
       "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.10.1.tgz",
@@ -3057,6 +3065,16 @@
         "node": "^20.19.0 || ^22.12.0 || >=24.0.0"
       }
     },
+    "node_modules/date-fns": {
+      "version": "4.4.0",
+      "resolved": "https://registry.npmjs.org/date-fns/-/date-fns-4.4.0.tgz",
+      "integrity": "sha512-+1UMbeh68lH1SegH83CGWwpb6OHHbpSgr3+s5Eww5M4CAgswBpoWS0AjTOfEJ33HiYKz1hdj/KTFprzXHmq/6w==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/kossnocorp"
+      }
+    },
     "node_modules/debug": {
       "version": "4.4.3",
       "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
@@ -4675,6 +4693,32 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/react-day-picker": {
+      "version": "10.0.2",
+      "resolved": "https://registry.npmjs.org/react-day-picker/-/react-day-picker-10.0.2.tgz",
+      "integrity": "sha512-QetiKtZWE9Uaw/pM/SYNv6WPYOTRnSJ2puL0GgwkmUFMIwiY0dtjH1W4B7DOVXVNQM0ZOClGpH/heOfBSzWeiA==",
+      "license": "MIT",
+      "dependencies": {
+        "@date-fns/tz": "^1.4.1",
+        "date-fns": "^4.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "type": "individual",
+        "url": "https://github.com/sponsors/gpbl"
+      },
+      "peerDependencies": {
+        "@types/react": ">=16.8.0",
+        "react": ">=16.8.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/react-dom": {
       "version": "19.2.8",
       "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.8.tgz",

From 6be57e80e5caabc70d5de15b75f276d3087eeeaf Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 9 Oct 2026 11:00:48 -0300
Subject: [PATCH 06/30] =?UTF-8?q?fix(admin-frontend):=20ajustes=20de=20rev?=
 =?UTF-8?q?is=C3=A3o=20no=20seletor=20de=20data=20(#154)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- botão do calendário passa a se chamar "Abrir calendário", sem repetir o
  rótulo do campo: o getByLabel do Playwright compara por trecho e o e2e de
  menor de idade casaria com o botão e com o campo (strict mode violation)
- DateField respeita disabled e readOnly: botão e seta para baixo não abrem
  o calendário com o campo travado
- remove date-fns do package.json (o app não importa; vem via react-day-picker)
- atributo do dia selecionado renomeado para data-selected (não há mais modo
  de intervalo)
- docs: skill agenza-form-field e ARCHITECTURE.md citam o DateField

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .claude/skills/agenza-form-field/SKILL.md     |  4 +-
 apps/admin-frontend/docs/ARCHITECTURE.md      |  2 +-
 apps/admin-frontend/package.json              |  1 -
 .../ClientFormPage/ClientFormPage.test.tsx    |  8 +---
 .../fields/components/date-field.test.tsx     | 37 ++++++++++++++++++-
 .../form/fields/components/date-field.tsx     | 23 ++++++------
 .../components/calendar-day-button.tsx        |  4 +-
 package-lock.json                             |  1 -
 8 files changed, 53 insertions(+), 27 deletions(-)

diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index 79e6736c..08b54cdf 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -8,7 +8,7 @@ description: Use when building or changing a form in admin-frontend — wiring R
 `TagFormPage` (`src/features/tags/ui/pages/TagFormPage/`) is the reference implementation for a
 dialog form. `ClientFormPage` (`src/features/clients/ui/pages/ClientFormPage/`) is the second
 consumer and the reference for a full-page form with **field arrays** (`useFieldArray`, nested paths
-such as `guardians.${number}.name`), masked inputs (`MaskedField`) and a custom multi-value control
+such as `guardians.${number}.name`), masked inputs (`MaskedField`), a typed-or-picked date (`DateField`: mask plus calendar popover, bounded by `minDate`/`maxDate`) and a custom multi-value control
 (`CheckboxGroup` through a `ControlledField` render function). Read
 [`docs/ARCHITECTURE.md` §5](../../../apps/admin-frontend/docs/ARCHITECTURE.md) (the "Tag create/edit
 UI reintroduced on React Hook Form + Zod" row and the row right after it) for the decision history
@@ -27,7 +27,7 @@ and has no input to attach to: render it in the section.
 | --- | --- | --- |
 | Error mapping | `shared/api/formErrors.ts` | `toFormErrors<F>(problem, fields)` — `ApiProblem` → `{fieldErrors, formError}`. Knows `ApiProblem`, nothing about RHF. |
 | RHF bridge | `shared/form/applyApiProblem.ts` | `applyApiProblem<T>(problem, fields, setError)` — calls the above, then `setError` per field plus `setError('root.serverError', …)`. Knows both shapes; the only file that does. |
-| Field components | `shared/form/fields/` | `TextField`/`TextareaField`, `MaskedField`, `ControlledField`, `ColorField`, `FormErrorBanner` — RHF wiring, zero domain knowledge. They render into `shared/ui/form-field/`'s `FormField` (label, hint, error, the `aria-*` wiring), which stays presentational and RHF-free like the rest of `shared/ui/` (`agenza-ui-primitive`). |
+| Field components | `shared/form/fields/` | `TextField`/`TextareaField`, `MaskedField`, `DateField`, `ControlledField`, `ColorField`, `FormErrorBanner` — RHF wiring, zero domain knowledge. They render into `shared/ui/form-field/`'s `FormField` (label, hint, error, the `aria-*` wiring), which stays presentational and RHF-free like the rest of `shared/ui/` (`agenza-ui-primitive`). |
 
 Never let a field component or `shared/form/` read `problem.errors` directly — that parsing (indexed
 keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See `agenza-api-contract`'s
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 44a4875f..2966b353 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -384,7 +384,7 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict reads the existing record's id from the typed `FieldError.meta` and links to `/pessoas/{id}` in a new tab, so the typed values survive; that page arrives with #155. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
-| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` and `date-fns` added, plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (ISO strings): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date`, so `isoToLocalDate`/`localDateToIso` convert at the edge; the model keeps ISO strings. `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
+| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (ISO strings): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date`, so `isoToLocalDate`/`localDateToIso` convert at the edge; the model keeps ISO strings. `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/package.json b/apps/admin-frontend/package.json
index 6ef344ae..c48f5b42 100644
--- a/apps/admin-frontend/package.json
+++ b/apps/admin-frontend/package.json
@@ -22,7 +22,6 @@
     "@hookform/resolvers": "^5.9.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "date-fns": "^4.4.0",
     "lucide-react": "^1.41.0",
     "oidc-client-ts": "^3.3.0",
     "openapi-fetch": "^0.17.0",
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 12d961cc..f8597901 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -205,9 +205,7 @@ describe('ClientFormPage', () => {
       renderPage();
 
       await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
-      await user.click(
-        screen.getByRole('button', { name: 'Abrir calendário de data de nascimento' }),
-      );
+      await user.click(screen.getByRole('button', { name: 'Abrir calendário' }));
       const calendar = await screen.findByRole('dialog');
       await user.selectOptions(
         within(calendar).getByRole('combobox', { name: 'Escolha o ano' }),
@@ -232,9 +230,7 @@ describe('ClientFormPage', () => {
       const user = userEvent.setup();
       renderPage();
 
-      await user.click(
-        screen.getByRole('button', { name: 'Abrir calendário de data de nascimento' }),
-      );
+      await user.click(screen.getByRole('button', { name: 'Abrir calendário' }));
       const calendar = await screen.findByRole('dialog');
 
       expect(
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
index 7c923608..ec02e2c2 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
@@ -8,7 +8,13 @@ interface DummyValues {
   birthDate: string;
 }
 
-function Harness({ initial = '' }: { initial?: string }) {
+interface HarnessProps {
+  initial?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+}
+
+function Harness({ initial = '', disabled = false, readOnly = false }: HarnessProps) {
   const methods = useForm<DummyValues>({ defaultValues: { birthDate: initial } });
 
   return (
@@ -19,6 +25,8 @@ function Harness({ initial = '' }: { initial?: string }) {
         hint="opcional"
         minDate="1990-01-01"
         maxDate="2026-10-01"
+        disabled={disabled}
+        readOnly={readOnly}
       />
       <CurrentValue />
     </FormProvider>
@@ -35,8 +43,12 @@ function input() {
   return screen.getByLabelText('Data de nascimento');
 }
 
+function calendarButton() {
+  return screen.getByRole('button', { name: 'Abrir calendário' });
+}
+
 async function openCalendar(user: ReturnType<typeof userEvent.setup>) {
-  await user.click(screen.getByRole('button', { name: 'Abrir calendário de data de nascimento' }));
+  await user.click(calendarButton());
   return screen.findByRole('dialog');
 }
 
@@ -58,6 +70,27 @@ describe('DateField', () => {
     expect(input()).toHaveAttribute('inputmode', 'numeric');
   });
 
+  it('names the calendar button without repeating the field label, so the label still finds one control', () => {
+    render(<Harness />);
+
+    expect(calendarButton()).not.toHaveAccessibleName(/data de nascimento/i);
+    expect(screen.getAllByLabelText(/data de nascimento/i)).toHaveLength(1);
+  });
+
+  it.each([['disabled'], ['readOnly']] as const)(
+    'does not open the calendar from the button or the arrow key while the field is %s',
+    async (mode) => {
+      const user = userEvent.setup();
+      render(<Harness {...{ [mode]: true }} />);
+
+      expect(calendarButton()).toBeDisabled();
+      await user.click(input());
+      await user.keyboard('{ArrowDown}');
+
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    },
+  );
+
   it('keeps the calendar closed until it is asked for', () => {
     render(<Harness />);
 
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
index dc761d23..8227bd75 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
@@ -20,7 +20,7 @@ import { Popover, PopoverContent, PopoverTrigger } from '@/shared/ui/popover';
 import type { DateFieldProps } from '../fields.types';
 import { ControlledField } from './controlled-field';
 
-type DateFieldControlProps = Omit<DateFieldProps<FieldValues>, 'hint'> &
+type DateFieldControlProps = Omit<DateFieldProps<FieldValues>, 'hint' | 'label'> &
   FormFieldControlProps & {
     value: unknown;
     inputRef: Ref<HTMLInputElement>;
@@ -40,7 +40,6 @@ export function DateField<T extends FieldValues>({
         <DateFieldControl
           {...rest}
           {...controlProps}
-          label={label}
           name={field.name}
           value={field.value}
           inputRef={field.ref}
@@ -53,7 +52,6 @@ export function DateField<T extends FieldValues>({
 }
 
 function DateFieldControl({
-  label,
   value: fieldValue,
   inputRef,
   onChange,
@@ -63,11 +61,15 @@ function DateFieldControl({
   ...inputProps
 }: DateFieldControlProps) {
   const [open, setOpen] = useState(false);
+  const { disabled, readOnly } = inputProps;
+  const isLocked = Boolean(disabled || readOnly);
 
   const value = typeof fieldValue === 'string' ? fieldValue : '';
   const typedDate = parseMaskedDate(value);
   const isSelectable = typedDate !== null && typedDate >= minDate && typedDate <= maxDate;
   const selected = isSelectable ? isoToLocalDate(typedDate) : undefined;
+  const firstDay = isoToLocalDate(minDate);
+  const lastDay = isoToLocalDate(maxDate);
 
   function selectDate(date: Date) {
     onChange(formatMaskedDate(localDateToIso(date)));
@@ -75,7 +77,7 @@ function DateFieldControl({
   }
 
   function openOnArrowDown(event: KeyboardEvent<HTMLInputElement>) {
-    if (event.key !== 'ArrowDown') return;
+    if (event.key !== 'ArrowDown' || isLocked) return;
     event.preventDefault();
     setOpen(true);
   }
@@ -95,10 +97,7 @@ function DateFieldControl({
         <InputGroupAddon align="inline-end">
           <PopoverTrigger
             render={
-              <InputGroupButton
-                size="icon-xs"
-                aria-label={`Abrir calendário de ${label.toLowerCase()}`}
-              />
+              <InputGroupButton size="icon-xs" aria-label="Abrir calendário" disabled={isLocked} />
             }
           >
             <CalendarIcon aria-hidden="true" />
@@ -117,10 +116,10 @@ function DateFieldControl({
             autoFocus
             captionLayout="dropdown"
             selected={selected}
-            defaultMonth={selected ?? isoToLocalDate(maxDate)}
-            startMonth={isoToLocalDate(minDate)}
-            endMonth={isoToLocalDate(maxDate)}
-            disabled={[{ before: isoToLocalDate(minDate) }, { after: isoToLocalDate(maxDate) }]}
+            defaultMonth={selected ?? lastDay}
+            startMonth={firstDay}
+            endMonth={lastDay}
+            disabled={[{ before: firstDay }, { after: lastDay }]}
             onSelect={selectDate}
           />
         </PopoverContent>
diff --git a/apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx b/apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx
index afb2afde..a93d9cfa 100644
--- a/apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx
+++ b/apps/admin-frontend/src/shared/ui/calendar/components/calendar-day-button.tsx
@@ -21,9 +21,9 @@ function CalendarDayButton({
       variant="ghost"
       size="icon"
       data-day={day.isoDate}
-      data-selected-single={modifiers.selected}
+      data-selected={modifiers.selected}
       className={cn(
-        'relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[selected-single=true]:bg-primary data-[selected-single=true]:text-primary-foreground dark:hover:text-foreground',
+        'relative isolate z-10 flex aspect-square size-auto w-full min-w-(--cell-size) flex-col gap-1 border-0 leading-none font-normal group-data-[focused=true]/day:relative group-data-[focused=true]/day:z-10 group-data-[focused=true]/day:border-ring group-data-[focused=true]/day:ring-[3px] group-data-[focused=true]/day:ring-ring/50 data-[selected=true]:bg-primary data-[selected=true]:text-primary-foreground dark:hover:text-foreground',
         className,
       )}
       {...props}
diff --git a/package-lock.json b/package-lock.json
index 01871c6b..39f0a753 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -30,7 +30,6 @@
         "@hookform/resolvers": "^5.9.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
-        "date-fns": "^4.4.0",
         "lucide-react": "^1.41.0",
         "oidc-client-ts": "^3.3.0",
         "openapi-fetch": "^0.17.0",

From c98a6ba3bea91e735a2d103967ed867a3a9ad003 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 9 Oct 2026 13:10:32 -0300
Subject: [PATCH 07/30] docs(admin-frontend): trecho verbatim de toFormErrors
 usa toFieldPath
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

O trecho marcado como verbatim em agenza-api-contract/references/errors.md
ainda buscava o campo com key.toLowerCase(); o código real normaliza o índice
de lista com toFieldPath (guardians[1].name -> guardians.1.name). O trecho
agora inclui o helper e o usa na busca.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .claude/skills/agenza-api-contract/references/errors.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.claude/skills/agenza-api-contract/references/errors.md b/.claude/skills/agenza-api-contract/references/errors.md
index a19c91f0..42dd5dc0 100644
--- a/.claude/skills/agenza-api-contract/references/errors.md
+++ b/.claude/skills/agenza-api-contract/references/errors.md
@@ -100,6 +100,8 @@ speculative. Revisit if a real case needs multiple messages per field; don't bui
 
 ```ts
 // shared/api/formErrors.ts (verbatim)
+const toFieldPath = (key: string) => key.replace(/\[(\d+)\]/g, '.$1').toLowerCase();
+
 export function toFormErrors<F extends string>(
   problem: ApiProblem,
   fields: readonly F[],
@@ -111,7 +113,7 @@ export function toFormErrors<F extends string>(
   for (const [key, entries] of Object.entries(problem.errors ?? {})) {
     const message = entries[0]?.message;
     if (!message) continue;
-    const field = byField.get(key.toLowerCase());
+    const field = byField.get(toFieldPath(key));
     if (field) fieldErrors[field] = message;
     else formLevel.push(message);
   }

From ebc59b0cc5266fff8f3b08fea84e9148cd169174 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 9 Oct 2026 18:42:20 -0300
Subject: [PATCH 08/30] asdasd

---
 .../agenza-api-contract/references/errors.md  |  4 +-
 apps/admin-frontend/docs/ARCHITECTURE.md      |  2 +-
 apps/admin-frontend/e2e/clients.spec.ts       |  6 +-
 .../clients/api/existingClientId.test.ts      | 63 -------------------
 .../features/clients/api/existingClientId.ts  | 16 -----
 .../ClientFormPage/ClientFormPage.test.tsx    | 41 +-----------
 .../pages/ClientFormPage/ClientFormPage.tsx   |  3 +-
 .../components/ClientPersonSection.tsx        | 36 +++--------
 .../pages/ClientFormPage/useClientFormPage.ts | 10 +--
 .../ClientFormPage/useClientFormPage.types.ts |  1 -
 10 files changed, 18 insertions(+), 164 deletions(-)
 delete mode 100644 apps/admin-frontend/src/features/clients/api/existingClientId.test.ts
 delete mode 100644 apps/admin-frontend/src/features/clients/api/existingClientId.ts

diff --git a/.claude/skills/agenza-api-contract/references/errors.md b/.claude/skills/agenza-api-contract/references/errors.md
index 42dd5dc0..465fe7b4 100644
--- a/.claude/skills/agenza-api-contract/references/errors.md
+++ b/.claude/skills/agenza-api-contract/references/errors.md
@@ -75,8 +75,8 @@ different ways** (`ApiProblemDetailsFactory`):
 
 `meta` is an optional string map on one entry, absent when empty. It carries context for the client,
 never prose: the CPF and e-mail conflicts put `clientId` and `clientName` there, and the record can always
-be opened because neither conflict matches a deleted person. The CPF one is read in
-`features/clients/api/existingClientId.ts`. Branch on the entry's `code` before trusting a `meta` key.
+be opened because neither conflict matches a deleted person. Branch on the entry's `code` before
+trusting a `meta` key.
 
 Authorization and unexpected problems carry an empty `errors` object, never `null` in practice —
 but the type says nullable, so guard anyway.
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 2966b353..713fd5cd 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -383,7 +383,7 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | Review fixes on the tag dialogs (PR #125) | Two defects, one line of reasoning each. (1) `useRouteScrollReset` keys on the **section** (first path segment), not the whole `pathname`: `new`, `:id/edit` and `:id/delete` are child routes of `/tags`, so every dialog open/close used to reset `<main>`'s scroll and throw the list back to the top. (2) `useTagFormPage.onValid` and `ConfirmDialog.handleConfirm` skip closing when the dialog already unmounted mid-request (browser Back): react-router's `useNavigate` stays live after unmount, so the stale `navigate(-1)` used to pop one entry too many — out of the app, when `/tags` was the tab's first entry. FR-018 still does not block browser Back; no `useBlocker`, since the request finishes anyway and the toast still reports it. Deliberately left as is, both judged not worth the code: a row someone else already removed stays listed after its `Tag.NotFound` until the next reload or search — the spec's edge case only asks for the "não encontrada" message, which already shows; and `TagDeletePage` keeps its loaded tag if `:id` changed without a remount, because no UI path goes from `/tags/A/delete` straight to `/tags/B/delete` — the modal blocks the list, and closing it goes back to `/tags` first. A `key={id}` on the confirmation is the fix if a flow like "excluir a próxima" ever appears. |
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
-| `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict reads the existing record's id from the typed `FieldError.meta` and links to `/pessoas/{id}` in a new tab, so the typed values survive; that page arrives with #155. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
+| `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
 | `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (ISO strings): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date`, so `isoToLocalDate`/`localDateToIso` convert at the edge; the model keeps ISO strings. `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
diff --git a/apps/admin-frontend/e2e/clients.spec.ts b/apps/admin-frontend/e2e/clients.spec.ts
index b519903d..d60fa01d 100644
--- a/apps/admin-frontend/e2e/clients.spec.ts
+++ b/apps/admin-frontend/e2e/clients.spec.ts
@@ -77,7 +77,7 @@ test.describe('Register a person', () => {
     await expect(page.getByText('Pessoa cadastrada')).toBeVisible();
   });
 
-  test('refuses a CPF that already belongs to someone and offers the existing record', async ({
+  test('refuses a CPF that already belongs to someone and keeps what was typed', async ({
     page,
   }) => {
     const cpf = validCpf();
@@ -97,9 +97,5 @@ test.describe('Register a person', () => {
     await expect(person.getByText('Já existe uma pessoa cadastrada com este CPF.')).toBeVisible();
     await expect(person.getByLabel('Nome completo')).toHaveValue(secondName);
     await expect(page).toHaveURL(/\/pessoas\/nova$/);
-    await expect(person.getByRole('link', { name: /Abrir cadastro existente/ })).toHaveAttribute(
-      'href',
-      /\/pessoas\/[0-9a-f-]{36}$/,
-    );
   });
 });
diff --git a/apps/admin-frontend/src/features/clients/api/existingClientId.test.ts b/apps/admin-frontend/src/features/clients/api/existingClientId.test.ts
deleted file mode 100644
index 8508bff9..00000000
--- a/apps/admin-frontend/src/features/clients/api/existingClientId.test.ts
+++ /dev/null
@@ -1,63 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import type { ApiProblem } from '@/shared/api/servicesFacade';
-import { existingClientIdFrom } from './existingClientId';
-
-const EXISTING_ID = '0197f2a0-0000-7000-8000-000000000001';
-
-describe('existingClientIdFrom', () => {
-  it('reads the id of the client that already owns the CPF', () => {
-    const problem: ApiProblem = {
-      status: 409,
-      code: 'Client.DuplicateCpf',
-      errors: {
-        Cpf: [
-          {
-            code: 'Client.DuplicateCpf',
-            message: 'Já existe uma pessoa cadastrada com este CPF.',
-            meta: { clientId: EXISTING_ID },
-          },
-        ],
-      },
-    };
-
-    expect(existingClientIdFrom(problem)).toBe(EXISTING_ID);
-  });
-
-  it('has nothing to open when the CPF belongs to a deleted client', () => {
-    const problem: ApiProblem = {
-      status: 409,
-      code: 'Client.DuplicateCpf',
-      errors: {
-        Cpf: [
-          { code: 'Client.DuplicateCpf', message: 'Este CPF pertence a um cadastro excluído.' },
-        ],
-      },
-    };
-
-    expect(existingClientIdFrom(problem)).toBeNull();
-  });
-
-  it('ignores a conflict that is not about the CPF', () => {
-    const problem: ApiProblem = {
-      status: 409,
-      code: 'Client.DuplicateEmail',
-      errors: {
-        Email: [
-          { code: 'Client.DuplicateEmail', message: 'Já existe.', meta: { clientId: EXISTING_ID } },
-        ],
-      },
-    };
-
-    expect(existingClientIdFrom(problem)).toBeNull();
-  });
-
-  it.each([
-    ['no errors at all', { status: 0, title: 'Sem conexão.' } satisfies ApiProblem],
-    [
-      'a form-level error',
-      { status: 409, errors: { '': [{ message: 'Conflito.' }] } } satisfies ApiProblem,
-    ],
-  ])('returns null for %s', (_name, problem) => {
-    expect(existingClientIdFrom(problem)).toBeNull();
-  });
-});
diff --git a/apps/admin-frontend/src/features/clients/api/existingClientId.ts b/apps/admin-frontend/src/features/clients/api/existingClientId.ts
deleted file mode 100644
index 53a77001..00000000
--- a/apps/admin-frontend/src/features/clients/api/existingClientId.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-import type { ApiProblem } from '@/shared/api/servicesFacade';
-
-const DUPLICATE_CPF_CODE = 'Client.DuplicateCpf';
-const CPF_FIELD = 'cpf';
-const CLIENT_ID_KEY = 'clientId';
-
-export function existingClientIdFrom(problem: ApiProblem): string | null {
-  for (const [field, errors] of Object.entries(problem.errors ?? {})) {
-    if (field.toLowerCase() !== CPF_FIELD) continue;
-
-    const conflict = errors.find((error) => error.code === DUPLICATE_CPF_CODE);
-    return conflict?.meta?.[CLIENT_ID_KEY] ?? null;
-  }
-
-  return null;
-}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index f8597901..d0b15914 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -13,8 +13,6 @@ vi.mock('../../../api/clientsRepository', () => ({
   clientsRepository: { create: mockCreate },
 }));
 
-const EXISTING_ID = '0197f2a0-0000-7000-8000-000000000001';
-
 const CREATED: Client = {
   id: '0197f2a0-0000-7000-8000-0000000000aa',
   fullName: 'Maria Souza',
@@ -522,7 +520,7 @@ describe('ClientFormPage', () => {
       await user.click(screen.getByRole('button', { name: 'Salvar' }));
     }
 
-    it('shows the duplicate CPF message on the CPF field, focuses it and offers the existing record', async () => {
+    it('shows the duplicate CPF message on the CPF field and focuses it', async () => {
       const user = userEvent.setup();
       mockCreate.mockResolvedValue(
         problem({
@@ -534,7 +532,6 @@ describe('ClientFormPage', () => {
               {
                 code: 'Client.DuplicateCpf',
                 message: 'Já existe uma pessoa cadastrada com este CPF.',
-                meta: { clientId: EXISTING_ID },
               },
             ],
           },
@@ -549,43 +546,12 @@ describe('ClientFormPage', () => {
       ).toBeInTheDocument();
       expect(screen.getByLabelText('CPF')).toHaveAttribute('aria-invalid', 'true');
       await waitFor(() => expect(screen.getByLabelText('CPF')).toHaveFocus());
-      const link = screen.getByRole('link', { name: /Abrir cadastro existente/ });
-      expect(link).toHaveAttribute('href', `/pessoas/${EXISTING_ID}`);
-      expect(link).toHaveAttribute('target', '_blank');
       expect(screen.getByLabelText('Nome completo')).toHaveValue('Maria Souza');
       expect(screen.getByLabelText('E-mail')).toHaveValue('maria@example.com');
       expect(screen.getByTestId('location')).toHaveTextContent('/pessoas/nova');
     });
 
-    it('stops offering the existing record once the CPF is changed', async () => {
-      const user = userEvent.setup();
-      mockCreate.mockResolvedValue(
-        problem({
-          status: 409,
-          code: 'Client.DuplicateCpf',
-          errors: {
-            Cpf: [
-              {
-                code: 'Client.DuplicateCpf',
-                message: 'Já existe uma pessoa cadastrada com este CPF.',
-                meta: { clientId: EXISTING_ID },
-              },
-            ],
-          },
-        }),
-      );
-      renderPage();
-      await fillAndSubmit(user);
-      await screen.findByRole('link', { name: /Abrir cadastro existente/ });
-
-      await user.type(screen.getByLabelText('CPF'), '{Backspace}');
-
-      expect(
-        screen.queryByRole('link', { name: /Abrir cadastro existente/ }),
-      ).not.toBeInTheDocument();
-    });
-
-    it('explains a CPF that belongs to a deleted record, with nothing to open', async () => {
+    it('explains a CPF that belongs to a deleted record', async () => {
       const user = userEvent.setup();
       mockCreate.mockResolvedValue(
         problem({
@@ -607,9 +573,6 @@ describe('ClientFormPage', () => {
       await fillAndSubmit(user);
 
       expect(await screen.findByText(/pertence a um cadastro excluído/)).toBeInTheDocument();
-      expect(
-        screen.queryByRole('link', { name: /Abrir cadastro existente/ }),
-      ).not.toBeInTheDocument();
     });
 
     it('shows a duplicate e-mail on the e-mail field and keeps everything typed', async () => {
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
index 0156d3da..7735e0ea 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -16,7 +16,6 @@ export function ClientFormPage() {
     referenceContacts,
     age,
     isMinor,
-    existingClientId,
     isSaving,
     addGuardianButtonRef,
     onSubmit,
@@ -29,7 +28,7 @@ export function ClientFormPage() {
       <PageHeader parents={PAGE_PARENTS} title="Nova pessoa" />
       <FormProvider {...methods}>
         <form onSubmit={onSubmit} noValidate className="space-y-6">
-          <ClientPersonSection age={age} existingClientId={existingClientId} />
+          <ClientPersonSection age={age} />
           <ClientGuardiansSection
             fieldIds={guardians.fields.map((field) => field.id)}
             isMinor={isMinor}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index fdfa5aec..1e3f74fc 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,7 +1,5 @@
-import { Link } from 'react-router';
 import { todayLocal } from '@/shared/format/date';
 import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
-import { buttonVariants } from '@/shared/ui/button';
 import { earliestBirthDate, formatAge, latestBirthDate } from '../../../../model/birthDate';
 import {
   CLIENT_NAME_MAX_LENGTH,
@@ -14,10 +12,9 @@ import { ClientFormSection } from './ClientFormSection';
 
 interface ClientPersonSectionProps {
   age: number | null;
-  existingClientId: string | null;
 }
 
-function ClientPersonSection({ age, existingClientId }: ClientPersonSectionProps) {
+function ClientPersonSection({ age }: ClientPersonSectionProps) {
   const today = todayLocal();
 
   return (
@@ -63,28 +60,15 @@ function ClientPersonSection({ age, existingClientId }: ClientPersonSectionProps
           autoComplete="off"
         />
 
-        <div className="space-y-1.5">
-          <MaskedField<ClientFormFieldValues>
-            name="cpf"
-            label="CPF"
-            hint="opcional"
-            mask={formatCpf}
-            inputMode="numeric"
-            placeholder="000.000.000-00"
-            autoComplete="off"
-          />
-          {existingClientId && (
-            <Link
-              to={`/pessoas/${existingClientId}`}
-              target="_blank"
-              rel="noreferrer"
-              className={buttonVariants({ variant: 'link', size: 'sm' })}
-            >
-              Abrir cadastro existente
-              <span className="sr-only"> (abre em outra aba)</span>
-            </Link>
-          )}
-        </div>
+        <MaskedField<ClientFormFieldValues>
+          name="cpf"
+          label="CPF"
+          hint="opcional"
+          mask={formatCpf}
+          inputMode="numeric"
+          placeholder="000.000.000-00"
+          autoComplete="off"
+        />
 
         <div className="space-y-1.5 md:col-span-2">
           <TextareaField<ClientFormFieldValues>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index 0b824905..8535478d 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -1,4 +1,4 @@
-import { useEffect, useRef, useState, type SubmitEvent } from 'react';
+import { useEffect, useRef, type SubmitEvent } from 'react';
 import { useNavigate } from 'react-router';
 import { useFieldArray, useForm, useWatch, type FieldErrors, type Path } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
@@ -6,7 +6,6 @@ import { toFormErrors } from '@/shared/api/formErrors';
 import { applyApiProblem } from '@/shared/form/applyApiProblem';
 import { toast } from '@/shared/ui/toast';
 import { clientsRepository } from '../../../api/clientsRepository';
-import { existingClientIdFrom } from '../../../api/existingClientId';
 import { ADULT_AGE_IN_YEARS } from '../../../model/birthDate';
 import {
   CLIENT_FORM_FIELDS,
@@ -40,7 +39,6 @@ export function useClientFormPage(): UseClientFormPageResult {
   const navigate = useNavigate();
   const isMountedRef = useRef(true);
   const addGuardianButtonRef = useRef<HTMLButtonElement>(null);
-  const [conflict, setConflict] = useState<{ cpf: string; clientId: string } | null>(null);
 
   const methods = useForm<ClientFormFieldValues, unknown, ClientFormValues>({
     resolver: zodResolver(clientFormSchema),
@@ -49,12 +47,10 @@ export function useClientFormPage(): UseClientFormPageResult {
   const guardians = useFieldArray({ control: methods.control, name: 'guardians' });
   const referenceContacts = useFieldArray({ control: methods.control, name: 'referenceContacts' });
   const birthDate = useWatch({ control: methods.control, name: 'birthDate' });
-  const cpf = useWatch({ control: methods.control, name: 'cpf' });
 
   const isSaving = methods.formState.isSubmitting;
   const age = ageFromBirthDate(birthDate);
   const isMinor = age !== null && age < ADULT_AGE_IN_YEARS;
-  const existingClientId = conflict?.cpf === cpf ? conflict.clientId : null;
 
   useEffect(() => {
     isMountedRef.current = true;
@@ -79,9 +75,6 @@ export function useClientFormPage(): UseClientFormPageResult {
     const paths = fieldPathsOf(methods.getValues());
     applyApiProblem<ClientFormFieldValues>(result.error, paths, methods.setError);
 
-    const clientId = existingClientIdFrom(result.error);
-    setConflict(clientId ? { cpf: methods.getValues('cpf'), clientId } : null);
-
     const { fieldErrors } = toFormErrors(result.error, paths);
     const firstInvalid = paths.find((path) => fieldErrors[path]);
     if (firstInvalid) methods.setFocus(firstInvalid);
@@ -103,7 +96,6 @@ export function useClientFormPage(): UseClientFormPageResult {
     referenceContacts,
     age,
     isMinor,
-    existingClientId,
     isSaving,
     addGuardianButtonRef,
     onSubmit: submit,
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
index 39d10767..7c0a4c6a 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
@@ -8,7 +8,6 @@ export interface UseClientFormPageResult {
   referenceContacts: UseFieldArrayReturn<ClientFormFieldValues, 'referenceContacts'>;
   age: number | null;
   isMinor: boolean;
-  existingClientId: string | null;
   isSaving: boolean;
   addGuardianButtonRef: RefObject<HTMLButtonElement | null>;
   onSubmit: (event: SubmitEvent<HTMLFormElement>) => void;

From 36df7cb655e6d1aae59d1e08e983b922ce942153 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Fri, 9 Oct 2026 18:49:29 -0300
Subject: [PATCH 09/30] asd

---
 apps/admin-frontend/docs/ARCHITECTURE.md      |  1 +
 .../features/clients/model/birthDate.test.ts  | 23 --------------
 .../src/features/clients/model/birthDate.ts   | 27 ++---------------
 .../src/features/clients/model/clientForm.ts  |  5 ++--
 .../src/shared/format/date.test.ts            | 30 +++++++++++++++++++
 apps/admin-frontend/src/shared/format/date.ts | 20 +++++++++++++
 6 files changed, 56 insertions(+), 50 deletions(-)

diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 713fd5cd..18488ad9 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -385,6 +385,7 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
 | `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (ISO strings): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date`, so `isoToLocalDate`/`localDateToIso` convert at the edge; the model keeps ISO strings. `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
+| Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `features/clients/model/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two ISO dates, so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test `fullYearsBetween('2008-02-29', '2026-02-28') === 18` is that contract. Months and days are not generalised: nothing needs them yet. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
index 22e6bfbd..6d6568f0 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
@@ -1,6 +1,5 @@
 import { describe, expect, it } from 'vitest';
 import {
-  calculateAge,
   earliestBirthDate,
   formatAge,
   isInThePast,
@@ -11,28 +10,6 @@ import {
 
 const TODAY = '2026-10-02';
 
-describe('calculateAge', () => {
-  it.each([
-    ['2008-10-02', 18],
-    ['2008-10-03', 17],
-    ['2008-10-01', 18],
-    ['2026-10-01', 0],
-    ['2000-02-29', 26],
-    ['1906-10-02', 120],
-    ['1906-10-03', 119],
-    ['1905-10-02', 121],
-  ] as const)('counts completed years for %s as %i', (birthDate, expected) => {
-    expect(calculateAge(birthDate, TODAY)).toBe(expected);
-  });
-
-  it('treats a leap-day birthday as February 28 in common years, like the backend', () => {
-    expect(calculateAge('2008-02-29', '2026-02-27')).toBe(17);
-    expect(calculateAge('2008-02-29', '2026-02-28')).toBe(18);
-    expect(calculateAge('2008-02-29', '2028-02-28')).toBe(19);
-    expect(calculateAge('2008-02-29', '2028-02-29')).toBe(20);
-  });
-});
-
 describe('birth date rules', () => {
   it('requires a date strictly in the past', () => {
     expect(isInThePast('2026-10-01', TODAY)).toBe(true);
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.ts b/apps/admin-frontend/src/features/clients/model/birthDate.ts
index 8f6b00fe..49438dcd 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.ts
@@ -1,34 +1,18 @@
-import { daysInMonth, isoToLocalDate, localDateToIso } from '@/shared/format/date';
+import { fullYearsBetween, isoToLocalDate, localDateToIso } from '@/shared/format/date';
 
 export const ADULT_AGE_IN_YEARS = 18;
 export const MAX_AGE_IN_YEARS = 120;
 
-export function calculateAge(birthDate: string, today: string): number {
-  const birth = toParts(birthDate);
-  const current = toParts(today);
-
-  const age = current.year - birth.year;
-  const birthdayThisYear = {
-    month: birth.month,
-    day: Math.min(birth.day, daysInMonth(current.year, birth.month)),
-  };
-  const hadBirthday =
-    current.month > birthdayThisYear.month ||
-    (current.month === birthdayThisYear.month && current.day >= birthdayThisYear.day);
-
-  return hadBirthday ? age : age - 1;
-}
-
 export function isInThePast(birthDate: string, today: string): boolean {
   return birthDate < today;
 }
 
 export function isWithinMaxAge(birthDate: string, today: string): boolean {
-  return calculateAge(birthDate, today) <= MAX_AGE_IN_YEARS;
+  return fullYearsBetween(birthDate, today) <= MAX_AGE_IN_YEARS;
 }
 
 export function isMinorOn(birthDate: string, today: string): boolean {
-  return isInThePast(birthDate, today) && calculateAge(birthDate, today) < ADULT_AGE_IN_YEARS;
+  return isInThePast(birthDate, today) && fullYearsBetween(birthDate, today) < ADULT_AGE_IN_YEARS;
 }
 
 export function latestBirthDate(today: string): string {
@@ -46,8 +30,3 @@ export function formatAge(age: number): string {
   if (age < 1) return 'menos de 1 ano';
   return age === 1 ? '1 ano' : `${age} anos`;
 }
-
-function toParts(isoDate: string): { year: number; month: number; day: number } {
-  const [year = 0, month = 0, day = 0] = isoDate.split('-').map(Number);
-  return { year, month, day };
-}
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index 0b3536b9..a3dbc4a7 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -1,9 +1,8 @@
 import { z } from 'zod';
-import { parseMaskedDate, todayLocal } from '@/shared/format/date';
+import { fullYearsBetween, parseMaskedDate, todayLocal } from '@/shared/format/date';
 import {
   ADULT_AGE_IN_YEARS,
   MAX_AGE_IN_YEARS,
-  calculateAge,
   isInThePast,
   isMinorOn,
   isWithinMaxAge,
@@ -178,5 +177,5 @@ export function ageFromBirthDate(masked: string): number | null {
     return null;
   }
 
-  return calculateAge(birthDate, today);
+  return fullYearsBetween(birthDate, today);
 }
diff --git a/apps/admin-frontend/src/shared/format/date.test.ts b/apps/admin-frontend/src/shared/format/date.test.ts
index 582a8fd0..b87a80a4 100644
--- a/apps/admin-frontend/src/shared/format/date.test.ts
+++ b/apps/admin-frontend/src/shared/format/date.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import {
   daysInMonth,
   formatMaskedDate,
+  fullYearsBetween,
   isoToLocalDate,
   localDateToIso,
   maskDate,
@@ -110,3 +111,32 @@ describe('daysInMonth', () => {
     expect(daysInMonth(year, month)).toBe(expected);
   });
 });
+
+describe('fullYearsBetween', () => {
+  it.each([
+    ['2008-10-02', '2026-10-02', 18],
+    ['2008-10-03', '2026-10-02', 17],
+    ['2008-10-01', '2026-10-02', 18],
+    ['2026-10-01', '2026-10-02', 0],
+    ['2026-10-02', '2026-10-02', 0],
+    ['2000-02-29', '2026-10-02', 26],
+    ['1906-10-02', '2026-10-02', 120],
+    ['1906-10-03', '2026-10-02', 119],
+    ['1905-10-02', '2026-10-02', 121],
+  ] as const)('counts the completed years from %s to %s as %i', (from, to, expected) => {
+    expect(fullYearsBetween(from, to)).toBe(expected);
+  });
+
+  it('moves a February 29 anniversary to February 28 in common years, like the backend', () => {
+    expect(fullYearsBetween('2008-02-29', '2026-02-27')).toBe(17);
+    expect(fullYearsBetween('2008-02-29', '2026-02-28')).toBe(18);
+    expect(fullYearsBetween('2008-02-29', '2028-02-28')).toBe(19);
+    expect(fullYearsBetween('2008-02-29', '2028-02-29')).toBe(20);
+  });
+
+  it('counts below zero when the end comes before the start', () => {
+    expect(fullYearsBetween('2026-10-03', '2026-10-02')).toBe(-1);
+    expect(fullYearsBetween('2026-10-02', '2025-10-02')).toBe(-1);
+    expect(fullYearsBetween('2026-10-02', '2025-10-01')).toBe(-2);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/format/date.ts b/apps/admin-frontend/src/shared/format/date.ts
index 4a74908a..f8654084 100644
--- a/apps/admin-frontend/src/shared/format/date.ts
+++ b/apps/admin-frontend/src/shared/format/date.ts
@@ -44,6 +44,26 @@ export function daysInMonth(year: number, month: number): number {
   return new Date(Date.UTC(year, month, 0)).getUTCDate();
 }
 
+export function fullYearsBetween(from: string, to: string): number {
+  const start = toParts(from);
+  const end = toParts(to);
+
+  const anniversary = {
+    month: start.month,
+    day: Math.min(start.day, daysInMonth(end.year, start.month)),
+  };
+  const reachedAnniversary =
+    end.month > anniversary.month ||
+    (end.month === anniversary.month && end.day >= anniversary.day);
+
+  return end.year - start.year - (reachedAnniversary ? 0 : 1);
+}
+
+function toParts(isoDate: string): { year: number; month: number; day: number } {
+  const [year = 0, month = 0, day = 0] = isoDate.split('-').map(Number);
+  return { year, month, day };
+}
+
 function pad(value: number, length: number): string {
   return String(value).padStart(length, '0');
 }

From 5a07994fca13947f254d0c992d003f24ef391f62 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Sun, 11 Oct 2026 17:07:54 -0300
Subject: [PATCH 10/30] Extract shared form/page widgets

This commit centralizes the shared form footer and page section patterns into reusable widgets in the admin frontend. Client and tag forms now consume the common components, reducing feature-specific duplication and keeping the UI consistent. It also updates the architecture doc and adds focused tests for the new widgets.
---
 apps/admin-frontend/docs/ARCHITECTURE.md      |   4 +-
 .../pages/ClientFormPage/ClientFormPage.tsx   |   4 +-
 .../components/ClientFormFooter.tsx           |  28 -----
 .../components/ClientGuardiansSection.tsx     |   6 +-
 .../components/ClientPersonSection.tsx        |   6 +-
 .../ClientReferenceContactsSection.tsx        |   6 +-
 .../tags/ui/pages/TagFormPage/TagFormPage.tsx |   4 +-
 .../TagFormPage/components/TagFormFooter.tsx  |  23 ----
 .../widgets/form-footer/form-footer.test.tsx  | 107 ++++++++++++++++++
 .../src/widgets/form-footer/index.tsx         |  47 ++++++++
 .../page-section/index.tsx}                   |  19 ++--
 .../page-section/page-section.test.tsx        |  71 ++++++++++++
 12 files changed, 251 insertions(+), 74 deletions(-)
 delete mode 100644 apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx
 delete mode 100644 apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormFooter.tsx
 create mode 100644 apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx
 create mode 100644 apps/admin-frontend/src/widgets/form-footer/index.tsx
 rename apps/admin-frontend/src/{features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx => widgets/page-section/index.tsx} (64%)
 create mode 100644 apps/admin-frontend/src/widgets/page-section/page-section.test.tsx

diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 18488ad9..1b0e0168 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -32,8 +32,8 @@ src/
 │   │                        state) + route.ts (loader/action), all re-exported by index.ts
 │   └── index.ts             The slice's ONLY public surface
 ├── widgets/                 Generic UI compositions with behaviour but no domain (confirm-dialog,
-│                            list-section, page-header); import shared/ only, consumed by features
-│                            (ADR 0042)
+│                            list-section, page-header, page-section, form-footer); import
+│                            shared/ only, consumed by features (ADR 0042)
 └── shared/                  Cross-cutting, no business logic
     ├── api/                 servicesFacade, servicesApi (its composition), apiClient,
     │                        unwrap (Result → exception at the framework boundary), formErrors
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
index 7735e0ea..23a51a61 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -1,7 +1,7 @@
 import { FormProvider } from 'react-hook-form';
 import { FormErrorBanner } from '@/shared/form/fields';
+import { FormFooter } from '@/widgets/form-footer';
 import { PageHeader } from '@/widgets/page-header';
-import { ClientFormFooter } from './components/ClientFormFooter';
 import { ClientGuardiansSection } from './components/ClientGuardiansSection';
 import { ClientPersonSection } from './components/ClientPersonSection';
 import { ClientReferenceContactsSection } from './components/ClientReferenceContactsSection';
@@ -42,7 +42,7 @@ export function ClientFormPage() {
             onRemove={referenceContacts.remove}
           />
           <FormErrorBanner />
-          <ClientFormFooter isSaving={isSaving} />
+          <FormFooter isSaving={isSaving} cancelTo="/pessoas" />
         </form>
       </FormProvider>
     </div>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx
deleted file mode 100644
index 617684ac..00000000
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormFooter.tsx
+++ /dev/null
@@ -1,28 +0,0 @@
-import { Link } from 'react-router';
-import { ActionButton } from '@/shared/ui/action-button';
-import { Button, buttonVariants } from '@/shared/ui/button';
-
-interface ClientFormFooterProps {
-  isSaving: boolean;
-}
-
-function ClientFormFooter({ isSaving }: ClientFormFooterProps) {
-  return (
-    <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
-      {isSaving ? (
-        <Button type="button" variant="outline" disabled>
-          Cancelar
-        </Button>
-      ) : (
-        <Link to="/pessoas" className={buttonVariants({ variant: 'outline' })}>
-          Cancelar
-        </Link>
-      )}
-      <ActionButton type="submit" pending={isSaving}>
-        {isSaving ? 'Salvando…' : 'Salvar'}
-      </ActionButton>
-    </div>
-  );
-}
-
-export { ClientFormFooter };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index 5d10eef1..cfba5f8b 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -2,9 +2,9 @@ import type { RefObject } from 'react';
 import { PlusIcon } from 'lucide-react';
 import { useFormContext } from 'react-hook-form';
 import { Button } from '@/shared/ui/button';
+import { PageSection } from '@/widgets/page-section';
 import { ADULT_AGE_IN_YEARS } from '../../../../model/birthDate';
 import { MAX_GUARDIANS, type ClientFormFieldValues } from '../../../../model/clientForm';
-import { ClientFormSection } from './ClientFormSection';
 import { ClientGuardianItem } from './ClientGuardianItem';
 
 interface ClientGuardiansSectionProps {
@@ -28,7 +28,7 @@ function ClientGuardiansSection({
   const listError = errors.guardians?.root?.message ?? errors.guardians?.message;
 
   return (
-    <ClientFormSection
+    <PageSection
       title="Responsáveis"
       description={`Quem responde pela pessoa. Obrigatório para menores de ${ADULT_AGE_IN_YEARS} anos.`}
       action={
@@ -64,7 +64,7 @@ function ClientGuardiansSection({
           {listError}
         </p>
       )}
-    </ClientFormSection>
+    </PageSection>
   );
 }
 
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 1e3f74fc..fa4c6532 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,5 +1,6 @@
 import { todayLocal } from '@/shared/format/date';
 import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
+import { PageSection } from '@/widgets/page-section';
 import { earliestBirthDate, formatAge, latestBirthDate } from '../../../../model/birthDate';
 import {
   CLIENT_NAME_MAX_LENGTH,
@@ -8,7 +9,6 @@ import {
 } from '../../../../model/clientForm';
 import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
 import { formatCpf } from '../../../../model/cpf';
-import { ClientFormSection } from './ClientFormSection';
 
 interface ClientPersonSectionProps {
   age: number | null;
@@ -18,7 +18,7 @@ function ClientPersonSection({ age }: ClientPersonSectionProps) {
   const today = todayLocal();
 
   return (
-    <ClientFormSection title="Dados da pessoa" hideTitle>
+    <PageSection title="Dados da pessoa" hideTitle>
       <div className="grid gap-4 md:grid-cols-2">
         <div className="md:col-span-2">
           <TextField<ClientFormFieldValues>
@@ -84,7 +84,7 @@ function ClientPersonSection({ age }: ClientPersonSectionProps) {
           </p>
         </div>
       </div>
-    </ClientFormSection>
+    </PageSection>
   );
 }
 
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
index 5bb7eecf..8fa7a84c 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -1,8 +1,8 @@
 import { PlusIcon } from 'lucide-react';
 import { useFormContext } from 'react-hook-form';
 import { Button } from '@/shared/ui/button';
+import { PageSection } from '@/widgets/page-section';
 import { MAX_REFERENCE_CONTACTS, type ClientFormFieldValues } from '../../../../model/clientForm';
-import { ClientFormSection } from './ClientFormSection';
 import { ClientReferenceContactItem } from './ClientReferenceContactItem';
 
 interface ClientReferenceContactsSectionProps {
@@ -22,7 +22,7 @@ function ClientReferenceContactsSection({
   const listError = errors.referenceContacts?.root?.message ?? errors.referenceContacts?.message;
 
   return (
-    <ClientFormSection
+    <PageSection
       title="Pessoas de referência"
       description="Familiares, amigos ou pessoas de apoio. Registrar não dá acesso aos dados nem envia mensagens."
       action={
@@ -51,7 +51,7 @@ function ClientReferenceContactsSection({
           {listError}
         </p>
       )}
-    </ClientFormSection>
+    </PageSection>
   );
 }
 
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
index 93f7b23b..6ffaaad6 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
@@ -1,9 +1,9 @@
 import { FormProvider } from 'react-hook-form';
 import { Dialog, DialogContent } from '@/shared/ui/dialog';
 import { FormFieldsSkeleton } from '@/shared/ui/form-field';
+import { FormFooter } from '@/widgets/form-footer';
 import { TAG_FORM_FIELDS } from '../../../model/tagForm';
 import { TagFormBody } from './components/TagFormBody';
-import { TagFormFooter } from './components/TagFormFooter';
 import { TagFormHeader } from './components/TagFormHeader';
 import { useTagFormPage } from './useTagFormPage';
 import { TagFormStatus } from './useTagFormPage.types';
@@ -23,7 +23,7 @@ export function TagFormPage() {
             ) : (
               <TagFormBody />
             )}
-            <TagFormFooter canSubmit={canSubmit} isSaving={isSaving} />
+            <FormFooter canSubmit={canSubmit} isSaving={isSaving} />
           </form>
         </FormProvider>
       </DialogContent>
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormFooter.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormFooter.tsx
deleted file mode 100644
index 78399596..00000000
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormFooter.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-import { ActionButton } from '@/shared/ui/action-button';
-import { Button } from '@/shared/ui/button';
-import { DialogClose, DialogFooter } from '@/shared/ui/dialog';
-
-interface TagFormFooterProps {
-  canSubmit: boolean;
-  isSaving: boolean;
-}
-
-function TagFormFooter({ canSubmit, isSaving }: TagFormFooterProps) {
-  return (
-    <DialogFooter>
-      <DialogClose disabled={isSaving} render={<Button variant="outline" />}>
-        Cancelar
-      </DialogClose>
-      <ActionButton type="submit" disabled={!canSubmit} pending={isSaving}>
-        {isSaving ? 'Salvando…' : 'Salvar'}
-      </ActionButton>
-    </DialogFooter>
-  );
-}
-
-export { TagFormFooter };
diff --git a/apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx b/apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx
new file mode 100644
index 00000000..5c1cbc23
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx
@@ -0,0 +1,107 @@
+import { describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { MemoryRouter } from 'react-router';
+import { Dialog, DialogContent, DialogDescription, DialogTitle } from '@/shared/ui/dialog';
+import { FormFooter, type FormFooterProps } from './index';
+
+function renderOnPage(props: FormFooterProps) {
+  const onSubmit = vi.fn((event: React.FormEvent) => event.preventDefault());
+  render(
+    <MemoryRouter>
+      <form onSubmit={onSubmit}>
+        <FormFooter {...props} />
+      </form>
+    </MemoryRouter>,
+  );
+  return { onSubmit };
+}
+
+function renderInDialog(props: FormFooterProps, onOpenChange = vi.fn()) {
+  const onSubmit = vi.fn((event: React.FormEvent) => event.preventDefault());
+  render(
+    <Dialog open onOpenChange={onOpenChange}>
+      <DialogContent>
+        <DialogTitle>Título</DialogTitle>
+        <DialogDescription>Descrição</DialogDescription>
+        <form onSubmit={onSubmit}>
+          <FormFooter {...props} />
+        </form>
+      </DialogContent>
+    </Dialog>,
+  );
+  return { onSubmit, onOpenChange };
+}
+
+describe('FormFooter', () => {
+  describe('on a page (cancelTo)', () => {
+    it('offers Cancelar as a link to cancelTo and Salvar as the submit button', async () => {
+      const user = userEvent.setup();
+      const { onSubmit } = renderOnPage({ isSaving: false, cancelTo: '/pessoas' });
+
+      expect(screen.getByRole('link', { name: 'Cancelar' })).toHaveAttribute('href', '/pessoas');
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(onSubmit).toHaveBeenCalledTimes(1);
+    });
+
+    it('swaps Cancelar for a disabled button and shows Salvando… while saving', () => {
+      renderOnPage({ isSaving: true, cancelTo: '/pessoas' });
+
+      expect(screen.getByRole('button', { name: 'Cancelar' })).toBeDisabled();
+      expect(screen.queryByRole('link', { name: 'Cancelar' })).not.toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Salvando…' })).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
+    });
+
+    it('keeps Salvar enabled unless canSubmit says otherwise', () => {
+      renderOnPage({ isSaving: false, cancelTo: '/pessoas' });
+
+      expect(screen.getByRole('button', { name: 'Salvar' })).toBeEnabled();
+    });
+
+    it('disables Salvar when canSubmit is false', () => {
+      renderOnPage({ isSaving: false, canSubmit: false, cancelTo: '/pessoas' });
+
+      expect(screen.getByRole('button', { name: 'Salvar' })).toBeDisabled();
+    });
+  });
+
+  describe('inside a dialog (no cancelTo)', () => {
+    it('closes the dialog from Cancelar', async () => {
+      const user = userEvent.setup();
+      const { onOpenChange } = renderInDialog({ isSaving: false });
+
+      await user.click(screen.getByRole('button', { name: 'Cancelar' }));
+
+      expect(onOpenChange).toHaveBeenCalledWith(false, expect.anything());
+    });
+
+    it('disables Cancelar and shows Salvando… while saving', () => {
+      renderInDialog({ isSaving: true });
+
+      expect(screen.getByRole('button', { name: 'Cancelar' })).toBeDisabled();
+      expect(screen.getByRole('button', { name: 'Salvando…' })).toHaveAttribute(
+        'aria-disabled',
+        'true',
+      );
+    });
+
+    it('disables Salvar when canSubmit is false', () => {
+      renderInDialog({ isSaving: false, canSubmit: false });
+
+      expect(screen.getByRole('button', { name: 'Salvar' })).toBeDisabled();
+    });
+
+    it('submits the surrounding form from Salvar', async () => {
+      const user = userEvent.setup();
+      const { onSubmit } = renderInDialog({ isSaving: false });
+
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      expect(onSubmit).toHaveBeenCalledTimes(1);
+    });
+  });
+});
diff --git a/apps/admin-frontend/src/widgets/form-footer/index.tsx b/apps/admin-frontend/src/widgets/form-footer/index.tsx
new file mode 100644
index 00000000..61a130bd
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/form-footer/index.tsx
@@ -0,0 +1,47 @@
+import { Link } from 'react-router';
+import { ActionButton } from '@/shared/ui/action-button';
+import { Button, buttonVariants } from '@/shared/ui/button';
+import { DialogClose, DialogFooter } from '@/shared/ui/dialog';
+
+interface FormFooterProps {
+  isSaving: boolean;
+  canSubmit?: boolean;
+  cancelTo?: string;
+}
+
+function FormFooter({ isSaving, canSubmit = true, cancelTo }: FormFooterProps) {
+  const submit = (
+    <ActionButton type="submit" disabled={!canSubmit} pending={isSaving}>
+      {isSaving ? 'Salvando…' : 'Salvar'}
+    </ActionButton>
+  );
+
+  if (cancelTo === undefined) {
+    return (
+      <DialogFooter>
+        <DialogClose disabled={isSaving} render={<Button variant="outline" />}>
+          Cancelar
+        </DialogClose>
+        {submit}
+      </DialogFooter>
+    );
+  }
+
+  return (
+    <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+      {isSaving ? (
+        <Button type="button" variant="outline" disabled>
+          Cancelar
+        </Button>
+      ) : (
+        <Link to={cancelTo} className={buttonVariants({ variant: 'outline' })}>
+          Cancelar
+        </Link>
+      )}
+      {submit}
+    </div>
+  );
+}
+
+export { FormFooter };
+export type { FormFooterProps };
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx b/apps/admin-frontend/src/widgets/page-section/index.tsx
similarity index 64%
rename from apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
rename to apps/admin-frontend/src/widgets/page-section/index.tsx
index 6c3be9e1..72d89b69 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientFormSection.tsx
+++ b/apps/admin-frontend/src/widgets/page-section/index.tsx
@@ -1,23 +1,23 @@
 import { useId, type ReactNode } from 'react';
 
-interface ClientFormSectionBase {
+interface PageSectionBase {
   title: string;
   children: ReactNode;
 }
 
-interface ClientFormSectionWithHeader extends ClientFormSectionBase {
+interface PageSectionWithHeader extends PageSectionBase {
   hideTitle?: false;
-  description: string;
+  description?: string;
   action?: ReactNode;
 }
 
-interface ClientFormSectionWithoutHeader extends ClientFormSectionBase {
+interface PageSectionWithoutHeader extends PageSectionBase {
   hideTitle: true;
 }
 
-type ClientFormSectionProps = ClientFormSectionWithHeader | ClientFormSectionWithoutHeader;
+type PageSectionProps = PageSectionWithHeader | PageSectionWithoutHeader;
 
-function ClientFormSection(props: ClientFormSectionProps) {
+function PageSection(props: PageSectionProps) {
   const headingId = useId();
 
   return (
@@ -35,7 +35,9 @@ function ClientFormSection(props: ClientFormSectionProps) {
             <h2 id={headingId} className="text-base font-semibold">
               {props.title}
             </h2>
-            <p className="text-sm text-muted-foreground">{props.description}</p>
+            {props.description && (
+              <p className="text-sm text-muted-foreground">{props.description}</p>
+            )}
           </div>
           {props.action && <div className="shrink-0">{props.action}</div>}
         </div>
@@ -45,4 +47,5 @@ function ClientFormSection(props: ClientFormSectionProps) {
   );
 }
 
-export { ClientFormSection };
+export { PageSection };
+export type { PageSectionProps };
diff --git a/apps/admin-frontend/src/widgets/page-section/page-section.test.tsx b/apps/admin-frontend/src/widgets/page-section/page-section.test.tsx
new file mode 100644
index 00000000..2c146ff1
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/page-section/page-section.test.tsx
@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen, within } from '@testing-library/react';
+import { PageSection } from './index';
+
+describe('PageSection', () => {
+  it('names the region after its title and shows the description under it', () => {
+    render(
+      <PageSection title="Responsáveis" description="Quem responde pela pessoa.">
+        <p>conteúdo</p>
+      </PageSection>,
+    );
+
+    const region = screen.getByRole('region', { name: 'Responsáveis' });
+    expect(within(region).getByRole('heading', { name: 'Responsáveis', level: 2 })).toBeVisible();
+    expect(within(region).getByText('Quem responde pela pessoa.')).toBeInTheDocument();
+    expect(within(region).getByText('conteúdo')).toBeInTheDocument();
+  });
+
+  it('renders the action next to the title', () => {
+    render(
+      <PageSection
+        title="Responsáveis"
+        description="Quem responde pela pessoa."
+        action={<button>Adicionar</button>}
+      >
+        <p>conteúdo</p>
+      </PageSection>,
+    );
+
+    const region = screen.getByRole('region', { name: 'Responsáveis' });
+    expect(within(region).getByRole('button', { name: 'Adicionar' })).toBeInTheDocument();
+  });
+
+  it('works with a title alone', () => {
+    render(
+      <PageSection title="Endereço">
+        <p>conteúdo</p>
+      </PageSection>,
+    );
+
+    const region = screen.getByRole('region', { name: 'Endereço' });
+    expect(region.querySelector('p.text-muted-foreground')).toBeNull();
+  });
+
+  it('keeps the title for assistive tech only when hideTitle is set', () => {
+    render(
+      <PageSection title="Dados da pessoa" hideTitle>
+        <p>conteúdo</p>
+      </PageSection>,
+    );
+
+    const region = screen.getByRole('region', { name: 'Dados da pessoa' });
+    expect(within(region).getByRole('heading', { name: 'Dados da pessoa' })).toHaveClass('sr-only');
+  });
+
+  it('gives each section its own heading id so several can share a page', () => {
+    render(
+      <>
+        <PageSection title="Um">
+          <p>a</p>
+        </PageSection>
+        <PageSection title="Dois">
+          <p>b</p>
+        </PageSection>
+      </>,
+    );
+
+    expect(screen.getByRole('region', { name: 'Um' })).toBeInTheDocument();
+    expect(screen.getByRole('region', { name: 'Dois' })).toBeInTheDocument();
+  });
+});

From a62d75db82e2820cc1f8dad7c86795ef7f558f87 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Sun, 11 Oct 2026 17:48:50 -0300
Subject: [PATCH 11/30] Normalize birth dates to Date objects

Switch the client form and shared date utilities from ISO strings to real calendar Date values. The change keeps birth-date comparisons, validation, and calendar bounds in UTC-safe day semantics, updates generated API types, and moves dynamic field-array ownership into the form sections themselves. It also updates repository payload serialization and tests to match the Date-based contract.
---
 .../agenza-ptbr-copy/references/formatting.md |  16 +--
 apps/admin-frontend/docs/ARCHITECTURE.md      |   6 +-
 .../scripts/generateApiTypes.mjs              |  17 ++-
 .../clients/api/clientsRepository.test.ts     |  14 +-
 .../features/clients/model/birthDate.test.ts  |  41 +++---
 .../src/features/clients/model/birthDate.ts   |  21 ++-
 .../src/features/clients/model/client.ts      |   4 +-
 .../features/clients/model/clientForm.test.ts |   3 +-
 .../ClientFormPage/ClientFormPage.test.tsx    |  11 +-
 .../pages/ClientFormPage/ClientFormPage.tsx   |  27 +---
 .../components/ClientGuardiansSection.tsx     |  37 +++---
 .../ClientReferenceContactsSection.tsx        |  40 +++---
 .../pages/ClientFormPage/useClientFormPage.ts |  10 +-
 .../ClientFormPage/useClientFormPage.types.ts |   6 +-
 .../shared/api/generated/services-api.d.ts    |   6 +-
 .../fields/components/date-field.test.tsx     |   5 +-
 .../form/fields/components/date-field.tsx     |  28 ++--
 .../src/shared/form/fields/fields.types.ts    |   4 +-
 .../src/shared/format/date.test.ts            | 121 +++++++++++-------
 apps/admin-frontend/src/shared/format/date.ts |  47 ++++---
 20 files changed, 240 insertions(+), 224 deletions(-)

diff --git a/.claude/skills/agenza-ptbr-copy/references/formatting.md b/.claude/skills/agenza-ptbr-copy/references/formatting.md
index 71001b1e..4597868f 100644
--- a/.claude/skills/agenza-ptbr-copy/references/formatting.md
+++ b/.claude/skills/agenza-ptbr-copy/references/formatting.md
@@ -79,14 +79,14 @@ Two kinds of value, and conflating them is the classic bug:
 owner's phone in Brazil, wrong on a CI runner in UTC, and wrong in a way that only shows up as a
 flaky test at 21:00 BRT.
 
-**A date-only value** (`2026-09-04`, no time) — **never hand it to `new Date()`**. The string parses
-as UTC midnight, which is 3 September in São Paulo, so the appointment renders one day early. Split
-the parts and build a local date, or format the string's parts directly:
-
-```ts
-const [year, month, day] = isoDate.split('-').map(Number);
-const localDate = new Date(year, month - 1, day);
-```
+**A date-only value** (`2026-09-04`, no time) is a `Date` at midnight UTC, and it is **read only in
+UTC**: `getUTCDate()` and friends, or `Intl.DateTimeFormat` with `timeZone: 'UTC'`. `new Date('2026-09-04')`
+is already that midnight; the bug is reading it back with the device's zone (`getDate()`,
+`toLocaleDateString()` without `timeZone: 'UTC'`), which prints 3 September in São Paulo, so the
+appointment renders one day early.
+
+In `admin-frontend` that is `utcDate` in `shared/format/date.ts`; the app holds a calendar day as a
+`Date` and only turns it into text where it is shown (`formatMaskedDate`).
 
 **"Today" for a form rule is the person's own day, not São Paulo's.** `todayLocal()`
 (`shared/format/date.ts`) reads the browser's calendar day. The pinned zone above is for *rendering
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 1b0e0168..f5d5fa2a 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -384,8 +384,10 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
-| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (ISO strings): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date`, so `isoToLocalDate`/`localDateToIso` convert at the edge; the model keeps ISO strings. `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
-| Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `features/clients/model/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two ISO dates, so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test `fullYearsBetween('2008-02-29', '2026-02-28') === 18` is that contract. Months and days are not generalised: nothing needs them yet. |
+| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
+| Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `features/clients/model/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
+| Calendar dates are `Date` from the form schema down to the repository; text only exists at the two edges (`dd/mm/aaaa` in the input, `yyyy-mm-dd` on the wire). `Client.birthDate`/`ClientInput.birthDate`, the schema's output, `DateField`'s `minDate`/`maxDate` and every function in `birthDate.ts` and `shared/format/date.ts` take `Date`; nothing converts a date by hand | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type and the compiler could not tell a swapped argument from a right one. A `Date` is always a real day; `parseMaskedDate` still rejects `31/02`. A `Date` here is a calendar day at **midnight UTC**, never a local instant: `utcDate(year, month, day)` is the one constructor (1-based month, so the `month - 1` off-by-one lives in one place), and comparisons, arithmetic and display read the `getUTC*` getters, so the day cannot shift with the device's zone. The one place the device's zone is read is `todayLocal`, which takes the browser's calendar day (the person's own "today", as before) and returns it as midnight UTC. `DateField` hands the calendar `timeZone="UTC"`, so the library reads and returns the same UTC days. `clientsRepository.create` is a pass-through, like the tags repository: the body carries the `Date` as is and `JSON.stringify` writes it as an instant at midnight UTC (`1990-05-20T00:00:00.000Z`). That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` (`transform`; `format: date-time` is untouched), so `birthDate` is `null | Date` in `services-api.d.ts`. **Known gap:** the same mapping types the response as `Date`, but JSON hands back a string, and nothing converts it. Nothing reads `Client.birthDate` today (the page uses `fullName`); the first screen that does must convert it (`new Date(isoDate)` is midnight UTC) or the type has to be narrowed. **Backend dependency:** as of this entry the backend does not read an instant for `BirthDate`. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`. Sending the `Date` raw needs the converter to accept an instant (and take its UTC date) first. Not branded strings (`IsoDate`) and not a `{ year, month, day }` object: the user asked for the native type, and the calendar library already speaks it. The cost is mutability and `===`: no function here mutates its argument, and equality goes through `getTime()` or `toEqual`. |
+| `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian` and `addReferenceContact`, and the references section takes no props. The one thing that stays in the hook is `addGuardianButtonRef`, still passed to the guardians section: `onInvalid` focuses the add button only when the missing guardian is the sole error, which the section cannot know, and RHF cannot do it itself (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/scripts/generateApiTypes.mjs b/apps/admin-frontend/scripts/generateApiTypes.mjs
index aaa9556a..78960b00 100644
--- a/apps/admin-frontend/scripts/generateApiTypes.mjs
+++ b/apps/admin-frontend/scripts/generateApiTypes.mjs
@@ -3,6 +3,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import path from 'node:path';
 import openapiTS, { astToString } from 'openapi-typescript';
 import prettier from 'prettier';
+import ts from 'typescript';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const OUTPUT_PATH = path.join(
@@ -33,9 +34,23 @@ function stripTenantHeaderParam(document) {
   return document;
 }
 
+function calendarDateAsDate(schemaObject) {
+  if (schemaObject.format !== 'date') return undefined;
+
+  const date = ts.factory.createTypeReferenceNode('Date');
+  if (!Array.isArray(schemaObject.type) || !schemaObject.type.includes('null')) return date;
+
+  return ts.factory.createUnionTypeNode([
+    ts.factory.createLiteralTypeNode(ts.factory.createNull()),
+    date,
+  ]);
+}
+
 export async function generate() {
   const document = await fetch(new URL(OPENAPI_URL)).then((response) => response.json());
-  const ast = await openapiTS(stripTenantHeaderParam(document));
+  const ast = await openapiTS(stripTenantHeaderParam(document), {
+    transform: calendarDateAsDate,
+  });
   const raw = astToString(ast);
   const prettierConfig = (await prettier.resolveConfig(__dirname)) ?? {};
   const formatted = await prettier.format(raw, { ...prettierConfig, parser: 'typescript' });
diff --git a/apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts b/apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts
index d0bf17b1..ebf9d781 100644
--- a/apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts
+++ b/apps/admin-frontend/src/features/clients/api/clientsRepository.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
+import { utcDate } from '@/shared/format/date';
 import type { ClientInput } from '../model/client';
 import { clientsRepository } from './clientsRepository';
 
@@ -10,7 +11,7 @@ vi.mock('@/shared/api/servicesApi', () => ({
 
 const INPUT: ClientInput = {
   fullName: 'Maria Souza',
-  birthDate: '2015-03-10',
+  birthDate: utcDate(2015, 3, 10),
   phone: null,
   email: 'maria@example.com',
   cpf: '52998224725',
@@ -32,6 +33,17 @@ describe('clientsRepository.create', () => {
     expect(result).toEqual({ ok: true, data: client });
   });
 
+  it('hands the birth date over as the Date itself, which JSON writes as an instant at midnight UTC', async () => {
+    mockPost.mockResolvedValue({ ok: true, data: {} });
+
+    await clientsRepository.create(INPUT);
+
+    const [, options] = mockPost.mock.calls.at(-1) as [string, { body: unknown }];
+    expect(JSON.parse(JSON.stringify(options.body))).toMatchObject({
+      birthDate: '2015-03-10T00:00:00.000Z',
+    });
+  });
+
   it('never sends a tenant, only what the person typed', async () => {
     mockPost.mockResolvedValue({ ok: true, data: {} });
 
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
index 6d6568f0..df9b0bcc 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest';
+import { utcDate } from '@/shared/format/date';
 import {
   earliestBirthDate,
   formatAge,
@@ -8,51 +9,51 @@ import {
   latestBirthDate,
 } from './birthDate';
 
-const TODAY = '2026-10-02';
+const TODAY = utcDate(2026, 10, 2);
 
 describe('birth date rules', () => {
   it('requires a date strictly in the past', () => {
-    expect(isInThePast('2026-10-01', TODAY)).toBe(true);
-    expect(isInThePast('2026-10-02', TODAY)).toBe(false);
-    expect(isInThePast('2026-10-03', TODAY)).toBe(false);
+    expect(isInThePast(utcDate(2026, 10, 1), TODAY)).toBe(true);
+    expect(isInThePast(utcDate(2026, 10, 2), TODAY)).toBe(false);
+    expect(isInThePast(utcDate(2026, 10, 3), TODAY)).toBe(false);
   });
 
   it('accepts up to 120 years and rejects 121', () => {
-    expect(isWithinMaxAge('1906-10-02', TODAY)).toBe(true);
-    expect(isWithinMaxAge('1905-10-02', TODAY)).toBe(false);
+    expect(isWithinMaxAge(utcDate(1906, 10, 2), TODAY)).toBe(true);
+    expect(isWithinMaxAge(utcDate(1905, 10, 2), TODAY)).toBe(false);
   });
 
   it('is a minor until the eighteenth birthday', () => {
-    expect(isMinorOn('2008-10-03', TODAY)).toBe(true);
-    expect(isMinorOn('2008-10-02', TODAY)).toBe(false);
-    expect(isMinorOn('2026-10-01', TODAY)).toBe(true);
-    expect(isMinorOn('1990-01-01', TODAY)).toBe(false);
+    expect(isMinorOn(utcDate(2008, 10, 3), TODAY)).toBe(true);
+    expect(isMinorOn(utcDate(2008, 10, 2), TODAY)).toBe(false);
+    expect(isMinorOn(utcDate(2026, 10, 1), TODAY)).toBe(true);
+    expect(isMinorOn(utcDate(1990, 1, 1), TODAY)).toBe(false);
   });
 
   it('is never a minor on a date that is not in the past', () => {
-    expect(isMinorOn('2026-10-03', TODAY)).toBe(false);
-    expect(isMinorOn('2026-10-02', TODAY)).toBe(false);
+    expect(isMinorOn(utcDate(2026, 10, 3), TODAY)).toBe(false);
+    expect(isMinorOn(utcDate(2026, 10, 2), TODAY)).toBe(false);
   });
 });
 
 describe('birth date picker bounds', () => {
   it('ends the day before today, since a birth date must be in the past', () => {
-    expect(latestBirthDate(TODAY)).toBe('2026-10-01');
+    expect(latestBirthDate(TODAY)).toEqual(utcDate(2026, 10, 1));
     expect(isInThePast(latestBirthDate(TODAY), TODAY)).toBe(true);
   });
 
   it.each([
-    ['2026-03-01', '2026-02-28'],
-    ['2024-03-01', '2024-02-29'],
-    ['2027-01-01', '2026-12-31'],
+    [utcDate(2026, 3, 1), utcDate(2026, 2, 28)],
+    [utcDate(2024, 3, 1), utcDate(2024, 2, 29)],
+    [utcDate(2027, 1, 1), utcDate(2026, 12, 31)],
   ] as const)('ends the day before %s on %s', (today, expected) => {
-    expect(latestBirthDate(today)).toBe(expected);
+    expect(latestBirthDate(today)).toEqual(expected);
   });
 
   it('starts on January 1st of the first year that can still be within the maximum age', () => {
-    expect(earliestBirthDate(TODAY)).toBe('1905-01-01');
-    expect(isWithinMaxAge('1905-12-31', '2026-01-01')).toBe(true);
-    expect(isWithinMaxAge('1905-01-01', '2026-12-31')).toBe(false);
+    expect(earliestBirthDate(TODAY)).toEqual(utcDate(1905, 1, 1));
+    expect(isWithinMaxAge(utcDate(1905, 12, 31), utcDate(2026, 1, 1))).toBe(true);
+    expect(isWithinMaxAge(utcDate(1905, 1, 1), utcDate(2026, 12, 31))).toBe(false);
   });
 });
 
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.ts b/apps/admin-frontend/src/features/clients/model/birthDate.ts
index 49438dcd..6e4249c2 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.ts
@@ -1,29 +1,26 @@
-import { fullYearsBetween, isoToLocalDate, localDateToIso } from '@/shared/format/date';
+import { addDays, fullYearsBetween, utcDate } from '@/shared/format/date';
 
 export const ADULT_AGE_IN_YEARS = 18;
 export const MAX_AGE_IN_YEARS = 120;
 
-export function isInThePast(birthDate: string, today: string): boolean {
-  return birthDate < today;
+export function isInThePast(birthDate: Date, today: Date): boolean {
+  return birthDate.getTime() < today.getTime();
 }
 
-export function isWithinMaxAge(birthDate: string, today: string): boolean {
+export function isWithinMaxAge(birthDate: Date, today: Date): boolean {
   return fullYearsBetween(birthDate, today) <= MAX_AGE_IN_YEARS;
 }
 
-export function isMinorOn(birthDate: string, today: string): boolean {
+export function isMinorOn(birthDate: Date, today: Date): boolean {
   return isInThePast(birthDate, today) && fullYearsBetween(birthDate, today) < ADULT_AGE_IN_YEARS;
 }
 
-export function latestBirthDate(today: string): string {
-  const yesterday = isoToLocalDate(today);
-  yesterday.setDate(yesterday.getDate() - 1);
-  return localDateToIso(yesterday);
+export function latestBirthDate(today: Date): Date {
+  return addDays(today, -1);
 }
 
-export function earliestBirthDate(today: string): string {
-  const year = Number(today.slice(0, 4)) - MAX_AGE_IN_YEARS - 1;
-  return `${year}-01-01`;
+export function earliestBirthDate(today: Date): Date {
+  return utcDate(today.getUTCFullYear() - MAX_AGE_IN_YEARS - 1, 1, 1);
 }
 
 export function formatAge(age: number): string {
diff --git a/apps/admin-frontend/src/features/clients/model/client.ts b/apps/admin-frontend/src/features/clients/model/client.ts
index face8328..b2347e71 100644
--- a/apps/admin-frontend/src/features/clients/model/client.ts
+++ b/apps/admin-frontend/src/features/clients/model/client.ts
@@ -21,7 +21,7 @@ export interface ClientReferenceContact {
 export interface Client {
   id: string;
   fullName: string;
-  birthDate: string | null;
+  birthDate: Date | null;
   phone: string | null;
   email: string | null;
   cpf: string | null;
@@ -40,7 +40,7 @@ export type ReferenceContactInput = Pick<
 
 export interface ClientInput {
   fullName: string;
-  birthDate: string | null;
+  birthDate: Date | null;
   phone: string | null;
   email: string | null;
   cpf: string | null;
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
index f85f419b..e0290ae2 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { utcDate } from '@/shared/format/date';
 import {
   CLIENT_FORM_FIELDS,
   GUARDIAN_FORM_FIELDS,
@@ -88,7 +89,7 @@ describe('clientFormSchema', () => {
     expect(result.success).toBe(true);
     expect(result.data).toEqual({
       fullName: 'Maria Souza',
-      birthDate: '1990-05-20',
+      birthDate: utcDate(1990, 5, 20),
       phone: '(11) 99999-0000',
       email: 'maria.souza@example.com',
       cpf: '52998224725',
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index d0b15914..4f9d4546 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -4,6 +4,7 @@ import userEvent from '@testing-library/user-event';
 import { MemoryRouter, Route, Routes, useLocation } from 'react-router';
 import { toast } from '@/shared/ui/toast';
 import type { ApiProblem } from '@/shared/api/servicesFacade';
+import { utcDate } from '@/shared/format/date';
 import type { Client } from '../../../model/client';
 import { ClientFormPage } from './ClientFormPage';
 
@@ -158,7 +159,7 @@ describe('ClientFormPage', () => {
       expect(await screen.findByRole('heading', { name: 'Lista de pessoas' })).toBeInTheDocument();
     });
 
-    it('sends every field normalized: ISO birth date, CPF without mask, lowercase e-mail', async () => {
+    it('sends every field normalized: birth date as a Date, CPF without mask, lowercase e-mail', async () => {
       const user = userEvent.setup();
       renderPage();
 
@@ -176,7 +177,7 @@ describe('ClientFormPage', () => {
       await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
       expect(lastPayload()).toEqual({
         fullName: 'Maria Souza',
-        birthDate: '1990-05-20',
+        birthDate: utcDate(1990, 5, 20),
         phone: '(11) 99999-0000',
         email: 'maria.souza@example.com',
         cpf: '52998224725',
@@ -198,7 +199,7 @@ describe('ClientFormPage', () => {
       expect(screen.getByText('36 anos')).toBeInTheDocument();
     });
 
-    it('picks the birth date from the calendar, shows the age and sends the ISO date', async () => {
+    it('picks the birth date from the calendar, shows the age and sends the date', async () => {
       const user = userEvent.setup();
       renderPage();
 
@@ -221,7 +222,7 @@ describe('ClientFormPage', () => {
       await user.click(screen.getByRole('button', { name: 'Salvar' }));
 
       await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
-      expect(lastPayload()).toMatchObject({ birthDate: '1990-05-20' });
+      expect(lastPayload()).toMatchObject({ birthDate: utcDate(1990, 5, 20) });
     });
 
     it('does not let the calendar pick today or later as a birth date', async () => {
@@ -394,7 +395,7 @@ describe('ClientFormPage', () => {
 
       await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
       expect(lastPayload()).toMatchObject({
-        birthDate: '2015-03-10',
+        birthDate: utcDate(2015, 3, 10),
         guardians: [
           { name: 'Ana Souza', relationship: 'Mãe', phone: '11 98888-0000', cpf: '12345678909' },
         ],
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
index 23a51a61..3fb3e013 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -10,18 +10,7 @@ import { useClientFormPage } from './useClientFormPage';
 const PAGE_PARENTS = [{ label: 'Pessoas', to: '/pessoas' }];
 
 export function ClientFormPage() {
-  const {
-    methods,
-    guardians,
-    referenceContacts,
-    age,
-    isMinor,
-    isSaving,
-    addGuardianButtonRef,
-    onSubmit,
-    addGuardian,
-    addReferenceContact,
-  } = useClientFormPage();
+  const { methods, age, isMinor, isSaving, addGuardianButtonRef, onSubmit } = useClientFormPage();
 
   return (
     <div className="mx-auto w-full max-w-3xl space-y-6">
@@ -29,18 +18,8 @@ export function ClientFormPage() {
       <FormProvider {...methods}>
         <form onSubmit={onSubmit} noValidate className="space-y-6">
           <ClientPersonSection age={age} />
-          <ClientGuardiansSection
-            fieldIds={guardians.fields.map((field) => field.id)}
-            isMinor={isMinor}
-            addButtonRef={addGuardianButtonRef}
-            onAdd={addGuardian}
-            onRemove={guardians.remove}
-          />
-          <ClientReferenceContactsSection
-            fieldIds={referenceContacts.fields.map((field) => field.id)}
-            onAdd={addReferenceContact}
-            onRemove={referenceContacts.remove}
-          />
+          <ClientGuardiansSection isMinor={isMinor} addButtonRef={addGuardianButtonRef} />
+          <ClientReferenceContactsSection />
           <FormErrorBanner />
           <FormFooter isSaving={isSaving} cancelTo="/pessoas" />
         </form>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index cfba5f8b..261d5f65 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -1,30 +1,25 @@
 import type { RefObject } from 'react';
 import { PlusIcon } from 'lucide-react';
-import { useFormContext } from 'react-hook-form';
+import { useFieldArray, useFormContext, useFormState } from 'react-hook-form';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
 import { ADULT_AGE_IN_YEARS } from '../../../../model/birthDate';
-import { MAX_GUARDIANS, type ClientFormFieldValues } from '../../../../model/clientForm';
+import {
+  MAX_GUARDIANS,
+  emptyGuardian,
+  type ClientFormFieldValues,
+} from '../../../../model/clientForm';
 import { ClientGuardianItem } from './ClientGuardianItem';
 
 interface ClientGuardiansSectionProps {
-  fieldIds: string[];
   isMinor: boolean;
   addButtonRef: RefObject<HTMLButtonElement | null>;
-  onAdd: () => void;
-  onRemove: (index: number) => void;
 }
 
-function ClientGuardiansSection({
-  fieldIds,
-  isMinor,
-  addButtonRef,
-  onAdd,
-  onRemove,
-}: ClientGuardiansSectionProps) {
-  const {
-    formState: { errors },
-  } = useFormContext<ClientFormFieldValues>();
+function ClientGuardiansSection({ isMinor, addButtonRef }: ClientGuardiansSectionProps) {
+  const { control } = useFormContext<ClientFormFieldValues>();
+  const { fields, append, remove } = useFieldArray({ control, name: 'guardians' });
+  const { errors } = useFormState({ control, name: 'guardians' });
   const listError = errors.guardians?.root?.message ?? errors.guardians?.message;
 
   return (
@@ -37,24 +32,24 @@ function ClientGuardiansSection({
           type="button"
           variant="outline"
           size="sm"
-          disabled={fieldIds.length >= MAX_GUARDIANS}
-          onClick={onAdd}
+          disabled={fields.length >= MAX_GUARDIANS}
+          onClick={() => append(emptyGuardian())}
         >
           <PlusIcon aria-hidden="true" />
           Adicionar responsável
         </Button>
       }
     >
-      {isMinor && fieldIds.length === 0 && (
+      {isMinor && fields.length === 0 && (
         <p role="status" className="rounded-md border border-border bg-muted p-3 text-sm">
           Esta pessoa tem menos de {ADULT_AGE_IN_YEARS} anos. Informe ao menos um responsável.
         </p>
       )}
 
-      {fieldIds.length > 0 && (
+      {fields.length > 0 && (
         <div className="divide-y divide-border border-t border-border">
-          {fieldIds.map((id, index) => (
-            <ClientGuardianItem key={id} index={index} onRemove={() => onRemove(index)} />
+          {fields.map((field, index) => (
+            <ClientGuardianItem key={field.id} index={index} onRemove={() => remove(index)} />
           ))}
         </div>
       )}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
index 8fa7a84c..13ee63d1 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -1,24 +1,18 @@
 import { PlusIcon } from 'lucide-react';
-import { useFormContext } from 'react-hook-form';
+import { useFieldArray, useFormContext, useFormState } from 'react-hook-form';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
-import { MAX_REFERENCE_CONTACTS, type ClientFormFieldValues } from '../../../../model/clientForm';
+import {
+  MAX_REFERENCE_CONTACTS,
+  emptyReferenceContact,
+  type ClientFormFieldValues,
+} from '../../../../model/clientForm';
 import { ClientReferenceContactItem } from './ClientReferenceContactItem';
 
-interface ClientReferenceContactsSectionProps {
-  fieldIds: string[];
-  onAdd: () => void;
-  onRemove: (index: number) => void;
-}
-
-function ClientReferenceContactsSection({
-  fieldIds,
-  onAdd,
-  onRemove,
-}: ClientReferenceContactsSectionProps) {
-  const {
-    formState: { errors },
-  } = useFormContext<ClientFormFieldValues>();
+function ClientReferenceContactsSection() {
+  const { control } = useFormContext<ClientFormFieldValues>();
+  const { fields, append, remove } = useFieldArray({ control, name: 'referenceContacts' });
+  const { errors } = useFormState({ control, name: 'referenceContacts' });
   const listError = errors.referenceContacts?.root?.message ?? errors.referenceContacts?.message;
 
   return (
@@ -30,18 +24,22 @@ function ClientReferenceContactsSection({
           type="button"
           variant="outline"
           size="sm"
-          disabled={fieldIds.length >= MAX_REFERENCE_CONTACTS}
-          onClick={onAdd}
+          disabled={fields.length >= MAX_REFERENCE_CONTACTS}
+          onClick={() => append(emptyReferenceContact())}
         >
           <PlusIcon aria-hidden="true" />
           Adicionar pessoa de referência
         </Button>
       }
     >
-      {fieldIds.length > 0 && (
+      {fields.length > 0 && (
         <div className="divide-y divide-border border-t border-border">
-          {fieldIds.map((id, index) => (
-            <ClientReferenceContactItem key={id} index={index} onRemove={() => onRemove(index)} />
+          {fields.map((field, index) => (
+            <ClientReferenceContactItem
+              key={field.id}
+              index={index}
+              onRemove={() => remove(index)}
+            />
           ))}
         </div>
       )}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index 8535478d..0d410d05 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -1,6 +1,6 @@
 import { useEffect, useRef, type SubmitEvent } from 'react';
 import { useNavigate } from 'react-router';
-import { useFieldArray, useForm, useWatch, type FieldErrors, type Path } from 'react-hook-form';
+import { useForm, useWatch, type FieldErrors, type Path } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { toFormErrors } from '@/shared/api/formErrors';
 import { applyApiProblem } from '@/shared/form/applyApiProblem';
@@ -13,8 +13,6 @@ import {
   REFERENCE_CONTACT_FORM_FIELDS,
   ageFromBirthDate,
   clientFormSchema,
-  emptyGuardian,
-  emptyReferenceContact,
   toClientFormFieldValues,
   type ClientFormFieldValues,
   type ClientFormValues,
@@ -44,8 +42,6 @@ export function useClientFormPage(): UseClientFormPageResult {
     resolver: zodResolver(clientFormSchema),
     defaultValues: toClientFormFieldValues(),
   });
-  const guardians = useFieldArray({ control: methods.control, name: 'guardians' });
-  const referenceContacts = useFieldArray({ control: methods.control, name: 'referenceContacts' });
   const birthDate = useWatch({ control: methods.control, name: 'birthDate' });
 
   const isSaving = methods.formState.isSubmitting;
@@ -92,14 +88,10 @@ export function useClientFormPage(): UseClientFormPageResult {
 
   return {
     methods,
-    guardians,
-    referenceContacts,
     age,
     isMinor,
     isSaving,
     addGuardianButtonRef,
     onSubmit: submit,
-    addGuardian: () => guardians.append(emptyGuardian()),
-    addReferenceContact: () => referenceContacts.append(emptyReferenceContact()),
   };
 }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
index 7c0a4c6a..2a55f79e 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
@@ -1,16 +1,12 @@
 import type { RefObject, SubmitEvent } from 'react';
-import type { UseFieldArrayReturn, UseFormReturn } from 'react-hook-form';
+import type { UseFormReturn } from 'react-hook-form';
 import type { ClientFormFieldValues, ClientFormValues } from '../../../model/clientForm';
 
 export interface UseClientFormPageResult {
   methods: UseFormReturn<ClientFormFieldValues, unknown, ClientFormValues>;
-  guardians: UseFieldArrayReturn<ClientFormFieldValues, 'guardians'>;
-  referenceContacts: UseFieldArrayReturn<ClientFormFieldValues, 'referenceContacts'>;
   age: number | null;
   isMinor: boolean;
   isSaving: boolean;
   addGuardianButtonRef: RefObject<HTMLButtonElement | null>;
   onSubmit: (event: SubmitEvent<HTMLFormElement>) => void;
-  addGuardian: () => void;
-  addReferenceContact: () => void;
 }
diff --git a/apps/admin-frontend/src/shared/api/generated/services-api.d.ts b/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
index 306c2cc7..8434ed1b 100644
--- a/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
+++ b/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
@@ -1847,7 +1847,7 @@ export interface components {
       id: string;
       fullName: string;
       /** Format: date */
-      birthDate: null | string;
+      birthDate: null | Date;
       phone: null | string;
       email: null | string;
       cpf: null | string;
@@ -1864,7 +1864,7 @@ export interface components {
     CreateClientCommand: {
       fullName: string;
       /** Format: date */
-      birthDate: null | string;
+      birthDate: null | Date;
       phone: null | string;
       email: null | string;
       cpf: null | string;
@@ -1983,7 +1983,7 @@ export interface components {
       clientId: string;
       fullName: string;
       /** Format: date */
-      birthDate: null | string;
+      birthDate: null | Date;
       phone: null | string;
       email: null | string;
       cpf: null | string;
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
index ec02e2c2..6513a3d0 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest';
 import { render, screen, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { FormProvider, useForm, useFormContext, useWatch } from 'react-hook-form';
+import { utcDate } from '@/shared/format/date';
 import { DateField } from './date-field';
 
 interface DummyValues {
@@ -23,8 +24,8 @@ function Harness({ initial = '', disabled = false, readOnly = false }: HarnessPr
         name="birthDate"
         label="Data de nascimento"
         hint="opcional"
-        minDate="1990-01-01"
-        maxDate="2026-10-01"
+        minDate={utcDate(1990, 1, 1)}
+        maxDate={utcDate(2026, 10, 1)}
         disabled={disabled}
         readOnly={readOnly}
       />
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
index 8227bd75..dfbb8120 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
@@ -1,13 +1,7 @@
 import { useState, type KeyboardEvent, type Ref } from 'react';
 import type { FieldValues } from 'react-hook-form';
 import { CalendarIcon } from 'lucide-react';
-import {
-  formatMaskedDate,
-  isoToLocalDate,
-  localDateToIso,
-  maskDate,
-  parseMaskedDate,
-} from '@/shared/format/date';
+import { formatMaskedDate, maskDate, parseMaskedDate } from '@/shared/format/date';
 import { Calendar } from '@/shared/ui/calendar';
 import type { FormFieldControlProps } from '@/shared/ui/form-field';
 import {
@@ -66,13 +60,14 @@ function DateFieldControl({
 
   const value = typeof fieldValue === 'string' ? fieldValue : '';
   const typedDate = parseMaskedDate(value);
-  const isSelectable = typedDate !== null && typedDate >= minDate && typedDate <= maxDate;
-  const selected = isSelectable ? isoToLocalDate(typedDate) : undefined;
-  const firstDay = isoToLocalDate(minDate);
-  const lastDay = isoToLocalDate(maxDate);
+  const isSelectable =
+    typedDate !== null &&
+    typedDate.getTime() >= minDate.getTime() &&
+    typedDate.getTime() <= maxDate.getTime();
+  const selected = isSelectable ? typedDate : undefined;
 
   function selectDate(date: Date) {
-    onChange(formatMaskedDate(localDateToIso(date)));
+    onChange(formatMaskedDate(date));
     setOpen(false);
   }
 
@@ -115,11 +110,12 @@ function DateFieldControl({
             required
             autoFocus
             captionLayout="dropdown"
+            timeZone="UTC"
             selected={selected}
-            defaultMonth={selected ?? lastDay}
-            startMonth={firstDay}
-            endMonth={lastDay}
-            disabled={[{ before: firstDay }, { after: lastDay }]}
+            defaultMonth={selected ?? maxDate}
+            startMonth={minDate}
+            endMonth={maxDate}
+            disabled={[{ before: minDate }, { after: maxDate }]}
             onSelect={selectDate}
           />
         </PopoverContent>
diff --git a/apps/admin-frontend/src/shared/form/fields/fields.types.ts b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
index 8c38216a..13e24d65 100644
--- a/apps/admin-frontend/src/shared/form/fields/fields.types.ts
+++ b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
@@ -30,8 +30,8 @@ export type DateFieldProps<T extends FieldValues> = BaseFieldProps<T> &
     ComponentProps<typeof Input>,
     RegisterOwnedProps | FormFieldOwnedProps | 'value' | 'type' | 'inputMode'
   > & {
-    minDate: string;
-    maxDate: string;
+    minDate: Date;
+    maxDate: Date;
   };
 
 export interface ControlledFieldProps<T extends FieldValues> {
diff --git a/apps/admin-frontend/src/shared/format/date.test.ts b/apps/admin-frontend/src/shared/format/date.test.ts
index b87a80a4..d5100927 100644
--- a/apps/admin-frontend/src/shared/format/date.test.ts
+++ b/apps/admin-frontend/src/shared/format/date.test.ts
@@ -1,28 +1,63 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import {
+  addDays,
   daysInMonth,
   formatMaskedDate,
   fullYearsBetween,
-  isoToLocalDate,
-  localDateToIso,
+  utcDate,
   maskDate,
   parseMaskedDate,
   todayLocal,
 } from './date';
 
+describe('utcDate', () => {
+  it('builds the calendar day at midnight UTC, with a 1-based month', () => {
+    expect(utcDate(1990, 5, 20).toISOString()).toBe('1990-05-20T00:00:00.000Z');
+  });
+});
+
 describe('todayLocal', () => {
   it.each([
-    [new Date(2026, 9, 2, 12, 0), '2026-10-02'],
-    [new Date(2026, 9, 2, 23, 59, 59), '2026-10-02'],
-    [new Date(2026, 9, 3, 0, 0, 0), '2026-10-03'],
-    [new Date(2025, 11, 31, 23, 30), '2025-12-31'],
-    [new Date(2026, 0, 1, 0, 30), '2026-01-01'],
-  ] as const)('reads %s as the calendar day on the device, %s', (instant, expected) => {
-    expect(todayLocal(instant)).toBe(expected);
-  });
+    [new Date(2026, 9, 2, 12, 0), utcDate(2026, 10, 2)],
+    [new Date(2026, 9, 2, 23, 59, 59), utcDate(2026, 10, 2)],
+    [new Date(2026, 9, 3, 0, 0, 0), utcDate(2026, 10, 3)],
+    [new Date(2025, 11, 31, 23, 30), utcDate(2025, 12, 31)],
+    [new Date(2026, 0, 1, 0, 30), utcDate(2026, 1, 1)],
+  ] as const)(
+    'reads %s as the calendar day on the device, held as midnight UTC (%s)',
+    (instant, expected) => {
+      expect(todayLocal(instant)).toEqual(expected);
+    },
+  );
 
   it('defaults to the current instant', () => {
-    expect(todayLocal()).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+    vi.useFakeTimers({ now: new Date(2026, 9, 2, 12, 0), toFake: ['Date'] });
+
+    expect(todayLocal()).toEqual(utcDate(2026, 10, 2));
+
+    vi.useRealTimers();
+  });
+});
+
+describe('addDays', () => {
+  it.each([
+    [utcDate(2026, 10, 2), 1, utcDate(2026, 10, 3)],
+    [utcDate(2026, 10, 2), -1, utcDate(2026, 10, 1)],
+    [utcDate(2026, 3, 1), -1, utcDate(2026, 2, 28)],
+    [utcDate(2024, 3, 1), -1, utcDate(2024, 2, 29)],
+    [utcDate(2027, 1, 1), -1, utcDate(2026, 12, 31)],
+    [utcDate(2026, 12, 31), 1, utcDate(2027, 1, 1)],
+    [utcDate(2026, 10, 2), 0, utcDate(2026, 10, 2)],
+  ] as const)('moves %s by %i days to %s', (date, days, expected) => {
+    expect(addDays(date, days)).toEqual(expected);
+  });
+
+  it('leaves the original date untouched', () => {
+    const date = utcDate(2026, 10, 2);
+
+    addDays(date, 5);
+
+    expect(date).toEqual(utcDate(2026, 10, 2));
   });
 });
 
@@ -45,12 +80,12 @@ describe('maskDate', () => {
 
 describe('parseMaskedDate', () => {
   it.each([
-    ['10/03/2015', '2015-03-10'],
-    ['01/01/1900', '1900-01-01'],
-    ['29/02/2000', '2000-02-29'],
-    [' 05/12/1990 ', '1990-12-05'],
+    ['10/03/2015', utcDate(2015, 3, 10)],
+    ['01/01/1900', utcDate(1900, 1, 1)],
+    ['29/02/2000', utcDate(2000, 2, 29)],
+    [' 05/12/1990 ', utcDate(1990, 12, 5)],
   ] as const)('reads %j as %s', (masked, expected) => {
-    expect(parseMaskedDate(masked)).toBe(expected);
+    expect(parseMaskedDate(masked)).toEqual(expected);
   });
 
   it.each([
@@ -72,31 +107,19 @@ describe('parseMaskedDate', () => {
 });
 
 describe('formatMaskedDate', () => {
-  it('writes an ISO date as dd/mm/aaaa', () => {
-    expect(formatMaskedDate('2015-03-10')).toBe('10/03/2015');
-    expect(formatMaskedDate('1900-01-01')).toBe('01/01/1900');
+  it('writes a date as dd/mm/aaaa', () => {
+    expect(formatMaskedDate(utcDate(2015, 3, 10))).toBe('10/03/2015');
+    expect(formatMaskedDate(utcDate(1900, 1, 1))).toBe('01/01/1900');
   });
 
-  it('round-trips with parseMaskedDate', () => {
-    expect(parseMaskedDate(formatMaskedDate('2000-02-29'))).toBe('2000-02-29');
+  it('shows the UTC calendar day, whatever the zone of the device', () => {
+    expect(formatMaskedDate(new Date('2015-03-10T00:00:00Z'))).toBe('10/03/2015');
+    expect(formatMaskedDate(new Date('2015-03-10T23:59:59Z'))).toBe('10/03/2015');
   });
-});
-
-describe('local date conversion', () => {
-  it('turns an ISO date into the same calendar day in local time', () => {
-    const date = isoToLocalDate('1990-05-20');
 
-    expect(date.getFullYear()).toBe(1990);
-    expect(date.getMonth()).toBe(4);
-    expect(date.getDate()).toBe(20);
+  it('round-trips with parseMaskedDate', () => {
+    expect(parseMaskedDate(formatMaskedDate(utcDate(2000, 2, 29)))).toEqual(utcDate(2000, 2, 29));
   });
-
-  it.each(['1990-05-20', '2000-02-29', '1900-01-01', '2026-12-31'])(
-    'round-trips %s through a local Date',
-    (isoDate) => {
-      expect(localDateToIso(isoToLocalDate(isoDate))).toBe(isoDate);
-    },
-  );
 });
 
 describe('daysInMonth', () => {
@@ -124,19 +147,27 @@ describe('fullYearsBetween', () => {
     ['1906-10-03', '2026-10-02', 119],
     ['1905-10-02', '2026-10-02', 121],
   ] as const)('counts the completed years from %s to %s as %i', (from, to, expected) => {
-    expect(fullYearsBetween(from, to)).toBe(expected);
+    expect(fullYearsBetween(new Date(from), new Date(to))).toBe(expected);
   });
 
   it('moves a February 29 anniversary to February 28 in common years, like the backend', () => {
-    expect(fullYearsBetween('2008-02-29', '2026-02-27')).toBe(17);
-    expect(fullYearsBetween('2008-02-29', '2026-02-28')).toBe(18);
-    expect(fullYearsBetween('2008-02-29', '2028-02-28')).toBe(19);
-    expect(fullYearsBetween('2008-02-29', '2028-02-29')).toBe(20);
+    const birth = utcDate(2008, 2, 29);
+
+    expect(fullYearsBetween(birth, utcDate(2026, 2, 27))).toBe(17);
+    expect(fullYearsBetween(birth, utcDate(2026, 2, 28))).toBe(18);
+    expect(fullYearsBetween(birth, utcDate(2028, 2, 28))).toBe(19);
+    expect(fullYearsBetween(birth, utcDate(2028, 2, 29))).toBe(20);
   });
 
   it('counts below zero when the end comes before the start', () => {
-    expect(fullYearsBetween('2026-10-03', '2026-10-02')).toBe(-1);
-    expect(fullYearsBetween('2026-10-02', '2025-10-02')).toBe(-1);
-    expect(fullYearsBetween('2026-10-02', '2025-10-01')).toBe(-2);
+    expect(fullYearsBetween(utcDate(2026, 10, 3), utcDate(2026, 10, 2))).toBe(-1);
+    expect(fullYearsBetween(utcDate(2026, 10, 2), utcDate(2025, 10, 2))).toBe(-1);
+    expect(fullYearsBetween(utcDate(2026, 10, 2), utcDate(2025, 10, 1))).toBe(-2);
+  });
+
+  it('counts calendar days, whatever the time of day of either date', () => {
+    expect(
+      fullYearsBetween(new Date('2008-10-02T23:59:00Z'), new Date('2026-10-02T00:01:00Z')),
+    ).toBe(18);
   });
 });
diff --git a/apps/admin-frontend/src/shared/format/date.ts b/apps/admin-frontend/src/shared/format/date.ts
index f8654084..b9985e73 100644
--- a/apps/admin-frontend/src/shared/format/date.ts
+++ b/apps/admin-frontend/src/shared/format/date.ts
@@ -1,7 +1,15 @@
 const MASKED_LENGTH = 10;
 
-export function todayLocal(now: Date = new Date()): string {
-  return localDateToIso(now);
+export function utcDate(year: number, month: number, day: number): Date {
+  return new Date(Date.UTC(year, month - 1, day));
+}
+
+export function todayLocal(now: Date = new Date()): Date {
+  return utcDate(now.getFullYear(), now.getMonth() + 1, now.getDate());
+}
+
+export function addDays(date: Date, days: number): Date {
+  return utcDate(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate() + days);
 }
 
 export function maskDate(value: string): string {
@@ -12,7 +20,7 @@ export function maskDate(value: string): string {
   return `${digits.slice(0, 2)}/${digits.slice(2, 4)}/${digits.slice(4)}`;
 }
 
-export function parseMaskedDate(masked: string): string | null {
+export function parseMaskedDate(masked: string): Date | null {
   const value = masked.trim();
   if (value.length !== MASKED_LENGTH) return null;
 
@@ -23,30 +31,26 @@ export function parseMaskedDate(masked: string): string | null {
     return null;
   }
 
-  return `${pad(year, 4)}-${pad(month, 2)}-${pad(day, 2)}`;
-}
-
-export function formatMaskedDate(isoDate: string): string {
-  const [year, month, day] = isoDate.split('-');
-  return `${day}/${month}/${year}`;
+  return utcDate(year, month, day);
 }
 
-export function isoToLocalDate(isoDate: string): Date {
-  const [year = 0, month = 1, day = 1] = isoDate.split('-').map(Number);
-  return new Date(year, month - 1, day);
-}
-
-export function localDateToIso(date: Date): string {
-  return `${pad(date.getFullYear(), 4)}-${pad(date.getMonth() + 1, 2)}-${pad(date.getDate(), 2)}`;
+export function formatMaskedDate(date: Date): string {
+  const day = pad(date.getUTCDate(), 2);
+  const month = pad(date.getUTCMonth() + 1, 2);
+  return `${day}/${month}/${pad(date.getUTCFullYear(), 4)}`;
 }
 
 export function daysInMonth(year: number, month: number): number {
   return new Date(Date.UTC(year, month, 0)).getUTCDate();
 }
 
-export function fullYearsBetween(from: string, to: string): number {
-  const start = toParts(from);
-  const end = toParts(to);
+export function fullYearsBetween(from: Date, to: Date): number {
+  const start = {
+    year: from.getUTCFullYear(),
+    month: from.getUTCMonth() + 1,
+    day: from.getUTCDate(),
+  };
+  const end = { year: to.getUTCFullYear(), month: to.getUTCMonth() + 1, day: to.getUTCDate() };
 
   const anniversary = {
     month: start.month,
@@ -59,11 +63,6 @@ export function fullYearsBetween(from: string, to: string): number {
   return end.year - start.year - (reachedAnniversary ? 0 : 1);
 }
 
-function toParts(isoDate: string): { year: number; month: number; day: number } {
-  const [year = 0, month = 0, day = 0] = isoDate.split('-').map(Number);
-  return { year, month, day };
-}
-
 function pad(value: number, length: number): string {
   return String(value).padStart(length, '0');
 }

From b8be8510a43cc717b85019c3f80d29cb454c56ab Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Sun, 11 Oct 2026 18:07:41 -0300
Subject: [PATCH 12/30] Normalize client birth-date handling

This commit aligns client birth-date handling with UTC-backed Date values across the form, shared date utilities, and generated API types. It simplifies the page by deriving age locally in the person and guardians sections, removes the page-level focus workaround for guardian-only errors, and updates the date parsing/formatting logic and tests to reflect the actual request/response contract: request schemas use Date while API responses remain ISO date strings.
---
 apps/admin-frontend/docs/ARCHITECTURE.md      |  6 +-
 .../scripts/generateApiTypes.mjs              |  8 ++-
 .../src/features/clients/model/birthDate.ts   |  6 +-
 .../src/features/clients/model/client.ts      |  1 -
 .../src/features/clients/model/clientForm.ts  |  9 +--
 .../ClientFormPage/ClientFormPage.test.tsx    | 13 ----
 .../pages/ClientFormPage/ClientFormPage.tsx   |  6 +-
 .../components/ClientGuardiansSection.tsx     | 15 ++---
 .../components/ClientPersonSection.tsx        | 11 ++--
 .../pages/ClientFormPage/useClientFormPage.ts | 19 +-----
 .../ClientFormPage/useClientFormPage.types.ts |  5 +-
 .../shared/api/generated/services-api.d.ts    |  2 +-
 .../form/fields/components/date-field.tsx     |  7 +-
 .../src/shared/format/date.test.ts            | 64 +++----------------
 apps/admin-frontend/src/shared/format/date.ts | 29 ++-------
 15 files changed, 50 insertions(+), 151 deletions(-)

diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index f5d5fa2a..0313162e 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -384,10 +384,10 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
-| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string, so the Zod schema, the payload and the backend contract are untouched. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
+| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
 | Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `features/clients/model/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
-| Calendar dates are `Date` from the form schema down to the repository; text only exists at the two edges (`dd/mm/aaaa` in the input, `yyyy-mm-dd` on the wire). `Client.birthDate`/`ClientInput.birthDate`, the schema's output, `DateField`'s `minDate`/`maxDate` and every function in `birthDate.ts` and `shared/format/date.ts` take `Date`; nothing converts a date by hand | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type and the compiler could not tell a swapped argument from a right one. A `Date` is always a real day; `parseMaskedDate` still rejects `31/02`. A `Date` here is a calendar day at **midnight UTC**, never a local instant: `utcDate(year, month, day)` is the one constructor (1-based month, so the `month - 1` off-by-one lives in one place), and comparisons, arithmetic and display read the `getUTC*` getters, so the day cannot shift with the device's zone. The one place the device's zone is read is `todayLocal`, which takes the browser's calendar day (the person's own "today", as before) and returns it as midnight UTC. `DateField` hands the calendar `timeZone="UTC"`, so the library reads and returns the same UTC days. `clientsRepository.create` is a pass-through, like the tags repository: the body carries the `Date` as is and `JSON.stringify` writes it as an instant at midnight UTC (`1990-05-20T00:00:00.000Z`). That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` (`transform`; `format: date-time` is untouched), so `birthDate` is `null | Date` in `services-api.d.ts`. **Known gap:** the same mapping types the response as `Date`, but JSON hands back a string, and nothing converts it. Nothing reads `Client.birthDate` today (the page uses `fullName`); the first screen that does must convert it (`new Date(isoDate)` is midnight UTC) or the type has to be narrowed. **Backend dependency:** as of this entry the backend does not read an instant for `BirthDate`. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`. Sending the `Date` raw needs the converter to accept an instant (and take its UTC date) first. Not branded strings (`IsoDate`) and not a `{ year, month, day }` object: the user asked for the native type, and the calendar library already speaks it. The cost is mutability and `===`: no function here mutates its argument, and equality goes through `getTime()` or `toEqual`. |
-| `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian` and `addReferenceContact`, and the references section takes no props. The one thing that stays in the hook is `addGuardianButtonRef`, still passed to the guardians section: `onInvalid` focuses the add button only when the missing guardian is the sole error, which the section cannot know, and RHF cannot do it itself (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
+| Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. `todayLocal` is the single place the device's zone is read: the browser's calendar day, returned as midnight UTC. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
+| `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/scripts/generateApiTypes.mjs b/apps/admin-frontend/scripts/generateApiTypes.mjs
index 78960b00..fc510293 100644
--- a/apps/admin-frontend/scripts/generateApiTypes.mjs
+++ b/apps/admin-frontend/scripts/generateApiTypes.mjs
@@ -34,8 +34,10 @@ function stripTenantHeaderParam(document) {
   return document;
 }
 
-function calendarDateAsDate(schemaObject) {
-  if (schemaObject.format !== 'date') return undefined;
+const REQUEST_SCHEMA_PROPERTY = /^#\/components\/schemas\/\w+(Command|Input)\//;
+
+function requestDateAsDate(schemaObject, { path: schemaPath = '' }) {
+  if (schemaObject.format !== 'date' || !REQUEST_SCHEMA_PROPERTY.test(schemaPath)) return undefined;
 
   const date = ts.factory.createTypeReferenceNode('Date');
   if (!Array.isArray(schemaObject.type) || !schemaObject.type.includes('null')) return date;
@@ -49,7 +51,7 @@ function calendarDateAsDate(schemaObject) {
 export async function generate() {
   const document = await fetch(new URL(OPENAPI_URL)).then((response) => response.json());
   const ast = await openapiTS(stripTenantHeaderParam(document), {
-    transform: calendarDateAsDate,
+    transform: requestDateAsDate,
   });
   const raw = astToString(ast);
   const prettierConfig = (await prettier.resolveConfig(__dirname)) ?? {};
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.ts b/apps/admin-frontend/src/features/clients/model/birthDate.ts
index 6e4249c2..f2d609ea 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.ts
@@ -1,10 +1,10 @@
-import { addDays, fullYearsBetween, utcDate } from '@/shared/format/date';
+import { fullYearsBetween, utcDate } from '@/shared/format/date';
 
 export const ADULT_AGE_IN_YEARS = 18;
 export const MAX_AGE_IN_YEARS = 120;
 
 export function isInThePast(birthDate: Date, today: Date): boolean {
-  return birthDate.getTime() < today.getTime();
+  return birthDate < today;
 }
 
 export function isWithinMaxAge(birthDate: Date, today: Date): boolean {
@@ -16,7 +16,7 @@ export function isMinorOn(birthDate: Date, today: Date): boolean {
 }
 
 export function latestBirthDate(today: Date): Date {
-  return addDays(today, -1);
+  return utcDate(today.getUTCFullYear(), today.getUTCMonth() + 1, today.getUTCDate() - 1);
 }
 
 export function earliestBirthDate(today: Date): Date {
diff --git a/apps/admin-frontend/src/features/clients/model/client.ts b/apps/admin-frontend/src/features/clients/model/client.ts
index b2347e71..3f687053 100644
--- a/apps/admin-frontend/src/features/clients/model/client.ts
+++ b/apps/admin-frontend/src/features/clients/model/client.ts
@@ -21,7 +21,6 @@ export interface ClientReferenceContact {
 export interface Client {
   id: string;
   fullName: string;
-  birthDate: Date | null;
   phone: string | null;
   email: string | null;
   cpf: string | null;
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index a3dbc4a7..d1929ab1 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -171,11 +171,8 @@ export function emptyReferenceContact(): ReferenceContactFormFieldValues {
 }
 
 export function ageFromBirthDate(masked: string): number | null {
-  const birthDate = parseMaskedDate(masked);
-  const today = todayLocal();
-  if (birthDate === null || !isInThePast(birthDate, today) || !isWithinMaxAge(birthDate, today)) {
-    return null;
-  }
+  const parsed = birthDateField.safeParse(masked);
+  if (!parsed.success || parsed.data === null) return null;
 
-  return fullYearsBetween(birthDate, today);
+  return fullYearsBetween(parsed.data, todayLocal());
 }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 4f9d4546..d33dd42f 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -17,7 +17,6 @@ vi.mock('../../../api/clientsRepository', () => ({
 const CREATED: Client = {
   id: '0197f2a0-0000-7000-8000-0000000000aa',
   fullName: 'Maria Souza',
-  birthDate: null,
   phone: null,
   email: null,
   cpf: null,
@@ -330,18 +329,6 @@ describe('ClientFormPage', () => {
       expect(screen.getByLabelText('Nome completo')).toHaveValue('Joana Souza');
     });
 
-    it('moves focus to the way out of the problem when only the guardian is missing', async () => {
-      const user = userEvent.setup();
-      renderPage();
-
-      await user.type(screen.getByLabelText('Nome completo'), 'Joana Souza');
-      await user.type(screen.getByLabelText('Data de nascimento'), '10032015');
-      await user.click(screen.getByRole('button', { name: 'Salvar' }));
-
-      await screen.findByRole('alert');
-      expect(screen.getByRole('button', { name: 'Adicionar responsável' })).toHaveFocus();
-    });
-
     it('keeps focus on the first invalid field when something else is wrong too', async () => {
       const user = userEvent.setup();
       renderPage();
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
index 3fb3e013..3addd691 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -10,15 +10,15 @@ import { useClientFormPage } from './useClientFormPage';
 const PAGE_PARENTS = [{ label: 'Pessoas', to: '/pessoas' }];
 
 export function ClientFormPage() {
-  const { methods, age, isMinor, isSaving, addGuardianButtonRef, onSubmit } = useClientFormPage();
+  const { methods, isSaving, onSubmit } = useClientFormPage();
 
   return (
     <div className="mx-auto w-full max-w-3xl space-y-6">
       <PageHeader parents={PAGE_PARENTS} title="Nova pessoa" />
       <FormProvider {...methods}>
         <form onSubmit={onSubmit} noValidate className="space-y-6">
-          <ClientPersonSection age={age} />
-          <ClientGuardiansSection isMinor={isMinor} addButtonRef={addGuardianButtonRef} />
+          <ClientPersonSection />
+          <ClientGuardiansSection />
           <ClientReferenceContactsSection />
           <FormErrorBanner />
           <FormFooter isSaving={isSaving} cancelTo="/pessoas" />
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index 261d5f65..3daccf04 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -1,25 +1,23 @@
-import type { RefObject } from 'react';
 import { PlusIcon } from 'lucide-react';
-import { useFieldArray, useFormContext, useFormState } from 'react-hook-form';
+import { useFieldArray, useFormContext, useFormState, useWatch } from 'react-hook-form';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
 import { ADULT_AGE_IN_YEARS } from '../../../../model/birthDate';
 import {
   MAX_GUARDIANS,
+  ageFromBirthDate,
   emptyGuardian,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
 import { ClientGuardianItem } from './ClientGuardianItem';
 
-interface ClientGuardiansSectionProps {
-  isMinor: boolean;
-  addButtonRef: RefObject<HTMLButtonElement | null>;
-}
-
-function ClientGuardiansSection({ isMinor, addButtonRef }: ClientGuardiansSectionProps) {
+function ClientGuardiansSection() {
   const { control } = useFormContext<ClientFormFieldValues>();
   const { fields, append, remove } = useFieldArray({ control, name: 'guardians' });
   const { errors } = useFormState({ control, name: 'guardians' });
+  const birthDate = useWatch({ control, name: 'birthDate' });
+  const age = ageFromBirthDate(birthDate);
+  const isMinor = age !== null && age < ADULT_AGE_IN_YEARS;
   const listError = errors.guardians?.root?.message ?? errors.guardians?.message;
 
   return (
@@ -28,7 +26,6 @@ function ClientGuardiansSection({ isMinor, addButtonRef }: ClientGuardiansSectio
       description={`Quem responde pela pessoa. Obrigatório para menores de ${ADULT_AGE_IN_YEARS} anos.`}
       action={
         <Button
-          ref={addButtonRef}
           type="button"
           variant="outline"
           size="sm"
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index fa4c6532..9473bf81 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,3 +1,4 @@
+import { useFormContext, useWatch } from 'react-hook-form';
 import { todayLocal } from '@/shared/format/date';
 import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
 import { PageSection } from '@/widgets/page-section';
@@ -5,16 +6,16 @@ import { earliestBirthDate, formatAge, latestBirthDate } from '../../../../model
 import {
   CLIENT_NAME_MAX_LENGTH,
   CLIENT_NOTES_MAX_LENGTH,
+  ageFromBirthDate,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
 import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
 import { formatCpf } from '../../../../model/cpf';
 
-interface ClientPersonSectionProps {
-  age: number | null;
-}
-
-function ClientPersonSection({ age }: ClientPersonSectionProps) {
+function ClientPersonSection() {
+  const { control } = useFormContext<ClientFormFieldValues>();
+  const birthDate = useWatch({ control, name: 'birthDate' });
+  const age = ageFromBirthDate(birthDate);
   const today = todayLocal();
 
   return (
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index 0d410d05..710d61de 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -1,17 +1,15 @@
 import { useEffect, useRef, type SubmitEvent } from 'react';
 import { useNavigate } from 'react-router';
-import { useForm, useWatch, type FieldErrors, type Path } from 'react-hook-form';
+import { useForm, type Path } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { toFormErrors } from '@/shared/api/formErrors';
 import { applyApiProblem } from '@/shared/form/applyApiProblem';
 import { toast } from '@/shared/ui/toast';
 import { clientsRepository } from '../../../api/clientsRepository';
-import { ADULT_AGE_IN_YEARS } from '../../../model/birthDate';
 import {
   CLIENT_FORM_FIELDS,
   GUARDIAN_FORM_FIELDS,
   REFERENCE_CONTACT_FORM_FIELDS,
-  ageFromBirthDate,
   clientFormSchema,
   toClientFormFieldValues,
   type ClientFormFieldValues,
@@ -36,17 +34,12 @@ function fieldPathsOf(values: ClientFormFieldValues): Path<ClientFormFieldValues
 export function useClientFormPage(): UseClientFormPageResult {
   const navigate = useNavigate();
   const isMountedRef = useRef(true);
-  const addGuardianButtonRef = useRef<HTMLButtonElement>(null);
 
   const methods = useForm<ClientFormFieldValues, unknown, ClientFormValues>({
     resolver: zodResolver(clientFormSchema),
     defaultValues: toClientFormFieldValues(),
   });
-  const birthDate = useWatch({ control: methods.control, name: 'birthDate' });
-
   const isSaving = methods.formState.isSubmitting;
-  const age = ageFromBirthDate(birthDate);
-  const isMinor = age !== null && age < ADULT_AGE_IN_YEARS;
 
   useEffect(() => {
     isMountedRef.current = true;
@@ -76,22 +69,14 @@ export function useClientFormPage(): UseClientFormPageResult {
     if (firstInvalid) methods.setFocus(firstInvalid);
   }
 
-  function onInvalid(errors: FieldErrors<ClientFormFieldValues>) {
-    const onlyGuardianMissing = Object.keys(errors).join() === 'guardians';
-    if (onlyGuardianMissing) addGuardianButtonRef.current?.focus();
-  }
-
   function submit(event: SubmitEvent<HTMLFormElement>) {
     event.preventDefault();
-    if (!isSaving) void methods.handleSubmit(onValid, onInvalid)(event);
+    if (!isSaving) void methods.handleSubmit(onValid)(event);
   }
 
   return {
     methods,
-    age,
-    isMinor,
     isSaving,
-    addGuardianButtonRef,
     onSubmit: submit,
   };
 }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
index 2a55f79e..6cb25ab8 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
@@ -1,12 +1,9 @@
-import type { RefObject, SubmitEvent } from 'react';
+import type { SubmitEvent } from 'react';
 import type { UseFormReturn } from 'react-hook-form';
 import type { ClientFormFieldValues, ClientFormValues } from '../../../model/clientForm';
 
 export interface UseClientFormPageResult {
   methods: UseFormReturn<ClientFormFieldValues, unknown, ClientFormValues>;
-  age: number | null;
-  isMinor: boolean;
   isSaving: boolean;
-  addGuardianButtonRef: RefObject<HTMLButtonElement | null>;
   onSubmit: (event: SubmitEvent<HTMLFormElement>) => void;
 }
diff --git a/apps/admin-frontend/src/shared/api/generated/services-api.d.ts b/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
index 8434ed1b..9e0fde18 100644
--- a/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
+++ b/apps/admin-frontend/src/shared/api/generated/services-api.d.ts
@@ -1847,7 +1847,7 @@ export interface components {
       id: string;
       fullName: string;
       /** Format: date */
-      birthDate: null | Date;
+      birthDate: null | string;
       phone: null | string;
       email: null | string;
       cpf: null | string;
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
index dfbb8120..566c0962 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
@@ -60,11 +60,8 @@ function DateFieldControl({
 
   const value = typeof fieldValue === 'string' ? fieldValue : '';
   const typedDate = parseMaskedDate(value);
-  const isSelectable =
-    typedDate !== null &&
-    typedDate.getTime() >= minDate.getTime() &&
-    typedDate.getTime() <= maxDate.getTime();
-  const selected = isSelectable ? typedDate : undefined;
+  const selected =
+    typedDate !== null && typedDate >= minDate && typedDate <= maxDate ? typedDate : undefined;
 
   function selectDate(date: Date) {
     onChange(formatMaskedDate(date));
diff --git a/apps/admin-frontend/src/shared/format/date.test.ts b/apps/admin-frontend/src/shared/format/date.test.ts
index d5100927..1c6821d5 100644
--- a/apps/admin-frontend/src/shared/format/date.test.ts
+++ b/apps/admin-frontend/src/shared/format/date.test.ts
@@ -1,32 +1,29 @@
 import { describe, expect, it, vi } from 'vitest';
 import {
-  addDays,
-  daysInMonth,
   formatMaskedDate,
   fullYearsBetween,
-  utcDate,
   maskDate,
   parseMaskedDate,
   todayLocal,
+  utcDate,
 } from './date';
 
 describe('utcDate', () => {
-  it('builds the calendar day at midnight UTC, with a 1-based month', () => {
+  it('is the calendar day at midnight UTC, with a 1-based month', () => {
     expect(utcDate(1990, 5, 20).toISOString()).toBe('1990-05-20T00:00:00.000Z');
   });
 });
 
 describe('todayLocal', () => {
   it.each([
-    [new Date(2026, 9, 2, 12, 0), utcDate(2026, 10, 2)],
+    [new Date(2026, 9, 2, 0, 0, 0), utcDate(2026, 10, 2)],
     [new Date(2026, 9, 2, 23, 59, 59), utcDate(2026, 10, 2)],
-    [new Date(2026, 9, 3, 0, 0, 0), utcDate(2026, 10, 3)],
     [new Date(2025, 11, 31, 23, 30), utcDate(2025, 12, 31)],
     [new Date(2026, 0, 1, 0, 30), utcDate(2026, 1, 1)],
   ] as const)(
-    'reads %s as the calendar day on the device, held as midnight UTC (%s)',
-    (instant, expected) => {
-      expect(todayLocal(instant)).toEqual(expected);
+    'reads %s as the calendar day on the device, held as midnight UTC',
+    (now, expected) => {
+      expect(todayLocal(now)).toEqual(expected);
     },
   );
 
@@ -39,28 +36,6 @@ describe('todayLocal', () => {
   });
 });
 
-describe('addDays', () => {
-  it.each([
-    [utcDate(2026, 10, 2), 1, utcDate(2026, 10, 3)],
-    [utcDate(2026, 10, 2), -1, utcDate(2026, 10, 1)],
-    [utcDate(2026, 3, 1), -1, utcDate(2026, 2, 28)],
-    [utcDate(2024, 3, 1), -1, utcDate(2024, 2, 29)],
-    [utcDate(2027, 1, 1), -1, utcDate(2026, 12, 31)],
-    [utcDate(2026, 12, 31), 1, utcDate(2027, 1, 1)],
-    [utcDate(2026, 10, 2), 0, utcDate(2026, 10, 2)],
-  ] as const)('moves %s by %i days to %s', (date, days, expected) => {
-    expect(addDays(date, days)).toEqual(expected);
-  });
-
-  it('leaves the original date untouched', () => {
-    const date = utcDate(2026, 10, 2);
-
-    addDays(date, 5);
-
-    expect(date).toEqual(utcDate(2026, 10, 2));
-  });
-});
-
 describe('maskDate', () => {
   it.each([
     ['', ''],
@@ -107,14 +82,10 @@ describe('parseMaskedDate', () => {
 });
 
 describe('formatMaskedDate', () => {
-  it('writes a date as dd/mm/aaaa', () => {
-    expect(formatMaskedDate(utcDate(2015, 3, 10))).toBe('10/03/2015');
-    expect(formatMaskedDate(utcDate(1900, 1, 1))).toBe('01/01/1900');
-  });
-
-  it('shows the UTC calendar day, whatever the zone of the device', () => {
+  it('writes the UTC calendar day as dd/mm/aaaa, whatever the zone of the device', () => {
     expect(formatMaskedDate(new Date('2015-03-10T00:00:00Z'))).toBe('10/03/2015');
     expect(formatMaskedDate(new Date('2015-03-10T23:59:59Z'))).toBe('10/03/2015');
+    expect(formatMaskedDate(utcDate(1900, 1, 1))).toBe('01/01/1900');
   });
 
   it('round-trips with parseMaskedDate', () => {
@@ -122,19 +93,6 @@ describe('formatMaskedDate', () => {
   });
 });
 
-describe('daysInMonth', () => {
-  it.each([
-    [2024, 2, 29],
-    [2025, 2, 28],
-    [1900, 2, 28],
-    [2000, 2, 29],
-    [2026, 4, 30],
-    [2026, 12, 31],
-  ] as const)('counts %i-%i as %i days', (year, month, expected) => {
-    expect(daysInMonth(year, month)).toBe(expected);
-  });
-});
-
 describe('fullYearsBetween', () => {
   it.each([
     ['2008-10-02', '2026-10-02', 18],
@@ -164,10 +122,4 @@ describe('fullYearsBetween', () => {
     expect(fullYearsBetween(utcDate(2026, 10, 2), utcDate(2025, 10, 2))).toBe(-1);
     expect(fullYearsBetween(utcDate(2026, 10, 2), utcDate(2025, 10, 1))).toBe(-2);
   });
-
-  it('counts calendar days, whatever the time of day of either date', () => {
-    expect(
-      fullYearsBetween(new Date('2008-10-02T23:59:00Z'), new Date('2026-10-02T00:01:00Z')),
-    ).toBe(18);
-  });
 });
diff --git a/apps/admin-frontend/src/shared/format/date.ts b/apps/admin-frontend/src/shared/format/date.ts
index b9985e73..8c01ae55 100644
--- a/apps/admin-frontend/src/shared/format/date.ts
+++ b/apps/admin-frontend/src/shared/format/date.ts
@@ -8,10 +8,6 @@ export function todayLocal(now: Date = new Date()): Date {
   return utcDate(now.getFullYear(), now.getMonth() + 1, now.getDate());
 }
 
-export function addDays(date: Date, days: number): Date {
-  return utcDate(date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate() + days);
-}
-
 export function maskDate(value: string): string {
   const digits = value.replace(/\D/g, '').slice(0, 8);
 
@@ -40,27 +36,16 @@ export function formatMaskedDate(date: Date): string {
   return `${day}/${month}/${pad(date.getUTCFullYear(), 4)}`;
 }
 
-export function daysInMonth(year: number, month: number): number {
-  return new Date(Date.UTC(year, month, 0)).getUTCDate();
-}
-
 export function fullYearsBetween(from: Date, to: Date): number {
-  const start = {
-    year: from.getUTCFullYear(),
-    month: from.getUTCMonth() + 1,
-    day: from.getUTCDate(),
-  };
-  const end = { year: to.getUTCFullYear(), month: to.getUTCMonth() + 1, day: to.getUTCDate() };
+  const year = to.getUTCFullYear();
+  const month = from.getUTCMonth() + 1;
+  const anniversary = utcDate(year, month, Math.min(from.getUTCDate(), daysInMonth(year, month)));
 
-  const anniversary = {
-    month: start.month,
-    day: Math.min(start.day, daysInMonth(end.year, start.month)),
-  };
-  const reachedAnniversary =
-    end.month > anniversary.month ||
-    (end.month === anniversary.month && end.day >= anniversary.day);
+  return year - from.getUTCFullYear() - (anniversary > to ? 1 : 0);
+}
 
-  return end.year - start.year - (reachedAnniversary ? 0 : 1);
+function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
 }
 
 function pad(value: number, length: number): string {

From e5e966dd2bec670e2448ebd4a3b26de7fce8a690 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Sun, 11 Oct 2026 18:14:18 -0300
Subject: [PATCH 13/30] Align client date rules with UTC

The frontend now validates client birth dates using the same UTC calendar day as the backend instead of the browser's local day. This includes replacing todayLocal with todayUtc, tightening masked date parsing, updating client form rules and UI age checks, and aligning the docs/tests with ADR 0045 so the form accepts only dates the API accepts.
---
 .../agenza-ptbr-copy/references/formatting.md | 12 +++----
 apps/admin-frontend/docs/ARCHITECTURE.md      |  4 +--
 .../features/clients/model/clientForm.test.ts |  8 ++---
 .../src/features/clients/model/clientForm.ts  |  8 ++---
 .../ClientFormPage/ClientFormPage.test.tsx    |  2 +-
 .../components/ClientPersonSection.tsx        |  4 +--
 .../src/shared/format/date.test.ts            | 27 ++++++++--------
 apps/admin-frontend/src/shared/format/date.ts | 31 +++++++++----------
 docs/adr/0045-backend-works-in-utc.md         |  4 +--
 9 files changed, 48 insertions(+), 52 deletions(-)

diff --git a/.claude/skills/agenza-ptbr-copy/references/formatting.md b/.claude/skills/agenza-ptbr-copy/references/formatting.md
index 4597868f..d3b08187 100644
--- a/.claude/skills/agenza-ptbr-copy/references/formatting.md
+++ b/.claude/skills/agenza-ptbr-copy/references/formatting.md
@@ -88,12 +88,12 @@ appointment renders one day early.
 In `admin-frontend` that is `utcDate` in `shared/format/date.ts`; the app holds a calendar day as a
 `Date` and only turns it into text where it is shown (`formatMaskedDate`).
 
-**"Today" for a form rule is the person's own day, not São Paulo's.** `todayLocal()`
-(`shared/format/date.ts`) reads the browser's calendar day. The pinned zone above is for *rendering
-instants*; it is not the answer to "what is today?" when validating a date the person typed
-([ADR 0045](../../../../docs/adr/0045-backend-works-in-utc.md)). In a test, build the clock with
-`new Date(2026, 9, 2, 12, 0)` (local fields), not an ISO string with `Z`, so it passes on a machine in
-any zone.
+**"Today" for a form rule is the UTC day, like the backend's, not São Paulo's.** `todayUtc()`
+(`shared/format/date.ts`) is the same calendar date the API uses, so a date the form accepts is one the
+API accepts. The pinned zone above is for *rendering instants*; it is not the answer to "what is
+today?" when validating a date the person typed
+([ADR 0045](../../../../docs/adr/0045-backend-works-in-utc.md)). In a test, build the clock with an ISO
+instant with `Z` (`new Date('2026-10-02T12:00:00Z')`), so it passes on a machine in any zone.
 
 Brazil has had no daylight saving since 2019, so the offset itself never moves — which is exactly why
 this bug survives review: the only thing that shifts is a date-only value, and only by one day.
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 0313162e..92ab1f82 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -383,10 +383,10 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | Review fixes on the tag dialogs (PR #125) | Two defects, one line of reasoning each. (1) `useRouteScrollReset` keys on the **section** (first path segment), not the whole `pathname`: `new`, `:id/edit` and `:id/delete` are child routes of `/tags`, so every dialog open/close used to reset `<main>`'s scroll and throw the list back to the top. (2) `useTagFormPage.onValid` and `ConfirmDialog.handleConfirm` skip closing when the dialog already unmounted mid-request (browser Back): react-router's `useNavigate` stays live after unmount, so the stale `navigate(-1)` used to pop one entry too many — out of the app, when `/tags` was the tab's first entry. FR-018 still does not block browser Back; no `useBlocker`, since the request finishes anyway and the toast still reports it. Deliberately left as is, both judged not worth the code: a row someone else already removed stays listed after its `Tag.NotFound` until the next reload or search — the spec's edge case only asks for the "não encontrada" message, which already shows; and `TagDeletePage` keeps its loaded tag if `:id` changed without a remount, because no UI path goes from `/tags/A/delete` straight to `/tags/B/delete` — the modal blocks the list, and closing it goes back to `/tags` first. A `key={id}` on the confirmation is the fix if a flow like "excluir a próxima" ever appears. |
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
-| `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayLocal()` (the browser's own calendar day, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
+| `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayUtc()` (the UTC calendar day the backend uses, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
 | `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
 | Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `features/clients/model/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
-| Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. `todayLocal` is the single place the device's zone is read: the browser's calendar day, returned as midnight UTC. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
+| Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
index e0290ae2..1ddcdee4 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
@@ -12,7 +12,7 @@ import {
   type ClientFormFieldValues,
 } from './clientForm';
 
-const LOCAL_NOON = new Date(2026, 9, 2, 12, 0);
+const NOON_UTC = new Date('2026-10-02T12:00:00Z');
 
 function values(overrides: Partial<ClientFormFieldValues> = {}): ClientFormFieldValues {
   return { ...toClientFormFieldValues(), fullName: 'Maria Souza', ...overrides };
@@ -46,7 +46,7 @@ function issuesOf(input: ClientFormFieldValues): Record<string, string> {
 }
 
 beforeEach(() => {
-  vi.useFakeTimers({ now: LOCAL_NOON, toFake: ['Date'] });
+  vi.useFakeTimers({ now: NOON_UTC, toFake: ['Date'] });
 });
 
 afterEach(() => {
@@ -221,8 +221,8 @@ describe('clientFormSchema', () => {
       expect(issues['guardians']).toBeUndefined();
     });
 
-    it('counts the local day late in the evening, before the next day starts', () => {
-      vi.setSystemTime(new Date(2026, 9, 2, 23, 30));
+    it('counts the UTC day until the last minute, before the next day starts', () => {
+      vi.setSystemTime(new Date('2026-10-02T23:59:00Z'));
 
       expect(
         issuesOf(values({ birthDate: '03/10/2008', guardians: [] }))['guardians'],
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index d1929ab1..f5e2b97e 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { fullYearsBetween, parseMaskedDate, todayLocal } from '@/shared/format/date';
+import { fullYearsBetween, parseMaskedDate, todayUtc } from '@/shared/format/date';
 import {
   ADULT_AGE_IN_YEARS,
   MAX_AGE_IN_YEARS,
@@ -78,7 +78,7 @@ const birthDateField = z.string().transform((value, ctx) => {
   const birthDate = parseMaskedDate(value);
   if (birthDate === null) return fail('Informe uma data válida no formato dd/mm/aaaa.');
 
-  const today = todayLocal();
+  const today = todayUtc();
   if (!isInThePast(birthDate, today)) return fail('A data de nascimento deve estar no passado.');
   if (!isWithinMaxAge(birthDate, today)) {
     return fail(`A data de nascimento não pode indicar idade superior a ${MAX_AGE_IN_YEARS} anos.`);
@@ -130,7 +130,7 @@ const clientFormObject = z.object({
 
 export const clientFormSchema = clientFormObject.refine(
   (value) =>
-    !value.birthDate || !isMinorOn(value.birthDate, todayLocal()) || value.guardians.length > 0,
+    !value.birthDate || !isMinorOn(value.birthDate, todayUtc()) || value.guardians.length > 0,
   {
     path: ['guardians'],
     message: `Informe ao menos um responsável para pessoas menores de ${ADULT_AGE_IN_YEARS} anos.`,
@@ -174,5 +174,5 @@ export function ageFromBirthDate(masked: string): number | null {
   const parsed = birthDateField.safeParse(masked);
   if (!parsed.success || parsed.data === null) return null;
 
-  return fullYearsBetween(parsed.data, todayLocal());
+  return fullYearsBetween(parsed.data, todayUtc());
 }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index d33dd42f..37206996 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -57,7 +57,7 @@ function lastPayload() {
 describe('ClientFormPage', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    vi.useFakeTimers({ now: new Date(2026, 9, 2, 12, 0), toFake: ['Date'] });
+    vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
     mockCreate.mockResolvedValue({ ok: true, data: CREATED });
   });
 
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 9473bf81..38b075a6 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,5 +1,5 @@
 import { useFormContext, useWatch } from 'react-hook-form';
-import { todayLocal } from '@/shared/format/date';
+import { todayUtc } from '@/shared/format/date';
 import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
 import { PageSection } from '@/widgets/page-section';
 import { earliestBirthDate, formatAge, latestBirthDate } from '../../../../model/birthDate';
@@ -16,7 +16,7 @@ function ClientPersonSection() {
   const { control } = useFormContext<ClientFormFieldValues>();
   const birthDate = useWatch({ control, name: 'birthDate' });
   const age = ageFromBirthDate(birthDate);
-  const today = todayLocal();
+  const today = todayUtc();
 
   return (
     <PageSection title="Dados da pessoa" hideTitle>
diff --git a/apps/admin-frontend/src/shared/format/date.test.ts b/apps/admin-frontend/src/shared/format/date.test.ts
index 1c6821d5..e3458e6d 100644
--- a/apps/admin-frontend/src/shared/format/date.test.ts
+++ b/apps/admin-frontend/src/shared/format/date.test.ts
@@ -4,7 +4,7 @@ import {
   fullYearsBetween,
   maskDate,
   parseMaskedDate,
-  todayLocal,
+  todayUtc,
   utcDate,
 } from './date';
 
@@ -14,23 +14,20 @@ describe('utcDate', () => {
   });
 });
 
-describe('todayLocal', () => {
+describe('todayUtc', () => {
   it.each([
-    [new Date(2026, 9, 2, 0, 0, 0), utcDate(2026, 10, 2)],
-    [new Date(2026, 9, 2, 23, 59, 59), utcDate(2026, 10, 2)],
-    [new Date(2025, 11, 31, 23, 30), utcDate(2025, 12, 31)],
-    [new Date(2026, 0, 1, 0, 30), utcDate(2026, 1, 1)],
-  ] as const)(
-    'reads %s as the calendar day on the device, held as midnight UTC',
-    (now, expected) => {
-      expect(todayLocal(now)).toEqual(expected);
-    },
-  );
+    ['2026-10-02T00:00:00Z', utcDate(2026, 10, 2)],
+    ['2026-10-02T23:59:59Z', utcDate(2026, 10, 2)],
+    ['2025-12-31T23:30:00Z', utcDate(2025, 12, 31)],
+    ['2026-01-01T00:30:00Z', utcDate(2026, 1, 1)],
+  ] as const)('reads %s as that UTC calendar day, at midnight', (instant, expected) => {
+    expect(todayUtc(new Date(instant))).toEqual(expected);
+  });
 
   it('defaults to the current instant', () => {
-    vi.useFakeTimers({ now: new Date(2026, 9, 2, 12, 0), toFake: ['Date'] });
+    vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
 
-    expect(todayLocal()).toEqual(utcDate(2026, 10, 2));
+    expect(todayUtc()).toEqual(utcDate(2026, 10, 2));
 
     vi.useRealTimers();
   });
@@ -76,6 +73,8 @@ describe('parseMaskedDate', () => {
     '10/03/0999',
     'aa/bb/cccc',
     '10-03-2015',
+    '1 /03/2015',
+    '10/03/2015/',
   ])('rejects %j', (masked) => {
     expect(parseMaskedDate(masked)).toBeNull();
   });
diff --git a/apps/admin-frontend/src/shared/format/date.ts b/apps/admin-frontend/src/shared/format/date.ts
index 8c01ae55..932ec2b4 100644
--- a/apps/admin-frontend/src/shared/format/date.ts
+++ b/apps/admin-frontend/src/shared/format/date.ts
@@ -1,11 +1,12 @@
-const MASKED_LENGTH = 10;
+const MASKED_DATE = /^(\d{2})\/(\d{2})\/(\d{4})$/;
+const MIN_YEAR = 1000;
 
 export function utcDate(year: number, month: number, day: number): Date {
   return new Date(Date.UTC(year, month - 1, day));
 }
 
-export function todayLocal(now: Date = new Date()): Date {
-  return utcDate(now.getFullYear(), now.getMonth() + 1, now.getDate());
+export function todayUtc(now: Date = new Date()): Date {
+  return utcDate(now.getUTCFullYear(), now.getUTCMonth() + 1, now.getUTCDate());
 }
 
 export function maskDate(value: string): string {
@@ -17,17 +18,16 @@ export function maskDate(value: string): string {
 }
 
 export function parseMaskedDate(masked: string): Date | null {
-  const value = masked.trim();
-  if (value.length !== MASKED_LENGTH) return null;
+  const match = MASKED_DATE.exec(masked.trim());
+  if (match === null) return null;
 
-  const [day, month, year] = value.split('/').map(Number);
-  if (day === undefined || month === undefined || year === undefined) return null;
-  if (!Number.isInteger(day) || !Number.isInteger(month) || !Number.isInteger(year)) return null;
-  if (year < 1000 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
-    return null;
-  }
+  const day = Number(match[1]);
+  const month = Number(match[2]);
+  const year = Number(match[3]);
+  if (year < MIN_YEAR) return null;
 
-  return utcDate(year, month, day);
+  const date = utcDate(year, month, day);
+  return date.getUTCMonth() + 1 === month && date.getUTCDate() === day ? date : null;
 }
 
 export function formatMaskedDate(date: Date): string {
@@ -39,15 +39,12 @@ export function formatMaskedDate(date: Date): string {
 export function fullYearsBetween(from: Date, to: Date): number {
   const year = to.getUTCFullYear();
   const month = from.getUTCMonth() + 1;
-  const anniversary = utcDate(year, month, Math.min(from.getUTCDate(), daysInMonth(year, month)));
+  const lastDayOfMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
+  const anniversary = utcDate(year, month, Math.min(from.getUTCDate(), lastDayOfMonth));
 
   return year - from.getUTCFullYear() - (anniversary > to ? 1 : 0);
 }
 
-function daysInMonth(year: number, month: number): number {
-  return new Date(Date.UTC(year, month, 0)).getUTCDate();
-}
-
 function pad(value: number, length: number): string {
   return String(value).padStart(length, '0');
 }
diff --git a/docs/adr/0045-backend-works-in-utc.md b/docs/adr/0045-backend-works-in-utc.md
index 53c009e9..b86dd24f 100644
--- a/docs/adr/0045-backend-works-in-utc.md
+++ b/docs/adr/0045-backend-works-in-utc.md
@@ -30,8 +30,8 @@ Showing an instant in local time, and reading a local date or time from the user
 - From 21:00 to midnight in Brasília (earlier in UTC−4/−5) the backend's "today" is already tomorrow. For the client
   rules that means: a person turning 18 tomorrow in Brazil is treated as an adult, and a birth date equal to the
   local today is accepted as "in the past". Accepted: nothing in the product depends on the exact hour.
-- A frontend that pre-validates with the browser's local date is stricter than the backend in that window, never
-  looser; the backend stays the authority.
+- The frontend pre-validates with the same UTC calendar date (`todayUtc`), so a birth date the form accepts is one the
+  backend accepts, in every time zone; the backend stays the authority.
 - When a rule does need the business's day — the day's agenda, opening hours, "no booking in the past" — that is a
   new decision (most likely a per-tenant IANA zone), recorded in its own ADR that supersedes this one.
 

From 3ffb521f57514c24818c6dc2c5c4f8396d903cf7 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Sun, 11 Oct 2026 18:30:17 -0300
Subject: [PATCH 14/30] asdads

---
 .../src/features/clients/model/birthDate.test.ts     | 11 ++++++++++-
 .../src/features/clients/model/birthDate.ts          |  6 +++---
 .../ClientFormPage/components/ClientGuardianItem.tsx |  2 +-
 .../components/ClientPersonSection.tsx               | 12 +++---------
 .../components/ClientReferenceContactItem.tsx        |  2 +-
 .../shared/ui/form-field/components/form-field.tsx   |  4 ++--
 6 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
index df9b0bcc..658f00a5 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import { utcDate } from '@/shared/format/date';
 import {
   earliestBirthDate,
@@ -55,6 +55,15 @@ describe('birth date picker bounds', () => {
     expect(isWithinMaxAge(utcDate(1905, 12, 31), utcDate(2026, 1, 1))).toBe(true);
     expect(isWithinMaxAge(utcDate(1905, 1, 1), utcDate(2026, 12, 31))).toBe(false);
   });
+
+  it('reads today from the clock when none is given', () => {
+    vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
+
+    expect(latestBirthDate()).toEqual(utcDate(2026, 10, 1));
+    expect(earliestBirthDate()).toEqual(utcDate(1905, 1, 1));
+
+    vi.useRealTimers();
+  });
 });
 
 describe('formatAge', () => {
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.ts b/apps/admin-frontend/src/features/clients/model/birthDate.ts
index f2d609ea..40299615 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.ts
+++ b/apps/admin-frontend/src/features/clients/model/birthDate.ts
@@ -1,4 +1,4 @@
-import { fullYearsBetween, utcDate } from '@/shared/format/date';
+import { fullYearsBetween, todayUtc, utcDate } from '@/shared/format/date';
 
 export const ADULT_AGE_IN_YEARS = 18;
 export const MAX_AGE_IN_YEARS = 120;
@@ -15,11 +15,11 @@ export function isMinorOn(birthDate: Date, today: Date): boolean {
   return isInThePast(birthDate, today) && fullYearsBetween(birthDate, today) < ADULT_AGE_IN_YEARS;
 }
 
-export function latestBirthDate(today: Date): Date {
+export function latestBirthDate(today: Date = todayUtc()): Date {
   return utcDate(today.getUTCFullYear(), today.getUTCMonth() + 1, today.getUTCDate() - 1);
 }
 
-export function earliestBirthDate(today: Date): Date {
+export function earliestBirthDate(today: Date = todayUtc()): Date {
   return utcDate(today.getUTCFullYear() - MAX_AGE_IN_YEARS - 1, 1, 1);
 }
 
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
index 4a9eeb4d..ee82359e 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -27,7 +27,7 @@ function ClientGuardianItem({ index, onRemove }: ClientGuardianItemProps) {
         </h3>
         <Button
           type="button"
-          variant="ghost"
+          variant="destructive"
           size="sm"
           onClick={onRemove}
           aria-label={`Remover responsável ${position}`}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 38b075a6..3df61b0d 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,5 +1,4 @@
 import { useFormContext, useWatch } from 'react-hook-form';
-import { todayUtc } from '@/shared/format/date';
 import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
 import { PageSection } from '@/widgets/page-section';
 import { earliestBirthDate, formatAge, latestBirthDate } from '../../../../model/birthDate';
@@ -16,7 +15,6 @@ function ClientPersonSection() {
   const { control } = useFormContext<ClientFormFieldValues>();
   const birthDate = useWatch({ control, name: 'birthDate' });
   const age = ageFromBirthDate(birthDate);
-  const today = todayUtc();
 
   return (
     <PageSection title="Dados da pessoa" hideTitle>
@@ -36,8 +34,8 @@ function ClientPersonSection() {
           name="birthDate"
           label="Data de nascimento"
           hint={age === null ? 'opcional' : formatAge(age)}
-          minDate={earliestBirthDate(today)}
-          maxDate={latestBirthDate(today)}
+          minDate={earliestBirthDate()}
+          maxDate={latestBirthDate()}
           autoComplete="off"
         />
 
@@ -71,7 +69,7 @@ function ClientPersonSection() {
           autoComplete="off"
         />
 
-        <div className="space-y-1.5 md:col-span-2">
+        <div className="md:col-span-2">
           <TextareaField<ClientFormFieldValues>
             name="administrativeNotes"
             label="Observações administrativas"
@@ -79,10 +77,6 @@ function ClientPersonSection() {
             maxLength={CLIENT_NOTES_MAX_LENGTH}
             placeholder="Ex.: prefere contato por WhatsApp pela manhã."
           />
-          <p className="text-xs text-muted-foreground">
-            Use só para informações administrativas. Não registre prontuário, diagnóstico ou outros
-            dados clínicos.
-          </p>
         </div>
       </div>
     </PageSection>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index 21a3e679..9e7f9a9a 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -28,7 +28,7 @@ function ClientReferenceContactItem({ index, onRemove }: ClientReferenceContactI
         </h3>
         <Button
           type="button"
-          variant="ghost"
+          variant="destructive"
           size="sm"
           onClick={onRemove}
           aria-label={`Remover pessoa de referência ${position}`}
diff --git a/apps/admin-frontend/src/shared/ui/form-field/components/form-field.tsx b/apps/admin-frontend/src/shared/ui/form-field/components/form-field.tsx
index 20345d4c..a31abae8 100644
--- a/apps/admin-frontend/src/shared/ui/form-field/components/form-field.tsx
+++ b/apps/admin-frontend/src/shared/ui/form-field/components/form-field.tsx
@@ -15,10 +15,10 @@ export function FormField({ label, hint, error, labelHtmlFor = true, children }:
 
   return (
     <div className="space-y-1.5">
-      <div className="flex items-center justify-between">
+      <div className="flex flex-wrap items-center justify-between gap-x-3 gap-y-1">
         <Label htmlFor={labelHtmlFor ? id : undefined}>{label}</Label>
         {hint && (
-          <span id={hintId} className="text-xs text-muted-foreground">
+          <span id={hintId} className="ml-auto text-xs whitespace-nowrap text-muted-foreground">
             {hint}
           </span>
         )}

From 24bc1ee73d2be2bf44fdfc9f0779baae9a260593 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Sun, 11 Oct 2026 18:39:41 -0300
Subject: [PATCH 15/30] =?UTF-8?q?fix(admin-frontend):=20corrige=20o=20e2e?=
 =?UTF-8?q?=20e=20o=20teste=20de=20observa=C3=A7=C3=B5es=20ap=C3=B3s=20a?=
 =?UTF-8?q?=20normaliza=C3=A7=C3=A3o=20de=20datas=20(#154)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- apiClient: o corpo da requisição passa por serializeBody, que escreve todo
  Date como yyyy-MM-dd (dia UTC). Com birthDate agora tipado como Date nos
  inputs gerados, o JSON.stringify padrão mandava 2016-06-15T00:00:00.000Z e o
  backend recusava o cadastro; o e2e do menor de idade não saía de /pessoas/nova
- date.ts: formatIsoDate (yyyy-MM-dd a partir do dia UTC), com testes
- ClientPersonSection: restaura o aviso de que as observações são só
  administrativas (sem prontuário nem dados clínicos), que o commit 3ffb521
  removeu sem tirar o teste que o exige

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .../components/ClientPersonSection.tsx        |  6 ++-
 .../src/shared/api/apiClient.test.ts          | 47 ++++++++++++++++++-
 .../src/shared/api/apiClient.ts               | 13 ++++-
 .../src/shared/format/date.test.ts            | 13 +++++
 apps/admin-frontend/src/shared/format/date.ts |  6 +++
 5 files changed, 82 insertions(+), 3 deletions(-)

diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 3df61b0d..da480260 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -69,7 +69,7 @@ function ClientPersonSection() {
           autoComplete="off"
         />
 
-        <div className="md:col-span-2">
+        <div className="space-y-1.5 md:col-span-2">
           <TextareaField<ClientFormFieldValues>
             name="administrativeNotes"
             label="Observações administrativas"
@@ -77,6 +77,10 @@ function ClientPersonSection() {
             maxLength={CLIENT_NOTES_MAX_LENGTH}
             placeholder="Ex.: prefere contato por WhatsApp pela manhã."
           />
+          <p className="text-xs text-muted-foreground">
+            Use só para informações administrativas. Não registre prontuário, diagnóstico ou outros
+            dados clínicos.
+          </p>
         </div>
       </div>
     </PageSection>
diff --git a/apps/admin-frontend/src/shared/api/apiClient.test.ts b/apps/admin-frontend/src/shared/api/apiClient.test.ts
index 6630629c..d207a139 100644
--- a/apps/admin-frontend/src/shared/api/apiClient.test.ts
+++ b/apps/admin-frontend/src/shared/api/apiClient.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi, beforeEach } from 'vitest';
-import { MissingSessionError, createApiClient } from './apiClient';
+import { MissingSessionError, createApiClient, serializeBody } from './apiClient';
 
 const CATEGORIES_PATH = '/api/v{version}/categories' as const;
 const REQUEST_PARAMS = { params: { path: { version: '1.0' } } };
@@ -35,6 +35,27 @@ describe('createApiClient', () => {
     expect(request.headers.get('X-Tenant-Id')).toBe('tenant-2');
   });
 
+  it('sends a Date in the body as a calendar day, not as an instant', async () => {
+    const client = createApiClient(() => ({ accessToken: 'token-1', tenantId: 'tenant-1' }));
+
+    await client.POST('/api/v{version}/clients', {
+      params: { path: { version: '1.0' } },
+      body: {
+        fullName: 'Maria Souza',
+        birthDate: new Date('2016-06-15T00:00:00Z'),
+        phone: null,
+        email: null,
+        cpf: null,
+        administrativeNotes: null,
+        guardians: [],
+        referenceContacts: [],
+      },
+    });
+
+    const request = fetchMock.mock.calls[0]?.[0] as Request;
+    expect(JSON.parse(await request.text())).toMatchObject({ birthDate: '2016-06-15' });
+  });
+
   it.each([
     ['accessToken', { accessToken: null, tenantId: 'tenant-1' }],
     ['tenantId', { accessToken: 'token-1', tenantId: null }],
@@ -50,3 +71,27 @@ describe('createApiClient', () => {
     },
   );
 });
+
+describe('serializeBody', () => {
+  it('turns every Date, however deep, into yyyy-MM-dd and leaves other values alone', () => {
+    const body = {
+      name: 'Maria',
+      count: 2,
+      nothing: null,
+      from: new Date('1990-05-20T00:00:00Z'),
+      nested: { items: [{ day: new Date('2000-02-29T00:00:00Z') }, 'text'] },
+    };
+
+    expect(JSON.parse(serializeBody(body))).toEqual({
+      name: 'Maria',
+      count: 2,
+      nothing: null,
+      from: '1990-05-20',
+      nested: { items: [{ day: '2000-02-29' }, 'text'] },
+    });
+  });
+
+  it('reads the UTC day, whatever the zone of the device', () => {
+    expect(serializeBody({ day: new Date('2015-03-10T23:59:59Z') })).toBe('{"day":"2015-03-10"}');
+  });
+});
diff --git a/apps/admin-frontend/src/shared/api/apiClient.ts b/apps/admin-frontend/src/shared/api/apiClient.ts
index beb68270..8ade9e33 100644
--- a/apps/admin-frontend/src/shared/api/apiClient.ts
+++ b/apps/admin-frontend/src/shared/api/apiClient.ts
@@ -1,6 +1,7 @@
 import createClient, { type Client } from 'openapi-fetch';
 import type { paths } from './generated/services-api.d.ts';
 import { loadEnv } from '@/shared/env';
+import { formatIsoDate } from '@/shared/format/date';
 
 export interface ApiClientCredentials {
   accessToken: string | null;
@@ -14,6 +15,16 @@ export class MissingSessionError extends Error {
   }
 }
 
+export function serializeBody(body: unknown): string {
+  return JSON.stringify(
+    body,
+    function (this: Record<string, unknown>, key: string, value: unknown) {
+      const original = this[key];
+      return original instanceof Date ? formatIsoDate(original) : value;
+    },
+  );
+}
+
 /** Single entry point for services-service (contracts/api-client-contract.md). Narrow
  * `{ accessToken, tenantId }` shape, not auth's types — `shared/` can't depend on `features/*`.
  * Takes a getter, not a value: the client is meant to be built once and reused, and reading
@@ -21,7 +32,7 @@ export class MissingSessionError extends Error {
  * across token renewal and tenant changes. */
 export function createApiClient(getCredentials: () => ApiClientCredentials): Client<paths> {
   const env = loadEnv();
-  const client = createClient<paths>({ baseUrl: env.apiBaseUrl });
+  const client = createClient<paths>({ baseUrl: env.apiBaseUrl, bodySerializer: serializeBody });
 
   client.use({
     onRequest({ request }) {
diff --git a/apps/admin-frontend/src/shared/format/date.test.ts b/apps/admin-frontend/src/shared/format/date.test.ts
index e3458e6d..7a7a92a3 100644
--- a/apps/admin-frontend/src/shared/format/date.test.ts
+++ b/apps/admin-frontend/src/shared/format/date.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
 import {
+  formatIsoDate,
   formatMaskedDate,
   fullYearsBetween,
   maskDate,
@@ -92,6 +93,18 @@ describe('formatMaskedDate', () => {
   });
 });
 
+describe('formatIsoDate', () => {
+  it('writes the UTC calendar day as yyyy-MM-dd, whatever the zone of the device', () => {
+    expect(formatIsoDate(new Date('2015-03-10T00:00:00Z'))).toBe('2015-03-10');
+    expect(formatIsoDate(new Date('2015-03-10T23:59:59Z'))).toBe('2015-03-10');
+    expect(formatIsoDate(utcDate(1900, 1, 1))).toBe('1900-01-01');
+  });
+
+  it('round-trips with utcDate', () => {
+    expect(formatIsoDate(utcDate(2000, 2, 29))).toBe('2000-02-29');
+  });
+});
+
 describe('fullYearsBetween', () => {
   it.each([
     ['2008-10-02', '2026-10-02', 18],
diff --git a/apps/admin-frontend/src/shared/format/date.ts b/apps/admin-frontend/src/shared/format/date.ts
index 932ec2b4..591ce988 100644
--- a/apps/admin-frontend/src/shared/format/date.ts
+++ b/apps/admin-frontend/src/shared/format/date.ts
@@ -36,6 +36,12 @@ export function formatMaskedDate(date: Date): string {
   return `${day}/${month}/${pad(date.getUTCFullYear(), 4)}`;
 }
 
+export function formatIsoDate(date: Date): string {
+  const month = pad(date.getUTCMonth() + 1, 2);
+  const day = pad(date.getUTCDate(), 2);
+  return `${pad(date.getUTCFullYear(), 4)}-${month}-${day}`;
+}
+
 export function fullYearsBetween(from: Date, to: Date): number {
   const year = to.getUTCFullYear();
   const month = from.getUTCMonth() + 1;

From 592d9f3e9a1424adb317f2cdce94ba613ae73c00 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 10:34:31 -0300
Subject: [PATCH 16/30] refactor(clients): improve contact sections readability

---
 .../components/ClientGuardiansSection.tsx       | 17 +++++++++++------
 .../ClientReferenceContactsSection.tsx          | 14 +++++++++-----
 2 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index 3daccf04..ff99f0ab 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -16,9 +16,14 @@ function ClientGuardiansSection() {
   const { fields, append, remove } = useFieldArray({ control, name: 'guardians' });
   const { errors } = useFormState({ control, name: 'guardians' });
   const birthDate = useWatch({ control, name: 'birthDate' });
+
+  const hasGuardians = fields.length > 0;
+  const hasReachedGuardianLimit = fields.length >= MAX_GUARDIANS;
+  const guardiansError = errors.guardians?.root?.message ?? errors.guardians?.message;
+
   const age = ageFromBirthDate(birthDate);
   const isMinor = age !== null && age < ADULT_AGE_IN_YEARS;
-  const listError = errors.guardians?.root?.message ?? errors.guardians?.message;
+  const needsGuardian = isMinor && !hasGuardians;
 
   return (
     <PageSection
@@ -29,7 +34,7 @@ function ClientGuardiansSection() {
           type="button"
           variant="outline"
           size="sm"
-          disabled={fields.length >= MAX_GUARDIANS}
+          disabled={hasReachedGuardianLimit}
           onClick={() => append(emptyGuardian())}
         >
           <PlusIcon aria-hidden="true" />
@@ -37,13 +42,13 @@ function ClientGuardiansSection() {
         </Button>
       }
     >
-      {isMinor && fields.length === 0 && (
+      {needsGuardian && (
         <p role="status" className="rounded-md border border-border bg-muted p-3 text-sm">
           Esta pessoa tem menos de {ADULT_AGE_IN_YEARS} anos. Informe ao menos um responsável.
         </p>
       )}
 
-      {fields.length > 0 && (
+      {hasGuardians && (
         <div className="divide-y divide-border border-t border-border">
           {fields.map((field, index) => (
             <ClientGuardianItem key={field.id} index={index} onRemove={() => remove(index)} />
@@ -51,9 +56,9 @@ function ClientGuardiansSection() {
         </div>
       )}
 
-      {listError && (
+      {guardiansError && (
         <p role="alert" className="text-sm text-destructive">
-          {listError}
+          {guardiansError}
         </p>
       )}
     </PageSection>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
index 13ee63d1..bffc9ec7 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -13,7 +13,11 @@ function ClientReferenceContactsSection() {
   const { control } = useFormContext<ClientFormFieldValues>();
   const { fields, append, remove } = useFieldArray({ control, name: 'referenceContacts' });
   const { errors } = useFormState({ control, name: 'referenceContacts' });
-  const listError = errors.referenceContacts?.root?.message ?? errors.referenceContacts?.message;
+
+  const hasReferenceContacts = fields.length > 0;
+  const hasReachedReferenceContactLimit = fields.length >= MAX_REFERENCE_CONTACTS;
+  const referenceContactsError =
+    errors.referenceContacts?.root?.message ?? errors.referenceContacts?.message;
 
   return (
     <PageSection
@@ -24,7 +28,7 @@ function ClientReferenceContactsSection() {
           type="button"
           variant="outline"
           size="sm"
-          disabled={fields.length >= MAX_REFERENCE_CONTACTS}
+          disabled={hasReachedReferenceContactLimit}
           onClick={() => append(emptyReferenceContact())}
         >
           <PlusIcon aria-hidden="true" />
@@ -32,7 +36,7 @@ function ClientReferenceContactsSection() {
         </Button>
       }
     >
-      {fields.length > 0 && (
+      {hasReferenceContacts && (
         <div className="divide-y divide-border border-t border-border">
           {fields.map((field, index) => (
             <ClientReferenceContactItem
@@ -44,9 +48,9 @@ function ClientReferenceContactsSection() {
         </div>
       )}
 
-      {listError && (
+      {referenceContactsError && (
         <p role="alert" className="text-sm text-destructive">
-          {listError}
+          {referenceContactsError}
         </p>
       )}
     </PageSection>

From 340beafa94aa744181784c3c4f5d4e4d081cc82d Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 11:05:28 -0300
Subject: [PATCH 17/30] Improve form error handling and date UX

This change centralizes API error application so RHF derives field paths from current values, maps nested and array errors automatically, and focuses the first invalid field without page-specific path lists. It also adds a reusable FieldError component for collection and nested field messages, and updates the date field to support clearing via both the inline X and the calendar footer while preserving validation behavior.
---
 apps/admin-frontend/docs/ARCHITECTURE.md      |  19 ++-
 .../ClientFormPage/ClientFormPage.test.tsx    |  19 +++
 .../components/ClientGuardiansSection.tsx     |  11 +-
 .../ClientReferenceContactsSection.tsx        |  12 +-
 .../pages/ClientFormPage/useClientFormPage.ts |  25 +---
 .../ui/pages/TagFormPage/useTagFormPage.ts    |   3 +-
 .../src/shared/form/applyApiProblem.test.ts   | 122 ++++++++++++++++--
 .../src/shared/form/applyApiProblem.ts        |  29 ++++-
 .../fields/components/date-field.test.tsx     |  66 ++++++++++
 .../form/fields/components/date-field.tsx     |  37 +++++-
 .../fields/components/field-error.test.tsx    |  95 ++++++++++++++
 .../form/fields/components/field-error.tsx    |  16 +++
 .../src/shared/form/fields/fields.types.ts    |   4 +
 .../src/shared/form/fields/index.tsx          |   2 +
 14 files changed, 396 insertions(+), 64 deletions(-)
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/field-error.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/field-error.tsx

diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 92ab1f82..5efe61b0 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -236,6 +236,23 @@ with `ok()` / `fail()` in `shared/result.ts` — custom, ~6 lines, no library. N
 The interface layer branches on `result.ok`, then on `result.error.code` / `.status`, renders
 `result.error.title`, reads `result.error.errors` directly.
 
+**Form mutations apply backend errors with `applyApiProblem(result.error, methods)`.** The shared
+RHF bridge derives paths from `methods.getValues()`, including nested objects, current array items
+and collection roots, maps the problem once through `toFormErrors`, sets field/general errors and
+attempts to focus the first invalid field in value traversal order. Pages no longer maintain error
+path lists or repeat the focus loop. Every form field must be represented in its current values
+(normally through `defaultValues`); unknown backend paths become `root.serverError`. Dates and other
+non-plain objects remain leaf values. Collection errors still render in the section: without a
+registered focusable ref, `setFocus` cannot move focus to a collection root.
+
+**Standalone field and collection errors use `FieldError<T>` from `shared/form/fields`.** Inside
+`FormProvider`, `<FieldError<ClientFormFieldValues> name="guardians" />` subscribes to that path with
+`useFormState` and reads it through `getFieldState`, including indexed nested paths. It renders a
+`role="alert"` message only when an error exists, preferring `root.message` for field-array validation
+over `message`. Backend and resolver errors share this rendering; it has no domain rules.
+`FormErrorBanner` remains responsible for the form-wide `root.serverError`, and field controls keep
+their existing `FormField` error rendering to avoid duplicate messages.
+
 **`Result` is the internal currency; the framework boundary is the cashier.** `servicesApi` never
 rejects, but React Router and TanStack Query signal failure _only_ by a rejected promise — a
 `loader` or `queryFn` that returns `{ ok: false, error }` reads as success. `shared/api/unwrap.ts`
@@ -384,7 +401,7 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayUtc()` (the UTC calendar day the backend uses, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
-| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. |
+| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. The date is optional, so the field can be cleared two ways besides erasing the text: an X inside the input (`aria-label="Limpar data"`, only while there is a value and the field is not disabled or read-only; it hands the cursor back to the input with RHF's `setFocus`) and a `Limpar` button in the calendar's footer (disabled while empty; it closes the calendar). Neither name contains the field label, because the e2e finds the field by label substring. The calendar stays `required`, so clicking the selected day again does nothing. |
 | Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `features/clients/model/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
 | Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 37206996..0a7ab183 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -198,6 +198,25 @@ describe('ClientFormPage', () => {
       expect(screen.getByText('36 anos')).toBeInTheDocument();
     });
 
+    it('clears the birth date, drops the age and sends no birth date', async () => {
+      const user = userEvent.setup();
+      renderPage();
+
+      await user.type(screen.getByLabelText('Nome completo'), 'Maria Souza');
+      await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
+      expect(screen.getByText('36 anos')).toBeInTheDocument();
+
+      await user.click(screen.getByRole('button', { name: 'Limpar data' }));
+
+      expect(screen.getByLabelText('Data de nascimento')).toHaveValue('');
+      expect(screen.queryByText('36 anos')).not.toBeInTheDocument();
+
+      await user.click(screen.getByRole('button', { name: 'Salvar' }));
+
+      await waitFor(() => expect(mockCreate).toHaveBeenCalledTimes(1));
+      expect(lastPayload()).toMatchObject({ birthDate: null });
+    });
+
     it('picks the birth date from the calendar, shows the age and sends the date', async () => {
       const user = userEvent.setup();
       renderPage();
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index ff99f0ab..56d52e9a 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -1,5 +1,6 @@
 import { PlusIcon } from 'lucide-react';
-import { useFieldArray, useFormContext, useFormState, useWatch } from 'react-hook-form';
+import { useFieldArray, useFormContext, useWatch } from 'react-hook-form';
+import { FieldError } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
 import { ADULT_AGE_IN_YEARS } from '../../../../model/birthDate';
@@ -14,12 +15,10 @@ import { ClientGuardianItem } from './ClientGuardianItem';
 function ClientGuardiansSection() {
   const { control } = useFormContext<ClientFormFieldValues>();
   const { fields, append, remove } = useFieldArray({ control, name: 'guardians' });
-  const { errors } = useFormState({ control, name: 'guardians' });
   const birthDate = useWatch({ control, name: 'birthDate' });
 
   const hasGuardians = fields.length > 0;
   const hasReachedGuardianLimit = fields.length >= MAX_GUARDIANS;
-  const guardiansError = errors.guardians?.root?.message ?? errors.guardians?.message;
 
   const age = ageFromBirthDate(birthDate);
   const isMinor = age !== null && age < ADULT_AGE_IN_YEARS;
@@ -56,11 +55,7 @@ function ClientGuardiansSection() {
         </div>
       )}
 
-      {guardiansError && (
-        <p role="alert" className="text-sm text-destructive">
-          {guardiansError}
-        </p>
-      )}
+      <FieldError<ClientFormFieldValues> name="guardians" />
     </PageSection>
   );
 }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
index bffc9ec7..45ea4654 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -1,5 +1,6 @@
 import { PlusIcon } from 'lucide-react';
-import { useFieldArray, useFormContext, useFormState } from 'react-hook-form';
+import { useFieldArray, useFormContext } from 'react-hook-form';
+import { FieldError } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
 import {
@@ -12,12 +13,9 @@ import { ClientReferenceContactItem } from './ClientReferenceContactItem';
 function ClientReferenceContactsSection() {
   const { control } = useFormContext<ClientFormFieldValues>();
   const { fields, append, remove } = useFieldArray({ control, name: 'referenceContacts' });
-  const { errors } = useFormState({ control, name: 'referenceContacts' });
 
   const hasReferenceContacts = fields.length > 0;
   const hasReachedReferenceContactLimit = fields.length >= MAX_REFERENCE_CONTACTS;
-  const referenceContactsError =
-    errors.referenceContacts?.root?.message ?? errors.referenceContacts?.message;
 
   return (
     <PageSection
@@ -48,11 +46,7 @@ function ClientReferenceContactsSection() {
         </div>
       )}
 
-      {referenceContactsError && (
-        <p role="alert" className="text-sm text-destructive">
-          {referenceContactsError}
-        </p>
-      )}
+      <FieldError<ClientFormFieldValues> name="referenceContacts" />
     </PageSection>
   );
 }
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index 710d61de..fd018615 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -1,15 +1,11 @@
 import { useEffect, useRef, type SubmitEvent } from 'react';
 import { useNavigate } from 'react-router';
-import { useForm, type Path } from 'react-hook-form';
+import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { toFormErrors } from '@/shared/api/formErrors';
 import { applyApiProblem } from '@/shared/form/applyApiProblem';
 import { toast } from '@/shared/ui/toast';
 import { clientsRepository } from '../../../api/clientsRepository';
 import {
-  CLIENT_FORM_FIELDS,
-  GUARDIAN_FORM_FIELDS,
-  REFERENCE_CONTACT_FORM_FIELDS,
   clientFormSchema,
   toClientFormFieldValues,
   type ClientFormFieldValues,
@@ -19,18 +15,6 @@ import type { UseClientFormPageResult } from './useClientFormPage.types';
 
 const CLIENTS_PATH = '/pessoas';
 
-function fieldPathsOf(values: ClientFormFieldValues): Path<ClientFormFieldValues>[] {
-  return [
-    ...CLIENT_FORM_FIELDS,
-    ...values.guardians.flatMap((_, index) =>
-      GUARDIAN_FORM_FIELDS.map((field) => `guardians.${index}.${field}` as const),
-    ),
-    ...values.referenceContacts.flatMap((_, index) =>
-      REFERENCE_CONTACT_FORM_FIELDS.map((field) => `referenceContacts.${index}.${field}` as const),
-    ),
-  ];
-}
-
 export function useClientFormPage(): UseClientFormPageResult {
   const navigate = useNavigate();
   const isMountedRef = useRef(true);
@@ -61,12 +45,7 @@ export function useClientFormPage(): UseClientFormPageResult {
       return;
     }
 
-    const paths = fieldPathsOf(methods.getValues());
-    applyApiProblem<ClientFormFieldValues>(result.error, paths, methods.setError);
-
-    const { fieldErrors } = toFormErrors(result.error, paths);
-    const firstInvalid = paths.find((path) => fieldErrors[path]);
-    if (firstInvalid) methods.setFocus(firstInvalid);
+    applyApiProblem(result.error, methods);
   }
 
   function submit(event: SubmitEvent<HTMLFormElement>) {
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
index a7633705..ae18b358 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
@@ -7,7 +7,6 @@ import { applyApiProblem } from '@/shared/form/applyApiProblem';
 import { tagsRepository } from '../../../api/tagsRepository';
 import { createTag, updateTag } from '../../../application/tagUseCases';
 import {
-  TAG_FORM_FIELDS,
   tagFormSchema,
   toTagFormFieldValues,
   type TagFormFieldValues,
@@ -88,7 +87,7 @@ export function useTagFormPage(): UseTagFormPageResult {
       return;
     }
 
-    applyApiProblem<TagFormFieldValues>(result.error, TAG_FORM_FIELDS, methods.setError);
+    applyApiProblem(result.error, methods);
   }
 
   function submit(event: SubmitEvent<HTMLFormElement>) {
diff --git a/apps/admin-frontend/src/shared/form/applyApiProblem.test.ts b/apps/admin-frontend/src/shared/form/applyApiProblem.test.ts
index 5566cd31..6c8af446 100644
--- a/apps/admin-frontend/src/shared/form/applyApiProblem.test.ts
+++ b/apps/admin-frontend/src/shared/form/applyApiProblem.test.ts
@@ -7,11 +7,17 @@ interface DummyValues {
   color: string;
 }
 
-const FIELDS = ['name', 'color'] as const;
+function formMethods() {
+  return {
+    getValues: () => ({ name: '', color: '' }),
+    setError: vi.fn(),
+    setFocus: vi.fn(),
+  };
+}
 
 describe('applyApiProblem', () => {
   it('sets an error for each mapped field', () => {
-    const setError = vi.fn();
+    const methods = formMethods();
     const problem: ApiProblem = {
       status: 400,
       title: 'Ocorreram erros de validação.',
@@ -20,17 +26,18 @@ describe('applyApiProblem', () => {
       },
     };
 
-    applyApiProblem<DummyValues>(problem, FIELDS, setError);
+    applyApiProblem<DummyValues>(problem, methods);
 
-    expect(setError).toHaveBeenCalledWith('name', {
+    expect(methods.setError).toHaveBeenCalledWith('name', {
       type: 'server',
       message: 'O nome é obrigatório.',
     });
-    expect(setError).toHaveBeenCalledTimes(1);
+    expect(methods.setError).toHaveBeenCalledTimes(1);
+    expect(methods.setFocus).toHaveBeenCalledExactlyOnceWith('name');
   });
 
   it('sets root.serverError for an unmatched form-level message, without touching any field', () => {
-    const setError = vi.fn();
+    const methods = formMethods();
     const problem: ApiProblem = {
       status: 409,
       title: 'Já existe um registro com esse nome.',
@@ -39,21 +46,112 @@ describe('applyApiProblem', () => {
       },
     };
 
-    applyApiProblem<DummyValues>(problem, FIELDS, setError);
+    applyApiProblem<DummyValues>(problem, methods);
 
-    expect(setError).toHaveBeenCalledWith('root.serverError', {
+    expect(methods.setError).toHaveBeenCalledWith('root.serverError', {
       type: 'server',
       message: 'Já existe um registro com esse nome.',
     });
-    expect(setError).toHaveBeenCalledTimes(1);
+    expect(methods.setError).toHaveBeenCalledTimes(1);
+    expect(methods.setFocus).not.toHaveBeenCalled();
   });
 
   it('does nothing when there is no field error and no form-level message', () => {
-    const setError = vi.fn();
+    const methods = formMethods();
     const problem: ApiProblem = { status: 400, title: '', errors: {} };
 
-    applyApiProblem<DummyValues>(problem, FIELDS, setError);
+    applyApiProblem<DummyValues>(problem, methods);
+
+    expect(methods.setError).not.toHaveBeenCalled();
+    expect(methods.setFocus).not.toHaveBeenCalled();
+  });
+
+  it('maps current nested array items and focuses the first invalid field in form order', () => {
+    const methods = {
+      getValues: () => ({
+        guardians: [{ name: 'Ana' }, { name: '' }],
+        referenceContacts: [{ purposes: ['operationalSupport'] }],
+      }),
+      setError: vi.fn(),
+      setFocus: vi.fn(),
+    };
+    const problem: ApiProblem = {
+      status: 400,
+      errors: {
+        'ReferenceContacts[0].Purposes[0]': [{ message: 'Finalidade inválida.' }],
+        'Guardians[1].Name': [{ message: 'O nome do responsável é obrigatório.' }],
+      },
+    };
+
+    applyApiProblem(problem, methods);
+
+    expect(methods.setError).toHaveBeenCalledWith('guardians.1.name', {
+      type: 'server',
+      message: 'O nome do responsável é obrigatório.',
+    });
+    expect(methods.setError).toHaveBeenCalledWith('referenceContacts.0.purposes.0', {
+      type: 'server',
+      message: 'Finalidade inválida.',
+    });
+    expect(methods.setError).toHaveBeenCalledTimes(2);
+    expect(methods.setFocus).toHaveBeenCalledExactlyOnceWith('guardians.1.name');
+  });
+
+  it('maps array-level errors even when the array is empty', () => {
+    const methods = {
+      getValues: () => ({ guardians: [] }),
+      setError: vi.fn(),
+      setFocus: vi.fn(),
+    };
+
+    applyApiProblem(
+      { status: 400, errors: { Guardians: [{ message: 'Informe um responsável.' }] } },
+      methods,
+    );
+
+    expect(methods.setError).toHaveBeenCalledExactlyOnceWith('guardians', {
+      type: 'server',
+      message: 'Informe um responsável.',
+    });
+  });
+
+  it('treats null, undefined and dates as field values and unknown paths as form errors', () => {
+    const methods = {
+      getValues: () => ({ name: undefined, color: null, birthDate: new Date('2000-01-01') }),
+      setError: vi.fn(),
+      setFocus: vi.fn(),
+    };
+
+    applyApiProblem(
+      {
+        status: 400,
+        errors: {
+          Name: [{ message: 'Nome obrigatório.' }],
+          Color: [{ message: 'Cor obrigatória.' }],
+          BirthDate: [{ message: 'Data inválida.' }],
+          Unknown: [{ message: 'Erro geral.' }],
+        },
+      },
+      methods,
+    );
 
-    expect(setError).not.toHaveBeenCalled();
+    expect(methods.setError).toHaveBeenNthCalledWith(1, 'name', {
+      type: 'server',
+      message: 'Nome obrigatório.',
+    });
+    expect(methods.setError).toHaveBeenNthCalledWith(2, 'color', {
+      type: 'server',
+      message: 'Cor obrigatória.',
+    });
+    expect(methods.setError).toHaveBeenNthCalledWith(3, 'birthDate', {
+      type: 'server',
+      message: 'Data inválida.',
+    });
+    expect(methods.setError).toHaveBeenNthCalledWith(4, 'root.serverError', {
+      type: 'server',
+      message: 'Erro geral.',
+    });
+    expect(methods.setError).toHaveBeenCalledTimes(4);
+    expect(methods.setFocus).toHaveBeenCalledExactlyOnceWith('name');
   });
 });
diff --git a/apps/admin-frontend/src/shared/form/applyApiProblem.ts b/apps/admin-frontend/src/shared/form/applyApiProblem.ts
index 04abc51d..fde225f1 100644
--- a/apps/admin-frontend/src/shared/form/applyApiProblem.ts
+++ b/apps/admin-frontend/src/shared/form/applyApiProblem.ts
@@ -1,16 +1,35 @@
-import type { FieldValues, Path, UseFormSetError } from 'react-hook-form';
+import type { FieldValues, Path, UseFormReturn } from 'react-hook-form';
 import type { ApiProblem } from '@/shared/api/servicesFacade';
 import { toFormErrors } from '@/shared/api/formErrors';
 
+function fieldPathsOf(values: unknown, prefix = ''): string[] {
+  if (
+    values === null ||
+    typeof values !== 'object' ||
+    (!Array.isArray(values) && Object.getPrototypeOf(values) !== Object.prototype)
+  ) {
+    return [];
+  }
+
+  return Object.entries(values).flatMap(([key, value]) => {
+    const path = prefix ? `${prefix}.${key}` : key;
+    return [path, ...fieldPathsOf(value, path)];
+  });
+}
+
 export function applyApiProblem<T extends FieldValues>(
   problem: ApiProblem,
-  fields: readonly Path<T>[],
-  setError: UseFormSetError<T>,
+  methods: Pick<UseFormReturn<T>, 'setError' | 'setFocus'> & { getValues: () => T },
 ): void {
+  const fields = fieldPathsOf(methods.getValues()) as Path<T>[];
   const { fieldErrors, formError } = toFormErrors(problem, fields);
+
   for (const field of fields) {
     const message = fieldErrors[field];
-    if (message) setError(field, { type: 'server', message });
+    if (message) methods.setError(field, { type: 'server', message });
   }
-  if (formError) setError('root.serverError', { type: 'server', message: formError });
+  if (formError) methods.setError('root.serverError', { type: 'server', message: formError });
+
+  const firstInvalid = fields.find((field) => fieldErrors[field]);
+  if (firstInvalid) methods.setFocus(firstInvalid);
 }
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
index 6513a3d0..a139689c 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
@@ -98,6 +98,72 @@ describe('DateField', () => {
     expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
   });
 
+  describe('clearing the date', () => {
+    function clearButton() {
+      return screen.queryByRole('button', { name: 'Limpar data' });
+    }
+
+    it('offers the clear button only while the field holds a date', async () => {
+      const user = userEvent.setup();
+      render(<Harness />);
+
+      expect(clearButton()).not.toBeInTheDocument();
+
+      await user.type(input(), '2');
+
+      expect(clearButton()).toBeInTheDocument();
+    });
+
+    it('names the clear button without repeating the field label, so the label still finds one control', () => {
+      render(<Harness initial="07/08/1995" />);
+
+      expect(clearButton()).not.toHaveAccessibleName(/data de nascimento/i);
+      expect(screen.getAllByLabelText(/data de nascimento/i)).toHaveLength(1);
+    });
+
+    it('empties the field and the form from the clear button, and puts the cursor back in the field', async () => {
+      const user = userEvent.setup();
+      render(<Harness initial="07/08/1995" />);
+
+      await user.click(clearButton()!);
+
+      expect(input()).toHaveValue('');
+      expect(screen.getByLabelText('valor do formulário')).toBeEmptyDOMElement();
+      expect(input()).toHaveFocus();
+      expect(clearButton()).not.toBeInTheDocument();
+    });
+
+    it.each([['disabled'], ['readOnly']] as const)(
+      'hides the clear button while the field is %s',
+      (mode) => {
+        render(<Harness initial="07/08/1995" {...{ [mode]: true }} />);
+
+        expect(clearButton()).not.toBeInTheDocument();
+      },
+    );
+
+    it('disables Limpar in the calendar while the field is empty', async () => {
+      const user = userEvent.setup();
+      render(<Harness />);
+
+      const calendar = await openCalendar(user);
+
+      expect(within(calendar).getByRole('button', { name: 'Limpar' })).toBeDisabled();
+    });
+
+    it('empties the field from Limpar in the calendar and closes it', async () => {
+      const user = userEvent.setup();
+      render(<Harness initial="07/08/1995" />);
+
+      const calendar = await openCalendar(user);
+      await user.click(within(calendar).getByRole('button', { name: 'Limpar' }));
+
+      expect(input()).toHaveValue('');
+      expect(screen.getByLabelText('valor do formulário')).toBeEmptyDOMElement();
+      expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    });
+  });
+
   it('opens the calendar from the button on the month of the latest allowed date', async () => {
     const user = userEvent.setup();
     render(<Harness />);
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
index 566c0962..326d2fa7 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
@@ -1,7 +1,8 @@
 import { useState, type KeyboardEvent, type Ref } from 'react';
-import type { FieldValues } from 'react-hook-form';
-import { CalendarIcon } from 'lucide-react';
+import { useFormContext, type FieldValues } from 'react-hook-form';
+import { CalendarIcon, XIcon } from 'lucide-react';
 import { formatMaskedDate, maskDate, parseMaskedDate } from '@/shared/format/date';
+import { Button } from '@/shared/ui/button';
 import { Calendar } from '@/shared/ui/calendar';
 import type { FormFieldControlProps } from '@/shared/ui/form-field';
 import {
@@ -54,11 +55,13 @@ function DateFieldControl({
   placeholder = 'dd/mm/aaaa',
   ...inputProps
 }: DateFieldControlProps) {
+  const { setFocus } = useFormContext();
   const [open, setOpen] = useState(false);
-  const { disabled, readOnly } = inputProps;
+  const { name, disabled, readOnly } = inputProps;
   const isLocked = Boolean(disabled || readOnly);
 
   const value = typeof fieldValue === 'string' ? fieldValue : '';
+  const hasValue = value !== '';
   const typedDate = parseMaskedDate(value);
   const selected =
     typedDate !== null && typedDate >= minDate && typedDate <= maxDate ? typedDate : undefined;
@@ -68,6 +71,16 @@ function DateFieldControl({
     setOpen(false);
   }
 
+  function clearFromField() {
+    onChange('');
+    setFocus(name);
+  }
+
+  function clearFromCalendar() {
+    onChange('');
+    setOpen(false);
+  }
+
   function openOnArrowDown(event: KeyboardEvent<HTMLInputElement>) {
     if (event.key !== 'ArrowDown' || isLocked) return;
     event.preventDefault();
@@ -86,7 +99,12 @@ function DateFieldControl({
           onChange={(event) => onChange(maskDate(event.target.value))}
           onKeyDown={openOnArrowDown}
         />
-        <InputGroupAddon align="inline-end">
+        <InputGroupAddon align="inline-end" className="gap-0.5">
+          {hasValue && !isLocked && (
+            <InputGroupButton size="icon-xs" aria-label="Limpar data" onClick={clearFromField}>
+              <XIcon aria-hidden="true" />
+            </InputGroupButton>
+          )}
           <PopoverTrigger
             render={
               <InputGroupButton size="icon-xs" aria-label="Abrir calendário" disabled={isLocked} />
@@ -115,6 +133,17 @@ function DateFieldControl({
             disabled={[{ before: minDate }, { after: maxDate }]}
             onSelect={selectDate}
           />
+          <div className="border-t border-border p-2">
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              disabled={!hasValue}
+              onClick={clearFromCalendar}
+            >
+              Limpar
+            </Button>
+          </div>
         </PopoverContent>
       </Popover>
     </InputGroup>
diff --git a/apps/admin-frontend/src/shared/form/fields/components/field-error.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/field-error.test.tsx
new file mode 100644
index 00000000..48584a41
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/field-error.test.tsx
@@ -0,0 +1,95 @@
+import { useEffect } from 'react';
+import { describe, expect, it } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { FormProvider, useForm, type FieldErrors, type Path } from 'react-hook-form';
+import { FieldError } from './field-error';
+
+interface DummyValues {
+  name: string;
+  guardians: { name: string }[];
+}
+
+function Harness({
+  name = 'guardians',
+  errors,
+  serverMessage,
+}: {
+  name?: Path<DummyValues>;
+  errors?: FieldErrors<DummyValues>;
+  serverMessage?: string;
+}) {
+  const methods = useForm<DummyValues>({
+    defaultValues: { name: '', guardians: [{ name: '' }] },
+    resolver: () => ({ values: {}, errors: errors ?? {} }),
+  });
+
+  useEffect(() => {
+    if (serverMessage !== undefined) {
+      methods.setError(name, { type: 'server', message: serverMessage });
+    } else if (errors) {
+      void methods.trigger();
+    }
+  }, [errors, serverMessage, name, methods]);
+
+  return (
+    <FormProvider {...methods}>
+      <FieldError<DummyValues> name={name} />
+      <button type="button" onClick={() => methods.clearErrors(name)}>
+        Limpar erro
+      </button>
+    </FormProvider>
+  );
+}
+
+describe('FieldError', () => {
+  it('renders nothing when the field has no error', () => {
+    render(<Harness />);
+
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
+
+  it('renders a backend collection error as an alert', () => {
+    render(<Harness serverMessage="Informe um responsável." />);
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Informe um responsável.');
+    expect(screen.getByRole('alert')).toHaveClass('text-sm', 'text-destructive');
+  });
+
+  it('prefers an array root validation message over a direct message', async () => {
+    render(
+      <Harness
+        errors={{
+          guardians: {
+            type: 'validation',
+            message: 'Mensagem direta.',
+            root: { type: 'minLength', message: 'Informe ao menos um responsável.' },
+          },
+        }}
+      />,
+    );
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Informe ao menos um responsável.');
+    expect(screen.queryByText('Mensagem direta.')).not.toBeInTheDocument();
+  });
+
+  it('renders errors for a nested indexed field', () => {
+    render(<Harness name="guardians.0.name" serverMessage="O nome é obrigatório." />);
+
+    expect(screen.getByRole('alert')).toHaveTextContent('O nome é obrigatório.');
+  });
+
+  it('also works for a simple field and removes the alert when its error is cleared', () => {
+    render(<Harness name="name" serverMessage="O nome é obrigatório." />);
+
+    expect(screen.getByRole('alert')).toHaveTextContent('O nome é obrigatório.');
+    fireEvent.click(screen.getByRole('button', { name: 'Limpar erro' }));
+
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
+
+  it('does not render an alert for an empty message', () => {
+    render(<Harness serverMessage="" />);
+
+    expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/field-error.tsx b/apps/admin-frontend/src/shared/form/fields/components/field-error.tsx
new file mode 100644
index 00000000..cedb236f
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/field-error.tsx
@@ -0,0 +1,16 @@
+import { useFormContext, useFormState, type FieldValues } from 'react-hook-form';
+import type { FieldErrorProps } from '../fields.types';
+
+export function FieldError<T extends FieldValues>({ name }: FieldErrorProps<T>) {
+  const { control, getFieldState } = useFormContext<T>();
+  const formState = useFormState({ control, name });
+  const { error } = getFieldState(name, formState);
+  const message = error?.root?.message ?? error?.message;
+  if (!message) return null;
+
+  return (
+    <p role="alert" className="text-sm text-destructive">
+      {message}
+    </p>
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/fields.types.ts b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
index 13e24d65..9030a1b4 100644
--- a/apps/admin-frontend/src/shared/form/fields/fields.types.ts
+++ b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
@@ -11,6 +11,10 @@ interface BaseFieldProps<T extends FieldValues> {
   hint?: string | undefined;
 }
 
+export interface FieldErrorProps<T extends FieldValues> {
+  name: Path<T>;
+}
+
 type RegisterOwnedProps = 'name' | 'onChange' | 'onBlur' | 'ref';
 type FormFieldOwnedProps = 'id' | 'aria-invalid' | 'aria-describedby';
 
diff --git a/apps/admin-frontend/src/shared/form/fields/index.tsx b/apps/admin-frontend/src/shared/form/fields/index.tsx
index f0cbcefd..9a4bfe44 100644
--- a/apps/admin-frontend/src/shared/form/fields/index.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/index.tsx
@@ -4,7 +4,9 @@ export { DateField } from './components/date-field';
 export { ControlledField } from './components/controlled-field';
 export { ColorField } from './components/color-field';
 export { FormErrorBanner } from './components/form-error-banner';
+export { FieldError } from './components/field-error';
 export type {
+  FieldErrorProps,
   TextFieldProps,
   TextareaFieldProps,
   MaskedFieldProps,

From c518cd269ccd66c549ae5f00c9e1be5579aacfe5 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 11:12:58 -0300
Subject: [PATCH 18/30] Move CPF and birth-date helpers to shared

Relocated the generic CPF and birth-date validation/formatting logic from the clients feature into shared/format so it can be reused by other modules. Updated imports across the client form and documentation to match the new structure, and moved the corresponding tests alongside the utilities.
---
 apps/admin-frontend/docs/ARCHITECTURE.md                      | 3 ++-
 apps/admin-frontend/src/features/clients/model/clientForm.ts  | 4 ++--
 .../ui/pages/ClientFormPage/components/ClientGuardianItem.tsx | 2 +-
 .../ClientFormPage/components/ClientGuardiansSection.tsx      | 2 +-
 .../pages/ClientFormPage/components/ClientPersonSection.tsx   | 4 ++--
 .../clients/model => shared/format}/birthDate.test.ts         | 2 +-
 .../{features/clients/model => shared/format}/birthDate.ts    | 2 +-
 .../src/{features/clients/model => shared/format}/cpf.test.ts | 0
 .../src/{features/clients/model => shared/format}/cpf.ts      | 0
 9 files changed, 10 insertions(+), 9 deletions(-)
 rename apps/admin-frontend/src/{features/clients/model => shared/format}/birthDate.test.ts (98%)
 rename apps/admin-frontend/src/{features/clients/model => shared/format}/birthDate.ts (92%)
 rename apps/admin-frontend/src/{features/clients/model => shared/format}/cpf.test.ts (100%)
 rename apps/admin-frontend/src/{features/clients/model => shared/format}/cpf.ts (100%)

diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 5efe61b0..5b7a1c1d 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -402,7 +402,8 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayUtc()` (the UTC calendar day the backend uses, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
 | `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. The date is optional, so the field can be cleared two ways besides erasing the text: an X inside the input (`aria-label="Limpar data"`, only while there is a value and the field is not disabled or read-only; it hands the cursor back to the input with RHF's `setFocus`) and a `Limpar` button in the calendar's footer (disabled while empty; it closes the calendar). Neither name contains the field label, because the e2e finds the field by label substring. The calendar stays `required`, so clicking the selected day again does nothing. |
-| Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `features/clients/model/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
+| Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `shared/format/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
+| `cpf.ts` and `birthDate.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: neither is specific to a client. A CPF identifies any person (the guardian's already uses it) and a birth date is a person attribute any future module can carry, and the backend already treats both as shared kernel (`CpfNumber` and `BirthDate` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` (phone, e-mail) is just as generic and stayed in `features/clients/model/` until a second module needs it. |
 | Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index f5e2b97e..1bf23e2b 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -6,10 +6,10 @@ import {
   isInThePast,
   isMinorOn,
   isWithinMaxAge,
-} from './birthDate';
+} from '@/shared/format/birthDate';
 import { CONTACT_PURPOSES } from './client';
 import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH, isValidEmail, isValidPhone } from './contactFormats';
-import { isValidCpf, stripCpfMask } from './cpf';
+import { isValidCpf, stripCpfMask } from '@/shared/format/cpf';
 
 // Mirrors the backend limits (ServicesService.Domain.Entities.Client / ClientContact). UX pre-check
 // only - the backend response stays the source of truth.
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
index ee82359e..3a1551a2 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -8,7 +8,7 @@ import {
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
 import { PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
-import { formatCpf } from '../../../../model/cpf';
+import { formatCpf } from '@/shared/format/cpf';
 
 interface ClientGuardianItemProps {
   index: number;
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index 56d52e9a..a58cf7f3 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -3,7 +3,7 @@ import { useFieldArray, useFormContext, useWatch } from 'react-hook-form';
 import { FieldError } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
-import { ADULT_AGE_IN_YEARS } from '../../../../model/birthDate';
+import { ADULT_AGE_IN_YEARS } from '@/shared/format/birthDate';
 import {
   MAX_GUARDIANS,
   ageFromBirthDate,
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index da480260..128813de 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,7 +1,7 @@
 import { useFormContext, useWatch } from 'react-hook-form';
 import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
 import { PageSection } from '@/widgets/page-section';
-import { earliestBirthDate, formatAge, latestBirthDate } from '../../../../model/birthDate';
+import { earliestBirthDate, formatAge, latestBirthDate } from '@/shared/format/birthDate';
 import {
   CLIENT_NAME_MAX_LENGTH,
   CLIENT_NOTES_MAX_LENGTH,
@@ -9,7 +9,7 @@ import {
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
 import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
-import { formatCpf } from '../../../../model/cpf';
+import { formatCpf } from '@/shared/format/cpf';
 
 function ClientPersonSection() {
   const { control } = useFormContext<ClientFormFieldValues>();
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts b/apps/admin-frontend/src/shared/format/birthDate.test.ts
similarity index 98%
rename from apps/admin-frontend/src/features/clients/model/birthDate.test.ts
rename to apps/admin-frontend/src/shared/format/birthDate.test.ts
index 658f00a5..5d37add0 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.test.ts
+++ b/apps/admin-frontend/src/shared/format/birthDate.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest';
-import { utcDate } from '@/shared/format/date';
+import { utcDate } from './date';
 import {
   earliestBirthDate,
   formatAge,
diff --git a/apps/admin-frontend/src/features/clients/model/birthDate.ts b/apps/admin-frontend/src/shared/format/birthDate.ts
similarity index 92%
rename from apps/admin-frontend/src/features/clients/model/birthDate.ts
rename to apps/admin-frontend/src/shared/format/birthDate.ts
index 40299615..f8b935be 100644
--- a/apps/admin-frontend/src/features/clients/model/birthDate.ts
+++ b/apps/admin-frontend/src/shared/format/birthDate.ts
@@ -1,4 +1,4 @@
-import { fullYearsBetween, todayUtc, utcDate } from '@/shared/format/date';
+import { fullYearsBetween, todayUtc, utcDate } from './date';
 
 export const ADULT_AGE_IN_YEARS = 18;
 export const MAX_AGE_IN_YEARS = 120;
diff --git a/apps/admin-frontend/src/features/clients/model/cpf.test.ts b/apps/admin-frontend/src/shared/format/cpf.test.ts
similarity index 100%
rename from apps/admin-frontend/src/features/clients/model/cpf.test.ts
rename to apps/admin-frontend/src/shared/format/cpf.test.ts
diff --git a/apps/admin-frontend/src/features/clients/model/cpf.ts b/apps/admin-frontend/src/shared/format/cpf.ts
similarity index 100%
rename from apps/admin-frontend/src/features/clients/model/cpf.ts
rename to apps/admin-frontend/src/shared/format/cpf.ts

From cb66c6a3e79e0c7a33069b7d9f6d396c13ff7c4b Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 11:21:54 -0300
Subject: [PATCH 19/30] Move shared contact format helpers

Relocate contact validation utilities from the clients feature into shared/format so they are reusable across modules. Update imports throughout the client form to the new shared path and move the associated tests with the code. This keeps the phone and email validation rules centralized and aligned with the backend's shared kernel contracts.
---
 apps/admin-frontend/docs/ARCHITECTURE.md                   | 2 +-
 .../src/features/clients/model/clientForm.ts               | 7 ++++++-
 .../pages/ClientFormPage/components/ClientGuardianItem.tsx | 2 +-
 .../ClientFormPage/components/ClientPersonSection.tsx      | 2 +-
 .../components/ClientReferenceContactItem.tsx              | 2 +-
 .../clients/model => shared/format}/contactFormats.test.ts | 0
 .../clients/model => shared/format}/contactFormats.ts      | 0
 7 files changed, 10 insertions(+), 5 deletions(-)
 rename apps/admin-frontend/src/{features/clients/model => shared/format}/contactFormats.test.ts (100%)
 rename apps/admin-frontend/src/{features/clients/model => shared/format}/contactFormats.ts (100%)

diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 5b7a1c1d..c66882d8 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -403,7 +403,7 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayUtc()` (the UTC calendar day the backend uses, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
 | `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. The date is optional, so the field can be cleared two ways besides erasing the text: an X inside the input (`aria-label="Limpar data"`, only while there is a value and the field is not disabled or read-only; it hands the cursor back to the input with RHF's `setFocus`) and a `Limpar` button in the calendar's footer (disabled while empty; it closes the calendar). Neither name contains the field label, because the e2e finds the field by label substring. The calendar stays `required`, so clicking the selected day again does nothing. |
 | Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `shared/format/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
-| `cpf.ts` and `birthDate.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: neither is specific to a client. A CPF identifies any person (the guardian's already uses it) and a birth date is a person attribute any future module can carry, and the backend already treats both as shared kernel (`CpfNumber` and `BirthDate` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` (phone, e-mail) is just as generic and stayed in `features/clients/model/` until a second module needs it. |
+| `cpf.ts`, `birthDate.ts` and `contactFormats.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: none of them is specific to a client. A CPF identifies any person (the guardian's already uses it), a birth date is a person attribute any future module can carry, phone and e-mail are contact data any module can hold, and the backend already treats all of them as shared kernel (`CpfNumber`, `BirthDate`, `PhoneNumber` and `EmailAddress` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` kept its name for now; it mirrors two backend value objects, so a split into `phone.ts` and `email.ts` is the natural next step. |
 | Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index 1bf23e2b..2523fddd 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -8,7 +8,12 @@ import {
   isWithinMaxAge,
 } from '@/shared/format/birthDate';
 import { CONTACT_PURPOSES } from './client';
-import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH, isValidEmail, isValidPhone } from './contactFormats';
+import {
+  EMAIL_MAX_LENGTH,
+  PHONE_MAX_LENGTH,
+  isValidEmail,
+  isValidPhone,
+} from '@/shared/format/contactFormats';
 import { isValidCpf, stripCpfMask } from '@/shared/format/cpf';
 
 // Mirrors the backend limits (ServicesService.Domain.Entities.Client / ClientContact). UX pre-check
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
index 3a1551a2..eeb3f5a0 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -7,7 +7,7 @@ import {
   CONTACT_RELATIONSHIP_MAX_LENGTH,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
-import { PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
+import { PHONE_MAX_LENGTH } from '@/shared/format/contactFormats';
 import { formatCpf } from '@/shared/format/cpf';
 
 interface ClientGuardianItemProps {
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 128813de..15814495 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -8,7 +8,7 @@ import {
   ageFromBirthDate,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
-import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
+import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH } from '@/shared/format/contactFormats';
 import { formatCpf } from '@/shared/format/cpf';
 
 function ClientPersonSection() {
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index 9e7f9a9a..4e23d44c 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -9,7 +9,7 @@ import {
   CONTACT_RELATIONSHIP_MAX_LENGTH,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
-import { PHONE_MAX_LENGTH } from '../../../../model/contactFormats';
+import { PHONE_MAX_LENGTH } from '@/shared/format/contactFormats';
 
 interface ClientReferenceContactItemProps {
   index: number;
diff --git a/apps/admin-frontend/src/features/clients/model/contactFormats.test.ts b/apps/admin-frontend/src/shared/format/contactFormats.test.ts
similarity index 100%
rename from apps/admin-frontend/src/features/clients/model/contactFormats.test.ts
rename to apps/admin-frontend/src/shared/format/contactFormats.test.ts
diff --git a/apps/admin-frontend/src/features/clients/model/contactFormats.ts b/apps/admin-frontend/src/shared/format/contactFormats.ts
similarity index 100%
rename from apps/admin-frontend/src/features/clients/model/contactFormats.ts
rename to apps/admin-frontend/src/shared/format/contactFormats.ts

From 4f02c2e562c5fa1197a74f53dc0edd8be0a109ec Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 11:41:27 -0300
Subject: [PATCH 20/30] asd

---
 .claude/skills/agenza-form-field/SKILL.md     |  27 +++-
 apps/admin-frontend/docs/ARCHITECTURE.md      |  17 ++-
 .../features/clients/model/clientForm.test.ts |  21 ---
 .../src/features/clients/model/clientForm.ts  |  82 ++---------
 .../components/ClientGuardianItem.tsx         |  23 +--
 .../components/ClientGuardiansSection.tsx     |   6 +-
 .../components/ClientPersonSection.tsx        |  60 ++------
 .../components/ClientReferenceContactItem.tsx |  12 +-
 .../fields/components/value-fields.test.tsx   | 135 ++++++++++++++++++
 .../form/fields/components/value-fields.tsx   |  94 ++++++++++++
 .../src/shared/form/fields/fields.types.ts    |  18 +++
 .../src/shared/form/fields/index.tsx          |   5 +
 .../src/shared/form/schemas/birthDate.test.ts |  68 +++++++++
 .../src/shared/form/schemas/birthDate.ts      |  40 ++++++
 .../src/shared/form/schemas/cpf.test.ts       |  18 +++
 .../src/shared/form/schemas/cpf.ts            |   6 +
 .../src/shared/form/schemas/email.test.ts     |  29 ++++
 .../src/shared/form/schemas/email.ts          |  10 ++
 .../src/shared/form/schemas/index.ts          |   5 +
 .../shared/form/schemas/optionalValue.test.ts |  24 ++++
 .../src/shared/form/schemas/optionalValue.ts  |  14 ++
 .../src/shared/form/schemas/phone.test.ts     |  20 +++
 .../src/shared/form/schemas/phone.ts          |  10 ++
 .../src/shared/format/age.test.ts             |  14 ++
 apps/admin-frontend/src/shared/format/age.ts  |   4 +
 .../src/shared/format/birthDate.test.ts       |  39 ++---
 .../src/shared/format/birthDate.ts            |  16 +--
 .../src/shared/format/contactFormats.test.ts  |  52 -------
 .../src/shared/format/contactFormats.ts       |  17 ---
 .../src/shared/format/cpf.test.ts             |  35 ++---
 apps/admin-frontend/src/shared/format/cpf.ts  |  26 ++--
 .../src/shared/format/email.test.ts           |  38 +++++
 .../admin-frontend/src/shared/format/email.ts |  13 ++
 .../src/shared/format/phone.test.ts           |  36 +++++
 .../admin-frontend/src/shared/format/phone.ts |   9 ++
 35 files changed, 721 insertions(+), 322 deletions(-)
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/birthDate.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/cpf.test.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/cpf.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/email.test.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/email.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/index.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/optionalValue.test.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/optionalValue.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/phone.test.ts
 create mode 100644 apps/admin-frontend/src/shared/form/schemas/phone.ts
 create mode 100644 apps/admin-frontend/src/shared/format/age.test.ts
 create mode 100644 apps/admin-frontend/src/shared/format/age.ts
 delete mode 100644 apps/admin-frontend/src/shared/format/contactFormats.test.ts
 delete mode 100644 apps/admin-frontend/src/shared/format/contactFormats.ts
 create mode 100644 apps/admin-frontend/src/shared/format/email.test.ts
 create mode 100644 apps/admin-frontend/src/shared/format/email.ts
 create mode 100644 apps/admin-frontend/src/shared/format/phone.test.ts
 create mode 100644 apps/admin-frontend/src/shared/format/phone.ts

diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index 08b54cdf..00c75f6b 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -27,7 +27,7 @@ and has no input to attach to: render it in the section.
 | --- | --- | --- |
 | Error mapping | `shared/api/formErrors.ts` | `toFormErrors<F>(problem, fields)` — `ApiProblem` → `{fieldErrors, formError}`. Knows `ApiProblem`, nothing about RHF. |
 | RHF bridge | `shared/form/applyApiProblem.ts` | `applyApiProblem<T>(problem, fields, setError)` — calls the above, then `setError` per field plus `setError('root.serverError', …)`. Knows both shapes; the only file that does. |
-| Field components | `shared/form/fields/` | `TextField`/`TextareaField`, `MaskedField`, `DateField`, `ControlledField`, `ColorField`, `FormErrorBanner` — RHF wiring, zero domain knowledge. They render into `shared/ui/form-field/`'s `FormField` (label, hint, error, the `aria-*` wiring), which stays presentational and RHF-free like the rest of `shared/ui/` (`agenza-ui-primitive`). |
+| Field components | `shared/form/fields/` | `TextField`/`TextareaField`, `MaskedField`, `DateField`, `ControlledField`, `ColorField`, `FormErrorBanner` — RHF wiring, zero entity knowledge. They render into `shared/ui/form-field/`'s `FormField` (label, hint, error, the `aria-*` wiring), which stays presentational and RHF-free like the rest of `shared/ui/` (`agenza-ui-primitive`). |
 
 Never let a field component or `shared/form/` read `problem.errors` directly — that parsing (indexed
 keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See `agenza-api-contract`'s
@@ -122,6 +122,26 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    `ControlledField` (pass a render function) or a named specialization built on top of it, per the
    rule below.
 
+5. **A CPF, phone, e-mail or birth date is not configured by hand: reuse the pair.** The schema half
+   comes from `@/shared/form/schemas` (`cpfSchema`, `phoneSchema`, `emailSchema`, `birthDateSchema`:
+   an empty field becomes `null`, anything else is parsed and fails with the pt-BR message), the
+   field half from `@/shared/form/fields` (`CpfField`, `PhoneField`, `EmailField`, `BirthDateField`:
+   mask, input type, limit, placeholder, default label and `opcional` hint already set, each one
+   overridable by prop):
+   ```ts
+   const personSchema = z.object({ phone: phoneSchema, cpf: cpfSchema });
+   ```
+   ```tsx
+   <CpfField<XFormFieldValues> name="cpf" />
+   <PhoneField<XFormFieldValues> name="phone" label="Telefone do contato" />
+   ```
+   The parsing underneath is `shared/format/` (`parseCpf`, `parsePhone`, `parseEmail`: canonical value
+   or `null`, mirroring the backend's `Create`), so never re-validate with a regex of your own. A new
+   value type is a `parseX` in `shared/format/`, a schema built with `optionalValue(parse)` (its
+   `fail(message)` becomes the Zod issue) and, only if several forms will configure it the same way, a
+   preset field. The schemas have no required variant yet; add it to `optionalValue` when the first
+   form needs one.
+
 ## Editing an existing entity: fetch fresh, don't trust what the list already had
 
 An edit route fetches its own record from the backend on mount — it does not reuse whatever the list
@@ -165,6 +185,11 @@ already applies to `entities/` and to not rebuilding `color-swatch-picker` befor
 (ARCHITECTURE §1, §5) — a one-off specialization for a control only `ControlledField` has ever wrapped
 is guessing at an API shape with a sample size of one.
 
+The value presets (`CpfField`, `PhoneField`, `EmailField`, `BirthDateField`) are a different thing:
+they are not custom controls but fixed configurations of `MaskedField`/`TextField`/`DateField`, kept in
+one place because the same value was being configured by hand at several call sites (the phone three
+times). Add another only for a value type that will be configured the same way in more than one form.
+
 ## Two gotchas, both caught by `tsc`/review, not by a test
 
 **1. `z.infer` is not enough once a schema has `.refine()` or `.transform()`.** A schema's *input*
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index c66882d8..b608f019 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -48,9 +48,15 @@ src/
     ├── pubsub/              Generic createTopic/useTopic — publish/subscribe with a payload, no
     │                        domain knowledge; a concrete topic (e.g. tagDeleted) lives in the
     │                        feature that owns it, never here
+    ├── format/              Pure parse/mask/format of values (date, cpf, phone, email, birthDate,
+    │                        age); each parseX returns the canonical value or null, like the
+    │                        backend's Create
     ├── form/                applyApiProblem — the one place ApiProblem meets React Hook Form's
-    │                        setError — and fields/, the RHF-bound TextField/TextareaField/
-    │                        MaskedField/DateField/ControlledField/ColorField/FormErrorBanner; no domain knowledge (§5)
+    │                        setError —, schemas/ (Zod fields built on format/: cpf, phone, email,
+    │                        birthDate) and fields/, the RHF-bound TextField/TextareaField/
+    │                        MaskedField/DateField/ControlledField/ColorField/FormErrorBanner plus
+    │                        the value presets CpfField/PhoneField/EmailField/BirthDateField; no
+    │                        entity knowledge (§5)
     ├── ui/                  Base UI primitives (owned source), lib/utils.ts (cn()); form-field/ is
     │                        the presentational label/hint/error frame those fields render into
     ├── env.ts               Fail-fast loader for the six VITE_* vars
@@ -401,9 +407,10 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `TagListPage` renders its own failure with a retry (`ErrorState`: title, the problem's message and `code`, **Tentar novamente**) instead of `list-section`'s fixed "Não foi possível carregar." | Asked for directly, reverting the accepted cost in §2 for tags only — a failed load had no way back short of a full reload, and resubmitting the same search did nothing because `?q=` didn't change. Done the way §2 already prescribed: the page builds the failure with `shared/ui/error-state` and passes `list-section` only loading/ready; `list-section` itself is unchanged. Retry drops the failed result so the skeleton shows while the same query reloads. |
 | `isTransientProblem` also treats `status >= 500` as transient | A real backend 500 arrives with its own problem body and code, which the three client-side sentinels never matched — `ConfirmDialog` classified it as a permanent block ("Não é possível excluir", no retry) instead of offering **Tentar novamente**. A 4xx without a code (ASP.NET's native model-binding 400) stays non-transient. |
 | `features/clients` — the Pessoas registration form (`/pessoas/nova`, issue #154), on a full page rather than a dialog; nav destination "Clientes" renamed **Pessoas** (`/pessoas`) and no longer "Em breve" | Second real slice and second consumer of `shared/form/fields`. A page, not a dialog like Tags: the form holds two dynamic lists (guardians, reference contacts) built with RHF `useFieldArray`. What it added to `shared/`: `MaskedField` (a specialization of `ControlledField` once CPF, guardian CPF and birth date made three call sites), a `CheckboxGroup` primitive for the contact purposes, `toFormErrors` mapping indexed backend keys (`Guardians[1].Name` → `guardians.1.name`), and `shared/format/date.ts`'s `todayUtc()` (the UTC calendar day the backend uses, [ADR 0045](../../../docs/adr/0045-backend-works-in-utc.md)) for the minor rule. Birth date is a masked `dd/mm/aaaa` text field, not `<input type="date">`: a half-typed native date reads as `''`, which would silently skip the minor rule. The form sets `noValidate` so the browser's own English bubbles never replace the pt-BR messages. A CPF conflict shows the backend's message on the CPF field, focuses it and keeps what was typed. An "Abrir cadastro existente" link (reading the existing record's id from the typed `FieldError.meta`) was built and removed before merge: it pointed at `/pessoas/{id}`, a page that only arrives with #155; the backend keeps sending `meta.clientId`, so it can come back with that page. Full contract and the backend half: [ADR 0044](../../../docs/adr/0044-clients-aggregate-uniqueness-and-conflict-contract.md). |
-| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `features/clients` passes `earliestBirthDate`/`latestBirthDate`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. The date is optional, so the field can be cleared two ways besides erasing the text: an X inside the input (`aria-label="Limpar data"`, only while there is a value and the field is not disabled or read-only; it hands the cursor back to the input with RHF's `setFocus`) and a `Limpar` button in the calendar's footer (disabled while empty; it closes the calendar). Neither name contains the field label, because the e2e finds the field by label substring. The calendar stays `required`, so clicking the selected day again does nothing. |
-| Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `shared/format/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; `ageFromBirthDate` stays in the slice because validating a birth date (parse the mask, reject the future, reject over 120) is client policy, not date arithmetic. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
-| `cpf.ts`, `birthDate.ts` and `contactFormats.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: none of them is specific to a client. A CPF identifies any person (the guardian's already uses it), a birth date is a person attribute any future module can carry, phone and e-mail are contact data any module can hold, and the backend already treats all of them as shared kernel (`CpfNumber`, `BirthDate`, `PhoneNumber` and `EmailAddress` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` kept its name for now; it mirrors two backend value objects, so a split into `phone.ts` and `email.ts` is the natural next step. |
+| `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `BirthDateField` passes the bounds of `birthDatePickerBounds()`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. The date is optional, so the field can be cleared two ways besides erasing the text: an X inside the input (`aria-label="Limpar data"`, only while there is a value and the field is not disabled or read-only; it hands the cursor back to the input with RHF's `setFocus`) and a `Limpar` button in the calendar's footer (disabled while empty; it closes the calendar). Neither name contains the field label, because the e2e finds the field by label substring. The calendar stays `required`, so clicking the selected day again does nothing. |
+| Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `shared/format/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) and the calendar's picker bounds on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; validating a birth date (parse the mask, reject the future, reject over 120) is not date arithmetic, so `ageFromBirthDate` sits with the birth-date schema in `shared/form/schemas/birthDate.ts`. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
+| `cpf.ts`, `birthDate.ts` and `contactFormats.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: none of them is specific to a client. A CPF identifies any person (the guardian's already uses it), a birth date is a person attribute any future module can carry, phone and e-mail are contact data any module can hold, and the backend already treats all of them as shared kernel (`CpfNumber`, `BirthDate`, `PhoneNumber` and `EmailAddress` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` was split into `phone.ts` and `email.ts` right after, one per backend value object (next row). |
+| A value more than one form can carry (CPF, phone, e-mail, birth date) is reused through three layers: `shared/format/` parses it, `shared/form/schemas/` turns that into a Zod field, `shared/form/fields/` renders it | Asked for: using a CPF meant assembling two unrelated halves by hand, a Zod fragment written in the slice's `clientForm.ts` (trim, refine, strip, empty to `null`, the pt-BR message) and a `MaskedField` repeating `mask`, `inputMode`, `placeholder` and `autoComplete`; the phone input, repeated three times, had its placeholder in only one of them. (1) `parseCpf`, `parsePhone` and `parseEmail` return the canonical value or `null`, mirroring the backend's `Create` (trim, strip, lowercase and validate in one step), so a caller cannot validate without normalising; the old `isValidX` plus `stripX` left the trim to the caller, which differed from the backend. `maskCpf` is the typing-time mask, named after `maskDate`. (2) `cpfSchema`, `phoneSchema`, `emailSchema` and `birthDateSchema` are built with `optionalValue(parse)`, which owns the empty-field-is-`null` rule and turns `fail(message)` into a Zod issue, so a new value type (a CNPJ) is one `parse` function and one line; `shared/` imports Zod for the first time there. The e-mail schema checks the length itself, before `parseEmail`, to keep the backend's two distinct messages without reporting the same address twice. (3) `CpfField`, `PhoneField`, `EmailField` and `BirthDateField` pin the mask, input type, limit, placeholder, label and `opcional` hint and let the call site override any of them; `BirthDateField` also owns the calendar bounds and the age hint. A call site is `<CpfField name="cpf" />`. The layers stay apart because `model/` has no React: a schema can be imported from a model file, a field only from `ui/`. `isMinorBirthDate` replaced the guardians section's own `age < 18` comparison, so the minor rule exists once (`isMinorOn`); `formatAge` moved to `shared/format/age.ts`. These presets are the exception to "fields have no domain knowledge": they know a value's format, never an entity. Not built: a required variant of the schemas, since nothing needs one yet; `optionalValue` is where it would go. |
 | Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
index 1ddcdee4..49508912 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.test.ts
@@ -4,7 +4,6 @@ import {
   CLIENT_FORM_FIELDS,
   GUARDIAN_FORM_FIELDS,
   REFERENCE_CONTACT_FORM_FIELDS,
-  ageFromBirthDate,
   clientFormSchema,
   emptyGuardian,
   emptyReferenceContact,
@@ -318,26 +317,6 @@ describe('clientFormSchema', () => {
   });
 });
 
-describe('ageFromBirthDate', () => {
-  it.each([
-    ['10/03/2015', 11],
-    ['03/10/2008', 17],
-    ['02/10/2008', 18],
-    ['20/05/1990', 36],
-    ['01/10/2026', 0],
-    ['02/10/1906', 120],
-  ] as const)('reads %j as %i years old today', (birthDate, expected) => {
-    expect(ageFromBirthDate(birthDate)).toBe(expected);
-  });
-
-  it.each(['', '10/03', '31/02/2020', '02/10/2026', '01/01/2030', '02/10/1905'])(
-    'has no age for %j',
-    (birthDate) => {
-      expect(ageFromBirthDate(birthDate)).toBeNull();
-    },
-  );
-});
-
 describe('form field lists', () => {
   it('names every field the backend can report on', () => {
     expect(CLIENT_FORM_FIELDS).toEqual([
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/model/clientForm.ts
index 2523fddd..035389ac 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/model/clientForm.ts
@@ -1,20 +1,8 @@
 import { z } from 'zod';
-import { fullYearsBetween, parseMaskedDate, todayUtc } from '@/shared/format/date';
-import {
-  ADULT_AGE_IN_YEARS,
-  MAX_AGE_IN_YEARS,
-  isInThePast,
-  isMinorOn,
-  isWithinMaxAge,
-} from '@/shared/format/birthDate';
+import { ADULT_AGE_IN_YEARS, isMinorOn } from '@/shared/format/birthDate';
+import { todayUtc } from '@/shared/format/date';
+import { birthDateSchema, cpfSchema, emailSchema, phoneSchema } from '@/shared/form/schemas';
 import { CONTACT_PURPOSES } from './client';
-import {
-  EMAIL_MAX_LENGTH,
-  PHONE_MAX_LENGTH,
-  isValidEmail,
-  isValidPhone,
-} from '@/shared/format/contactFormats';
-import { isValidCpf, stripCpfMask } from '@/shared/format/cpf';
 
 // Mirrors the backend limits (ServicesService.Domain.Entities.Client / ClientContact). UX pre-check
 // only - the backend response stays the source of truth.
@@ -49,60 +37,17 @@ const relationshipField = (subject: string) =>
       `O vínculo ${subject} deve ter no máximo ${CONTACT_RELATIONSHIP_MAX_LENGTH} caracteres.`,
     );
 
-const phoneField = z
-  .string()
-  .trim()
-  .refine(
-    (value) => value === '' || isValidPhone(value),
-    `Informe um telefone válido, com até ${PHONE_MAX_LENGTH} caracteres entre dígitos, espaços, +, parênteses e hífen.`,
-  )
-  .transform((value) => value || null);
-
-const cpfField = z
-  .string()
-  .trim()
-  .refine((value) => value === '' || isValidCpf(value), 'Informe um CPF válido.')
-  .transform((value) => (value ? stripCpfMask(value) : null));
-
-const emailField = z
-  .string()
-  .trim()
-  .toLowerCase()
-  .max(EMAIL_MAX_LENGTH, `O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`)
-  .refine((value) => value === '' || isValidEmail(value), 'Informe um e-mail válido.')
-  .transform((value) => value || null);
-
-const birthDateField = z.string().transform((value, ctx) => {
-  if (value.trim() === '') return null;
-
-  const fail = (message: string) => {
-    ctx.addIssue({ code: 'custom', message });
-    return z.NEVER;
-  };
-
-  const birthDate = parseMaskedDate(value);
-  if (birthDate === null) return fail('Informe uma data válida no formato dd/mm/aaaa.');
-
-  const today = todayUtc();
-  if (!isInThePast(birthDate, today)) return fail('A data de nascimento deve estar no passado.');
-  if (!isWithinMaxAge(birthDate, today)) {
-    return fail(`A data de nascimento não pode indicar idade superior a ${MAX_AGE_IN_YEARS} anos.`);
-  }
-
-  return birthDate;
-});
-
 const guardianSchema = z.object({
   name: nameField('do responsável'),
   relationship: relationshipField('do responsável'),
-  phone: phoneField,
-  cpf: cpfField,
+  phone: phoneSchema,
+  cpf: cpfSchema,
 });
 
 const referenceContactSchema = z.object({
   name: nameField('da pessoa de referência'),
   relationship: relationshipField('da pessoa de referência'),
-  phone: phoneField,
+  phone: phoneSchema,
   purposes: z
     .array(z.enum(CONTACT_PURPOSES))
     .min(1, 'Informe ao menos uma finalidade para a pessoa de referência.'),
@@ -110,10 +55,10 @@ const referenceContactSchema = z.object({
 
 const clientFormObject = z.object({
   fullName: nameField('completo'),
-  birthDate: birthDateField,
-  phone: phoneField,
-  email: emailField,
-  cpf: cpfField,
+  birthDate: birthDateSchema,
+  phone: phoneSchema,
+  email: emailSchema,
+  cpf: cpfSchema,
   administrativeNotes: z
     .string()
     .trim()
@@ -174,10 +119,3 @@ export function emptyGuardian(): GuardianFormFieldValues {
 export function emptyReferenceContact(): ReferenceContactFormFieldValues {
   return { name: '', relationship: '', phone: '', purposes: [] };
 }
-
-export function ageFromBirthDate(masked: string): number | null {
-  const parsed = birthDateField.safeParse(masked);
-  if (!parsed.success || parsed.data === null) return null;
-
-  return fullYearsBetween(parsed.data, todayUtc());
-}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
index eeb3f5a0..a4c00844 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -1,14 +1,12 @@
 import { useId } from 'react';
 import { XIcon } from 'lucide-react';
-import { MaskedField, TextField } from '@/shared/form/fields';
+import { CpfField, PhoneField, TextField } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import {
   CLIENT_NAME_MAX_LENGTH,
   CONTACT_RELATIONSHIP_MAX_LENGTH,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
-import { PHONE_MAX_LENGTH } from '@/shared/format/contactFormats';
-import { formatCpf } from '@/shared/format/cpf';
 
 interface ClientGuardianItemProps {
   index: number;
@@ -53,23 +51,8 @@ function ClientGuardianItem({ index, onRemove }: ClientGuardianItemProps) {
           placeholder="Ex.: mãe, pai, tutor legal"
           autoComplete="off"
         />
-        <TextField<ClientFormFieldValues>
-          name={`guardians.${index}.phone`}
-          label="Telefone"
-          hint="opcional"
-          type="tel"
-          maxLength={PHONE_MAX_LENGTH}
-          autoComplete="off"
-        />
-        <MaskedField<ClientFormFieldValues>
-          name={`guardians.${index}.cpf`}
-          label="CPF"
-          hint="opcional"
-          mask={formatCpf}
-          inputMode="numeric"
-          placeholder="000.000.000-00"
-          autoComplete="off"
-        />
+        <PhoneField<ClientFormFieldValues> name={`guardians.${index}.phone`} />
+        <CpfField<ClientFormFieldValues> name={`guardians.${index}.cpf`} />
       </div>
     </div>
   );
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index a58cf7f3..198bb2de 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -4,9 +4,9 @@ import { FieldError } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
 import { ADULT_AGE_IN_YEARS } from '@/shared/format/birthDate';
+import { isMinorBirthDate } from '@/shared/form/schemas';
 import {
   MAX_GUARDIANS,
-  ageFromBirthDate,
   emptyGuardian,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
@@ -20,9 +20,7 @@ function ClientGuardiansSection() {
   const hasGuardians = fields.length > 0;
   const hasReachedGuardianLimit = fields.length >= MAX_GUARDIANS;
 
-  const age = ageFromBirthDate(birthDate);
-  const isMinor = age !== null && age < ADULT_AGE_IN_YEARS;
-  const needsGuardian = isMinor && !hasGuardians;
+  const needsGuardian = isMinorBirthDate(birthDate) && !hasGuardians;
 
   return (
     <PageSection
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 15814495..ec272d28 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -1,21 +1,19 @@
-import { useFormContext, useWatch } from 'react-hook-form';
-import { DateField, MaskedField, TextField, TextareaField } from '@/shared/form/fields';
+import {
+  BirthDateField,
+  CpfField,
+  EmailField,
+  PhoneField,
+  TextField,
+  TextareaField,
+} from '@/shared/form/fields';
 import { PageSection } from '@/widgets/page-section';
-import { earliestBirthDate, formatAge, latestBirthDate } from '@/shared/format/birthDate';
 import {
   CLIENT_NAME_MAX_LENGTH,
   CLIENT_NOTES_MAX_LENGTH,
-  ageFromBirthDate,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
-import { EMAIL_MAX_LENGTH, PHONE_MAX_LENGTH } from '@/shared/format/contactFormats';
-import { formatCpf } from '@/shared/format/cpf';
 
 function ClientPersonSection() {
-  const { control } = useFormContext<ClientFormFieldValues>();
-  const birthDate = useWatch({ control, name: 'birthDate' });
-  const age = ageFromBirthDate(birthDate);
-
   return (
     <PageSection title="Dados da pessoa" hideTitle>
       <div className="grid gap-4 md:grid-cols-2">
@@ -30,44 +28,10 @@ function ClientPersonSection() {
           />
         </div>
 
-        <DateField<ClientFormFieldValues>
-          name="birthDate"
-          label="Data de nascimento"
-          hint={age === null ? 'opcional' : formatAge(age)}
-          minDate={earliestBirthDate()}
-          maxDate={latestBirthDate()}
-          autoComplete="off"
-        />
-
-        <TextField<ClientFormFieldValues>
-          name="phone"
-          label="Telefone"
-          hint="opcional"
-          type="tel"
-          maxLength={PHONE_MAX_LENGTH}
-          placeholder="(11) 91234-5678"
-          autoComplete="off"
-        />
-
-        <TextField<ClientFormFieldValues>
-          name="email"
-          label="E-mail"
-          hint="opcional"
-          type="email"
-          maxLength={EMAIL_MAX_LENGTH}
-          placeholder="nome@exemplo.com"
-          autoComplete="off"
-        />
-
-        <MaskedField<ClientFormFieldValues>
-          name="cpf"
-          label="CPF"
-          hint="opcional"
-          mask={formatCpf}
-          inputMode="numeric"
-          placeholder="000.000.000-00"
-          autoComplete="off"
-        />
+        <BirthDateField<ClientFormFieldValues> name="birthDate" />
+        <PhoneField<ClientFormFieldValues> name="phone" />
+        <EmailField<ClientFormFieldValues> name="email" />
+        <CpfField<ClientFormFieldValues> name="cpf" />
 
         <div className="space-y-1.5 md:col-span-2">
           <TextareaField<ClientFormFieldValues>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index 4e23d44c..fa3f2f27 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -1,6 +1,6 @@
 import { useId } from 'react';
 import { XIcon } from 'lucide-react';
-import { ControlledField, TextField } from '@/shared/form/fields';
+import { ControlledField, PhoneField, TextField } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { CheckboxGroup } from '@/shared/ui/checkbox-group';
 import { CONTACT_PURPOSE_OPTIONS } from '../../../../model/client';
@@ -9,7 +9,6 @@ import {
   CONTACT_RELATIONSHIP_MAX_LENGTH,
   type ClientFormFieldValues,
 } from '../../../../model/clientForm';
-import { PHONE_MAX_LENGTH } from '@/shared/format/contactFormats';
 
 interface ClientReferenceContactItemProps {
   index: number;
@@ -54,14 +53,7 @@ function ClientReferenceContactItem({ index, onRemove }: ClientReferenceContactI
           placeholder="Ex.: tio, vizinha, amigo"
           autoComplete="off"
         />
-        <TextField<ClientFormFieldValues>
-          name={`referenceContacts.${index}.phone`}
-          label="Telefone"
-          hint="opcional"
-          type="tel"
-          maxLength={PHONE_MAX_LENGTH}
-          autoComplete="off"
-        />
+        <PhoneField<ClientFormFieldValues> name={`referenceContacts.${index}.phone`} />
         <ControlledField<ClientFormFieldValues>
           name={`referenceContacts.${index}.purposes`}
           label="Finalidades"
diff --git a/apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx
new file mode 100644
index 00000000..cf897712
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx
@@ -0,0 +1,135 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FormProvider, useForm } from 'react-hook-form';
+import { BirthDateField, CpfField, EmailField, PhoneField } from './value-fields';
+
+interface DummyValues {
+  birthDate: string;
+  cpf: string;
+  phone: string;
+  email: string;
+}
+
+function Harness({ children }: { children: React.ReactNode }) {
+  const methods = useForm<DummyValues>({
+    defaultValues: { birthDate: '', cpf: '', phone: '', email: '' },
+  });
+
+  return <FormProvider {...methods}>{children}</FormProvider>;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('CpfField', () => {
+  it('arrives labelled, optional, numeric and masking what is typed', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <CpfField<DummyValues> name="cpf" />
+      </Harness>,
+    );
+
+    const input = screen.getByLabelText('CPF');
+    await user.type(input, '52998224725');
+
+    expect(input).toHaveValue('529.982.247-25');
+    expect(input).toHaveAttribute('inputmode', 'numeric');
+    expect(input).toHaveAttribute('placeholder', '000.000.000-00');
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+
+  it('lets the call site rename the field and change its hint', () => {
+    render(
+      <Harness>
+        <CpfField<DummyValues> name="cpf" label="CPF do responsável" hint="obrigatório" />
+      </Harness>,
+    );
+
+    expect(screen.getByLabelText('CPF do responsável')).toBeInTheDocument();
+    expect(screen.getByText('obrigatório')).toBeInTheDocument();
+  });
+});
+
+describe('PhoneField', () => {
+  it('arrives as a telephone input capped at the backend limit', () => {
+    render(
+      <Harness>
+        <PhoneField<DummyValues> name="phone" />
+      </Harness>,
+    );
+
+    const input = screen.getByLabelText('Telefone');
+    expect(input).toHaveAttribute('type', 'tel');
+    expect(input).toHaveAttribute('maxlength', '20');
+    expect(input).toHaveAttribute('placeholder', '(11) 91234-5678');
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+});
+
+describe('EmailField', () => {
+  it('arrives as an e-mail input capped at the backend limit', () => {
+    render(
+      <Harness>
+        <EmailField<DummyValues> name="email" />
+      </Harness>,
+    );
+
+    const input = screen.getByLabelText('E-mail');
+    expect(input).toHaveAttribute('type', 'email');
+    expect(input).toHaveAttribute('maxlength', '254');
+    expect(input).toHaveAttribute('placeholder', 'nome@exemplo.com');
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+});
+
+describe('BirthDateField', () => {
+  it('arrives labelled and optional, and swaps the hint for the age once the date is complete', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <BirthDateField<DummyValues> name="birthDate" />
+      </Harness>,
+    );
+
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+
+    await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
+
+    expect(screen.getByText('36 anos')).toBeInTheDocument();
+    expect(screen.queryByText('opcional')).not.toBeInTheDocument();
+  });
+
+  it('keeps the optional hint while the typed date is not a valid birth date', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <BirthDateField<DummyValues> name="birthDate" />
+      </Harness>,
+    );
+
+    await user.type(screen.getByLabelText('Data de nascimento'), '02102026');
+
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+
+  it('prefers a hint given by the call site over the age', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <BirthDateField<DummyValues> name="birthDate" hint="obrigatório" />
+      </Harness>,
+    );
+
+    await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
+
+    expect(screen.getByText('obrigatório')).toBeInTheDocument();
+    expect(screen.queryByText('36 anos')).not.toBeInTheDocument();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx b/apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx
new file mode 100644
index 00000000..9912f331
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx
@@ -0,0 +1,94 @@
+import { useFormContext, useWatch, type FieldValues } from 'react-hook-form';
+import { formatAge } from '@/shared/format/age';
+import { birthDatePickerBounds } from '@/shared/format/birthDate';
+import { maskCpf } from '@/shared/format/cpf';
+import { EMAIL_MAX_LENGTH } from '@/shared/format/email';
+import { PHONE_MAX_LENGTH } from '@/shared/format/phone';
+import { ageFromBirthDate } from '@/shared/form/schemas';
+import type {
+  BirthDateFieldProps,
+  CpfFieldProps,
+  EmailFieldProps,
+  PhoneFieldProps,
+} from '../fields.types';
+import { DateField } from './date-field';
+import { MaskedField } from './masked-field';
+import { TextField } from './text-fields';
+
+export function CpfField<T extends FieldValues>({
+  label = 'CPF',
+  hint = 'opcional',
+  ...props
+}: CpfFieldProps<T>) {
+  return (
+    <MaskedField<T>
+      label={label}
+      hint={hint}
+      mask={maskCpf}
+      inputMode="numeric"
+      placeholder="000.000.000-00"
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
+
+export function PhoneField<T extends FieldValues>({
+  label = 'Telefone',
+  hint = 'opcional',
+  ...props
+}: PhoneFieldProps<T>) {
+  return (
+    <TextField<T>
+      label={label}
+      hint={hint}
+      type="tel"
+      maxLength={PHONE_MAX_LENGTH}
+      placeholder="(11) 91234-5678"
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
+
+export function EmailField<T extends FieldValues>({
+  label = 'E-mail',
+  hint = 'opcional',
+  ...props
+}: EmailFieldProps<T>) {
+  return (
+    <TextField<T>
+      label={label}
+      hint={hint}
+      type="email"
+      maxLength={EMAIL_MAX_LENGTH}
+      placeholder="nome@exemplo.com"
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
+
+export function BirthDateField<T extends FieldValues>({
+  name,
+  label = 'Data de nascimento',
+  hint,
+  ...props
+}: BirthDateFieldProps<T>) {
+  const { control } = useFormContext<T>();
+  const typed: unknown = useWatch({ control, name });
+  const age = ageFromBirthDate(typeof typed === 'string' ? typed : '');
+  const { min, max } = birthDatePickerBounds();
+
+  return (
+    <DateField<T>
+      name={name}
+      label={label}
+      hint={hint ?? (age === null ? 'opcional' : formatAge(age))}
+      minDate={min}
+      maxDate={max}
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/fields.types.ts b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
index 9030a1b4..52dcf82e 100644
--- a/apps/admin-frontend/src/shared/form/fields/fields.types.ts
+++ b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
@@ -38,6 +38,24 @@ export type DateFieldProps<T extends FieldValues> = BaseFieldProps<T> &
     maxDate: Date;
   };
 
+type WithOptionalLabel<P> = Omit<P, 'label'> & { label?: string | undefined };
+
+export type CpfFieldProps<T extends FieldValues> = WithOptionalLabel<
+  Omit<MaskedFieldProps<T>, 'mask'>
+>;
+
+export type PhoneFieldProps<T extends FieldValues> = WithOptionalLabel<
+  Omit<TextFieldProps<T>, 'type'>
+>;
+
+export type EmailFieldProps<T extends FieldValues> = WithOptionalLabel<
+  Omit<TextFieldProps<T>, 'type'>
+>;
+
+export type BirthDateFieldProps<T extends FieldValues> = WithOptionalLabel<
+  Omit<DateFieldProps<T>, 'minDate' | 'maxDate'>
+>;
+
 export interface ControlledFieldProps<T extends FieldValues> {
   name: Path<T>;
   label: string;
diff --git a/apps/admin-frontend/src/shared/form/fields/index.tsx b/apps/admin-frontend/src/shared/form/fields/index.tsx
index 9a4bfe44..fb4f0d4f 100644
--- a/apps/admin-frontend/src/shared/form/fields/index.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/index.tsx
@@ -1,6 +1,7 @@
 export { TextField, TextareaField } from './components/text-fields';
 export { MaskedField } from './components/masked-field';
 export { DateField } from './components/date-field';
+export { BirthDateField, CpfField, EmailField, PhoneField } from './components/value-fields';
 export { ControlledField } from './components/controlled-field';
 export { ColorField } from './components/color-field';
 export { FormErrorBanner } from './components/form-error-banner';
@@ -11,6 +12,10 @@ export type {
   TextareaFieldProps,
   MaskedFieldProps,
   DateFieldProps,
+  CpfFieldProps,
+  PhoneFieldProps,
+  EmailFieldProps,
+  BirthDateFieldProps,
   ControlledFieldProps,
   ColorFieldProps,
 } from './fields.types';
diff --git a/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts b/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
new file mode 100644
index 00000000..bbdb10ff
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
@@ -0,0 +1,68 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { utcDate } from '@/shared/format/date';
+import { ageFromBirthDate, birthDateSchema, isMinorBirthDate } from './birthDate';
+
+beforeEach(() => {
+  vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+function messagesOf(raw: string): string[] | undefined {
+  return birthDateSchema.safeParse(raw).error?.issues.map((issue) => issue.message);
+}
+
+describe('birthDateSchema', () => {
+  it('reads dd/mm/aaaa as a Date at midnight UTC', () => {
+    expect(birthDateSchema.parse('20/05/1990')).toEqual(utcDate(1990, 5, 20));
+  });
+
+  it.each(['', '  '])('treats %j as no birth date', (raw) => {
+    expect(birthDateSchema.parse(raw)).toBeNull();
+  });
+
+  it.each([
+    ['10/03', 'Informe uma data válida no formato dd/mm/aaaa.'],
+    ['31/02/2020', 'Informe uma data válida no formato dd/mm/aaaa.'],
+    ['02/10/2026', 'A data de nascimento deve estar no passado.'],
+    ['01/01/2030', 'A data de nascimento deve estar no passado.'],
+    ['02/10/1905', 'A data de nascimento não pode indicar idade superior a 120 anos.'],
+  ] as const)('explains %j in pt-BR', (raw, message) => {
+    expect(messagesOf(raw)).toEqual([message]);
+  });
+});
+
+describe('ageFromBirthDate', () => {
+  it.each([
+    ['10/03/2015', 11],
+    ['03/10/2008', 17],
+    ['02/10/2008', 18],
+    ['20/05/1990', 36],
+    ['01/10/2026', 0],
+    ['02/10/1906', 120],
+  ] as const)('reads %j as %i years old today', (birthDate, expected) => {
+    expect(ageFromBirthDate(birthDate)).toBe(expected);
+  });
+
+  it.each(['', '10/03', '31/02/2020', '02/10/2026', '01/01/2030', '02/10/1905'])(
+    'has no age for %j',
+    (birthDate) => {
+      expect(ageFromBirthDate(birthDate)).toBeNull();
+    },
+  );
+});
+
+describe('isMinorBirthDate', () => {
+  it.each(['03/10/2008', '10/03/2015', '01/10/2026'])('is true for %j', (birthDate) => {
+    expect(isMinorBirthDate(birthDate)).toBe(true);
+  });
+
+  it.each(['02/10/2008', '20/05/1990', '', '10/03', '02/10/2026', '01/01/2030', '02/10/1905'])(
+    'is false for %j',
+    (birthDate) => {
+      expect(isMinorBirthDate(birthDate)).toBe(false);
+    },
+  );
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/birthDate.ts b/apps/admin-frontend/src/shared/form/schemas/birthDate.ts
new file mode 100644
index 00000000..4ba8f98b
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/birthDate.ts
@@ -0,0 +1,40 @@
+import {
+  MAX_AGE_IN_YEARS,
+  isInThePast,
+  isMinorOn,
+  isWithinMaxAge,
+} from '@/shared/format/birthDate';
+import { fullYearsBetween, parseMaskedDate, todayUtc } from '@/shared/format/date';
+import { optionalValue } from './optionalValue';
+
+export const birthDateSchema = optionalValue((raw, fail) => {
+  const birthDate = parseMaskedDate(raw);
+  if (birthDate === null) return fail('Informe uma data válida no formato dd/mm/aaaa.');
+
+  const today = todayUtc();
+  if (!isInThePast(birthDate, today)) return fail('A data de nascimento deve estar no passado.');
+  if (!isWithinMaxAge(birthDate, today)) {
+    return fail(`A data de nascimento não pode indicar idade superior a ${MAX_AGE_IN_YEARS} anos.`);
+  }
+
+  return birthDate;
+});
+
+export function ageFromBirthDate(masked: string): number | null {
+  const birthDate = parseBirthDate(masked);
+  if (birthDate === null) return null;
+
+  return fullYearsBetween(birthDate, todayUtc());
+}
+
+export function isMinorBirthDate(masked: string): boolean {
+  const birthDate = parseBirthDate(masked);
+  if (birthDate === null) return false;
+
+  return isMinorOn(birthDate, todayUtc());
+}
+
+function parseBirthDate(masked: string): Date | null {
+  const parsed = birthDateSchema.safeParse(masked);
+  return parsed.success ? parsed.data : null;
+}
diff --git a/apps/admin-frontend/src/shared/form/schemas/cpf.test.ts b/apps/admin-frontend/src/shared/form/schemas/cpf.test.ts
new file mode 100644
index 00000000..94542944
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/cpf.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+import { cpfSchema } from './cpf';
+
+describe('cpfSchema', () => {
+  it('stores the digits only, whatever mask the person typed', () => {
+    expect(cpfSchema.parse('529.982.247-25')).toBe('52998224725');
+  });
+
+  it('treats an empty field as no CPF', () => {
+    expect(cpfSchema.parse('  ')).toBeNull();
+  });
+
+  it('explains an invalid CPF in pt-BR', () => {
+    const result = cpfSchema.safeParse('529.982.247-24');
+
+    expect(result.error?.issues.map((issue) => issue.message)).toEqual(['Informe um CPF válido.']);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/cpf.ts b/apps/admin-frontend/src/shared/form/schemas/cpf.ts
new file mode 100644
index 00000000..db93beca
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/cpf.ts
@@ -0,0 +1,6 @@
+import { parseCpf } from '@/shared/format/cpf';
+import { optionalValue } from './optionalValue';
+
+export const cpfSchema = optionalValue(
+  (raw, fail) => parseCpf(raw) ?? fail('Informe um CPF válido.'),
+);
diff --git a/apps/admin-frontend/src/shared/form/schemas/email.test.ts b/apps/admin-frontend/src/shared/form/schemas/email.test.ts
new file mode 100644
index 00000000..3dff84ee
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/email.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { EMAIL_MAX_LENGTH } from '@/shared/format/email';
+import { emailSchema } from './email';
+
+function messagesOf(raw: string): string[] | undefined {
+  return emailSchema.safeParse(raw).error?.issues.map((issue) => issue.message);
+}
+
+describe('emailSchema', () => {
+  it('stores the e-mail trimmed and in lowercase', () => {
+    expect(emailSchema.parse(' Maria.Souza@Example.COM ')).toBe('maria.souza@example.com');
+  });
+
+  it('treats an empty field as no e-mail', () => {
+    expect(emailSchema.parse('')).toBeNull();
+  });
+
+  it('explains an invalid format in pt-BR', () => {
+    expect(messagesOf('maria@example')).toEqual(['Informe um e-mail válido.']);
+  });
+
+  it('reports a too-long e-mail once, as too long and not as invalid', () => {
+    const tooLong = `${'a'.repeat(EMAIL_MAX_LENGTH)}@example.com`;
+
+    expect(messagesOf(tooLong)).toEqual([
+      `O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`,
+    ]);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/email.ts b/apps/admin-frontend/src/shared/form/schemas/email.ts
new file mode 100644
index 00000000..9ae2d444
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/email.ts
@@ -0,0 +1,10 @@
+import { EMAIL_MAX_LENGTH, parseEmail } from '@/shared/format/email';
+import { optionalValue } from './optionalValue';
+
+export const emailSchema = optionalValue((raw, fail) => {
+  if (raw.trim().length > EMAIL_MAX_LENGTH) {
+    return fail(`O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`);
+  }
+
+  return parseEmail(raw) ?? fail('Informe um e-mail válido.');
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/index.ts b/apps/admin-frontend/src/shared/form/schemas/index.ts
new file mode 100644
index 00000000..51351746
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/index.ts
@@ -0,0 +1,5 @@
+export { optionalValue } from './optionalValue';
+export { cpfSchema } from './cpf';
+export { phoneSchema } from './phone';
+export { emailSchema } from './email';
+export { birthDateSchema, ageFromBirthDate, isMinorBirthDate } from './birthDate';
diff --git a/apps/admin-frontend/src/shared/form/schemas/optionalValue.test.ts b/apps/admin-frontend/src/shared/form/schemas/optionalValue.test.ts
new file mode 100644
index 00000000..c590a629
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/optionalValue.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { optionalValue } from './optionalValue';
+
+const evenNumber = optionalValue((raw, fail) => {
+  const value = Number(raw);
+  return value % 2 === 0 ? value : fail('Informe um número par.');
+});
+
+describe('optionalValue', () => {
+  it.each(['', '   '])('turns %j into null without calling the parser', (raw) => {
+    expect(evenNumber.parse(raw)).toBeNull();
+  });
+
+  it('returns what the parser returns', () => {
+    expect(evenNumber.parse('4')).toBe(4);
+  });
+
+  it('reports the parser failure as an issue carrying its message', () => {
+    const result = evenNumber.safeParse('3');
+
+    expect(result.success).toBe(false);
+    expect(result.error?.issues.map((issue) => issue.message)).toEqual(['Informe um número par.']);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/optionalValue.ts b/apps/admin-frontend/src/shared/form/schemas/optionalValue.ts
new file mode 100644
index 00000000..584edcef
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/optionalValue.ts
@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+type Fail = (message: string) => never;
+
+export function optionalValue<T>(parse: (raw: string, fail: Fail) => T) {
+  return z.string().transform((raw, ctx): T | null => {
+    if (raw.trim() === '') return null;
+
+    return parse(raw, (message) => {
+      ctx.addIssue({ code: 'custom', message });
+      return z.NEVER;
+    });
+  });
+}
diff --git a/apps/admin-frontend/src/shared/form/schemas/phone.test.ts b/apps/admin-frontend/src/shared/form/schemas/phone.test.ts
new file mode 100644
index 00000000..c3714b99
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/phone.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest';
+import { phoneSchema } from './phone';
+
+describe('phoneSchema', () => {
+  it('keeps the phone as typed, without the surrounding spaces', () => {
+    expect(phoneSchema.parse('  (11) 99999-0000 ')).toBe('(11) 99999-0000');
+  });
+
+  it('treats an empty field as no phone', () => {
+    expect(phoneSchema.parse('')).toBeNull();
+  });
+
+  it('explains the accepted shape in pt-BR', () => {
+    const result = phoneSchema.safeParse('telefone');
+
+    expect(result.error?.issues.map((issue) => issue.message)).toEqual([
+      'Informe um telefone válido, com até 20 caracteres entre dígitos, espaços, +, parênteses e hífen.',
+    ]);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/phone.ts b/apps/admin-frontend/src/shared/form/schemas/phone.ts
new file mode 100644
index 00000000..def147db
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/schemas/phone.ts
@@ -0,0 +1,10 @@
+import { PHONE_MAX_LENGTH, parsePhone } from '@/shared/format/phone';
+import { optionalValue } from './optionalValue';
+
+export const phoneSchema = optionalValue(
+  (raw, fail) =>
+    parsePhone(raw) ??
+    fail(
+      `Informe um telefone válido, com até ${PHONE_MAX_LENGTH} caracteres entre dígitos, espaços, +, parênteses e hífen.`,
+    ),
+);
diff --git a/apps/admin-frontend/src/shared/format/age.test.ts b/apps/admin-frontend/src/shared/format/age.test.ts
new file mode 100644
index 00000000..0da0dbf9
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/age.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { formatAge } from './age';
+
+describe('formatAge', () => {
+  it.each([
+    [0, 'menos de 1 ano'],
+    [1, '1 ano'],
+    [2, '2 anos'],
+    [17, '17 anos'],
+    [120, '120 anos'],
+  ] as const)('writes %i as %j', (age, expected) => {
+    expect(formatAge(age)).toBe(expected);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/format/age.ts b/apps/admin-frontend/src/shared/format/age.ts
new file mode 100644
index 00000000..c940a6d5
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/age.ts
@@ -0,0 +1,4 @@
+export function formatAge(age: number): string {
+  if (age < 1) return 'menos de 1 ano';
+  return age === 1 ? '1 ano' : `${age} anos`;
+}
diff --git a/apps/admin-frontend/src/shared/format/birthDate.test.ts b/apps/admin-frontend/src/shared/format/birthDate.test.ts
index 5d37add0..c32303d6 100644
--- a/apps/admin-frontend/src/shared/format/birthDate.test.ts
+++ b/apps/admin-frontend/src/shared/format/birthDate.test.ts
@@ -1,13 +1,6 @@
 import { describe, expect, it, vi } from 'vitest';
+import { birthDatePickerBounds, isInThePast, isMinorOn, isWithinMaxAge } from './birthDate';
 import { utcDate } from './date';
-import {
-  earliestBirthDate,
-  formatAge,
-  isInThePast,
-  isMinorOn,
-  isWithinMaxAge,
-  latestBirthDate,
-} from './birthDate';
 
 const TODAY = utcDate(2026, 10, 2);
 
@@ -36,10 +29,12 @@ describe('birth date rules', () => {
   });
 });
 
-describe('birth date picker bounds', () => {
+describe('birthDatePickerBounds', () => {
   it('ends the day before today, since a birth date must be in the past', () => {
-    expect(latestBirthDate(TODAY)).toEqual(utcDate(2026, 10, 1));
-    expect(isInThePast(latestBirthDate(TODAY), TODAY)).toBe(true);
+    const { max } = birthDatePickerBounds(TODAY);
+
+    expect(max).toEqual(utcDate(2026, 10, 1));
+    expect(isInThePast(max, TODAY)).toBe(true);
   });
 
   it.each([
@@ -47,11 +42,11 @@ describe('birth date picker bounds', () => {
     [utcDate(2024, 3, 1), utcDate(2024, 2, 29)],
     [utcDate(2027, 1, 1), utcDate(2026, 12, 31)],
   ] as const)('ends the day before %s on %s', (today, expected) => {
-    expect(latestBirthDate(today)).toEqual(expected);
+    expect(birthDatePickerBounds(today).max).toEqual(expected);
   });
 
   it('starts on January 1st of the first year that can still be within the maximum age', () => {
-    expect(earliestBirthDate(TODAY)).toEqual(utcDate(1905, 1, 1));
+    expect(birthDatePickerBounds(TODAY).min).toEqual(utcDate(1905, 1, 1));
     expect(isWithinMaxAge(utcDate(1905, 12, 31), utcDate(2026, 1, 1))).toBe(true);
     expect(isWithinMaxAge(utcDate(1905, 1, 1), utcDate(2026, 12, 31))).toBe(false);
   });
@@ -59,21 +54,11 @@ describe('birth date picker bounds', () => {
   it('reads today from the clock when none is given', () => {
     vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
 
-    expect(latestBirthDate()).toEqual(utcDate(2026, 10, 1));
-    expect(earliestBirthDate()).toEqual(utcDate(1905, 1, 1));
+    expect(birthDatePickerBounds()).toEqual({
+      min: utcDate(1905, 1, 1),
+      max: utcDate(2026, 10, 1),
+    });
 
     vi.useRealTimers();
   });
 });
-
-describe('formatAge', () => {
-  it.each([
-    [0, 'menos de 1 ano'],
-    [1, '1 ano'],
-    [2, '2 anos'],
-    [17, '17 anos'],
-    [120, '120 anos'],
-  ] as const)('writes %i as %j', (age, expected) => {
-    expect(formatAge(age)).toBe(expected);
-  });
-});
diff --git a/apps/admin-frontend/src/shared/format/birthDate.ts b/apps/admin-frontend/src/shared/format/birthDate.ts
index f8b935be..8e696fe3 100644
--- a/apps/admin-frontend/src/shared/format/birthDate.ts
+++ b/apps/admin-frontend/src/shared/format/birthDate.ts
@@ -15,15 +15,9 @@ export function isMinorOn(birthDate: Date, today: Date): boolean {
   return isInThePast(birthDate, today) && fullYearsBetween(birthDate, today) < ADULT_AGE_IN_YEARS;
 }
 
-export function latestBirthDate(today: Date = todayUtc()): Date {
-  return utcDate(today.getUTCFullYear(), today.getUTCMonth() + 1, today.getUTCDate() - 1);
-}
-
-export function earliestBirthDate(today: Date = todayUtc()): Date {
-  return utcDate(today.getUTCFullYear() - MAX_AGE_IN_YEARS - 1, 1, 1);
-}
-
-export function formatAge(age: number): string {
-  if (age < 1) return 'menos de 1 ano';
-  return age === 1 ? '1 ano' : `${age} anos`;
+export function birthDatePickerBounds(today: Date = todayUtc()): { min: Date; max: Date } {
+  return {
+    min: utcDate(today.getUTCFullYear() - MAX_AGE_IN_YEARS - 1, 1, 1),
+    max: utcDate(today.getUTCFullYear(), today.getUTCMonth() + 1, today.getUTCDate() - 1),
+  };
 }
diff --git a/apps/admin-frontend/src/shared/format/contactFormats.test.ts b/apps/admin-frontend/src/shared/format/contactFormats.test.ts
deleted file mode 100644
index 54751921..00000000
--- a/apps/admin-frontend/src/shared/format/contactFormats.test.ts
+++ /dev/null
@@ -1,52 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { isValidEmail, isValidPhone } from './contactFormats';
-
-describe('isValidPhone', () => {
-  it.each([
-    '11999990000',
-    '(11) 99999-0000',
-    '+55 (11) 99999-0000',
-    '11 9999-0000',
-    '1'.repeat(20),
-  ])('accepts %j', (phone) => {
-    expect(isValidPhone(phone)).toBe(true);
-  });
-
-  it.each([
-    '',
-    '1'.repeat(21),
-    '(11) 99999-0000 ramal 12',
-    '11.99999.0000',
-    '11/99999',
-    'telefone',
-    '+-() ',
-    '---',
-  ])('rejects %j', (phone) => {
-    expect(isValidPhone(phone)).toBe(false);
-  });
-});
-
-describe('isValidEmail', () => {
-  it.each(['maria@example.com', 'maria.souza+agenda@mail.example.com.br', 'a@b.co'])(
-    'accepts %j',
-    (email) => {
-      expect(isValidEmail(email)).toBe(true);
-    },
-  );
-
-  it.each([
-    '',
-    'maria',
-    'maria@',
-    '@example.com',
-    'maria@example',
-    'maria@@example.com',
-    'maria@example..com',
-    'maria@.example.com',
-    'maria@example.com.',
-    'maria souza@example.com',
-    `${'a'.repeat(250)}@example.com`,
-  ])('rejects %j', (email) => {
-    expect(isValidEmail(email)).toBe(false);
-  });
-});
diff --git a/apps/admin-frontend/src/shared/format/contactFormats.ts b/apps/admin-frontend/src/shared/format/contactFormats.ts
deleted file mode 100644
index 1f36492c..00000000
--- a/apps/admin-frontend/src/shared/format/contactFormats.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-export const PHONE_MAX_LENGTH = 20;
-export const EMAIL_MAX_LENGTH = 254;
-
-export function isValidPhone(value: string): boolean {
-  return value.length <= PHONE_MAX_LENGTH && /\d/.test(value) && /^[\d +()-]+$/.test(value);
-}
-
-export function isValidEmail(value: string): boolean {
-  if (value.length > EMAIL_MAX_LENGTH || /\s/.test(value)) return false;
-
-  const parts = value.split('@');
-  if (parts.length !== 2) return false;
-
-  const [local = '', domain = ''] = parts;
-  const labels = domain.split('.');
-  return local.length > 0 && labels.length >= 2 && labels.every((label) => label.length > 0);
-}
diff --git a/apps/admin-frontend/src/shared/format/cpf.test.ts b/apps/admin-frontend/src/shared/format/cpf.test.ts
index c38d698c..d3d5e6ce 100644
--- a/apps/admin-frontend/src/shared/format/cpf.test.ts
+++ b/apps/admin-frontend/src/shared/format/cpf.test.ts
@@ -1,19 +1,21 @@
 import { describe, expect, it } from 'vitest';
-import { formatCpf, isValidCpf, stripCpfMask } from './cpf';
+import { maskCpf, parseCpf } from './cpf';
 
-describe('isValidCpf', () => {
+describe('parseCpf', () => {
   it.each([
-    '529.982.247-25',
-    '52998224725',
-    ' 529.982.247-25 ',
-    '123.456.789-09',
-    '111.444.777-35',
-  ])('accepts %s', (cpf) => {
-    expect(isValidCpf(cpf)).toBe(true);
+    ['529.982.247-25', '52998224725'],
+    ['52998224725', '52998224725'],
+    [' 529.982.247-25 ', '52998224725'],
+    ['529 982 247 25', '52998224725'],
+    ['123.456.789-09', '12345678909'],
+    ['111.444.777-35', '11144477735'],
+  ] as const)('reads %j as the digits %j', (cpf, expected) => {
+    expect(parseCpf(cpf)).toBe(expected);
   });
 
   it.each([
     '',
+    '   ',
     '529.982.247-24',
     '529.982.247-52',
     '123.456.789-00',
@@ -25,18 +27,11 @@ describe('isValidCpf', () => {
     'abc.def.ghi-jk',
     '529.982.247-2a',
   ])('rejects %j', (cpf) => {
-    expect(isValidCpf(cpf)).toBe(false);
+    expect(parseCpf(cpf)).toBeNull();
   });
 });
 
-describe('stripCpfMask', () => {
-  it('removes dots, hyphens and spaces only', () => {
-    expect(stripCpfMask(' 529.982.247-25 ')).toBe('52998224725');
-    expect(stripCpfMask('529 982 247 25')).toBe('52998224725');
-  });
-});
-
-describe('formatCpf', () => {
+describe('maskCpf', () => {
   it.each([
     ['', ''],
     ['5', '5'],
@@ -50,7 +45,7 @@ describe('formatCpf', () => {
     ['529982247259999', '529.982.247-25'],
     ['529.982.247-25', '529.982.247-25'],
     ['abc529x', '529'],
-  ] as const)('formats %j as %j while typing', (typed, expected) => {
-    expect(formatCpf(typed)).toBe(expected);
+  ] as const)('masks %j as %j while typing', (typed, expected) => {
+    expect(maskCpf(typed)).toBe(expected);
   });
 });
diff --git a/apps/admin-frontend/src/shared/format/cpf.ts b/apps/admin-frontend/src/shared/format/cpf.ts
index 57abdb4c..5ba42a5d 100644
--- a/apps/admin-frontend/src/shared/format/cpf.ts
+++ b/apps/admin-frontend/src/shared/format/cpf.ts
@@ -1,20 +1,18 @@
 const CPF_LENGTH = 11;
 
-export function stripCpfMask(value: string): string {
-  return value.replace(/[.\-\s]/g, '');
-}
-
-export function isValidCpf(value: string): boolean {
-  const digits = stripCpfMask(value);
-  if (!/^\d{11}$/.test(digits) || /^(\d)\1{10}$/.test(digits)) return false;
+export function parseCpf(raw: string): string | null {
+  const digits = raw.replace(/[.\-\s]/g, '');
+  if (digits.length !== CPF_LENGTH || !/^\d+$/.test(digits) || new Set(digits).size === 1) {
+    return null;
+  }
 
-  return (
+  const hasValidCheckDigits =
     checkDigit(digits, 9) === Number(digits.charAt(9)) &&
-    checkDigit(digits, 10) === Number(digits.charAt(10))
-  );
+    checkDigit(digits, 10) === Number(digits.charAt(10));
+  return hasValidCheckDigits ? digits : null;
 }
 
-export function formatCpf(value: string): string {
+export function maskCpf(value: string): string {
   const digits = value.replace(/\D/g, '').slice(0, CPF_LENGTH);
 
   if (digits.length <= 3) return digits;
@@ -23,10 +21,10 @@ export function formatCpf(value: string): string {
   return `${digits.slice(0, 3)}.${digits.slice(3, 6)}.${digits.slice(6, 9)}-${digits.slice(9)}`;
 }
 
-function checkDigit(digits: string, length: number): number {
+function checkDigit(digits: string, digitCount: number): number {
   let sum = 0;
-  for (let index = 0; index < length; index += 1) {
-    sum += Number(digits.charAt(index)) * (length + 1 - index);
+  for (let index = 0; index < digitCount; index += 1) {
+    sum += Number(digits.charAt(index)) * (digitCount + 1 - index);
   }
 
   const remainder = (sum * 10) % 11;
diff --git a/apps/admin-frontend/src/shared/format/email.test.ts b/apps/admin-frontend/src/shared/format/email.test.ts
new file mode 100644
index 00000000..077e5f6d
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/email.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, it } from 'vitest';
+import { EMAIL_MAX_LENGTH, parseEmail } from './email';
+
+describe('parseEmail', () => {
+  it.each([
+    ['maria@example.com', 'maria@example.com'],
+    ['maria.souza+agenda@mail.example.com.br', 'maria.souza+agenda@mail.example.com.br'],
+    ['a@b.co', 'a@b.co'],
+    ['  Maria.Souza@Example.COM  ', 'maria.souza@example.com'],
+  ] as const)('reads %j as %j', (email, expected) => {
+    expect(parseEmail(email)).toBe(expected);
+  });
+
+  it('measures the trimmed, lowercased address against the limit', () => {
+    const domain = '@example.com';
+    const atTheLimit = `${'a'.repeat(EMAIL_MAX_LENGTH - domain.length)}${domain}`;
+
+    expect(parseEmail(` ${atTheLimit} `)).toBe(atTheLimit);
+    expect(parseEmail(`a${atTheLimit}`)).toBeNull();
+  });
+
+  it.each([
+    '',
+    '   ',
+    'maria',
+    'maria@',
+    '@example.com',
+    'maria@example',
+    'maria@@example.com',
+    'a@b@example.com',
+    'maria@example..com',
+    'maria@.example.com',
+    'maria@example.com.',
+    'maria souza@example.com',
+  ])('rejects %j', (email) => {
+    expect(parseEmail(email)).toBeNull();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/format/email.ts b/apps/admin-frontend/src/shared/format/email.ts
new file mode 100644
index 00000000..c212f81b
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/email.ts
@@ -0,0 +1,13 @@
+export const EMAIL_MAX_LENGTH = 254;
+
+export function parseEmail(raw: string): string | null {
+  const email = raw.trim().toLowerCase();
+  if (email.length > EMAIL_MAX_LENGTH || /\s/.test(email)) return null;
+
+  const atIndex = email.indexOf('@');
+  if (atIndex < 1 || atIndex !== email.lastIndexOf('@')) return null;
+
+  const labels = email.slice(atIndex + 1).split('.');
+  const hasValidDomain = labels.length >= 2 && labels.every((label) => label.length > 0);
+  return hasValidDomain ? email : null;
+}
diff --git a/apps/admin-frontend/src/shared/format/phone.test.ts b/apps/admin-frontend/src/shared/format/phone.test.ts
new file mode 100644
index 00000000..e45996e3
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/phone.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { PHONE_MAX_LENGTH, parsePhone } from './phone';
+
+describe('parsePhone', () => {
+  it.each([
+    ['11999990000', '11999990000'],
+    ['(11) 99999-0000', '(11) 99999-0000'],
+    ['+55 (11) 99999-0000', '+55 (11) 99999-0000'],
+    ['11 9999-0000', '11 9999-0000'],
+    ['+55 11 99999 0000', '+55 11 99999 0000'],
+    ['1'.repeat(PHONE_MAX_LENGTH), '1'.repeat(PHONE_MAX_LENGTH)],
+  ] as const)('accepts %j', (phone, expected) => {
+    expect(parsePhone(phone)).toBe(expected);
+  });
+
+  it('trims before measuring, so padding never counts against the limit', () => {
+    const padded = `  ${'1'.repeat(PHONE_MAX_LENGTH)}  `;
+
+    expect(parsePhone(padded)).toBe('1'.repeat(PHONE_MAX_LENGTH));
+    expect(parsePhone('  (11) 99999-0000  ')).toBe('(11) 99999-0000');
+  });
+
+  it.each([
+    '',
+    '   ',
+    '1'.repeat(PHONE_MAX_LENGTH + 1),
+    '(11) 99999-0000 ramal 12',
+    '11.99999.0000',
+    '11/99999',
+    'telefone',
+    '+-() ',
+    '---',
+  ])('rejects %j', (phone) => {
+    expect(parsePhone(phone)).toBeNull();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/format/phone.ts b/apps/admin-frontend/src/shared/format/phone.ts
new file mode 100644
index 00000000..64f60d9b
--- /dev/null
+++ b/apps/admin-frontend/src/shared/format/phone.ts
@@ -0,0 +1,9 @@
+export const PHONE_MAX_LENGTH = 20;
+
+export function parsePhone(raw: string): string | null {
+  const phone = raw.trim();
+  const hasValidShape =
+    phone.length <= PHONE_MAX_LENGTH && /\d/.test(phone) && /^[\d +()-]+$/.test(phone);
+
+  return hasValidShape ? phone : null;
+}

From 27982764895b87216a890564890b79076d1a3f21 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 14:41:39 -0300
Subject: [PATCH 21/30] Relocate form schemas to page modules

Move the client and tag form schema/test files into their page folders and update affected imports to match the new local structure. This keeps form validation and page-level logic co-located, reducing cross-feature coupling and making the feature modules easier to reason about.
---
 .../{model => ui/pages/ClientFormPage}/clientForm.test.ts   | 0
 .../{model => ui/pages/ClientFormPage}/clientForm.ts        | 2 +-
 .../pages/ClientFormPage/components/ClientGuardianItem.tsx  | 2 +-
 .../ClientFormPage/components/ClientGuardiansSection.tsx    | 6 +-----
 .../pages/ClientFormPage/components/ClientPersonSection.tsx | 2 +-
 .../components/ClientReferenceContactItem.tsx               | 2 +-
 .../components/ClientReferenceContactsSection.tsx           | 2 +-
 .../clients/ui/pages/ClientFormPage/useClientFormPage.ts    | 2 +-
 .../ui/pages/ClientFormPage/useClientFormPage.types.ts      | 2 +-
 .../features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx | 2 +-
 .../src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx  | 2 +-
 .../tags/ui/pages/TagFormPage/components/TagFormBody.tsx    | 2 +-
 .../tags/{model => ui/pages/TagFormPage}/tagForm.test.ts    | 2 +-
 .../tags/{model => ui/pages/TagFormPage}/tagForm.ts         | 2 +-
 .../features/tags/ui/pages/TagFormPage/useTagFormPage.ts    | 2 +-
 .../tags/ui/pages/TagFormPage/useTagFormPage.types.ts       | 2 +-
 16 files changed, 15 insertions(+), 19 deletions(-)
 rename apps/admin-frontend/src/features/clients/{model => ui/pages/ClientFormPage}/clientForm.test.ts (100%)
 rename apps/admin-frontend/src/features/clients/{model => ui/pages/ClientFormPage}/clientForm.ts (98%)
 rename apps/admin-frontend/src/features/tags/{model => ui/pages/TagFormPage}/tagForm.test.ts (98%)
 rename apps/admin-frontend/src/features/tags/{model => ui/pages/TagFormPage}/tagForm.ts (96%)

diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.test.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
similarity index 100%
rename from apps/admin-frontend/src/features/clients/model/clientForm.test.ts
rename to apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
diff --git a/apps/admin-frontend/src/features/clients/model/clientForm.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
similarity index 98%
rename from apps/admin-frontend/src/features/clients/model/clientForm.ts
rename to apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
index 035389ac..6b5a4721 100644
--- a/apps/admin-frontend/src/features/clients/model/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ADULT_AGE_IN_YEARS, isMinorOn } from '@/shared/format/birthDate';
 import { todayUtc } from '@/shared/format/date';
 import { birthDateSchema, cpfSchema, emailSchema, phoneSchema } from '@/shared/form/schemas';
-import { CONTACT_PURPOSES } from './client';
+import { CONTACT_PURPOSES } from '../../../model/client';
 
 // Mirrors the backend limits (ServicesService.Domain.Entities.Client / ClientContact). UX pre-check
 // only - the backend response stays the source of truth.
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
index a4c00844..4ebeb95a 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -6,7 +6,7 @@ import {
   CLIENT_NAME_MAX_LENGTH,
   CONTACT_RELATIONSHIP_MAX_LENGTH,
   type ClientFormFieldValues,
-} from '../../../../model/clientForm';
+} from '../clientForm';
 
 interface ClientGuardianItemProps {
   index: number;
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index 198bb2de..1a1b3b53 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -5,11 +5,7 @@ import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
 import { ADULT_AGE_IN_YEARS } from '@/shared/format/birthDate';
 import { isMinorBirthDate } from '@/shared/form/schemas';
-import {
-  MAX_GUARDIANS,
-  emptyGuardian,
-  type ClientFormFieldValues,
-} from '../../../../model/clientForm';
+import { MAX_GUARDIANS, emptyGuardian, type ClientFormFieldValues } from '../clientForm';
 import { ClientGuardianItem } from './ClientGuardianItem';
 
 function ClientGuardiansSection() {
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index ec272d28..4784a3d1 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -11,7 +11,7 @@ import {
   CLIENT_NAME_MAX_LENGTH,
   CLIENT_NOTES_MAX_LENGTH,
   type ClientFormFieldValues,
-} from '../../../../model/clientForm';
+} from '../clientForm';
 
 function ClientPersonSection() {
   return (
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index fa3f2f27..55f5ea02 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -8,7 +8,7 @@ import {
   CLIENT_NAME_MAX_LENGTH,
   CONTACT_RELATIONSHIP_MAX_LENGTH,
   type ClientFormFieldValues,
-} from '../../../../model/clientForm';
+} from '../clientForm';
 
 interface ClientReferenceContactItemProps {
   index: number;
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
index 45ea4654..e62fe510 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -7,7 +7,7 @@ import {
   MAX_REFERENCE_CONTACTS,
   emptyReferenceContact,
   type ClientFormFieldValues,
-} from '../../../../model/clientForm';
+} from '../clientForm';
 import { ClientReferenceContactItem } from './ClientReferenceContactItem';
 
 function ClientReferenceContactsSection() {
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index fd018615..b63537bf 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -10,7 +10,7 @@ import {
   toClientFormFieldValues,
   type ClientFormFieldValues,
   type ClientFormValues,
-} from '../../../model/clientForm';
+} from './clientForm';
 import type { UseClientFormPageResult } from './useClientFormPage.types';
 
 const CLIENTS_PATH = '/pessoas';
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
index 6cb25ab8..69153d5d 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.types.ts
@@ -1,6 +1,6 @@
 import type { SubmitEvent } from 'react';
 import type { UseFormReturn } from 'react-hook-form';
-import type { ClientFormFieldValues, ClientFormValues } from '../../../model/clientForm';
+import type { ClientFormFieldValues, ClientFormValues } from './clientForm';
 
 export interface UseClientFormPageResult {
   methods: UseFormReturn<ClientFormFieldValues, unknown, ClientFormValues>;
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx
index 8e831e53..783d534d 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx
@@ -13,7 +13,7 @@ import {
 import { TagListPage } from '../TagListPage/TagListPage';
 import { TagFormPage } from './TagFormPage';
 import type { Tag } from '../../../model/tag';
-import { TAG_DESCRIPTION_MAX_LENGTH, TAG_NAME_MAX_LENGTH } from '../../../model/tagForm';
+import { TAG_DESCRIPTION_MAX_LENGTH, TAG_NAME_MAX_LENGTH } from './tagForm';
 
 const { mockList, mockGet, mockCreate, mockUpdate } = vi.hoisted(() => ({
   mockList: vi.fn(),
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
index 6ffaaad6..dc3ec547 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
@@ -2,7 +2,7 @@ import { FormProvider } from 'react-hook-form';
 import { Dialog, DialogContent } from '@/shared/ui/dialog';
 import { FormFieldsSkeleton } from '@/shared/ui/form-field';
 import { FormFooter } from '@/widgets/form-footer';
-import { TAG_FORM_FIELDS } from '../../../model/tagForm';
+import { TAG_FORM_FIELDS } from './tagForm';
 import { TagFormBody } from './components/TagFormBody';
 import { TagFormHeader } from './components/TagFormHeader';
 import { useTagFormPage } from './useTagFormPage';
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
index 08d52cfa..2b0f1d7a 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
@@ -4,7 +4,7 @@ import {
   TAG_DESCRIPTION_MAX_LENGTH,
   TAG_NAME_MAX_LENGTH,
   type TagFormFieldValues,
-} from '../../../../model/tagForm';
+} from '../tagForm';
 
 function TagFormBody() {
   return (
diff --git a/apps/admin-frontend/src/features/tags/model/tagForm.test.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
similarity index 98%
rename from apps/admin-frontend/src/features/tags/model/tagForm.test.ts
rename to apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
index ecde9503..0348feb8 100644
--- a/apps/admin-frontend/src/features/tags/model/tagForm.test.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
-import type { Tag } from './tag';
+import type { Tag } from '../../../model/tag';
 import {
   TAG_DESCRIPTION_MAX_LENGTH,
   TAG_FORM_FIELDS,
diff --git a/apps/admin-frontend/src/features/tags/model/tagForm.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.ts
similarity index 96%
rename from apps/admin-frontend/src/features/tags/model/tagForm.ts
rename to apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.ts
index 3a98ee0a..48a4b8a7 100644
--- a/apps/admin-frontend/src/features/tags/model/tagForm.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.ts
@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { Tag } from './tag';
+import type { Tag } from '../../../model/tag';
 
 // Mirrors backend length limits (ServicesService.Domain.Entities.Tag.NameMaxLength /
 // DescriptionMaxLength) so the maxLength attributes and messages below match what the backend
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
index ae18b358..24cfc3e2 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
@@ -11,7 +11,7 @@ import {
   toTagFormFieldValues,
   type TagFormFieldValues,
   type TagFormValues,
-} from '../../../model/tagForm';
+} from './tagForm';
 import { TagFormStatus, type UseTagFormPageResult } from './useTagFormPage.types';
 
 export function useTagFormPage(): UseTagFormPageResult {
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.types.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.types.ts
index abbc612b..166c8248 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.types.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.types.ts
@@ -1,6 +1,6 @@
 import type { SubmitEvent } from 'react';
 import type { UseFormReturn } from 'react-hook-form';
-import type { TagFormFieldValues, TagFormValues } from '../../../model/tagForm';
+import type { TagFormFieldValues, TagFormValues } from './tagForm';
 
 export const TagFormStatus = {
   Loading: 'loading',

From 68876e45f02ba48dc08c4dfb28f734b2d2fa87c3 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 15:04:51 -0300
Subject: [PATCH 22/30] Split client model types and add birthDate

The client domain types were split into dedicated files for guardians, reference contacts, and contact purpose metadata. This also adds the missing birthDate field to Client and renames the empty form factory to emptyClientFormFieldValues so form initialization stays explicit and consistent with the updated model.
---
 .../src/features/clients/model/client.ts      | 44 +++----------------
 .../features/clients/model/clientGuardian.ts  |  7 +++
 .../clients/model/clientReferenceContact.ts   |  9 ++++
 .../features/clients/model/contactPurpose.ts  | 14 ++++++
 .../ClientFormPage/ClientFormPage.test.tsx    |  1 +
 .../pages/ClientFormPage/clientForm.test.ts   |  6 +--
 .../ui/pages/ClientFormPage/clientForm.ts     |  4 +-
 .../components/ClientReferenceContactItem.tsx |  2 +-
 .../pages/ClientFormPage/useClientFormPage.ts |  4 +-
 .../src/features/tags/model/tag.ts            | 16 -------
 .../src/features/tags/model/tagColor.ts       | 15 +++++++
 .../TagFormPage/components/TagFormBody.tsx    |  2 +-
 12 files changed, 60 insertions(+), 64 deletions(-)
 create mode 100644 apps/admin-frontend/src/features/clients/model/clientGuardian.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/clientReferenceContact.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/contactPurpose.ts
 create mode 100644 apps/admin-frontend/src/features/tags/model/tagColor.ts

diff --git a/apps/admin-frontend/src/features/clients/model/client.ts b/apps/admin-frontend/src/features/clients/model/client.ts
index 3f687053..5e3eb1c1 100644
--- a/apps/admin-frontend/src/features/clients/model/client.ts
+++ b/apps/admin-frontend/src/features/clients/model/client.ts
@@ -1,26 +1,10 @@
-export interface ClientGuardian {
-  id: string;
-  name: string;
-  relationship: string;
-  phone: string | null;
-  cpf: string | null;
-}
-
-export const CONTACT_PURPOSES = ['emergency', 'operationalSupport', 'dailyCommunication'] as const;
-
-export type ContactPurpose = (typeof CONTACT_PURPOSES)[number];
-
-export interface ClientReferenceContact {
-  id: string;
-  name: string;
-  relationship: string;
-  phone: string | null;
-  purposes: ContactPurpose[];
-}
+import type { ClientGuardian } from './clientGuardian';
+import type { ClientReferenceContact } from './clientReferenceContact';
 
 export interface Client {
   id: string;
   fullName: string;
+  birthDate: string | null;
   phone: string | null;
   email: string | null;
   cpf: string | null;
@@ -30,13 +14,6 @@ export interface Client {
   referenceContacts: ClientReferenceContact[];
 }
 
-export type GuardianInput = Pick<ClientGuardian, 'name' | 'relationship' | 'phone' | 'cpf'>;
-
-export type ReferenceContactInput = Pick<
-  ClientReferenceContact,
-  'name' | 'relationship' | 'phone' | 'purposes'
->;
-
 export interface ClientInput {
   fullName: string;
   birthDate: Date | null;
@@ -44,17 +21,6 @@ export interface ClientInput {
   email: string | null;
   cpf: string | null;
   administrativeNotes: string | null;
-  guardians: GuardianInput[];
-  referenceContacts: ReferenceContactInput[];
+  guardians: Omit<ClientGuardian, 'id'>[];
+  referenceContacts: Omit<ClientReferenceContact, 'id'>[];
 }
-
-export interface ContactPurposeOption {
-  value: ContactPurpose;
-  label: string;
-}
-
-export const CONTACT_PURPOSE_OPTIONS: readonly ContactPurposeOption[] = [
-  { value: 'emergency', label: 'Emergência' },
-  { value: 'operationalSupport', label: 'Apoio operacional' },
-  { value: 'dailyCommunication', label: 'Comunicação cotidiana' },
-];
diff --git a/apps/admin-frontend/src/features/clients/model/clientGuardian.ts b/apps/admin-frontend/src/features/clients/model/clientGuardian.ts
new file mode 100644
index 00000000..7d1c0c8c
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/clientGuardian.ts
@@ -0,0 +1,7 @@
+export interface ClientGuardian {
+  id: string;
+  name: string;
+  relationship: string;
+  phone: string | null;
+  cpf: string | null;
+}
diff --git a/apps/admin-frontend/src/features/clients/model/clientReferenceContact.ts b/apps/admin-frontend/src/features/clients/model/clientReferenceContact.ts
new file mode 100644
index 00000000..bf26a501
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/clientReferenceContact.ts
@@ -0,0 +1,9 @@
+import type { ContactPurpose } from './contactPurpose';
+
+export interface ClientReferenceContact {
+  id: string;
+  name: string;
+  relationship: string;
+  phone: string | null;
+  purposes: ContactPurpose[];
+}
diff --git a/apps/admin-frontend/src/features/clients/model/contactPurpose.ts b/apps/admin-frontend/src/features/clients/model/contactPurpose.ts
new file mode 100644
index 00000000..a4da37fd
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/contactPurpose.ts
@@ -0,0 +1,14 @@
+export const CONTACT_PURPOSES = ['emergency', 'operationalSupport', 'dailyCommunication'] as const;
+
+export type ContactPurpose = (typeof CONTACT_PURPOSES)[number];
+
+export interface ContactPurposeOption {
+  value: ContactPurpose;
+  label: string;
+}
+
+export const CONTACT_PURPOSE_OPTIONS: readonly ContactPurposeOption[] = [
+  { value: 'emergency', label: 'Emergência' },
+  { value: 'operationalSupport', label: 'Apoio operacional' },
+  { value: 'dailyCommunication', label: 'Comunicação cotidiana' },
+];
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 0a7ab183..263a18f2 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -17,6 +17,7 @@ vi.mock('../../../api/clientsRepository', () => ({
 const CREATED: Client = {
   id: '0197f2a0-0000-7000-8000-0000000000aa',
   fullName: 'Maria Souza',
+  birthDate: null,
   phone: null,
   email: null,
   cpf: null,
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
index 49508912..0bcca042 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
@@ -7,14 +7,14 @@ import {
   clientFormSchema,
   emptyGuardian,
   emptyReferenceContact,
-  toClientFormFieldValues,
+  emptyClientFormFieldValues,
   type ClientFormFieldValues,
 } from './clientForm';
 
 const NOON_UTC = new Date('2026-10-02T12:00:00Z');
 
 function values(overrides: Partial<ClientFormFieldValues> = {}): ClientFormFieldValues {
-  return { ...toClientFormFieldValues(), fullName: 'Maria Souza', ...overrides };
+  return { ...emptyClientFormFieldValues(), fullName: 'Maria Souza', ...overrides };
 }
 
 function guardian(overrides: Partial<ReturnType<typeof emptyGuardian>> = {}) {
@@ -334,7 +334,7 @@ describe('form field lists', () => {
   });
 
   it('starts empty so nothing is asked up front', () => {
-    expect(toClientFormFieldValues()).toEqual({
+    expect(emptyClientFormFieldValues()).toEqual({
       fullName: '',
       birthDate: '',
       phone: '',
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
index 6b5a4721..69f20411 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { ADULT_AGE_IN_YEARS, isMinorOn } from '@/shared/format/birthDate';
 import { todayUtc } from '@/shared/format/date';
 import { birthDateSchema, cpfSchema, emailSchema, phoneSchema } from '@/shared/form/schemas';
-import { CONTACT_PURPOSES } from '../../../model/client';
+import { CONTACT_PURPOSES } from '../../../model/contactPurpose';
 
 // Mirrors the backend limits (ServicesService.Domain.Entities.Client / ClientContact). UX pre-check
 // only - the backend response stays the source of truth.
@@ -99,7 +99,7 @@ export const CLIENT_FORM_FIELDS = clientFormObject.keyof().options;
 export const GUARDIAN_FORM_FIELDS = guardianSchema.keyof().options;
 export const REFERENCE_CONTACT_FORM_FIELDS = referenceContactSchema.keyof().options;
 
-export function toClientFormFieldValues(): ClientFormFieldValues {
+export function emptyClientFormFieldValues(): ClientFormFieldValues {
   return {
     fullName: '',
     birthDate: '',
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index 55f5ea02..2e3d14d4 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -3,7 +3,7 @@ import { XIcon } from 'lucide-react';
 import { ControlledField, PhoneField, TextField } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { CheckboxGroup } from '@/shared/ui/checkbox-group';
-import { CONTACT_PURPOSE_OPTIONS } from '../../../../model/client';
+import { CONTACT_PURPOSE_OPTIONS } from '../../../../model/contactPurpose';
 import {
   CLIENT_NAME_MAX_LENGTH,
   CONTACT_RELATIONSHIP_MAX_LENGTH,
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index b63537bf..e74e83ff 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -7,7 +7,7 @@ import { toast } from '@/shared/ui/toast';
 import { clientsRepository } from '../../../api/clientsRepository';
 import {
   clientFormSchema,
-  toClientFormFieldValues,
+  emptyClientFormFieldValues,
   type ClientFormFieldValues,
   type ClientFormValues,
 } from './clientForm';
@@ -21,7 +21,7 @@ export function useClientFormPage(): UseClientFormPageResult {
 
   const methods = useForm<ClientFormFieldValues, unknown, ClientFormValues>({
     resolver: zodResolver(clientFormSchema),
-    defaultValues: toClientFormFieldValues(),
+    defaultValues: emptyClientFormFieldValues(),
   });
   const isSaving = methods.formState.isSubmitting;
 
diff --git a/apps/admin-frontend/src/features/tags/model/tag.ts b/apps/admin-frontend/src/features/tags/model/tag.ts
index 47e19116..f186dabf 100644
--- a/apps/admin-frontend/src/features/tags/model/tag.ts
+++ b/apps/admin-frontend/src/features/tags/model/tag.ts
@@ -6,19 +6,3 @@ export interface Tag {
 }
 
 export type TagInput = Pick<Tag, 'name' | 'color' | 'description'>;
-
-export interface TagColorOption {
-  value: string;
-  label: string;
-}
-
-export const TAG_COLOR_PALETTE: readonly TagColorOption[] = [
-  { value: '#0d9488', label: 'Verde-azulado' },
-  { value: '#0ea5e9', label: 'Azul' },
-  { value: '#8b5cf6', label: 'Violeta' },
-  { value: '#ec4899', label: 'Rosa' },
-  { value: '#ef4444', label: 'Vermelho' },
-  { value: '#f59e0b', label: 'Âmbar' },
-  { value: '#22c55e', label: 'Verde' },
-  { value: '#64748b', label: 'Cinza' },
-];
diff --git a/apps/admin-frontend/src/features/tags/model/tagColor.ts b/apps/admin-frontend/src/features/tags/model/tagColor.ts
new file mode 100644
index 00000000..b487ed83
--- /dev/null
+++ b/apps/admin-frontend/src/features/tags/model/tagColor.ts
@@ -0,0 +1,15 @@
+export interface TagColorOption {
+  value: string;
+  label: string;
+}
+
+export const TAG_COLOR_PALETTE: readonly TagColorOption[] = [
+  { value: '#0d9488', label: 'Verde-azulado' },
+  { value: '#0ea5e9', label: 'Azul' },
+  { value: '#8b5cf6', label: 'Violeta' },
+  { value: '#ec4899', label: 'Rosa' },
+  { value: '#ef4444', label: 'Vermelho' },
+  { value: '#f59e0b', label: 'Âmbar' },
+  { value: '#22c55e', label: 'Verde' },
+  { value: '#64748b', label: 'Cinza' },
+];
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
index 2b0f1d7a..603f6852 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
@@ -1,5 +1,5 @@
 import { ColorField, FormErrorBanner, TextField, TextareaField } from '@/shared/form/fields';
-import { TAG_COLOR_PALETTE } from '../../../../model/tag';
+import { TAG_COLOR_PALETTE } from '../../../../model/tagColor';
 import {
   TAG_DESCRIPTION_MAX_LENGTH,
   TAG_NAME_MAX_LENGTH,

From f036c0ad16fb319f95bce7fe57041f4884bd68cc Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 15:17:23 -0300
Subject: [PATCH 23/30] docs(admin-frontend): skill agenza-form-field usa a
 assinatura atual de applyApiProblem (#154)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

applyApiProblem passou a receber (problem, methods): ele monta os caminhos de
campo a partir de methods.getValues() e dá foco no primeiro campo inválido.
A skill ainda mostrava (problem, fields, setError), a lista de campos mantida
pela página (fieldPathsOf no hook) e o genérico explícito do helper.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 .claude/skills/agenza-form-field/SKILL.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index 00c75f6b..d61e7922 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -15,9 +15,10 @@ UI reintroduced on React Hook Form + Zod" row and the row right after it) for th
 and the two gotchas below in their original context, and §6's "Provisional" section for what's still
 unproven.
 
-Backend errors on a list item arrive keyed `Guardians[1].Name`; `toFormErrors` normalizes that to
-`guardians.1.name`, so the hook passes it the **current** field paths (top-level plus one per item),
-not a static list — see `useClientFormPage.ts`'s `fieldPathsOf`. A field-array root error (e.g.
+Backend errors on a list item arrive keyed `guardians[1].name`; `toFormErrors` normalizes that to
+`guardians.1.name`, and `applyApiProblem` matches it against the **current** field paths: it derives
+them from `methods.getValues()` when the response arrives (top-level plus one per item), so a page
+keeps no path list of its own. A field-array root error (e.g.
 "informe ao menos um responsável") lives at `errors.guardians.message` / `errors.guardians.root.message`
 and has no input to attach to: render it in the section.
 
@@ -26,7 +27,7 @@ and has no input to attach to: render it in the section.
 | Layer | File | Job |
 | --- | --- | --- |
 | Error mapping | `shared/api/formErrors.ts` | `toFormErrors<F>(problem, fields)` — `ApiProblem` → `{fieldErrors, formError}`. Knows `ApiProblem`, nothing about RHF. |
-| RHF bridge | `shared/form/applyApiProblem.ts` | `applyApiProblem<T>(problem, fields, setError)` — calls the above, then `setError` per field plus `setError('root.serverError', …)`. Knows both shapes; the only file that does. |
+| RHF bridge | `shared/form/applyApiProblem.ts` | `applyApiProblem(problem, methods)` — builds the current field paths from `methods.getValues()`, calls the above, then `setError` per field, `setError('root.serverError', …)` for the form-level message and `setFocus` on the first invalid field. Knows both shapes; the only file that does. |
 | Field components | `shared/form/fields/` | `TextField`/`TextareaField`, `MaskedField`, `DateField`, `ControlledField`, `ColorField`, `FormErrorBanner` — RHF wiring, zero entity knowledge. They render into `shared/ui/form-field/`'s `FormField` (label, hint, error, the `aria-*` wiring), which stays presentational and RHF-free like the rest of `shared/ui/` (`agenza-ui-primitive`). |
 
 Never let a field component or `shared/form/` read `problem.errors` directly — that parsing (indexed
@@ -67,7 +68,7 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    async function onValid(values: XFormValues) {
      const result = isEdit ? await xRepository.update(id, values) : await xRepository.create(values);
      if (result.ok) { /* publish, toast, navigate */ return; }
-     applyApiProblem<XFormFieldValues>(result.error, X_FORM_FIELDS, methods.setError);
+     applyApiProblem(result.error, methods);
    }
 
    function submit(event: SubmitEvent<HTMLFormElement>) {
@@ -201,7 +202,7 @@ TTransformedValues>` needs the input shape as its first generic, the output shap
 Modeling both as one `z.infer<typeof schema>` type — the natural first guess — compiles right up
 until `resolver: zodResolver(schema)` is attached to `useForm`, where `tsc` names a `Resolver<Input,
 any, Output>` mismatch. Fix: `z.input<typeof schema>` for the field components and
-`applyApiProblem`'s generic, `z.output<typeof schema>` for `onValid`'s parameter — see
+`useForm`'s first generic (`applyApiProblem` infers its own from `methods`), `z.output<typeof schema>` for `onValid`'s parameter — see
 `TagFormFieldValues`/`TagFormValues` in `tagForm.ts`.
 
 **2. Not every control accepts `id`/`htmlFor`.** `FormField`'s `<Label htmlFor={id}>` assumes the

From af38ce261b096a9963924086ba79eb93a6092728 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 15:35:32 -0300
Subject: [PATCH 24/30] Split shared form field components

The legacy value-fields module was split into dedicated field components for birth date, CPF, email, and phone, and re-exported from the shared fields index. This keeps each field isolated and easier to maintain while preserving the existing behavior, including masked inputs, max-length constraints, and the age hint logic for birth dates.
---
 .../components/birth-date-field.test.tsx      |  68 +++++++++
 .../fields/components/birth-date-field.tsx    |  30 ++++
 .../form/fields/components/cpf-field.test.tsx |  45 ++++++
 .../form/fields/components/cpf-field.tsx      |  22 +++
 .../fields/components/email-field.test.tsx    |  30 ++++
 .../form/fields/components/email-field.tsx    |  22 +++
 .../fields/components/phone-field.test.tsx    |  30 ++++
 .../form/fields/components/phone-field.tsx    |  22 +++
 .../fields/components/value-fields.test.tsx   | 135 ------------------
 .../form/fields/components/value-fields.tsx   |  94 ------------
 .../src/shared/form/fields/index.tsx          |   5 +-
 11 files changed, 273 insertions(+), 230 deletions(-)
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/birth-date-field.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/cpf-field.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/email-field.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/email-field.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/phone-field.test.tsx
 create mode 100644 apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx
 delete mode 100644 apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx
 delete mode 100644 apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx

diff --git a/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.test.tsx
new file mode 100644
index 00000000..9cfbc978
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.test.tsx
@@ -0,0 +1,68 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FormProvider, useForm } from 'react-hook-form';
+import { BirthDateField } from './birth-date-field';
+
+interface DummyValues {
+  birthDate: string;
+}
+
+function Harness({ children }: { children: React.ReactNode }) {
+  const methods = useForm<DummyValues>({ defaultValues: { birthDate: '' } });
+
+  return <FormProvider {...methods}>{children}</FormProvider>;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe('BirthDateField', () => {
+  it('arrives labelled and optional, and swaps the hint for the age once the date is complete', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <BirthDateField<DummyValues> name="birthDate" />
+      </Harness>,
+    );
+
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+
+    await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
+
+    expect(screen.getByText('36 anos')).toBeInTheDocument();
+    expect(screen.queryByText('opcional')).not.toBeInTheDocument();
+  });
+
+  it('keeps the optional hint while the typed date is not a valid birth date', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <BirthDateField<DummyValues> name="birthDate" />
+      </Harness>,
+    );
+
+    await user.type(screen.getByLabelText('Data de nascimento'), '02102026');
+
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+
+  it('prefers a hint given by the call site over the age', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <BirthDateField<DummyValues> name="birthDate" hint="obrigatório" />
+      </Harness>,
+    );
+
+    await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
+
+    expect(screen.getByText('obrigatório')).toBeInTheDocument();
+    expect(screen.queryByText('36 anos')).not.toBeInTheDocument();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx
new file mode 100644
index 00000000..9c262c52
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx
@@ -0,0 +1,30 @@
+import { useFormContext, useWatch, type FieldValues } from 'react-hook-form';
+import { formatAge } from '@/shared/format/age';
+import { birthDatePickerBounds } from '@/shared/format/birthDate';
+import { ageFromBirthDate } from '@/shared/form/schemas';
+import type { BirthDateFieldProps } from '../fields.types';
+import { DateField } from './date-field';
+
+export function BirthDateField<T extends FieldValues>({
+  name,
+  label = 'Data de nascimento',
+  hint,
+  ...props
+}: BirthDateFieldProps<T>) {
+  const { control } = useFormContext<T>();
+  const typed: unknown = useWatch({ control, name });
+  const age = ageFromBirthDate(typeof typed === 'string' ? typed : '');
+  const { min, max } = birthDatePickerBounds();
+
+  return (
+    <DateField<T>
+      name={name}
+      label={label}
+      hint={hint ?? (age === null ? 'opcional' : formatAge(age))}
+      minDate={min}
+      maxDate={max}
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/components/cpf-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/cpf-field.test.tsx
new file mode 100644
index 00000000..8a83b3d3
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/cpf-field.test.tsx
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { FormProvider, useForm } from 'react-hook-form';
+import { CpfField } from './cpf-field';
+
+interface DummyValues {
+  cpf: string;
+}
+
+function Harness({ children }: { children: React.ReactNode }) {
+  const methods = useForm<DummyValues>({ defaultValues: { cpf: '' } });
+
+  return <FormProvider {...methods}>{children}</FormProvider>;
+}
+
+describe('CpfField', () => {
+  it('arrives labelled, optional, numeric and masking what is typed', async () => {
+    const user = userEvent.setup();
+    render(
+      <Harness>
+        <CpfField<DummyValues> name="cpf" />
+      </Harness>,
+    );
+
+    const input = screen.getByLabelText('CPF');
+    await user.type(input, '52998224725');
+
+    expect(input).toHaveValue('529.982.247-25');
+    expect(input).toHaveAttribute('inputmode', 'numeric');
+    expect(input).toHaveAttribute('placeholder', '000.000.000-00');
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+
+  it('lets the call site rename the field and change its hint', () => {
+    render(
+      <Harness>
+        <CpfField<DummyValues> name="cpf" label="CPF do responsável" hint="obrigatório" />
+      </Harness>,
+    );
+
+    expect(screen.getByLabelText('CPF do responsável')).toBeInTheDocument();
+    expect(screen.getByText('obrigatório')).toBeInTheDocument();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx
new file mode 100644
index 00000000..ad36df7e
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx
@@ -0,0 +1,22 @@
+import type { FieldValues } from 'react-hook-form';
+import { maskCpf } from '@/shared/format/cpf';
+import type { CpfFieldProps } from '../fields.types';
+import { MaskedField } from './masked-field';
+
+export function CpfField<T extends FieldValues>({
+  label = 'CPF',
+  hint = 'opcional',
+  ...props
+}: CpfFieldProps<T>) {
+  return (
+    <MaskedField<T>
+      label={label}
+      hint={hint}
+      mask={maskCpf}
+      inputMode="numeric"
+      placeholder="000.000.000-00"
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/components/email-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/email-field.test.tsx
new file mode 100644
index 00000000..ce6b9191
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/email-field.test.tsx
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { FormProvider, useForm } from 'react-hook-form';
+import { EmailField } from './email-field';
+
+interface DummyValues {
+  email: string;
+}
+
+function Harness({ children }: { children: React.ReactNode }) {
+  const methods = useForm<DummyValues>({ defaultValues: { email: '' } });
+
+  return <FormProvider {...methods}>{children}</FormProvider>;
+}
+
+describe('EmailField', () => {
+  it('arrives as an e-mail input capped at the backend limit', () => {
+    render(
+      <Harness>
+        <EmailField<DummyValues> name="email" />
+      </Harness>,
+    );
+
+    const input = screen.getByLabelText('E-mail');
+    expect(input).toHaveAttribute('type', 'email');
+    expect(input).toHaveAttribute('maxlength', '254');
+    expect(input).toHaveAttribute('placeholder', 'nome@exemplo.com');
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/email-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/email-field.tsx
new file mode 100644
index 00000000..b479714a
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/email-field.tsx
@@ -0,0 +1,22 @@
+import type { FieldValues } from 'react-hook-form';
+import { EMAIL_MAX_LENGTH } from '@/shared/format/email';
+import type { EmailFieldProps } from '../fields.types';
+import { TextField } from './text-fields';
+
+export function EmailField<T extends FieldValues>({
+  label = 'E-mail',
+  hint = 'opcional',
+  ...props
+}: EmailFieldProps<T>) {
+  return (
+    <TextField<T>
+      label={label}
+      hint={hint}
+      type="email"
+      maxLength={EMAIL_MAX_LENGTH}
+      placeholder="nome@exemplo.com"
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/components/phone-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/phone-field.test.tsx
new file mode 100644
index 00000000..ea7b1897
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/phone-field.test.tsx
@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { FormProvider, useForm } from 'react-hook-form';
+import { PhoneField } from './phone-field';
+
+interface DummyValues {
+  phone: string;
+}
+
+function Harness({ children }: { children: React.ReactNode }) {
+  const methods = useForm<DummyValues>({ defaultValues: { phone: '' } });
+
+  return <FormProvider {...methods}>{children}</FormProvider>;
+}
+
+describe('PhoneField', () => {
+  it('arrives as a telephone input capped at the backend limit', () => {
+    render(
+      <Harness>
+        <PhoneField<DummyValues> name="phone" />
+      </Harness>,
+    );
+
+    const input = screen.getByLabelText('Telefone');
+    expect(input).toHaveAttribute('type', 'tel');
+    expect(input).toHaveAttribute('maxlength', '20');
+    expect(input).toHaveAttribute('placeholder', '(11) 91234-5678');
+    expect(screen.getByText('opcional')).toBeInTheDocument();
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx
new file mode 100644
index 00000000..4006621e
--- /dev/null
+++ b/apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx
@@ -0,0 +1,22 @@
+import type { FieldValues } from 'react-hook-form';
+import { PHONE_MAX_LENGTH } from '@/shared/format/phone';
+import type { PhoneFieldProps } from '../fields.types';
+import { TextField } from './text-fields';
+
+export function PhoneField<T extends FieldValues>({
+  label = 'Telefone',
+  hint = 'opcional',
+  ...props
+}: PhoneFieldProps<T>) {
+  return (
+    <TextField<T>
+      label={label}
+      hint={hint}
+      type="tel"
+      maxLength={PHONE_MAX_LENGTH}
+      placeholder="(11) 91234-5678"
+      autoComplete="off"
+      {...props}
+    />
+  );
+}
diff --git a/apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx
deleted file mode 100644
index cf897712..00000000
--- a/apps/admin-frontend/src/shared/form/fields/components/value-fields.test.tsx
+++ /dev/null
@@ -1,135 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { FormProvider, useForm } from 'react-hook-form';
-import { BirthDateField, CpfField, EmailField, PhoneField } from './value-fields';
-
-interface DummyValues {
-  birthDate: string;
-  cpf: string;
-  phone: string;
-  email: string;
-}
-
-function Harness({ children }: { children: React.ReactNode }) {
-  const methods = useForm<DummyValues>({
-    defaultValues: { birthDate: '', cpf: '', phone: '', email: '' },
-  });
-
-  return <FormProvider {...methods}>{children}</FormProvider>;
-}
-
-beforeEach(() => {
-  vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
-});
-
-afterEach(() => {
-  vi.useRealTimers();
-});
-
-describe('CpfField', () => {
-  it('arrives labelled, optional, numeric and masking what is typed', async () => {
-    const user = userEvent.setup();
-    render(
-      <Harness>
-        <CpfField<DummyValues> name="cpf" />
-      </Harness>,
-    );
-
-    const input = screen.getByLabelText('CPF');
-    await user.type(input, '52998224725');
-
-    expect(input).toHaveValue('529.982.247-25');
-    expect(input).toHaveAttribute('inputmode', 'numeric');
-    expect(input).toHaveAttribute('placeholder', '000.000.000-00');
-    expect(screen.getByText('opcional')).toBeInTheDocument();
-  });
-
-  it('lets the call site rename the field and change its hint', () => {
-    render(
-      <Harness>
-        <CpfField<DummyValues> name="cpf" label="CPF do responsável" hint="obrigatório" />
-      </Harness>,
-    );
-
-    expect(screen.getByLabelText('CPF do responsável')).toBeInTheDocument();
-    expect(screen.getByText('obrigatório')).toBeInTheDocument();
-  });
-});
-
-describe('PhoneField', () => {
-  it('arrives as a telephone input capped at the backend limit', () => {
-    render(
-      <Harness>
-        <PhoneField<DummyValues> name="phone" />
-      </Harness>,
-    );
-
-    const input = screen.getByLabelText('Telefone');
-    expect(input).toHaveAttribute('type', 'tel');
-    expect(input).toHaveAttribute('maxlength', '20');
-    expect(input).toHaveAttribute('placeholder', '(11) 91234-5678');
-    expect(screen.getByText('opcional')).toBeInTheDocument();
-  });
-});
-
-describe('EmailField', () => {
-  it('arrives as an e-mail input capped at the backend limit', () => {
-    render(
-      <Harness>
-        <EmailField<DummyValues> name="email" />
-      </Harness>,
-    );
-
-    const input = screen.getByLabelText('E-mail');
-    expect(input).toHaveAttribute('type', 'email');
-    expect(input).toHaveAttribute('maxlength', '254');
-    expect(input).toHaveAttribute('placeholder', 'nome@exemplo.com');
-    expect(screen.getByText('opcional')).toBeInTheDocument();
-  });
-});
-
-describe('BirthDateField', () => {
-  it('arrives labelled and optional, and swaps the hint for the age once the date is complete', async () => {
-    const user = userEvent.setup();
-    render(
-      <Harness>
-        <BirthDateField<DummyValues> name="birthDate" />
-      </Harness>,
-    );
-
-    expect(screen.getByText('opcional')).toBeInTheDocument();
-
-    await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
-
-    expect(screen.getByText('36 anos')).toBeInTheDocument();
-    expect(screen.queryByText('opcional')).not.toBeInTheDocument();
-  });
-
-  it('keeps the optional hint while the typed date is not a valid birth date', async () => {
-    const user = userEvent.setup();
-    render(
-      <Harness>
-        <BirthDateField<DummyValues> name="birthDate" />
-      </Harness>,
-    );
-
-    await user.type(screen.getByLabelText('Data de nascimento'), '02102026');
-
-    expect(screen.getByText('opcional')).toBeInTheDocument();
-  });
-
-  it('prefers a hint given by the call site over the age', async () => {
-    const user = userEvent.setup();
-    render(
-      <Harness>
-        <BirthDateField<DummyValues> name="birthDate" hint="obrigatório" />
-      </Harness>,
-    );
-
-    await user.type(screen.getByLabelText('Data de nascimento'), '20051990');
-
-    expect(screen.getByText('obrigatório')).toBeInTheDocument();
-    expect(screen.queryByText('36 anos')).not.toBeInTheDocument();
-  });
-});
diff --git a/apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx b/apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx
deleted file mode 100644
index 9912f331..00000000
--- a/apps/admin-frontend/src/shared/form/fields/components/value-fields.tsx
+++ /dev/null
@@ -1,94 +0,0 @@
-import { useFormContext, useWatch, type FieldValues } from 'react-hook-form';
-import { formatAge } from '@/shared/format/age';
-import { birthDatePickerBounds } from '@/shared/format/birthDate';
-import { maskCpf } from '@/shared/format/cpf';
-import { EMAIL_MAX_LENGTH } from '@/shared/format/email';
-import { PHONE_MAX_LENGTH } from '@/shared/format/phone';
-import { ageFromBirthDate } from '@/shared/form/schemas';
-import type {
-  BirthDateFieldProps,
-  CpfFieldProps,
-  EmailFieldProps,
-  PhoneFieldProps,
-} from '../fields.types';
-import { DateField } from './date-field';
-import { MaskedField } from './masked-field';
-import { TextField } from './text-fields';
-
-export function CpfField<T extends FieldValues>({
-  label = 'CPF',
-  hint = 'opcional',
-  ...props
-}: CpfFieldProps<T>) {
-  return (
-    <MaskedField<T>
-      label={label}
-      hint={hint}
-      mask={maskCpf}
-      inputMode="numeric"
-      placeholder="000.000.000-00"
-      autoComplete="off"
-      {...props}
-    />
-  );
-}
-
-export function PhoneField<T extends FieldValues>({
-  label = 'Telefone',
-  hint = 'opcional',
-  ...props
-}: PhoneFieldProps<T>) {
-  return (
-    <TextField<T>
-      label={label}
-      hint={hint}
-      type="tel"
-      maxLength={PHONE_MAX_LENGTH}
-      placeholder="(11) 91234-5678"
-      autoComplete="off"
-      {...props}
-    />
-  );
-}
-
-export function EmailField<T extends FieldValues>({
-  label = 'E-mail',
-  hint = 'opcional',
-  ...props
-}: EmailFieldProps<T>) {
-  return (
-    <TextField<T>
-      label={label}
-      hint={hint}
-      type="email"
-      maxLength={EMAIL_MAX_LENGTH}
-      placeholder="nome@exemplo.com"
-      autoComplete="off"
-      {...props}
-    />
-  );
-}
-
-export function BirthDateField<T extends FieldValues>({
-  name,
-  label = 'Data de nascimento',
-  hint,
-  ...props
-}: BirthDateFieldProps<T>) {
-  const { control } = useFormContext<T>();
-  const typed: unknown = useWatch({ control, name });
-  const age = ageFromBirthDate(typeof typed === 'string' ? typed : '');
-  const { min, max } = birthDatePickerBounds();
-
-  return (
-    <DateField<T>
-      name={name}
-      label={label}
-      hint={hint ?? (age === null ? 'opcional' : formatAge(age))}
-      minDate={min}
-      maxDate={max}
-      autoComplete="off"
-      {...props}
-    />
-  );
-}
diff --git a/apps/admin-frontend/src/shared/form/fields/index.tsx b/apps/admin-frontend/src/shared/form/fields/index.tsx
index fb4f0d4f..22de6f47 100644
--- a/apps/admin-frontend/src/shared/form/fields/index.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/index.tsx
@@ -1,7 +1,10 @@
 export { TextField, TextareaField } from './components/text-fields';
 export { MaskedField } from './components/masked-field';
 export { DateField } from './components/date-field';
-export { BirthDateField, CpfField, EmailField, PhoneField } from './components/value-fields';
+export { CpfField } from './components/cpf-field';
+export { PhoneField } from './components/phone-field';
+export { EmailField } from './components/email-field';
+export { BirthDateField } from './components/birth-date-field';
 export { ControlledField } from './components/controlled-field';
 export { ColorField } from './components/color-field';
 export { FormErrorBanner } from './components/form-error-banner';

From 4ed6ad8acfaac78c21457b6cfebbd60bb2ec1bbf Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 16:05:35 -0300
Subject: [PATCH 25/30] Centralize form limits in model layer

Moves entity length and boundary constants out of page-level form files and into the feature model, so tag and client rules are shared consistently across schema, UI, and tests. This also replaces duplicated minor/guardian checks with a shared needsGuardian helper, removes the stale birth-date helper, and updates imports and tests to match the new ownership boundaries.
---
 .claude/skills/agenza-form-field/SKILL.md     | 17 +++++--
 apps/admin-frontend/docs/ARCHITECTURE.md      |  3 +-
 .../src/features/clients/model/client.test.ts | 35 +++++++++++++
 .../src/features/clients/model/client.ts      | 16 ++++++
 .../features/clients/model/clientContact.ts   |  3 ++
 .../ui/pages/ClientFormPage/clientForm.ts     | 49 +++++++++----------
 .../components/ClientGuardianItem.tsx         |  8 +--
 .../components/ClientGuardiansSection.tsx     |  9 ++--
 .../components/ClientPersonSection.tsx        |  9 ++--
 .../components/ClientReferenceContactItem.tsx | 10 ++--
 .../ClientReferenceContactsSection.tsx        |  7 +--
 .../src/features/tags/model/tag.ts            |  3 ++
 .../ui/pages/TagFormPage/TagFormPage.test.tsx |  3 +-
 .../TagFormPage/components/TagFormBody.tsx    |  7 +--
 .../tags/ui/pages/TagFormPage/tagForm.test.ts | 10 +---
 .../tags/ui/pages/TagFormPage/tagForm.ts      |  9 +---
 .../src/shared/form/schemas/birthDate.test.ts | 15 +-----
 .../src/shared/form/schemas/birthDate.ts      | 14 +-----
 .../src/shared/form/schemas/index.ts          |  2 +-
 19 files changed, 124 insertions(+), 105 deletions(-)
 create mode 100644 apps/admin-frontend/src/features/clients/model/client.test.ts
 create mode 100644 apps/admin-frontend/src/features/clients/model/clientContact.ts

diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index d61e7922..4013dbff 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -36,9 +36,18 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
 
 ## Wiring a new entity's form
 
-1. **Schema** in that entity's `model/<entity>Form.ts`, mirroring `tagForm.ts`:
+1. **Limits and invariants** in the slice's `model/<entity>.ts`, beside the entity's types, mirroring
+   the backend aggregate: plain constants (`TAG_NAME_MAX_LENGTH`, `MAX_GUARDIANS`) and pure functions
+   over the plain types (`needsGuardian(birthDate, guardianCount, today)`). No Zod, no pt-BR copy, no
+   class. Anything outside the form that needs the rule (a list badge, another page) imports it from
+   there, and so does the form's own UI when it shows the rule before submit.
+
+   **Schema** in the page that owns the form, `ui/pages/<X>FormPage/<x>Form.ts`, mirroring
+   `tagForm.ts`, built from those limits and composing those invariants:
    ```ts
-   export const xFormSchema = z.object({ /* z.string().trim().min(1, '…') etc */ });
+   export const xFormSchema = z.object({
+     name: z.string().trim().min(1, '…').max(X_NAME_MAX_LENGTH, `… ${X_NAME_MAX_LENGTH} …`),
+   });
    export type XFormFieldValues = z.input<typeof xFormSchema>;
    export type XFormValues = z.output<typeof xFormSchema>;
    export const X_FORM_FIELDS = xFormSchema.keyof().options;
@@ -49,8 +58,8 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    ```
    **Use `z.input`/`z.output`, never a single `z.infer`, the moment the schema has a `.refine()` or
    `.transform()`.** See Gotcha 1 below — this is not optional once either is present.
-   `keyof().options` is already typed as the key union, so the model needs no `as` cast and no
-   `react-hook-form` import — `model/` stays library-free. `toXFormFieldValues` is the inverse of the
+   `keyof().options` is already typed as the key union, so the schema file needs no `as` cast and no
+   `react-hook-form` import. `toXFormFieldValues` is the inverse of the
    schema's `.transform()`s (a `null` description back to `''`) and sits beside them: `useForm`'s
    `defaultValues` is `toXFormFieldValues()`, the edit fetch's `reset` is `toXFormFieldValues(entity)`.
 
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index b608f019..952252a9 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -410,9 +410,10 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `DateField` — the birth date field gets a calendar popover on top of the typed mask; `react-day-picker` added (it brings `date-fns` along, which the app never imports itself), plus `shared/ui/popover` and `shared/ui/calendar` | Asked for: type `dd/mm/aaaa` **and** pick on a calendar. `DateField` (`shared/form/fields`) is the `InputGroup` shape from shadcn's date-picker "Input" example, with the mask and ISO parsing of `shared/format/date.ts` instead of its English `new Date(text)`; the form value stays the masked string and the schema turns it into a `Date`. The calendar is shadcn's `Calendar` (`react-day-picker`, `ptBR` locale with its pt-BR aria labels) over Base UI's `Popover`, trimmed to single-date mode, with the month/year dropdowns a birth date needs. It lives behind the field's `minDate`/`maxDate` (`Date`s): `BirthDateField` passes the bounds of `birthDatePickerBounds()`, so today and the future are disabled in the calendar the same way the schema rejects them. The library speaks `Date` and so does the model, so nothing converts at the edge (see the dates-are-`Date` row below). `maskBirthDate`/`parseBirthDate` moved to `shared/format/date.ts` as `maskDate`/`parseMaskedDate`. The `Popover` is rendered as a sibling of `InputGroupAddon`, not inside it: React events bubble through the portal, and the addon's click-to-focus-the-input handler would otherwise steal focus from the month/year `<select>`s. The date is optional, so the field can be cleared two ways besides erasing the text: an X inside the input (`aria-label="Limpar data"`, only while there is a value and the field is not disabled or read-only; it hands the cursor back to the input with RHF's `setFocus`) and a `Limpar` button in the calendar's footer (disabled while empty; it closes the calendar). Neither name contains the field label, because the e2e finds the field by label substring. The calendar stays `required`, so clicking the selected day again does nothing. |
 | Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `shared/format/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) and the calendar's picker bounds on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; validating a birth date (parse the mask, reject the future, reject over 120) is not date arithmetic, so `ageFromBirthDate` sits with the birth-date schema in `shared/form/schemas/birthDate.ts`. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
 | `cpf.ts`, `birthDate.ts` and `contactFormats.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: none of them is specific to a client. A CPF identifies any person (the guardian's already uses it), a birth date is a person attribute any future module can carry, phone and e-mail are contact data any module can hold, and the backend already treats all of them as shared kernel (`CpfNumber`, `BirthDate`, `PhoneNumber` and `EmailAddress` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` was split into `phone.ts` and `email.ts` right after, one per backend value object (next row). |
-| A value more than one form can carry (CPF, phone, e-mail, birth date) is reused through three layers: `shared/format/` parses it, `shared/form/schemas/` turns that into a Zod field, `shared/form/fields/` renders it | Asked for: using a CPF meant assembling two unrelated halves by hand, a Zod fragment written in the slice's `clientForm.ts` (trim, refine, strip, empty to `null`, the pt-BR message) and a `MaskedField` repeating `mask`, `inputMode`, `placeholder` and `autoComplete`; the phone input, repeated three times, had its placeholder in only one of them. (1) `parseCpf`, `parsePhone` and `parseEmail` return the canonical value or `null`, mirroring the backend's `Create` (trim, strip, lowercase and validate in one step), so a caller cannot validate without normalising; the old `isValidX` plus `stripX` left the trim to the caller, which differed from the backend. `maskCpf` is the typing-time mask, named after `maskDate`. (2) `cpfSchema`, `phoneSchema`, `emailSchema` and `birthDateSchema` are built with `optionalValue(parse)`, which owns the empty-field-is-`null` rule and turns `fail(message)` into a Zod issue, so a new value type (a CNPJ) is one `parse` function and one line; `shared/` imports Zod for the first time there. The e-mail schema checks the length itself, before `parseEmail`, to keep the backend's two distinct messages without reporting the same address twice. (3) `CpfField`, `PhoneField`, `EmailField` and `BirthDateField` pin the mask, input type, limit, placeholder, label and `opcional` hint and let the call site override any of them; `BirthDateField` also owns the calendar bounds and the age hint. A call site is `<CpfField name="cpf" />`. The layers stay apart because `model/` has no React: a schema can be imported from a model file, a field only from `ui/`. `isMinorBirthDate` replaced the guardians section's own `age < 18` comparison, so the minor rule exists once (`isMinorOn`); `formatAge` moved to `shared/format/age.ts`. These presets are the exception to "fields have no domain knowledge": they know a value's format, never an entity. Not built: a required variant of the schemas, since nothing needs one yet; `optionalValue` is where it would go. |
+| A value more than one form can carry (CPF, phone, e-mail, birth date) is reused through three layers: `shared/format/` parses it, `shared/form/schemas/` turns that into a Zod field, `shared/form/fields/` renders it | Asked for: using a CPF meant assembling two unrelated halves by hand, a Zod fragment written in the slice's `clientForm.ts` (trim, refine, strip, empty to `null`, the pt-BR message) and a `MaskedField` repeating `mask`, `inputMode`, `placeholder` and `autoComplete`; the phone input, repeated three times, had its placeholder in only one of them. (1) `parseCpf`, `parsePhone` and `parseEmail` return the canonical value or `null`, mirroring the backend's `Create` (trim, strip, lowercase and validate in one step), so a caller cannot validate without normalising; the old `isValidX` plus `stripX` left the trim to the caller, which differed from the backend. `maskCpf` is the typing-time mask, named after `maskDate`. (2) `cpfSchema`, `phoneSchema`, `emailSchema` and `birthDateSchema` are built with `optionalValue(parse)`, which owns the empty-field-is-`null` rule and turns `fail(message)` into a Zod issue, so a new value type (a CNPJ) is one `parse` function and one line; `shared/` imports Zod for the first time there. The e-mail schema checks the length itself, before `parseEmail`, to keep the backend's two distinct messages without reporting the same address twice. (3) `CpfField`, `PhoneField`, `EmailField` and `BirthDateField` pin the mask, input type, limit, placeholder, label and `opcional` hint and let the call site override any of them; `BirthDateField` also owns the calendar bounds and the age hint. A call site is `<CpfField name="cpf" />`. The layers stay apart because `model/` has no React: a schema can be imported from a model file, a field only from `ui/`. The guardians section's own `age < 18` comparison was replaced, so the minor rule exists once (`isMinorOn`), and the "a minor needs a guardian" rule built on it lives in the slice's model (`needsGuardian`, two rows below); `formatAge` moved to `shared/format/age.ts`. These presets are the exception to "fields have no domain knowledge": they know a value's format, never an entity. Not built: a required variant of the schemas, since nothing needs one yet; `optionalValue` is where it would go. |
 | Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
+| An aggregate's limits and invariants live in the slice's `model/`, beside its types; the Zod schema, its pt-BR messages and the empty form values live in the page that owns the form (`ui/pages/<Page>/<entity>Form.ts`) | Asked for, in review of #174. Both form schemas had already moved from `model/<entity>Form.ts` into their pages (`tagForm.ts`, `clientForm.ts`), but the numbers and rules went with them: the limits mirrored from `Client`/`ClientContact` and the "a minor needs a guardian" invariant sat in `ClientFormPage/clientForm.ts`, and the invariant was written twice with two APIs, the schema's `refine` (`isMinorOn` over a `Date`) and the guardians section's notice (`isMinorBirthDate` over the masked text, a non-schema export of `shared/form/schemas`). The next readers of the rule (the list in #155, a detail page, editing in #156) would have imported from inside a page or copied it. Now `features/clients/model/client.ts` holds `CLIENT_FULL_NAME_MIN_LENGTH`/`_MAX_LENGTH`, `CLIENT_NOTES_MAX_LENGTH`, `MAX_GUARDIANS`, `MAX_REFERENCE_CONTACTS` and `needsGuardian(birthDate, guardianCount, today = todayUtc())`, the same check as the backend's `Client` (`birthDate.IsMinorOn(today) && guardianCount == 0`), and `model/clientContact.ts` holds the contact's name and relationship limits, which only happen to equal the person's today (`ClientContact` and `FullName` are separate in the backend). The schema composes `needsGuardian`; the section calls it on `parseMaskedDate(birthDate)`, which gives the same answer the schema-based check gave, since `isMinorOn` already requires a past date and an age under 18; `isMinorBirthDate` was deleted. `model/` stays free of React, Zod and copy: numbers and pure functions over the plain types, not entity classes, which every repository would have to hydrate. The limits are a UX pre-check; the backend's response stays the source of truth. Tags got the same move (`TAG_NAME_MAX_LENGTH`, `TAG_DESCRIPTION_MAX_LENGTH` in `model/tag.ts`). `FullName` and `AdministrativeNotes` are shared kernel in the backend; their limits stay in the clients model until a second slice needs them, then move to `shared/` as the CPF did. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/src/features/clients/model/client.test.ts b/apps/admin-frontend/src/features/clients/model/client.test.ts
new file mode 100644
index 00000000..c613fedf
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/client.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from 'vitest';
+import { utcDate } from '@/shared/format/date';
+import { needsGuardian } from './client';
+
+const TODAY = utcDate(2026, 10, 2);
+
+describe('needsGuardian', () => {
+  it('asks for a guardian for a minor without one', () => {
+    expect(needsGuardian(utcDate(2015, 3, 10), 0, TODAY)).toBe(true);
+    expect(needsGuardian(utcDate(2008, 10, 3), 0, TODAY)).toBe(true);
+  });
+
+  it('is satisfied once a minor has a guardian', () => {
+    expect(needsGuardian(utcDate(2015, 3, 10), 1, TODAY)).toBe(false);
+  });
+
+  it.each([
+    ['no birth date', null],
+    ['an adult', utcDate(1990, 5, 20)],
+    ['someone turning 18 today', utcDate(2008, 10, 2)],
+    ['a birth date today', utcDate(2026, 10, 2)],
+    ['a birth date in the future', utcDate(2027, 1, 1)],
+  ] as const)('does not ask for a guardian for %s', (_, birthDate) => {
+    expect(needsGuardian(birthDate, 0, TODAY)).toBe(false);
+  });
+
+  it('reads today from the clock when none is given', () => {
+    vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
+
+    expect(needsGuardian(utcDate(2008, 10, 3), 0)).toBe(true);
+    expect(needsGuardian(utcDate(2008, 10, 2), 0)).toBe(false);
+
+    vi.useRealTimers();
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/model/client.ts b/apps/admin-frontend/src/features/clients/model/client.ts
index 5e3eb1c1..421fa4ea 100644
--- a/apps/admin-frontend/src/features/clients/model/client.ts
+++ b/apps/admin-frontend/src/features/clients/model/client.ts
@@ -1,6 +1,14 @@
+import { isMinorOn } from '@/shared/format/birthDate';
+import { todayUtc } from '@/shared/format/date';
 import type { ClientGuardian } from './clientGuardian';
 import type { ClientReferenceContact } from './clientReferenceContact';
 
+export const CLIENT_FULL_NAME_MIN_LENGTH = 2;
+export const CLIENT_FULL_NAME_MAX_LENGTH = 150;
+export const CLIENT_NOTES_MAX_LENGTH = 500;
+export const MAX_GUARDIANS = 10;
+export const MAX_REFERENCE_CONTACTS = 10;
+
 export interface Client {
   id: string;
   fullName: string;
@@ -24,3 +32,11 @@ export interface ClientInput {
   guardians: Omit<ClientGuardian, 'id'>[];
   referenceContacts: Omit<ClientReferenceContact, 'id'>[];
 }
+
+export function needsGuardian(
+  birthDate: Date | null,
+  guardianCount: number,
+  today: Date = todayUtc(),
+): boolean {
+  return birthDate !== null && isMinorOn(birthDate, today) && guardianCount === 0;
+}
diff --git a/apps/admin-frontend/src/features/clients/model/clientContact.ts b/apps/admin-frontend/src/features/clients/model/clientContact.ts
new file mode 100644
index 00000000..ec114dd4
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/model/clientContact.ts
@@ -0,0 +1,3 @@
+export const CONTACT_NAME_MIN_LENGTH = 2;
+export const CONTACT_NAME_MAX_LENGTH = 150;
+export const CONTACT_RELATIONSHIP_MAX_LENGTH = 60;
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
index 69f20411..57dcdcf6 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
@@ -1,31 +1,31 @@
 import { z } from 'zod';
-import { ADULT_AGE_IN_YEARS, isMinorOn } from '@/shared/format/birthDate';
-import { todayUtc } from '@/shared/format/date';
+import { ADULT_AGE_IN_YEARS } from '@/shared/format/birthDate';
 import { birthDateSchema, cpfSchema, emailSchema, phoneSchema } from '@/shared/form/schemas';
+import {
+  CLIENT_FULL_NAME_MAX_LENGTH,
+  CLIENT_FULL_NAME_MIN_LENGTH,
+  CLIENT_NOTES_MAX_LENGTH,
+  MAX_GUARDIANS,
+  MAX_REFERENCE_CONTACTS,
+  needsGuardian,
+} from '../../../model/client';
+import {
+  CONTACT_NAME_MAX_LENGTH,
+  CONTACT_NAME_MIN_LENGTH,
+  CONTACT_RELATIONSHIP_MAX_LENGTH,
+} from '../../../model/clientContact';
 import { CONTACT_PURPOSES } from '../../../model/contactPurpose';
 
-// Mirrors the backend limits (ServicesService.Domain.Entities.Client / ClientContact). UX pre-check
-// only - the backend response stays the source of truth.
-export const CLIENT_NAME_MIN_LENGTH = 2;
-export const CLIENT_NAME_MAX_LENGTH = 150;
-export const CLIENT_NOTES_MAX_LENGTH = 500;
-export const CONTACT_RELATIONSHIP_MAX_LENGTH = 60;
-export const MAX_GUARDIANS = 10;
-export const MAX_REFERENCE_CONTACTS = 10;
-
-const nameField = (subject: string) =>
+const nameField = (subject: string, minLength: number, maxLength: number) =>
   z
     .string()
     .trim()
     .min(1, `O nome ${subject} é obrigatório.`)
-    .min(
-      CLIENT_NAME_MIN_LENGTH,
-      `O nome ${subject} deve ter pelo menos ${CLIENT_NAME_MIN_LENGTH} caracteres.`,
-    )
-    .max(
-      CLIENT_NAME_MAX_LENGTH,
-      `O nome ${subject} deve ter no máximo ${CLIENT_NAME_MAX_LENGTH} caracteres.`,
-    );
+    .min(minLength, `O nome ${subject} deve ter pelo menos ${minLength} caracteres.`)
+    .max(maxLength, `O nome ${subject} deve ter no máximo ${maxLength} caracteres.`);
+
+const contactNameField = (subject: string) =>
+  nameField(subject, CONTACT_NAME_MIN_LENGTH, CONTACT_NAME_MAX_LENGTH);
 
 const relationshipField = (subject: string) =>
   z
@@ -38,14 +38,14 @@ const relationshipField = (subject: string) =>
     );
 
 const guardianSchema = z.object({
-  name: nameField('do responsável'),
+  name: contactNameField('do responsável'),
   relationship: relationshipField('do responsável'),
   phone: phoneSchema,
   cpf: cpfSchema,
 });
 
 const referenceContactSchema = z.object({
-  name: nameField('da pessoa de referência'),
+  name: contactNameField('da pessoa de referência'),
   relationship: relationshipField('da pessoa de referência'),
   phone: phoneSchema,
   purposes: z
@@ -54,7 +54,7 @@ const referenceContactSchema = z.object({
 });
 
 const clientFormObject = z.object({
-  fullName: nameField('completo'),
+  fullName: nameField('completo', CLIENT_FULL_NAME_MIN_LENGTH, CLIENT_FULL_NAME_MAX_LENGTH),
   birthDate: birthDateSchema,
   phone: phoneSchema,
   email: emailSchema,
@@ -79,8 +79,7 @@ const clientFormObject = z.object({
 });
 
 export const clientFormSchema = clientFormObject.refine(
-  (value) =>
-    !value.birthDate || !isMinorOn(value.birthDate, todayUtc()) || value.guardians.length > 0,
+  (value) => !needsGuardian(value.birthDate, value.guardians.length),
   {
     path: ['guardians'],
     message: `Informe ao menos um responsável para pessoas menores de ${ADULT_AGE_IN_YEARS} anos.`,
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
index 4ebeb95a..ef562d87 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardianItem.tsx
@@ -3,10 +3,10 @@ import { XIcon } from 'lucide-react';
 import { CpfField, PhoneField, TextField } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import {
-  CLIENT_NAME_MAX_LENGTH,
+  CONTACT_NAME_MAX_LENGTH,
   CONTACT_RELATIONSHIP_MAX_LENGTH,
-  type ClientFormFieldValues,
-} from '../clientForm';
+} from '../../../../model/clientContact';
+import type { ClientFormFieldValues } from '../clientForm';
 
 interface ClientGuardianItemProps {
   index: number;
@@ -40,7 +40,7 @@ function ClientGuardianItem({ index, onRemove }: ClientGuardianItemProps) {
           name={`guardians.${index}.name`}
           label="Nome"
           hint="obrigatório"
-          maxLength={CLIENT_NAME_MAX_LENGTH}
+          maxLength={CONTACT_NAME_MAX_LENGTH}
           autoComplete="off"
         />
         <TextField<ClientFormFieldValues>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index 1a1b3b53..aca2b03e 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -4,8 +4,9 @@ import { FieldError } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
 import { ADULT_AGE_IN_YEARS } from '@/shared/format/birthDate';
-import { isMinorBirthDate } from '@/shared/form/schemas';
-import { MAX_GUARDIANS, emptyGuardian, type ClientFormFieldValues } from '../clientForm';
+import { parseMaskedDate } from '@/shared/format/date';
+import { MAX_GUARDIANS, needsGuardian } from '../../../../model/client';
+import { emptyGuardian, type ClientFormFieldValues } from '../clientForm';
 import { ClientGuardianItem } from './ClientGuardianItem';
 
 function ClientGuardiansSection() {
@@ -16,7 +17,7 @@ function ClientGuardiansSection() {
   const hasGuardians = fields.length > 0;
   const hasReachedGuardianLimit = fields.length >= MAX_GUARDIANS;
 
-  const needsGuardian = isMinorBirthDate(birthDate) && !hasGuardians;
+  const showGuardianNotice = needsGuardian(parseMaskedDate(birthDate), fields.length);
 
   return (
     <PageSection
@@ -35,7 +36,7 @@ function ClientGuardiansSection() {
         </Button>
       }
     >
-      {needsGuardian && (
+      {showGuardianNotice && (
         <p role="status" className="rounded-md border border-border bg-muted p-3 text-sm">
           Esta pessoa tem menos de {ADULT_AGE_IN_YEARS} anos. Informe ao menos um responsável.
         </p>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
index 4784a3d1..cda229f4 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientPersonSection.tsx
@@ -7,11 +7,8 @@ import {
   TextareaField,
 } from '@/shared/form/fields';
 import { PageSection } from '@/widgets/page-section';
-import {
-  CLIENT_NAME_MAX_LENGTH,
-  CLIENT_NOTES_MAX_LENGTH,
-  type ClientFormFieldValues,
-} from '../clientForm';
+import { CLIENT_FULL_NAME_MAX_LENGTH, CLIENT_NOTES_MAX_LENGTH } from '../../../../model/client';
+import type { ClientFormFieldValues } from '../clientForm';
 
 function ClientPersonSection() {
   return (
@@ -22,7 +19,7 @@ function ClientPersonSection() {
             name="fullName"
             label="Nome completo"
             hint="obrigatório"
-            maxLength={CLIENT_NAME_MAX_LENGTH}
+            maxLength={CLIENT_FULL_NAME_MAX_LENGTH}
             autoComplete="off"
             autoFocus
           />
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index 2e3d14d4..9976eb13 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -3,12 +3,12 @@ import { XIcon } from 'lucide-react';
 import { ControlledField, PhoneField, TextField } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { CheckboxGroup } from '@/shared/ui/checkbox-group';
-import { CONTACT_PURPOSE_OPTIONS } from '../../../../model/contactPurpose';
 import {
-  CLIENT_NAME_MAX_LENGTH,
+  CONTACT_NAME_MAX_LENGTH,
   CONTACT_RELATIONSHIP_MAX_LENGTH,
-  type ClientFormFieldValues,
-} from '../clientForm';
+} from '../../../../model/clientContact';
+import { CONTACT_PURPOSE_OPTIONS } from '../../../../model/contactPurpose';
+import type { ClientFormFieldValues } from '../clientForm';
 
 interface ClientReferenceContactItemProps {
   index: number;
@@ -42,7 +42,7 @@ function ClientReferenceContactItem({ index, onRemove }: ClientReferenceContactI
           name={`referenceContacts.${index}.name`}
           label="Nome"
           hint="obrigatório"
-          maxLength={CLIENT_NAME_MAX_LENGTH}
+          maxLength={CONTACT_NAME_MAX_LENGTH}
           autoComplete="off"
         />
         <TextField<ClientFormFieldValues>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
index e62fe510..1fb556d1 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactsSection.tsx
@@ -3,11 +3,8 @@ import { useFieldArray, useFormContext } from 'react-hook-form';
 import { FieldError } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
-import {
-  MAX_REFERENCE_CONTACTS,
-  emptyReferenceContact,
-  type ClientFormFieldValues,
-} from '../clientForm';
+import { MAX_REFERENCE_CONTACTS } from '../../../../model/client';
+import { emptyReferenceContact, type ClientFormFieldValues } from '../clientForm';
 import { ClientReferenceContactItem } from './ClientReferenceContactItem';
 
 function ClientReferenceContactsSection() {
diff --git a/apps/admin-frontend/src/features/tags/model/tag.ts b/apps/admin-frontend/src/features/tags/model/tag.ts
index f186dabf..f5958226 100644
--- a/apps/admin-frontend/src/features/tags/model/tag.ts
+++ b/apps/admin-frontend/src/features/tags/model/tag.ts
@@ -1,3 +1,6 @@
+export const TAG_NAME_MAX_LENGTH = 40;
+export const TAG_DESCRIPTION_MAX_LENGTH = 200;
+
 export interface Tag {
   id: string;
   name: string;
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx
index 783d534d..56d1143b 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.test.tsx
@@ -12,8 +12,7 @@ import {
 } from 'react-router';
 import { TagListPage } from '../TagListPage/TagListPage';
 import { TagFormPage } from './TagFormPage';
-import type { Tag } from '../../../model/tag';
-import { TAG_DESCRIPTION_MAX_LENGTH, TAG_NAME_MAX_LENGTH } from './tagForm';
+import { TAG_DESCRIPTION_MAX_LENGTH, TAG_NAME_MAX_LENGTH, type Tag } from '../../../model/tag';
 
 const { mockList, mockGet, mockCreate, mockUpdate } = vi.hoisted(() => ({
   mockList: vi.fn(),
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
index 603f6852..a3d036f8 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/components/TagFormBody.tsx
@@ -1,10 +1,7 @@
 import { ColorField, FormErrorBanner, TextField, TextareaField } from '@/shared/form/fields';
+import { TAG_DESCRIPTION_MAX_LENGTH, TAG_NAME_MAX_LENGTH } from '../../../../model/tag';
 import { TAG_COLOR_PALETTE } from '../../../../model/tagColor';
-import {
-  TAG_DESCRIPTION_MAX_LENGTH,
-  TAG_NAME_MAX_LENGTH,
-  type TagFormFieldValues,
-} from '../tagForm';
+import type { TagFormFieldValues } from '../tagForm';
 
 function TagFormBody() {
   return (
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
index 0348feb8..14b37cbb 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
@@ -1,13 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
-import type { Tag } from '../../../model/tag';
-import {
-  TAG_DESCRIPTION_MAX_LENGTH,
-  TAG_FORM_FIELDS,
-  TAG_NAME_MAX_LENGTH,
-  tagFormSchema,
-  toTagFormFieldValues,
-} from './tagForm';
+import { TAG_DESCRIPTION_MAX_LENGTH, TAG_NAME_MAX_LENGTH, type Tag } from '../../../model/tag';
+import { TAG_FORM_FIELDS, tagFormSchema, toTagFormFieldValues } from './tagForm';
 
 function fieldError(input: unknown, field: 'name' | 'color' | 'description') {
   const result = tagFormSchema.safeParse(input);
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.ts
index 48a4b8a7..f69eef30 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.ts
@@ -1,12 +1,5 @@
 import { z } from 'zod';
-import type { Tag } from '../../../model/tag';
-
-// Mirrors backend length limits (ServicesService.Domain.Entities.Tag.NameMaxLength /
-// DescriptionMaxLength) so the maxLength attributes and messages below match what the backend
-// itself enforces. UX pre-check only, never the source of truth — the backend's response is
-// (spec FR-012); this only avoids a pointless round-trip for empty/too-long input.
-export const TAG_NAME_MAX_LENGTH = 40;
-export const TAG_DESCRIPTION_MAX_LENGTH = 200;
+import { TAG_DESCRIPTION_MAX_LENGTH, TAG_NAME_MAX_LENGTH, type Tag } from '../../../model/tag';
 
 export const tagFormSchema = z.object({
   name: z
diff --git a/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts b/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
index bbdb10ff..39659050 100644
--- a/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
+++ b/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { utcDate } from '@/shared/format/date';
-import { ageFromBirthDate, birthDateSchema, isMinorBirthDate } from './birthDate';
+import { ageFromBirthDate, birthDateSchema } from './birthDate';
 
 beforeEach(() => {
   vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
@@ -53,16 +53,3 @@ describe('ageFromBirthDate', () => {
     },
   );
 });
-
-describe('isMinorBirthDate', () => {
-  it.each(['03/10/2008', '10/03/2015', '01/10/2026'])('is true for %j', (birthDate) => {
-    expect(isMinorBirthDate(birthDate)).toBe(true);
-  });
-
-  it.each(['02/10/2008', '20/05/1990', '', '10/03', '02/10/2026', '01/01/2030', '02/10/1905'])(
-    'is false for %j',
-    (birthDate) => {
-      expect(isMinorBirthDate(birthDate)).toBe(false);
-    },
-  );
-});
diff --git a/apps/admin-frontend/src/shared/form/schemas/birthDate.ts b/apps/admin-frontend/src/shared/form/schemas/birthDate.ts
index 4ba8f98b..8989fcc0 100644
--- a/apps/admin-frontend/src/shared/form/schemas/birthDate.ts
+++ b/apps/admin-frontend/src/shared/form/schemas/birthDate.ts
@@ -1,9 +1,4 @@
-import {
-  MAX_AGE_IN_YEARS,
-  isInThePast,
-  isMinorOn,
-  isWithinMaxAge,
-} from '@/shared/format/birthDate';
+import { MAX_AGE_IN_YEARS, isInThePast, isWithinMaxAge } from '@/shared/format/birthDate';
 import { fullYearsBetween, parseMaskedDate, todayUtc } from '@/shared/format/date';
 import { optionalValue } from './optionalValue';
 
@@ -27,13 +22,6 @@ export function ageFromBirthDate(masked: string): number | null {
   return fullYearsBetween(birthDate, todayUtc());
 }
 
-export function isMinorBirthDate(masked: string): boolean {
-  const birthDate = parseBirthDate(masked);
-  if (birthDate === null) return false;
-
-  return isMinorOn(birthDate, todayUtc());
-}
-
 function parseBirthDate(masked: string): Date | null {
   const parsed = birthDateSchema.safeParse(masked);
   return parsed.success ? parsed.data : null;
diff --git a/apps/admin-frontend/src/shared/form/schemas/index.ts b/apps/admin-frontend/src/shared/form/schemas/index.ts
index 51351746..9a98855e 100644
--- a/apps/admin-frontend/src/shared/form/schemas/index.ts
+++ b/apps/admin-frontend/src/shared/form/schemas/index.ts
@@ -2,4 +2,4 @@ export { optionalValue } from './optionalValue';
 export { cpfSchema } from './cpf';
 export { phoneSchema } from './phone';
 export { emailSchema } from './email';
-export { birthDateSchema, ageFromBirthDate, isMinorBirthDate } from './birthDate';
+export { birthDateSchema, ageFromBirthDate } from './birthDate';

From e9c1cb16484528310bebe3f1d383d6b823d1d0dc Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 16:12:08 -0300
Subject: [PATCH 26/30] dfg

---
 .claude/skills/agenza-form-field/SKILL.md     | 16 ++--
 .claude/skills/agenza-ptbr-copy/SKILL.md      | 11 +--
 apps/admin-frontend/docs/ARCHITECTURE.md      | 14 ++--
 .../src/features/clients/model/client.ts      |  2 +-
 .../pages/ClientFormPage/ClientFormPage.tsx   |  4 +-
 .../ui/pages/ClientFormPage/clientForm.ts     |  6 +-
 .../components/ClientGuardiansSection.tsx     |  2 +-
 .../tags/ui/pages/TagFormPage/TagFormPage.tsx |  4 +-
 .../fields/components/birth-date-field.tsx    |  3 +-
 .../form/fields/components/cpf-field.tsx      |  2 +-
 .../form/fields/components/email-field.tsx    |  2 +-
 .../form/fields/components/phone-field.tsx    |  2 +-
 .../src/shared/form/schemas/birthDate.test.ts | 55 --------------
 .../src/shared/form/schemas/birthDate.ts      | 28 -------
 .../src/shared/form/schemas/cpf.test.ts       | 18 -----
 .../src/shared/form/schemas/cpf.ts            |  6 --
 .../src/shared/form/schemas/email.test.ts     | 29 --------
 .../src/shared/form/schemas/email.ts          | 10 ---
 .../src/shared/form/schemas/index.ts          |  5 --
 .../src/shared/form/schemas/phone.test.ts     | 20 -----
 .../src/shared/format/birthDate.ts            | 23 ------
 .../admin-frontend/src/shared/format/phone.ts |  9 ---
 .../{format => values}/birthDate.test.ts      | 73 ++++++++++++++++++-
 .../src/shared/values/birthDate.ts            | 46 ++++++++++++
 .../src/shared/{format => values}/cpf.test.ts | 18 ++++-
 .../src/shared/{format => values}/cpf.ts      |  6 ++
 .../shared/{format => values}/email.test.ts   | 28 ++++++-
 .../src/shared/{format => values}/email.ts    | 10 +++
 .../schemas => values}/optionalValue.test.ts  |  0
 .../{form/schemas => values}/optionalValue.ts |  0
 .../shared/{format => values}/phone.test.ts   | 20 ++++-
 .../shared/{form/schemas => values}/phone.ts  | 11 ++-
 .../components/dialog-form-footer.tsx         | 17 +++++
 .../components/form-submit-button.tsx         | 12 +++
 .../components/page-form-footer.tsx           | 23 ++++++
 .../widgets/form-footer/form-footer.test.tsx  | 23 +++---
 .../widgets/form-footer/form-footer.types.ts  | 12 +++
 .../src/widgets/form-footer/index.tsx         | 50 +------------
 38 files changed, 324 insertions(+), 296 deletions(-)
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/birthDate.ts
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/cpf.test.ts
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/cpf.ts
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/email.test.ts
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/email.ts
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/index.ts
 delete mode 100644 apps/admin-frontend/src/shared/form/schemas/phone.test.ts
 delete mode 100644 apps/admin-frontend/src/shared/format/birthDate.ts
 delete mode 100644 apps/admin-frontend/src/shared/format/phone.ts
 rename apps/admin-frontend/src/shared/{format => values}/birthDate.test.ts (51%)
 create mode 100644 apps/admin-frontend/src/shared/values/birthDate.ts
 rename apps/admin-frontend/src/shared/{format => values}/cpf.test.ts (69%)
 rename apps/admin-frontend/src/shared/{format => values}/cpf.ts (87%)
 rename apps/admin-frontend/src/shared/{format => values}/email.test.ts (53%)
 rename apps/admin-frontend/src/shared/{format => values}/email.ts (62%)
 rename apps/admin-frontend/src/shared/{form/schemas => values}/optionalValue.test.ts (100%)
 rename apps/admin-frontend/src/shared/{form/schemas => values}/optionalValue.ts (100%)
 rename apps/admin-frontend/src/shared/{format => values}/phone.test.ts (60%)
 rename apps/admin-frontend/src/shared/{form/schemas => values}/phone.ts (50%)
 create mode 100644 apps/admin-frontend/src/widgets/form-footer/components/dialog-form-footer.tsx
 create mode 100644 apps/admin-frontend/src/widgets/form-footer/components/form-submit-button.tsx
 create mode 100644 apps/admin-frontend/src/widgets/form-footer/components/page-form-footer.tsx
 create mode 100644 apps/admin-frontend/src/widgets/form-footer/form-footer.types.ts

diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index 4013dbff..1ca1baf2 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -133,8 +133,9 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    rule below.
 
 5. **A CPF, phone, e-mail or birth date is not configured by hand: reuse the pair.** The schema half
-   comes from `@/shared/form/schemas` (`cpfSchema`, `phoneSchema`, `emailSchema`, `birthDateSchema`:
-   an empty field becomes `null`, anything else is parsed and fails with the pt-BR message), the
+   comes from that value's file in `@/shared/values/` (`cpfSchema` from `@/shared/values/cpf`, then
+   `phoneSchema`, `emailSchema`, `birthDateSchema`: an empty field becomes `null`, anything else is
+   parsed and fails with the pt-BR message), the
    field half from `@/shared/form/fields` (`CpfField`, `PhoneField`, `EmailField`, `BirthDateField`:
    mask, input type, limit, placeholder, default label and `opcional` hint already set, each one
    overridable by prop):
@@ -145,11 +146,12 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    <CpfField<XFormFieldValues> name="cpf" />
    <PhoneField<XFormFieldValues> name="phone" label="Telefone do contato" />
    ```
-   The parsing underneath is `shared/format/` (`parseCpf`, `parsePhone`, `parseEmail`: canonical value
-   or `null`, mirroring the backend's `Create`), so never re-validate with a regex of your own. A new
-   value type is a `parseX` in `shared/format/`, a schema built with `optionalValue(parse)` (its
-   `fail(message)` becomes the Zod issue) and, only if several forms will configure it the same way, a
-   preset field. The schemas have no required variant yet; add it to `optionalValue` when the first
+   The parsing underneath sits in the same file as the schema (`parseCpf`, `parsePhone`, `parseEmail`:
+   canonical value or `null`, mirroring the backend's `Create`), so never re-validate with a regex of
+   your own. A new value type (a CNPJ) is one file, `shared/values/cnpj.ts`, mirroring the backend's
+   value object: its `parseX`, its limits and a schema built with `optionalValue(parse)` (its
+   `fail(message)` becomes the Zod issue); plus, only if several forms will configure it the same way,
+   a preset field in `shared/form/fields/`. The schemas have no required variant yet; add it to `optionalValue` when the first
    form needs one.
 
 ## Editing an existing entity: fetch fresh, don't trust what the list already had
diff --git a/.claude/skills/agenza-ptbr-copy/SKILL.md b/.claude/skills/agenza-ptbr-copy/SKILL.md
index aa57b04e..f2e17843 100644
--- a/.claude/skills/agenza-ptbr-copy/SKILL.md
+++ b/.claude/skills/agenza-ptbr-copy/SKILL.md
@@ -79,11 +79,12 @@ i18n layer to "prepare" for a language nobody asked for.
 The one exception: a **code → message map is data, not markup**. It belongs in the slice's `model/`,
 where it is pure and testable without React, next to the branch that consumes it.
 
-**Formatters live in `src/shared/format/`** — cross-cutting, no business rule, so `shared/` by the
-dependency direction in [`docs/ARCHITECTURE.md` §1](../../../apps/admin-frontend/docs/ARCHITECTURE.md).
-The folder does not exist yet; create it with the first screen that needs it, not before. Note that
-the coverage exclusion covers `src/shared/ui/**` only — `shared/format/**` is measured, and these are
-exactly the pure functions that make the gate easy.
+**Formatters live in `src/shared/format/`** (`date.ts`, `age.ts`) — cross-cutting, no business rule,
+so `shared/` by the dependency direction in
+[`docs/ARCHITECTURE.md` §1](../../../apps/admin-frontend/docs/ARCHITECTURE.md). A value with its own
+validation and limits (CPF, phone, e-mail, birth date) is not a formatter: its mask and parse live with
+its schema in `src/shared/values/<value>.ts`. Note that the coverage exclusion covers `src/shared/ui/**`
+only — both folders are measured, and these are exactly the pure functions that make the gate easy.
 
 ## What breaks
 
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 952252a9..90434a18 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -48,12 +48,14 @@ src/
     ├── pubsub/              Generic createTopic/useTopic — publish/subscribe with a payload, no
     │                        domain knowledge; a concrete topic (e.g. tagDeleted) lives in the
     │                        feature that owns it, never here
-    ├── format/              Pure parse/mask/format of values (date, cpf, phone, email, birthDate,
-    │                        age); each parseX returns the canonical value or null, like the
-    │                        backend's Create
+    ├── format/              Policy-free calendar and display helpers: date.ts (utcDate, todayUtc,
+    │                        dd/mm/aaaa mask/parse/format, fullYearsBetween) and age.ts
+    ├── values/              One file per shared value, mirroring the backend's
+    │                        SharedKernel.ValueObjects (cpf, phone, email, birthDate): its parseX
+    │                        (canonical value or null, like the backend's Create), limits, rules and
+    │                        Zod schema, built with optionalValue
     ├── form/                applyApiProblem — the one place ApiProblem meets React Hook Form's
-    │                        setError —, schemas/ (Zod fields built on format/: cpf, phone, email,
-    │                        birthDate) and fields/, the RHF-bound TextField/TextareaField/
+    │                        setError — and fields/, the RHF-bound TextField/TextareaField/
     │                        MaskedField/DateField/ControlledField/ColorField/FormErrorBanner plus
     │                        the value presets CpfField/PhoneField/EmailField/BirthDateField; no
     │                        entity knowledge (§5)
@@ -414,6 +416,8 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 | An aggregate's limits and invariants live in the slice's `model/`, beside its types; the Zod schema, its pt-BR messages and the empty form values live in the page that owns the form (`ui/pages/<Page>/<entity>Form.ts`) | Asked for, in review of #174. Both form schemas had already moved from `model/<entity>Form.ts` into their pages (`tagForm.ts`, `clientForm.ts`), but the numbers and rules went with them: the limits mirrored from `Client`/`ClientContact` and the "a minor needs a guardian" invariant sat in `ClientFormPage/clientForm.ts`, and the invariant was written twice with two APIs, the schema's `refine` (`isMinorOn` over a `Date`) and the guardians section's notice (`isMinorBirthDate` over the masked text, a non-schema export of `shared/form/schemas`). The next readers of the rule (the list in #155, a detail page, editing in #156) would have imported from inside a page or copied it. Now `features/clients/model/client.ts` holds `CLIENT_FULL_NAME_MIN_LENGTH`/`_MAX_LENGTH`, `CLIENT_NOTES_MAX_LENGTH`, `MAX_GUARDIANS`, `MAX_REFERENCE_CONTACTS` and `needsGuardian(birthDate, guardianCount, today = todayUtc())`, the same check as the backend's `Client` (`birthDate.IsMinorOn(today) && guardianCount == 0`), and `model/clientContact.ts` holds the contact's name and relationship limits, which only happen to equal the person's today (`ClientContact` and `FullName` are separate in the backend). The schema composes `needsGuardian`; the section calls it on `parseMaskedDate(birthDate)`, which gives the same answer the schema-based check gave, since `isMinorOn` already requires a past date and an age under 18; `isMinorBirthDate` was deleted. `model/` stays free of React, Zod and copy: numbers and pure functions over the plain types, not entity classes, which every repository would have to hydrate. The limits are a UX pre-check; the backend's response stays the source of truth. Tags got the same move (`TAG_NAME_MAX_LENGTH`, `TAG_DESCRIPTION_MAX_LENGTH` in `model/tag.ts`). `FullName` and `AdministrativeNotes` are shared kernel in the backend; their limits stay in the clients model until a second slice needs them, then move to `shared/` as the CPF did. |
+| `widgets/form-footer` exports `DialogFormFooter` and `PageFormFooter` instead of one `FormFooter` that switched on `cancelTo` | Asked for, in review of #174. Passing `cancelTo` or not chose between two different footers, `DialogClose` inside `DialogFooter` or a `Link` back that becomes a disabled button while saving, so `<FormFooter isSaving canSubmit />` in `TagFormPage` read as generic while it only works inside a `Dialog`, and a page that forgot `cancelTo` silently got a dialog footer. Each footer now names where it belongs and `PageFormFooter` requires `cancelTo`; the **Salvar**/**Salvando…** button both render is the folder's internal `FormSubmitButton`. One folder, because it is one concept with two placements. |
+| A value more than one form carries (CPF, phone, e-mail, birth date) is one file in `shared/values/`: its `parseX`, limits, rules and Zod schema together. `shared/format/` keeps only the policy-free `date.ts` and `age.ts`; `shared/form/schemas/` is gone | Asked for, in review of #174, collapsing the first two of the three layers above. Reading or changing a CPF meant `shared/format/cpf.ts`, `shared/form/schemas/cpf.ts` with its barrel, and `cpf-field.tsx`; `format/` also held policy (`ADULT_AGE_IN_YEARS`, `MAX_AGE_IN_YEARS`), not only formatting; and `schemas/birthDate.ts` exported `ageFromBirthDate`, which is not a schema and ran Zod on every render of `BirthDateField`. `shared/values/<value>.ts` mirrors the backend's `Admin.SharedKernel.ValueObjects` one file per value object (`CpfNumber` ↔ `cpf.ts`), so a new value type (a CNPJ) is one file plus, if several forms configure it the same way, a preset field. `ageFromBirthDate(masked, today = todayUtc())` composes `parseMaskedDate`, `isInThePast` and `isWithinMaxAge` itself. The preset fields stay in `shared/form/fields/`: keeping the React half apart lets `model/` import a value's rules (`features/clients/model/client.ts` imports `isMinorOn`) without pulling React in; it does pull Zod, which the three-layer row already accepted. No barrel, as `shared/format/` never had one: imports are `@/shared/values/cpf`. Tests are merged per value (`cpf.test.ts` covers `parseCpf`, `maskCpf` and `cpfSchema`). |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/src/features/clients/model/client.ts b/apps/admin-frontend/src/features/clients/model/client.ts
index 421fa4ea..deaff8cb 100644
--- a/apps/admin-frontend/src/features/clients/model/client.ts
+++ b/apps/admin-frontend/src/features/clients/model/client.ts
@@ -1,5 +1,5 @@
-import { isMinorOn } from '@/shared/format/birthDate';
 import { todayUtc } from '@/shared/format/date';
+import { isMinorOn } from '@/shared/values/birthDate';
 import type { ClientGuardian } from './clientGuardian';
 import type { ClientReferenceContact } from './clientReferenceContact';
 
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
index 3addd691..b6ff2506 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -1,6 +1,6 @@
 import { FormProvider } from 'react-hook-form';
 import { FormErrorBanner } from '@/shared/form/fields';
-import { FormFooter } from '@/widgets/form-footer';
+import { PageFormFooter } from '@/widgets/form-footer';
 import { PageHeader } from '@/widgets/page-header';
 import { ClientGuardiansSection } from './components/ClientGuardiansSection';
 import { ClientPersonSection } from './components/ClientPersonSection';
@@ -21,7 +21,7 @@ export function ClientFormPage() {
           <ClientGuardiansSection />
           <ClientReferenceContactsSection />
           <FormErrorBanner />
-          <FormFooter isSaving={isSaving} cancelTo="/pessoas" />
+          <PageFormFooter isSaving={isSaving} cancelTo="/pessoas" />
         </form>
       </FormProvider>
     </div>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
index 57dcdcf6..93e4efc6 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
@@ -1,6 +1,8 @@
 import { z } from 'zod';
-import { ADULT_AGE_IN_YEARS } from '@/shared/format/birthDate';
-import { birthDateSchema, cpfSchema, emailSchema, phoneSchema } from '@/shared/form/schemas';
+import { ADULT_AGE_IN_YEARS, birthDateSchema } from '@/shared/values/birthDate';
+import { cpfSchema } from '@/shared/values/cpf';
+import { emailSchema } from '@/shared/values/email';
+import { phoneSchema } from '@/shared/values/phone';
 import {
   CLIENT_FULL_NAME_MAX_LENGTH,
   CLIENT_FULL_NAME_MIN_LENGTH,
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
index aca2b03e..33270798 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientGuardiansSection.tsx
@@ -3,8 +3,8 @@ import { useFieldArray, useFormContext, useWatch } from 'react-hook-form';
 import { FieldError } from '@/shared/form/fields';
 import { Button } from '@/shared/ui/button';
 import { PageSection } from '@/widgets/page-section';
-import { ADULT_AGE_IN_YEARS } from '@/shared/format/birthDate';
 import { parseMaskedDate } from '@/shared/format/date';
+import { ADULT_AGE_IN_YEARS } from '@/shared/values/birthDate';
 import { MAX_GUARDIANS, needsGuardian } from '../../../../model/client';
 import { emptyGuardian, type ClientFormFieldValues } from '../clientForm';
 import { ClientGuardianItem } from './ClientGuardianItem';
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
index dc3ec547..65eb5012 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/TagFormPage.tsx
@@ -1,7 +1,7 @@
 import { FormProvider } from 'react-hook-form';
 import { Dialog, DialogContent } from '@/shared/ui/dialog';
 import { FormFieldsSkeleton } from '@/shared/ui/form-field';
-import { FormFooter } from '@/widgets/form-footer';
+import { DialogFormFooter } from '@/widgets/form-footer';
 import { TAG_FORM_FIELDS } from './tagForm';
 import { TagFormBody } from './components/TagFormBody';
 import { TagFormHeader } from './components/TagFormHeader';
@@ -23,7 +23,7 @@ export function TagFormPage() {
             ) : (
               <TagFormBody />
             )}
-            <FormFooter canSubmit={canSubmit} isSaving={isSaving} />
+            <DialogFormFooter canSubmit={canSubmit} isSaving={isSaving} />
           </form>
         </FormProvider>
       </DialogContent>
diff --git a/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx
index 9c262c52..49776076 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/birth-date-field.tsx
@@ -1,7 +1,6 @@
 import { useFormContext, useWatch, type FieldValues } from 'react-hook-form';
 import { formatAge } from '@/shared/format/age';
-import { birthDatePickerBounds } from '@/shared/format/birthDate';
-import { ageFromBirthDate } from '@/shared/form/schemas';
+import { ageFromBirthDate, birthDatePickerBounds } from '@/shared/values/birthDate';
 import type { BirthDateFieldProps } from '../fields.types';
 import { DateField } from './date-field';
 
diff --git a/apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx
index ad36df7e..db2716cc 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/cpf-field.tsx
@@ -1,5 +1,5 @@
 import type { FieldValues } from 'react-hook-form';
-import { maskCpf } from '@/shared/format/cpf';
+import { maskCpf } from '@/shared/values/cpf';
 import type { CpfFieldProps } from '../fields.types';
 import { MaskedField } from './masked-field';
 
diff --git a/apps/admin-frontend/src/shared/form/fields/components/email-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/email-field.tsx
index b479714a..bcdc157e 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/email-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/email-field.tsx
@@ -1,5 +1,5 @@
 import type { FieldValues } from 'react-hook-form';
-import { EMAIL_MAX_LENGTH } from '@/shared/format/email';
+import { EMAIL_MAX_LENGTH } from '@/shared/values/email';
 import type { EmailFieldProps } from '../fields.types';
 import { TextField } from './text-fields';
 
diff --git a/apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx
index 4006621e..48469b76 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/phone-field.tsx
@@ -1,5 +1,5 @@
 import type { FieldValues } from 'react-hook-form';
-import { PHONE_MAX_LENGTH } from '@/shared/format/phone';
+import { PHONE_MAX_LENGTH } from '@/shared/values/phone';
 import type { PhoneFieldProps } from '../fields.types';
 import { TextField } from './text-fields';
 
diff --git a/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts b/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
deleted file mode 100644
index 39659050..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/birthDate.test.ts
+++ /dev/null
@@ -1,55 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { utcDate } from '@/shared/format/date';
-import { ageFromBirthDate, birthDateSchema } from './birthDate';
-
-beforeEach(() => {
-  vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
-});
-
-afterEach(() => {
-  vi.useRealTimers();
-});
-
-function messagesOf(raw: string): string[] | undefined {
-  return birthDateSchema.safeParse(raw).error?.issues.map((issue) => issue.message);
-}
-
-describe('birthDateSchema', () => {
-  it('reads dd/mm/aaaa as a Date at midnight UTC', () => {
-    expect(birthDateSchema.parse('20/05/1990')).toEqual(utcDate(1990, 5, 20));
-  });
-
-  it.each(['', '  '])('treats %j as no birth date', (raw) => {
-    expect(birthDateSchema.parse(raw)).toBeNull();
-  });
-
-  it.each([
-    ['10/03', 'Informe uma data válida no formato dd/mm/aaaa.'],
-    ['31/02/2020', 'Informe uma data válida no formato dd/mm/aaaa.'],
-    ['02/10/2026', 'A data de nascimento deve estar no passado.'],
-    ['01/01/2030', 'A data de nascimento deve estar no passado.'],
-    ['02/10/1905', 'A data de nascimento não pode indicar idade superior a 120 anos.'],
-  ] as const)('explains %j in pt-BR', (raw, message) => {
-    expect(messagesOf(raw)).toEqual([message]);
-  });
-});
-
-describe('ageFromBirthDate', () => {
-  it.each([
-    ['10/03/2015', 11],
-    ['03/10/2008', 17],
-    ['02/10/2008', 18],
-    ['20/05/1990', 36],
-    ['01/10/2026', 0],
-    ['02/10/1906', 120],
-  ] as const)('reads %j as %i years old today', (birthDate, expected) => {
-    expect(ageFromBirthDate(birthDate)).toBe(expected);
-  });
-
-  it.each(['', '10/03', '31/02/2020', '02/10/2026', '01/01/2030', '02/10/1905'])(
-    'has no age for %j',
-    (birthDate) => {
-      expect(ageFromBirthDate(birthDate)).toBeNull();
-    },
-  );
-});
diff --git a/apps/admin-frontend/src/shared/form/schemas/birthDate.ts b/apps/admin-frontend/src/shared/form/schemas/birthDate.ts
deleted file mode 100644
index 8989fcc0..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/birthDate.ts
+++ /dev/null
@@ -1,28 +0,0 @@
-import { MAX_AGE_IN_YEARS, isInThePast, isWithinMaxAge } from '@/shared/format/birthDate';
-import { fullYearsBetween, parseMaskedDate, todayUtc } from '@/shared/format/date';
-import { optionalValue } from './optionalValue';
-
-export const birthDateSchema = optionalValue((raw, fail) => {
-  const birthDate = parseMaskedDate(raw);
-  if (birthDate === null) return fail('Informe uma data válida no formato dd/mm/aaaa.');
-
-  const today = todayUtc();
-  if (!isInThePast(birthDate, today)) return fail('A data de nascimento deve estar no passado.');
-  if (!isWithinMaxAge(birthDate, today)) {
-    return fail(`A data de nascimento não pode indicar idade superior a ${MAX_AGE_IN_YEARS} anos.`);
-  }
-
-  return birthDate;
-});
-
-export function ageFromBirthDate(masked: string): number | null {
-  const birthDate = parseBirthDate(masked);
-  if (birthDate === null) return null;
-
-  return fullYearsBetween(birthDate, todayUtc());
-}
-
-function parseBirthDate(masked: string): Date | null {
-  const parsed = birthDateSchema.safeParse(masked);
-  return parsed.success ? parsed.data : null;
-}
diff --git a/apps/admin-frontend/src/shared/form/schemas/cpf.test.ts b/apps/admin-frontend/src/shared/form/schemas/cpf.test.ts
deleted file mode 100644
index 94542944..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/cpf.test.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { cpfSchema } from './cpf';
-
-describe('cpfSchema', () => {
-  it('stores the digits only, whatever mask the person typed', () => {
-    expect(cpfSchema.parse('529.982.247-25')).toBe('52998224725');
-  });
-
-  it('treats an empty field as no CPF', () => {
-    expect(cpfSchema.parse('  ')).toBeNull();
-  });
-
-  it('explains an invalid CPF in pt-BR', () => {
-    const result = cpfSchema.safeParse('529.982.247-24');
-
-    expect(result.error?.issues.map((issue) => issue.message)).toEqual(['Informe um CPF válido.']);
-  });
-});
diff --git a/apps/admin-frontend/src/shared/form/schemas/cpf.ts b/apps/admin-frontend/src/shared/form/schemas/cpf.ts
deleted file mode 100644
index db93beca..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/cpf.ts
+++ /dev/null
@@ -1,6 +0,0 @@
-import { parseCpf } from '@/shared/format/cpf';
-import { optionalValue } from './optionalValue';
-
-export const cpfSchema = optionalValue(
-  (raw, fail) => parseCpf(raw) ?? fail('Informe um CPF válido.'),
-);
diff --git a/apps/admin-frontend/src/shared/form/schemas/email.test.ts b/apps/admin-frontend/src/shared/form/schemas/email.test.ts
deleted file mode 100644
index 3dff84ee..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/email.test.ts
+++ /dev/null
@@ -1,29 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { EMAIL_MAX_LENGTH } from '@/shared/format/email';
-import { emailSchema } from './email';
-
-function messagesOf(raw: string): string[] | undefined {
-  return emailSchema.safeParse(raw).error?.issues.map((issue) => issue.message);
-}
-
-describe('emailSchema', () => {
-  it('stores the e-mail trimmed and in lowercase', () => {
-    expect(emailSchema.parse(' Maria.Souza@Example.COM ')).toBe('maria.souza@example.com');
-  });
-
-  it('treats an empty field as no e-mail', () => {
-    expect(emailSchema.parse('')).toBeNull();
-  });
-
-  it('explains an invalid format in pt-BR', () => {
-    expect(messagesOf('maria@example')).toEqual(['Informe um e-mail válido.']);
-  });
-
-  it('reports a too-long e-mail once, as too long and not as invalid', () => {
-    const tooLong = `${'a'.repeat(EMAIL_MAX_LENGTH)}@example.com`;
-
-    expect(messagesOf(tooLong)).toEqual([
-      `O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`,
-    ]);
-  });
-});
diff --git a/apps/admin-frontend/src/shared/form/schemas/email.ts b/apps/admin-frontend/src/shared/form/schemas/email.ts
deleted file mode 100644
index 9ae2d444..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/email.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import { EMAIL_MAX_LENGTH, parseEmail } from '@/shared/format/email';
-import { optionalValue } from './optionalValue';
-
-export const emailSchema = optionalValue((raw, fail) => {
-  if (raw.trim().length > EMAIL_MAX_LENGTH) {
-    return fail(`O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`);
-  }
-
-  return parseEmail(raw) ?? fail('Informe um e-mail válido.');
-});
diff --git a/apps/admin-frontend/src/shared/form/schemas/index.ts b/apps/admin-frontend/src/shared/form/schemas/index.ts
deleted file mode 100644
index 9a98855e..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/index.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-export { optionalValue } from './optionalValue';
-export { cpfSchema } from './cpf';
-export { phoneSchema } from './phone';
-export { emailSchema } from './email';
-export { birthDateSchema, ageFromBirthDate } from './birthDate';
diff --git a/apps/admin-frontend/src/shared/form/schemas/phone.test.ts b/apps/admin-frontend/src/shared/form/schemas/phone.test.ts
deleted file mode 100644
index c3714b99..00000000
--- a/apps/admin-frontend/src/shared/form/schemas/phone.test.ts
+++ /dev/null
@@ -1,20 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { phoneSchema } from './phone';
-
-describe('phoneSchema', () => {
-  it('keeps the phone as typed, without the surrounding spaces', () => {
-    expect(phoneSchema.parse('  (11) 99999-0000 ')).toBe('(11) 99999-0000');
-  });
-
-  it('treats an empty field as no phone', () => {
-    expect(phoneSchema.parse('')).toBeNull();
-  });
-
-  it('explains the accepted shape in pt-BR', () => {
-    const result = phoneSchema.safeParse('telefone');
-
-    expect(result.error?.issues.map((issue) => issue.message)).toEqual([
-      'Informe um telefone válido, com até 20 caracteres entre dígitos, espaços, +, parênteses e hífen.',
-    ]);
-  });
-});
diff --git a/apps/admin-frontend/src/shared/format/birthDate.ts b/apps/admin-frontend/src/shared/format/birthDate.ts
deleted file mode 100644
index 8e696fe3..00000000
--- a/apps/admin-frontend/src/shared/format/birthDate.ts
+++ /dev/null
@@ -1,23 +0,0 @@
-import { fullYearsBetween, todayUtc, utcDate } from './date';
-
-export const ADULT_AGE_IN_YEARS = 18;
-export const MAX_AGE_IN_YEARS = 120;
-
-export function isInThePast(birthDate: Date, today: Date): boolean {
-  return birthDate < today;
-}
-
-export function isWithinMaxAge(birthDate: Date, today: Date): boolean {
-  return fullYearsBetween(birthDate, today) <= MAX_AGE_IN_YEARS;
-}
-
-export function isMinorOn(birthDate: Date, today: Date): boolean {
-  return isInThePast(birthDate, today) && fullYearsBetween(birthDate, today) < ADULT_AGE_IN_YEARS;
-}
-
-export function birthDatePickerBounds(today: Date = todayUtc()): { min: Date; max: Date } {
-  return {
-    min: utcDate(today.getUTCFullYear() - MAX_AGE_IN_YEARS - 1, 1, 1),
-    max: utcDate(today.getUTCFullYear(), today.getUTCMonth() + 1, today.getUTCDate() - 1),
-  };
-}
diff --git a/apps/admin-frontend/src/shared/format/phone.ts b/apps/admin-frontend/src/shared/format/phone.ts
deleted file mode 100644
index 64f60d9b..00000000
--- a/apps/admin-frontend/src/shared/format/phone.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-export const PHONE_MAX_LENGTH = 20;
-
-export function parsePhone(raw: string): string | null {
-  const phone = raw.trim();
-  const hasValidShape =
-    phone.length <= PHONE_MAX_LENGTH && /\d/.test(phone) && /^[\d +()-]+$/.test(phone);
-
-  return hasValidShape ? phone : null;
-}
diff --git a/apps/admin-frontend/src/shared/format/birthDate.test.ts b/apps/admin-frontend/src/shared/values/birthDate.test.ts
similarity index 51%
rename from apps/admin-frontend/src/shared/format/birthDate.test.ts
rename to apps/admin-frontend/src/shared/values/birthDate.test.ts
index c32303d6..1aac14b7 100644
--- a/apps/admin-frontend/src/shared/format/birthDate.test.ts
+++ b/apps/admin-frontend/src/shared/values/birthDate.test.ts
@@ -1,6 +1,13 @@
-import { describe, expect, it, vi } from 'vitest';
-import { birthDatePickerBounds, isInThePast, isMinorOn, isWithinMaxAge } from './birthDate';
-import { utcDate } from './date';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { utcDate } from '@/shared/format/date';
+import {
+  ageFromBirthDate,
+  birthDatePickerBounds,
+  birthDateSchema,
+  isInThePast,
+  isMinorOn,
+  isWithinMaxAge,
+} from './birthDate';
 
 const TODAY = utcDate(2026, 10, 2);
 
@@ -62,3 +69,63 @@ describe('birthDatePickerBounds', () => {
     vi.useRealTimers();
   });
 });
+
+describe('ageFromBirthDate', () => {
+  it.each([
+    ['10/03/2015', 11],
+    ['03/10/2008', 17],
+    ['02/10/2008', 18],
+    ['20/05/1990', 36],
+    ['01/10/2026', 0],
+    ['02/10/1906', 120],
+  ] as const)('reads %j as %i years old today', (birthDate, expected) => {
+    expect(ageFromBirthDate(birthDate, TODAY)).toBe(expected);
+  });
+
+  it.each(['', '10/03', '31/02/2020', '02/10/2026', '01/01/2030', '02/10/1905'])(
+    'has no age for %j',
+    (birthDate) => {
+      expect(ageFromBirthDate(birthDate, TODAY)).toBeNull();
+    },
+  );
+
+  it('reads today from the clock when none is given', () => {
+    vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
+
+    expect(ageFromBirthDate('03/10/2008')).toBe(17);
+
+    vi.useRealTimers();
+  });
+});
+
+describe('birthDateSchema', () => {
+  beforeEach(() => {
+    vi.useFakeTimers({ now: new Date('2026-10-02T12:00:00Z'), toFake: ['Date'] });
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  function messagesOf(raw: string): string[] | undefined {
+    return birthDateSchema.safeParse(raw).error?.issues.map((issue) => issue.message);
+  }
+
+  it('reads dd/mm/aaaa as a Date at midnight UTC', () => {
+    expect(birthDateSchema.parse('20/05/1990')).toEqual(utcDate(1990, 5, 20));
+  });
+
+  it.each(['', '  '])('treats %j as no birth date', (raw) => {
+    expect(birthDateSchema.parse(raw)).toBeNull();
+  });
+
+  it.each([
+    ['10/03', 'Informe uma data válida no formato dd/mm/aaaa.'],
+    ['31/02/2020', 'Informe uma data válida no formato dd/mm/aaaa.'],
+    ['02/10/2026', 'A data de nascimento deve estar no passado.'],
+    ['01/01/2030', 'A data de nascimento deve estar no passado.'],
+    ['02/10/1905', 'A data de nascimento não pode indicar idade superior a 120 anos.'],
+  ] as const)('explains %j in pt-BR', (raw, message) => {
+    expect(messagesOf(raw)).toEqual([message]);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/values/birthDate.ts b/apps/admin-frontend/src/shared/values/birthDate.ts
new file mode 100644
index 00000000..e15ad9db
--- /dev/null
+++ b/apps/admin-frontend/src/shared/values/birthDate.ts
@@ -0,0 +1,46 @@
+import { fullYearsBetween, parseMaskedDate, todayUtc, utcDate } from '@/shared/format/date';
+import { optionalValue } from './optionalValue';
+
+export const ADULT_AGE_IN_YEARS = 18;
+export const MAX_AGE_IN_YEARS = 120;
+
+export function isInThePast(birthDate: Date, today: Date): boolean {
+  return birthDate < today;
+}
+
+export function isWithinMaxAge(birthDate: Date, today: Date): boolean {
+  return fullYearsBetween(birthDate, today) <= MAX_AGE_IN_YEARS;
+}
+
+export function isMinorOn(birthDate: Date, today: Date): boolean {
+  return isInThePast(birthDate, today) && fullYearsBetween(birthDate, today) < ADULT_AGE_IN_YEARS;
+}
+
+export function ageFromBirthDate(masked: string, today: Date = todayUtc()): number | null {
+  const birthDate = parseMaskedDate(masked);
+  if (birthDate === null || !isInThePast(birthDate, today) || !isWithinMaxAge(birthDate, today)) {
+    return null;
+  }
+
+  return fullYearsBetween(birthDate, today);
+}
+
+export function birthDatePickerBounds(today: Date = todayUtc()): { min: Date; max: Date } {
+  return {
+    min: utcDate(today.getUTCFullYear() - MAX_AGE_IN_YEARS - 1, 1, 1),
+    max: utcDate(today.getUTCFullYear(), today.getUTCMonth() + 1, today.getUTCDate() - 1),
+  };
+}
+
+export const birthDateSchema = optionalValue((raw, fail) => {
+  const birthDate = parseMaskedDate(raw);
+  if (birthDate === null) return fail('Informe uma data válida no formato dd/mm/aaaa.');
+
+  const today = todayUtc();
+  if (!isInThePast(birthDate, today)) return fail('A data de nascimento deve estar no passado.');
+  if (!isWithinMaxAge(birthDate, today)) {
+    return fail(`A data de nascimento não pode indicar idade superior a ${MAX_AGE_IN_YEARS} anos.`);
+  }
+
+  return birthDate;
+});
diff --git a/apps/admin-frontend/src/shared/format/cpf.test.ts b/apps/admin-frontend/src/shared/values/cpf.test.ts
similarity index 69%
rename from apps/admin-frontend/src/shared/format/cpf.test.ts
rename to apps/admin-frontend/src/shared/values/cpf.test.ts
index d3d5e6ce..ba36de79 100644
--- a/apps/admin-frontend/src/shared/format/cpf.test.ts
+++ b/apps/admin-frontend/src/shared/values/cpf.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { maskCpf, parseCpf } from './cpf';
+import { cpfSchema, maskCpf, parseCpf } from './cpf';
 
 describe('parseCpf', () => {
   it.each([
@@ -49,3 +49,19 @@ describe('maskCpf', () => {
     expect(maskCpf(typed)).toBe(expected);
   });
 });
+
+describe('cpfSchema', () => {
+  it('stores the digits only, whatever mask the person typed', () => {
+    expect(cpfSchema.parse('529.982.247-25')).toBe('52998224725');
+  });
+
+  it('treats an empty field as no CPF', () => {
+    expect(cpfSchema.parse('  ')).toBeNull();
+  });
+
+  it('explains an invalid CPF in pt-BR', () => {
+    const result = cpfSchema.safeParse('529.982.247-24');
+
+    expect(result.error?.issues.map((issue) => issue.message)).toEqual(['Informe um CPF válido.']);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/format/cpf.ts b/apps/admin-frontend/src/shared/values/cpf.ts
similarity index 87%
rename from apps/admin-frontend/src/shared/format/cpf.ts
rename to apps/admin-frontend/src/shared/values/cpf.ts
index 5ba42a5d..3a595b17 100644
--- a/apps/admin-frontend/src/shared/format/cpf.ts
+++ b/apps/admin-frontend/src/shared/values/cpf.ts
@@ -1,3 +1,5 @@
+import { optionalValue } from './optionalValue';
+
 const CPF_LENGTH = 11;
 
 export function parseCpf(raw: string): string | null {
@@ -21,6 +23,10 @@ export function maskCpf(value: string): string {
   return `${digits.slice(0, 3)}.${digits.slice(3, 6)}.${digits.slice(6, 9)}-${digits.slice(9)}`;
 }
 
+export const cpfSchema = optionalValue(
+  (raw, fail) => parseCpf(raw) ?? fail('Informe um CPF válido.'),
+);
+
 function checkDigit(digits: string, digitCount: number): number {
   let sum = 0;
   for (let index = 0; index < digitCount; index += 1) {
diff --git a/apps/admin-frontend/src/shared/format/email.test.ts b/apps/admin-frontend/src/shared/values/email.test.ts
similarity index 53%
rename from apps/admin-frontend/src/shared/format/email.test.ts
rename to apps/admin-frontend/src/shared/values/email.test.ts
index 077e5f6d..b8e4b0bb 100644
--- a/apps/admin-frontend/src/shared/format/email.test.ts
+++ b/apps/admin-frontend/src/shared/values/email.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { EMAIL_MAX_LENGTH, parseEmail } from './email';
+import { EMAIL_MAX_LENGTH, emailSchema, parseEmail } from './email';
 
 describe('parseEmail', () => {
   it.each([
@@ -36,3 +36,29 @@ describe('parseEmail', () => {
     expect(parseEmail(email)).toBeNull();
   });
 });
+
+describe('emailSchema', () => {
+  function messagesOf(raw: string): string[] | undefined {
+    return emailSchema.safeParse(raw).error?.issues.map((issue) => issue.message);
+  }
+
+  it('stores the e-mail trimmed and in lowercase', () => {
+    expect(emailSchema.parse(' Maria.Souza@Example.COM ')).toBe('maria.souza@example.com');
+  });
+
+  it('treats an empty field as no e-mail', () => {
+    expect(emailSchema.parse('')).toBeNull();
+  });
+
+  it('explains an invalid format in pt-BR', () => {
+    expect(messagesOf('maria@example')).toEqual(['Informe um e-mail válido.']);
+  });
+
+  it('reports a too-long e-mail once, as too long and not as invalid', () => {
+    const tooLong = `${'a'.repeat(EMAIL_MAX_LENGTH)}@example.com`;
+
+    expect(messagesOf(tooLong)).toEqual([
+      `O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`,
+    ]);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/format/email.ts b/apps/admin-frontend/src/shared/values/email.ts
similarity index 62%
rename from apps/admin-frontend/src/shared/format/email.ts
rename to apps/admin-frontend/src/shared/values/email.ts
index c212f81b..7a59ae59 100644
--- a/apps/admin-frontend/src/shared/format/email.ts
+++ b/apps/admin-frontend/src/shared/values/email.ts
@@ -1,3 +1,5 @@
+import { optionalValue } from './optionalValue';
+
 export const EMAIL_MAX_LENGTH = 254;
 
 export function parseEmail(raw: string): string | null {
@@ -11,3 +13,11 @@ export function parseEmail(raw: string): string | null {
   const hasValidDomain = labels.length >= 2 && labels.every((label) => label.length > 0);
   return hasValidDomain ? email : null;
 }
+
+export const emailSchema = optionalValue((raw, fail) => {
+  if (raw.trim().length > EMAIL_MAX_LENGTH) {
+    return fail(`O e-mail deve ter no máximo ${EMAIL_MAX_LENGTH} caracteres.`);
+  }
+
+  return parseEmail(raw) ?? fail('Informe um e-mail válido.');
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/optionalValue.test.ts b/apps/admin-frontend/src/shared/values/optionalValue.test.ts
similarity index 100%
rename from apps/admin-frontend/src/shared/form/schemas/optionalValue.test.ts
rename to apps/admin-frontend/src/shared/values/optionalValue.test.ts
diff --git a/apps/admin-frontend/src/shared/form/schemas/optionalValue.ts b/apps/admin-frontend/src/shared/values/optionalValue.ts
similarity index 100%
rename from apps/admin-frontend/src/shared/form/schemas/optionalValue.ts
rename to apps/admin-frontend/src/shared/values/optionalValue.ts
diff --git a/apps/admin-frontend/src/shared/format/phone.test.ts b/apps/admin-frontend/src/shared/values/phone.test.ts
similarity index 60%
rename from apps/admin-frontend/src/shared/format/phone.test.ts
rename to apps/admin-frontend/src/shared/values/phone.test.ts
index e45996e3..9a5ebcec 100644
--- a/apps/admin-frontend/src/shared/format/phone.test.ts
+++ b/apps/admin-frontend/src/shared/values/phone.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { PHONE_MAX_LENGTH, parsePhone } from './phone';
+import { PHONE_MAX_LENGTH, parsePhone, phoneSchema } from './phone';
 
 describe('parsePhone', () => {
   it.each([
@@ -34,3 +34,21 @@ describe('parsePhone', () => {
     expect(parsePhone(phone)).toBeNull();
   });
 });
+
+describe('phoneSchema', () => {
+  it('keeps the phone as typed, without the surrounding spaces', () => {
+    expect(phoneSchema.parse('  (11) 99999-0000 ')).toBe('(11) 99999-0000');
+  });
+
+  it('treats an empty field as no phone', () => {
+    expect(phoneSchema.parse('')).toBeNull();
+  });
+
+  it('explains the accepted shape in pt-BR', () => {
+    const result = phoneSchema.safeParse('telefone');
+
+    expect(result.error?.issues.map((issue) => issue.message)).toEqual([
+      'Informe um telefone válido, com até 20 caracteres entre dígitos, espaços, +, parênteses e hífen.',
+    ]);
+  });
+});
diff --git a/apps/admin-frontend/src/shared/form/schemas/phone.ts b/apps/admin-frontend/src/shared/values/phone.ts
similarity index 50%
rename from apps/admin-frontend/src/shared/form/schemas/phone.ts
rename to apps/admin-frontend/src/shared/values/phone.ts
index def147db..a1a77882 100644
--- a/apps/admin-frontend/src/shared/form/schemas/phone.ts
+++ b/apps/admin-frontend/src/shared/values/phone.ts
@@ -1,6 +1,15 @@
-import { PHONE_MAX_LENGTH, parsePhone } from '@/shared/format/phone';
 import { optionalValue } from './optionalValue';
 
+export const PHONE_MAX_LENGTH = 20;
+
+export function parsePhone(raw: string): string | null {
+  const phone = raw.trim();
+  const hasValidShape =
+    phone.length <= PHONE_MAX_LENGTH && /\d/.test(phone) && /^[\d +()-]+$/.test(phone);
+
+  return hasValidShape ? phone : null;
+}
+
 export const phoneSchema = optionalValue(
   (raw, fail) =>
     parsePhone(raw) ??
diff --git a/apps/admin-frontend/src/widgets/form-footer/components/dialog-form-footer.tsx b/apps/admin-frontend/src/widgets/form-footer/components/dialog-form-footer.tsx
new file mode 100644
index 00000000..4ce2bb2d
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/form-footer/components/dialog-form-footer.tsx
@@ -0,0 +1,17 @@
+import { Button } from '@/shared/ui/button';
+import { DialogClose, DialogFooter } from '@/shared/ui/dialog';
+import type { DialogFormFooterProps } from '../form-footer.types';
+import { FormSubmitButton } from './form-submit-button';
+
+function DialogFormFooter({ isSaving, canSubmit = true }: DialogFormFooterProps) {
+  return (
+    <DialogFooter>
+      <DialogClose disabled={isSaving} render={<Button variant="outline" />}>
+        Cancelar
+      </DialogClose>
+      <FormSubmitButton isSaving={isSaving} canSubmit={canSubmit} />
+    </DialogFooter>
+  );
+}
+
+export { DialogFormFooter };
diff --git a/apps/admin-frontend/src/widgets/form-footer/components/form-submit-button.tsx b/apps/admin-frontend/src/widgets/form-footer/components/form-submit-button.tsx
new file mode 100644
index 00000000..b1e3546a
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/form-footer/components/form-submit-button.tsx
@@ -0,0 +1,12 @@
+import { ActionButton } from '@/shared/ui/action-button';
+import type { FormSubmitButtonProps } from '../form-footer.types';
+
+function FormSubmitButton({ isSaving, canSubmit }: FormSubmitButtonProps) {
+  return (
+    <ActionButton type="submit" disabled={!canSubmit} pending={isSaving}>
+      {isSaving ? 'Salvando…' : 'Salvar'}
+    </ActionButton>
+  );
+}
+
+export { FormSubmitButton };
diff --git a/apps/admin-frontend/src/widgets/form-footer/components/page-form-footer.tsx b/apps/admin-frontend/src/widgets/form-footer/components/page-form-footer.tsx
new file mode 100644
index 00000000..a9f3d73c
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/form-footer/components/page-form-footer.tsx
@@ -0,0 +1,23 @@
+import { Link } from 'react-router';
+import { Button, buttonVariants } from '@/shared/ui/button';
+import type { PageFormFooterProps } from '../form-footer.types';
+import { FormSubmitButton } from './form-submit-button';
+
+function PageFormFooter({ isSaving, canSubmit = true, cancelTo }: PageFormFooterProps) {
+  return (
+    <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
+      {isSaving ? (
+        <Button type="button" variant="outline" disabled>
+          Cancelar
+        </Button>
+      ) : (
+        <Link to={cancelTo} className={buttonVariants({ variant: 'outline' })}>
+          Cancelar
+        </Link>
+      )}
+      <FormSubmitButton isSaving={isSaving} canSubmit={canSubmit} />
+    </div>
+  );
+}
+
+export { PageFormFooter };
diff --git a/apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx b/apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx
index 5c1cbc23..d51f0605 100644
--- a/apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx
+++ b/apps/admin-frontend/src/widgets/form-footer/form-footer.test.tsx
@@ -3,21 +3,26 @@ import { render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { MemoryRouter } from 'react-router';
 import { Dialog, DialogContent, DialogDescription, DialogTitle } from '@/shared/ui/dialog';
-import { FormFooter, type FormFooterProps } from './index';
-
-function renderOnPage(props: FormFooterProps) {
+import {
+  DialogFormFooter,
+  PageFormFooter,
+  type DialogFormFooterProps,
+  type PageFormFooterProps,
+} from './index';
+
+function renderOnPage(props: PageFormFooterProps) {
   const onSubmit = vi.fn((event: React.FormEvent) => event.preventDefault());
   render(
     <MemoryRouter>
       <form onSubmit={onSubmit}>
-        <FormFooter {...props} />
+        <PageFormFooter {...props} />
       </form>
     </MemoryRouter>,
   );
   return { onSubmit };
 }
 
-function renderInDialog(props: FormFooterProps, onOpenChange = vi.fn()) {
+function renderInDialog(props: DialogFormFooterProps, onOpenChange = vi.fn()) {
   const onSubmit = vi.fn((event: React.FormEvent) => event.preventDefault());
   render(
     <Dialog open onOpenChange={onOpenChange}>
@@ -25,7 +30,7 @@ function renderInDialog(props: FormFooterProps, onOpenChange = vi.fn()) {
         <DialogTitle>Título</DialogTitle>
         <DialogDescription>Descrição</DialogDescription>
         <form onSubmit={onSubmit}>
-          <FormFooter {...props} />
+          <DialogFormFooter {...props} />
         </form>
       </DialogContent>
     </Dialog>,
@@ -33,8 +38,8 @@ function renderInDialog(props: FormFooterProps, onOpenChange = vi.fn()) {
   return { onSubmit, onOpenChange };
 }
 
-describe('FormFooter', () => {
-  describe('on a page (cancelTo)', () => {
+describe('form footers', () => {
+  describe('PageFormFooter', () => {
     it('offers Cancelar as a link to cancelTo and Salvar as the submit button', async () => {
       const user = userEvent.setup();
       const { onSubmit } = renderOnPage({ isSaving: false, cancelTo: '/pessoas' });
@@ -69,7 +74,7 @@ describe('FormFooter', () => {
     });
   });
 
-  describe('inside a dialog (no cancelTo)', () => {
+  describe('DialogFormFooter', () => {
     it('closes the dialog from Cancelar', async () => {
       const user = userEvent.setup();
       const { onOpenChange } = renderInDialog({ isSaving: false });
diff --git a/apps/admin-frontend/src/widgets/form-footer/form-footer.types.ts b/apps/admin-frontend/src/widgets/form-footer/form-footer.types.ts
new file mode 100644
index 00000000..58bb20af
--- /dev/null
+++ b/apps/admin-frontend/src/widgets/form-footer/form-footer.types.ts
@@ -0,0 +1,12 @@
+interface FormFooterBaseProps {
+  isSaving: boolean;
+  canSubmit?: boolean;
+}
+
+export type DialogFormFooterProps = FormFooterBaseProps;
+
+export interface PageFormFooterProps extends FormFooterBaseProps {
+  cancelTo: string;
+}
+
+export type FormSubmitButtonProps = Required<FormFooterBaseProps>;
diff --git a/apps/admin-frontend/src/widgets/form-footer/index.tsx b/apps/admin-frontend/src/widgets/form-footer/index.tsx
index 61a130bd..631d434b 100644
--- a/apps/admin-frontend/src/widgets/form-footer/index.tsx
+++ b/apps/admin-frontend/src/widgets/form-footer/index.tsx
@@ -1,47 +1,3 @@
-import { Link } from 'react-router';
-import { ActionButton } from '@/shared/ui/action-button';
-import { Button, buttonVariants } from '@/shared/ui/button';
-import { DialogClose, DialogFooter } from '@/shared/ui/dialog';
-
-interface FormFooterProps {
-  isSaving: boolean;
-  canSubmit?: boolean;
-  cancelTo?: string;
-}
-
-function FormFooter({ isSaving, canSubmit = true, cancelTo }: FormFooterProps) {
-  const submit = (
-    <ActionButton type="submit" disabled={!canSubmit} pending={isSaving}>
-      {isSaving ? 'Salvando…' : 'Salvar'}
-    </ActionButton>
-  );
-
-  if (cancelTo === undefined) {
-    return (
-      <DialogFooter>
-        <DialogClose disabled={isSaving} render={<Button variant="outline" />}>
-          Cancelar
-        </DialogClose>
-        {submit}
-      </DialogFooter>
-    );
-  }
-
-  return (
-    <div className="flex flex-col-reverse gap-2 sm:flex-row sm:justify-end">
-      {isSaving ? (
-        <Button type="button" variant="outline" disabled>
-          Cancelar
-        </Button>
-      ) : (
-        <Link to={cancelTo} className={buttonVariants({ variant: 'outline' })}>
-          Cancelar
-        </Link>
-      )}
-      {submit}
-    </div>
-  );
-}
-
-export { FormFooter };
-export type { FormFooterProps };
+export { DialogFormFooter } from './components/dialog-form-footer';
+export { PageFormFooter } from './components/page-form-footer';
+export type { DialogFormFooterProps, PageFormFooterProps } from './form-footer.types';

From bc615a2cc74d27e49537f838a76327b311f33573 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 16:21:43 -0300
Subject: [PATCH 27/30] Align date fields with API contract

This commit fixes the frontend/backend date contract by generating Date types only for request-body-only schemas and serializing every Date as a UTC yyyy-MM-dd calendar day, matching the backend DateOnly binding. It removes dead field-list exports from form schemas, updates the architecture notes and tests to reflect the actual API behavior, and changes DateField to open from the calendar button with proper Esc focus restoration while leaving arrow keys to the input.
---
 .claude/skills/agenza-api-contract/SKILL.md   | 17 +++++
 .claude/skills/agenza-form-field/SKILL.md     |  8 +-
 apps/admin-frontend/docs/ARCHITECTURE.md      |  3 +-
 .../scripts/generateApiTypes.mjs              | 73 ++++++++++++++++---
 .../pages/ClientFormPage/clientForm.test.ts   | 22 +-----
 .../ui/pages/ClientFormPage/clientForm.ts     |  4 -
 .../tags/ui/pages/TagFormPage/tagForm.test.ts |  2 +-
 .../fields/components/date-field.test.tsx     | 27 +++++--
 .../form/fields/components/date-field.tsx     |  9 +--
 9 files changed, 110 insertions(+), 55 deletions(-)

diff --git a/.claude/skills/agenza-api-contract/SKILL.md b/.claude/skills/agenza-api-contract/SKILL.md
index aa0edf58..dc9cf1d2 100644
--- a/.claude/skills/agenza-api-contract/SKILL.md
+++ b/.claude/skills/agenza-api-contract/SKILL.md
@@ -54,6 +54,23 @@ document. It also fires on a backend-only PR, by design — that is the drift it
    resolved config, so regenerate rather than reformat by hand.
 4. Never relax the check, never hand-patch the `.d.ts`.
 
+## Calendar dates cross as `Date`, instants as `string`
+
+Two rules, one per direction, that only hold together:
+
+- **Types.** `generateApiTypes.mjs` turns `format: date` into `Date` only in schemas reached solely
+  from request bodies: it follows the `$ref`s from each operation's `requestBody`, so the DTO's name
+  (`*Command`, `*Input`, `*Request`) does not matter. A schema that a response or a parameter also
+  uses stays `string`. A date in a response is therefore always a `string`, and the repository that
+  reads it converts it (`new Date(isoDate)` is midnight UTC). `format: date-time` is never mapped.
+- **Wire.** `serializeBody` (`apiClient.ts`, the client's `bodySerializer`) writes **every** `Date`
+  in a request body as `yyyy-MM-dd`, its UTC calendar day; the backend's `DateOnly` binding answers
+  400 to an instant. A `Date` in a body always means a calendar day: never carry an instant in one,
+  send it as the ISO `string` its `date-time` type already asks for.
+
+Build calendar days with `utcDate`/`todayUtc` (`shared/format/date.ts`), never `new Date(y, m, d)`:
+that is local midnight, which east of UTC serializes as the previous day.
+
 ## Write a repository
 
 None exists today ([ADR 0038](../../../docs/adr/0038-admin-frontend-remove-categories-harness.md)
diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index 1ca1baf2..936cde2a 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -50,7 +50,6 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    });
    export type XFormFieldValues = z.input<typeof xFormSchema>;
    export type XFormValues = z.output<typeof xFormSchema>;
-   export const X_FORM_FIELDS = xFormSchema.keyof().options;
 
    export function toXFormFieldValues(x?: X): XFormFieldValues {
      return { name: x?.name ?? '', description: x?.description ?? '' };
@@ -58,8 +57,11 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    ```
    **Use `z.input`/`z.output`, never a single `z.infer`, the moment the schema has a `.refine()` or
    `.transform()`.** See Gotcha 1 below — this is not optional once either is present.
-   `keyof().options` is already typed as the key union, so the schema file needs no `as` cast and no
-   `react-hook-form` import. `toXFormFieldValues` is the inverse of the
+   **No field list for errors**: `applyApiProblem` derives the paths from `methods.getValues()`, so
+   `toXFormFieldValues()` must return every field (the `z.input` return type already forces it).
+   Export `X_FORM_FIELDS = xFormSchema.keyof().options` only when something renders from it, like
+   the loading skeleton below; an export kept alive only by its own test is dead code.
+   `toXFormFieldValues` is the inverse of the
    schema's `.transform()`s (a `null` description back to `''`) and sits beside them: `useForm`'s
    `defaultValues` is `toXFormFieldValues()`, the edit fetch's `reset` is `toXFormFieldValues(entity)`.
 
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 90434a18..fb4ddffe 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -413,11 +413,12 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `shared/format/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) and the calendar's picker bounds on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; validating a birth date (parse the mask, reject the future, reject over 120) is not date arithmetic, so `ageFromBirthDate` sits with the birth-date schema in `shared/form/schemas/birthDate.ts`. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
 | `cpf.ts`, `birthDate.ts` and `contactFormats.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: none of them is specific to a client. A CPF identifies any person (the guardian's already uses it), a birth date is a person attribute any future module can carry, phone and e-mail are contact data any module can hold, and the backend already treats all of them as shared kernel (`CpfNumber`, `BirthDate`, `PhoneNumber` and `EmailAddress` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` was split into `phone.ts` and `email.ts` right after, one per backend value object (next row). |
 | A value more than one form can carry (CPF, phone, e-mail, birth date) is reused through three layers: `shared/format/` parses it, `shared/form/schemas/` turns that into a Zod field, `shared/form/fields/` renders it | Asked for: using a CPF meant assembling two unrelated halves by hand, a Zod fragment written in the slice's `clientForm.ts` (trim, refine, strip, empty to `null`, the pt-BR message) and a `MaskedField` repeating `mask`, `inputMode`, `placeholder` and `autoComplete`; the phone input, repeated three times, had its placeholder in only one of them. (1) `parseCpf`, `parsePhone` and `parseEmail` return the canonical value or `null`, mirroring the backend's `Create` (trim, strip, lowercase and validate in one step), so a caller cannot validate without normalising; the old `isValidX` plus `stripX` left the trim to the caller, which differed from the backend. `maskCpf` is the typing-time mask, named after `maskDate`. (2) `cpfSchema`, `phoneSchema`, `emailSchema` and `birthDateSchema` are built with `optionalValue(parse)`, which owns the empty-field-is-`null` rule and turns `fail(message)` into a Zod issue, so a new value type (a CNPJ) is one `parse` function and one line; `shared/` imports Zod for the first time there. The e-mail schema checks the length itself, before `parseEmail`, to keep the backend's two distinct messages without reporting the same address twice. (3) `CpfField`, `PhoneField`, `EmailField` and `BirthDateField` pin the mask, input type, limit, placeholder, label and `opcional` hint and let the call site override any of them; `BirthDateField` also owns the calendar bounds and the age hint. A call site is `<CpfField name="cpf" />`. The layers stay apart because `model/` has no React: a schema can be imported from a model file, a field only from `ui/`. The guardians section's own `age < 18` comparison was replaced, so the minor rule exists once (`isMinorOn`), and the "a minor needs a guardian" rule built on it lives in the slice's model (`needsGuardian`, two rows below); `formatAge` moved to `shared/format/age.ts`. These presets are the exception to "fields have no domain knowledge": they know a value's format, never an entity. Not built: a required variant of the schemas, since nothing needs one yet; `optionalValue` is where it would go. |
-| Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `JSON.stringify` writes the `Date` as `1990-05-20T00:00:00.000Z`. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in request schemas** (`*Command`, `*Input`); responses stay `string`, since JSON cannot return a `Date`. So `Client` has no `birthDate` until a screen reads it, and that screen's repository must convert it (`new Date(isoDate)` is midnight UTC); the compiler forces it. **Backend dependency:** the backend does not read an instant for `BirthDate` yet. `DateValueObjectJsonConverter` delegates to the framework's `DateOnly` converter, and a `POST /clients` through the real `AddWireJson` pipeline answers 400 (`Validation.Failed` on `birthDate`) to `1990-05-20T00:00:00.000Z` and 200 to `1990-05-20`, so creating a person with a birth date needs that converter to accept an instant first. Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
+| Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `createApiClient`'s `bodySerializer` (`serializeBody`) writes **every** `Date` in a request body as `yyyy-MM-dd`, its UTC calendar day, which is what the backend's `DateOnly` converter reads (`DateValueObjectJsonConverter` answers 400 to an instant such as `1990-05-20T00:00:00.000Z`). So a `Date` on the wire always means a calendar day; an instant (`format: date-time`) is never mapped and travels as the ISO `string` it is typed as. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in schemas reached solely from request bodies**, following `$ref`s from each operation's `requestBody`; a schema a response or a parameter also uses stays `string`, since JSON cannot return a `Date` and only the body goes through `serializeBody`. That set was first picked by name (`*Command`, `*Input`), which would have left a `*Request` DTO as `string` without a word; it is derived from the document now, and the generated file came out byte-identical. `Client.birthDate` is the response's `string | null`; the first screen that reads it converts it in its repository (`new Date(isoDate)` is midnight UTC). Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 | An aggregate's limits and invariants live in the slice's `model/`, beside its types; the Zod schema, its pt-BR messages and the empty form values live in the page that owns the form (`ui/pages/<Page>/<entity>Form.ts`) | Asked for, in review of #174. Both form schemas had already moved from `model/<entity>Form.ts` into their pages (`tagForm.ts`, `clientForm.ts`), but the numbers and rules went with them: the limits mirrored from `Client`/`ClientContact` and the "a minor needs a guardian" invariant sat in `ClientFormPage/clientForm.ts`, and the invariant was written twice with two APIs, the schema's `refine` (`isMinorOn` over a `Date`) and the guardians section's notice (`isMinorBirthDate` over the masked text, a non-schema export of `shared/form/schemas`). The next readers of the rule (the list in #155, a detail page, editing in #156) would have imported from inside a page or copied it. Now `features/clients/model/client.ts` holds `CLIENT_FULL_NAME_MIN_LENGTH`/`_MAX_LENGTH`, `CLIENT_NOTES_MAX_LENGTH`, `MAX_GUARDIANS`, `MAX_REFERENCE_CONTACTS` and `needsGuardian(birthDate, guardianCount, today = todayUtc())`, the same check as the backend's `Client` (`birthDate.IsMinorOn(today) && guardianCount == 0`), and `model/clientContact.ts` holds the contact's name and relationship limits, which only happen to equal the person's today (`ClientContact` and `FullName` are separate in the backend). The schema composes `needsGuardian`; the section calls it on `parseMaskedDate(birthDate)`, which gives the same answer the schema-based check gave, since `isMinorOn` already requires a past date and an age under 18; `isMinorBirthDate` was deleted. `model/` stays free of React, Zod and copy: numbers and pure functions over the plain types, not entity classes, which every repository would have to hydrate. The limits are a UX pre-check; the backend's response stays the source of truth. Tags got the same move (`TAG_NAME_MAX_LENGTH`, `TAG_DESCRIPTION_MAX_LENGTH` in `model/tag.ts`). `FullName` and `AdministrativeNotes` are shared kernel in the backend; their limits stay in the clients model until a second slice needs them, then move to `shared/` as the CPF did. |
 | `widgets/form-footer` exports `DialogFormFooter` and `PageFormFooter` instead of one `FormFooter` that switched on `cancelTo` | Asked for, in review of #174. Passing `cancelTo` or not chose between two different footers, `DialogClose` inside `DialogFooter` or a `Link` back that becomes a disabled button while saving, so `<FormFooter isSaving canSubmit />` in `TagFormPage` read as generic while it only works inside a `Dialog`, and a page that forgot `cancelTo` silently got a dialog footer. Each footer now names where it belongs and `PageFormFooter` requires `cancelTo`; the **Salvar**/**Salvando…** button both render is the folder's internal `FormSubmitButton`. One folder, because it is one concept with two placements. |
 | A value more than one form carries (CPF, phone, e-mail, birth date) is one file in `shared/values/`: its `parseX`, limits, rules and Zod schema together. `shared/format/` keeps only the policy-free `date.ts` and `age.ts`; `shared/form/schemas/` is gone | Asked for, in review of #174, collapsing the first two of the three layers above. Reading or changing a CPF meant `shared/format/cpf.ts`, `shared/form/schemas/cpf.ts` with its barrel, and `cpf-field.tsx`; `format/` also held policy (`ADULT_AGE_IN_YEARS`, `MAX_AGE_IN_YEARS`), not only formatting; and `schemas/birthDate.ts` exported `ageFromBirthDate`, which is not a schema and ran Zod on every render of `BirthDateField`. `shared/values/<value>.ts` mirrors the backend's `Admin.SharedKernel.ValueObjects` one file per value object (`CpfNumber` ↔ `cpf.ts`), so a new value type (a CNPJ) is one file plus, if several forms configure it the same way, a preset field. `ageFromBirthDate(masked, today = todayUtc())` composes `parseMaskedDate`, `isInThePast` and `isWithinMaxAge` itself. The preset fields stay in `shared/form/fields/`: keeping the React half apart lets `model/` import a value's rules (`features/clients/model/client.ts` imports `isMinorOn`) without pulling React in; it does pull Zod, which the three-layer row already accepted. No barrel, as `shared/format/` never had one: imports are `@/shared/values/cpf`. Tests are merged per value (`cpf.test.ts` covers `parseCpf`, `maskCpf` and `cpfSchema`). |
+| `DateField` has no key handler of its own: the keyboard reaches the calendar through its **Abrir calendário** button (Tab, Enter or Space; Esc closes and returns focus to the button), and the arrow keys stay with the input | Asked for, in review of #174. An `onKeyDown` on the input opened the calendar on `↓`, the only key handler in `src/`, against AGENTS.md's "prefer the primitive's behaviour to a key handler of your own". `↓`-opens is the combobox pattern, which needs `role="combobox"`, `aria-expanded`, `aria-haspopup` and `aria-controls` on the input; without them a screen reader user had no way to learn it existed, and adding them would have been more hand-written behaviour, not less. It also replaced any `onKeyDown` a caller passed, since the spread came first. The input plus a button that opens the calendar as a dialog is the WAI-ARIA date picker dialog pattern, and Base UI's `PopoverTrigger` already gives it all. A test pins both halves: the keyboard path through the button, and `↓` in the input opening nothing. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
diff --git a/apps/admin-frontend/scripts/generateApiTypes.mjs b/apps/admin-frontend/scripts/generateApiTypes.mjs
index fc510293..6eb9e9d1 100644
--- a/apps/admin-frontend/scripts/generateApiTypes.mjs
+++ b/apps/admin-frontend/scripts/generateApiTypes.mjs
@@ -34,24 +34,73 @@ function stripTenantHeaderParam(document) {
   return document;
 }
 
-const REQUEST_SCHEMA_PROPERTY = /^#\/components\/schemas\/\w+(Command|Input)\//;
+const SCHEMA_REF = '#/components/schemas/';
 
-function requestDateAsDate(schemaObject, { path: schemaPath = '' }) {
-  if (schemaObject.format !== 'date' || !REQUEST_SCHEMA_PROPERTY.test(schemaPath)) return undefined;
+function schemaRefsIn(value, refs = new Set()) {
+  if (Array.isArray(value)) {
+    for (const item of value) schemaRefsIn(item, refs);
+  } else if (value !== null && typeof value === 'object') {
+    for (const [key, item] of Object.entries(value)) {
+      if (key === '$ref' && typeof item === 'string' && item.startsWith(SCHEMA_REF)) {
+        refs.add(item.slice(SCHEMA_REF.length));
+      } else {
+        schemaRefsIn(item, refs);
+      }
+    }
+  }
+  return refs;
+}
+
+function reachableSchemas(document, roots) {
+  const reached = new Set();
+  const pending = [...schemaRefsIn(roots)];
+  while (pending.length > 0) {
+    const name = pending.pop();
+    if (reached.has(name)) continue;
+    reached.add(name);
+    pending.push(...schemaRefsIn(document.components?.schemas?.[name]));
+  }
+  return reached;
+}
+
+function requestBodyOnlySchemas(document) {
+  const operations = Object.values(document.paths ?? {}).flatMap((pathItem) =>
+    HTTP_METHODS.map((method) => pathItem[method]).filter(Boolean),
+  );
+  const sent = reachableSchemas(
+    document,
+    operations.map((operation) => operation.requestBody),
+  );
+  const usedElsewhere = reachableSchemas(
+    document,
+    operations.map(({ requestBody: _requestBody, ...rest }) => rest),
+  );
+  return new Set([...sent].filter((name) => !usedElsewhere.has(name)));
+}
+
+function requestDateAsDate(requestOnly) {
+  return (schemaObject, { path: schemaPath = '' }) => {
+    const schemaName = schemaPath.startsWith(SCHEMA_REF)
+      ? schemaPath.slice(SCHEMA_REF.length).split('/')[0]
+      : undefined;
+    if (schemaObject.format !== 'date' || !requestOnly.has(schemaName)) return undefined;
 
-  const date = ts.factory.createTypeReferenceNode('Date');
-  if (!Array.isArray(schemaObject.type) || !schemaObject.type.includes('null')) return date;
+    const date = ts.factory.createTypeReferenceNode('Date');
+    if (!Array.isArray(schemaObject.type) || !schemaObject.type.includes('null')) return date;
 
-  return ts.factory.createUnionTypeNode([
-    ts.factory.createLiteralTypeNode(ts.factory.createNull()),
-    date,
-  ]);
+    return ts.factory.createUnionTypeNode([
+      ts.factory.createLiteralTypeNode(ts.factory.createNull()),
+      date,
+    ]);
+  };
 }
 
 export async function generate() {
-  const document = await fetch(new URL(OPENAPI_URL)).then((response) => response.json());
-  const ast = await openapiTS(stripTenantHeaderParam(document), {
-    transform: requestDateAsDate,
+  const document = stripTenantHeaderParam(
+    await fetch(new URL(OPENAPI_URL)).then((response) => response.json()),
+  );
+  const ast = await openapiTS(document, {
+    transform: requestDateAsDate(requestBodyOnlySchemas(document)),
   });
   const raw = astToString(ast);
   const prettierConfig = (await prettier.resolveConfig(__dirname)) ?? {};
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
index 0bcca042..5d9274dd 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.test.ts
@@ -1,9 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { utcDate } from '@/shared/format/date';
 import {
-  CLIENT_FORM_FIELDS,
-  GUARDIAN_FORM_FIELDS,
-  REFERENCE_CONTACT_FORM_FIELDS,
   clientFormSchema,
   emptyGuardian,
   emptyReferenceContact,
@@ -317,23 +314,8 @@ describe('clientFormSchema', () => {
   });
 });
 
-describe('form field lists', () => {
-  it('names every field the backend can report on', () => {
-    expect(CLIENT_FORM_FIELDS).toEqual([
-      'fullName',
-      'birthDate',
-      'phone',
-      'email',
-      'cpf',
-      'administrativeNotes',
-      'guardians',
-      'referenceContacts',
-    ]);
-    expect(GUARDIAN_FORM_FIELDS).toEqual(['name', 'relationship', 'phone', 'cpf']);
-    expect(REFERENCE_CONTACT_FORM_FIELDS).toEqual(['name', 'relationship', 'phone', 'purposes']);
-  });
-
-  it('starts empty so nothing is asked up front', () => {
+describe('emptyClientFormFieldValues', () => {
+  it('holds every field, empty, so nothing is asked up front and a backend error on any of them finds its input', () => {
     expect(emptyClientFormFieldValues()).toEqual({
       fullName: '',
       birthDate: '',
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
index 93e4efc6..24366134 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/clientForm.ts
@@ -96,10 +96,6 @@ export type ClientFormValues = z.output<typeof clientFormSchema>;
 export type GuardianFormFieldValues = ClientFormFieldValues['guardians'][number];
 export type ReferenceContactFormFieldValues = ClientFormFieldValues['referenceContacts'][number];
 
-export const CLIENT_FORM_FIELDS = clientFormObject.keyof().options;
-export const GUARDIAN_FORM_FIELDS = guardianSchema.keyof().options;
-export const REFERENCE_CONTACT_FORM_FIELDS = referenceContactSchema.keyof().options;
-
 export function emptyClientFormFieldValues(): ClientFormFieldValues {
   return {
     fullName: '',
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
index 14b37cbb..91e588a9 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/tagForm.test.ts
@@ -83,7 +83,7 @@ describe('tagFormSchema', () => {
     }
   });
 
-  it('lists every schema field in TAG_FORM_FIELDS, so a backend error on any of them maps to its input', () => {
+  it('lists every schema field in TAG_FORM_FIELDS, so the loading skeleton has one row per field', () => {
     expect(TAG_FORM_FIELDS).toEqual(['name', 'color', 'description']);
   });
 });
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
index a139689c..56bf71a8 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.test.tsx
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { render, screen, within } from '@testing-library/react';
+import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { FormProvider, useForm, useFormContext, useWatch } from 'react-hook-form';
 import { utcDate } from '@/shared/format/date';
@@ -79,14 +79,13 @@ describe('DateField', () => {
   });
 
   it.each([['disabled'], ['readOnly']] as const)(
-    'does not open the calendar from the button or the arrow key while the field is %s',
+    'does not open the calendar while the field is %s',
     async (mode) => {
       const user = userEvent.setup();
       render(<Harness {...{ [mode]: true }} />);
 
       expect(calendarButton()).toBeDisabled();
-      await user.click(input());
-      await user.keyboard('{ArrowDown}');
+      await user.click(calendarButton());
 
       expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
     },
@@ -173,14 +172,30 @@ describe('DateField', () => {
     expect(within(calendar).getByRole('grid', { name: 'outubro 2026' })).toBeInTheDocument();
   });
 
-  it('opens the calendar with the arrow down key from the input', async () => {
+  it('opens the calendar from the keyboard through its button and closes it with Esc', async () => {
     const user = userEvent.setup();
     render(<Harness />);
 
     await user.click(input());
-    await user.keyboard('{ArrowDown}');
+    await user.tab();
+    expect(calendarButton()).toHaveFocus();
 
+    await user.keyboard('{Enter}');
     expect(await screen.findByRole('dialog')).toBeInTheDocument();
+
+    await user.keyboard('{Escape}');
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+    expect(calendarButton()).toHaveFocus();
+  });
+
+  it('leaves the arrow keys to the input', async () => {
+    const user = userEvent.setup();
+    render(<Harness />);
+
+    await user.click(input());
+    await user.keyboard('{ArrowDown}');
+
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
   });
 
   it('fills the field with the picked day and closes the calendar', async () => {
diff --git a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
index 326d2fa7..191d975d 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/date-field.tsx
@@ -1,4 +1,4 @@
-import { useState, type KeyboardEvent, type Ref } from 'react';
+import { useState, type Ref } from 'react';
 import { useFormContext, type FieldValues } from 'react-hook-form';
 import { CalendarIcon, XIcon } from 'lucide-react';
 import { formatMaskedDate, maskDate, parseMaskedDate } from '@/shared/format/date';
@@ -81,12 +81,6 @@ function DateFieldControl({
     setOpen(false);
   }
 
-  function openOnArrowDown(event: KeyboardEvent<HTMLInputElement>) {
-    if (event.key !== 'ArrowDown' || isLocked) return;
-    event.preventDefault();
-    setOpen(true);
-  }
-
   return (
     <InputGroup>
       <Popover open={open} onOpenChange={setOpen}>
@@ -97,7 +91,6 @@ function DateFieldControl({
           inputMode="numeric"
           placeholder={placeholder}
           onChange={(event) => onChange(maskDate(event.target.value))}
-          onKeyDown={openOnArrowDown}
         />
         <InputGroupAddon align="inline-end" className="gap-0.5">
           {hasValue && !isLocked && (

From fe48782572521df74f11d427ff087576a07d2339 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 16:28:14 -0300
Subject: [PATCH 28/30] 0897

---
 .claude/skills/agenza-api-contract/SKILL.md   |   2 +
 .claude/skills/agenza-form-field/SKILL.md     |  24 ++--
 apps/admin-frontend/docs/ARCHITECTURE.md      |  27 ++++-
 .../scripts/generateApiTypes.mjs              |  13 +-
 .../scripts/generateApiTypes.test.mjs         | 111 ++++++++++++++++++
 .../src/features/clients/ui/clientsPaths.ts   |   1 +
 .../pages/ClientFormPage/ClientFormPage.tsx   |   5 +-
 .../components/ClientReferenceContactItem.tsx |   4 +-
 .../pages/ClientFormPage/useClientFormPage.ts |   3 +-
 .../pages/TagDeletePage/useTagDeletePage.ts   |   3 +-
 .../ui/pages/TagFormPage/useTagFormPage.ts    |   3 +-
 .../src/features/tags/ui/tagsPaths.ts         |   1 +
 .../fields/components/controlled-field.tsx    |   8 +-
 .../src/shared/form/fields/fields.types.ts    |   9 +-
 14 files changed, 178 insertions(+), 36 deletions(-)
 create mode 100644 apps/admin-frontend/scripts/generateApiTypes.test.mjs
 create mode 100644 apps/admin-frontend/src/features/clients/ui/clientsPaths.ts
 create mode 100644 apps/admin-frontend/src/features/tags/ui/tagsPaths.ts

diff --git a/.claude/skills/agenza-api-contract/SKILL.md b/.claude/skills/agenza-api-contract/SKILL.md
index dc9cf1d2..ca9cba5d 100644
--- a/.claude/skills/agenza-api-contract/SKILL.md
+++ b/.claude/skills/agenza-api-contract/SKILL.md
@@ -63,6 +63,8 @@ Two rules, one per direction, that only hold together:
   (`*Command`, `*Input`, `*Request`) does not matter. A schema that a response or a parameter also
   uses stays `string`. A date in a response is therefore always a `string`, and the repository that
   reads it converts it (`new Date(isoDate)` is midnight UTC). `format: date-time` is never mapped.
+  `scripts/generateApiTypes.test.mjs` pins each case against a fixture document (`typesFromDocument`,
+  no backend needed); change the rule there first.
 - **Wire.** `serializeBody` (`apiClient.ts`, the client's `bodySerializer`) writes **every** `Date`
   in a request body as `yyyy-MM-dd`, its UTC calendar day; the backend's `DateOnly` binding answers
   400 to an instant. A `Date` in a body always means a calendar day: never carry an instant in one,
diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index 936cde2a..d5267f62 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -95,20 +95,23 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    trips `@typescript-eslint/no-misused-promises`; `tsc` alone won't catch it, only `npm run lint`.
 
    `canSubmit` is the rule behind the **Salvar** button's `disabled` state. The form's
-   `onSubmit` calls `submit`. The footer uses:
+   `onSubmit` calls `submit`. The footer is a widget, chosen by where the form lives:
    ```tsx
-   <DialogClose disabled={isSaving} render={<Button variant="outline" />}>Cancelar</DialogClose>
-   <ActionButton type="submit" disabled={!canSubmit} pending={isSaving}>
-     {isSaving ? 'Salvando…' : 'Salvar'}
-   </ActionButton>
+   import { DialogFormFooter, PageFormFooter } from '@/widgets/form-footer';
+
+   <DialogFormFooter canSubmit={canSubmit} isSaving={isSaving} />
+   <PageFormFooter isSaving={isSaving} cancelTo="/pessoas" />
    ```
-   `ActionButton` turns `pending` into a spinner and disables the button.
+   `DialogFormFooter` goes inside a `Dialog` (its Cancelar is a `DialogClose`); `PageFormFooter` goes on
+   a full page and requires `cancelTo` (its Cancelar is a link that turns into a disabled button while
+   saving). Both render **Salvar**/**Salvando…** as an `ActionButton`, which turns `pending` into a
+   spinner and disables the button.
 
    **While saving, the dialog offers no way out** — a Cancelar clicked mid-request would close the
    dialog while the save still lands, a Cancel that doesn't cancel. Three lines, all with APIs the
    dialog already had: the hook's `onOpenChange` ignores a close while `isSaving` (a controlled dialog
-   stays open when its handler doesn't close it, which covers Esc and outside press), Cancelar is
-   `<DialogClose disabled={isSaving}>`, and the shell passes `showCloseButton={!isSaving}` to
+   stays open when its handler doesn't close it, which covers Esc and outside press),
+   `DialogFormFooter` disables its Cancelar, and the shell passes `showCloseButton={!isSaving}` to
    `DialogContent`. `shared/ui/dialog` itself stays a plain wrapper — a `busy` prop with a context was
    tried there and reverted as more machinery than three lines per dialog.
 
@@ -122,9 +125,10 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    field-values type as an explicit JSX type argument:
    ```tsx
    import { ColorField, TextField } from '@/shared/form/fields';
-   import type { XFormFieldValues } from '../../model/xForm';
+   import { X_NAME_MAX_LENGTH } from '../../../../model/x';
+   import type { XFormFieldValues } from '../xForm';
 
-   <TextField<XFormFieldValues> name="name" label="Nome" hint="…" maxLength={40} placeholder="…" />
+   <TextField<XFormFieldValues> name="name" label="Nome" hint="…" maxLength={X_NAME_MAX_LENGTH} />
    <ColorField<XFormFieldValues> name="color" label="Cor" aria-label="Cor…" options={PALETTE} />
    ```
    The type argument is what makes `name` type-check against `Path<XFormFieldValues>` — a bare
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index fb4ddffe..40b213eb 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -28,8 +28,9 @@ src/
 │   ├── model/               Types + rules. No React. ( = domain + application )
 │   ├── api/                 Backend gateway — repositories. ( = infrastructure )
 │   ├── ui/                  Everything that imports React
-│   │   └── pages/<Page>/    One folder per route: <Page>.tsx (shell) + use<Page>.ts (form
-│   │                        state) + route.ts (loader/action), all re-exported by index.ts
+│   │   ├── pages/<Page>/    One folder per route: <Page>.tsx (shell) + use<Page>.ts (form
+│   │   │                    state) + route.ts (loader/action), all re-exported by index.ts
+│   │   └── <slice>Paths.ts  The slice's own URL, written once (CLIENTS_PATH, TAGS_PATH)
 │   └── index.ts             The slice's ONLY public surface
 ├── widgets/                 Generic UI compositions with behaviour but no domain (confirm-dialog,
 │                            list-section, page-header, page-section, form-footer); import
@@ -180,6 +181,23 @@ component does or how many sub-parts it has:
 component-specific before/after; the rules above are what should carry over to the next component,
 whatever it renders.
 
+**Vocabulary: what the screen says, what the code says.** Code is in English and uses the backend's
+names; the text on screen and the routes are pt-BR (spec 002, clarification of 2026-10-02). Where the
+two differ, read one as the other:
+
+| On screen                                                         | In code (frontend and backend)                                             | Route / API                   |
+| ----------------------------------------------------------------- | -------------------------------------------------------------------------- | ----------------------------- |
+| Pessoa (pessoa atendida)                                          | `Client`, `features/clients`                                               | `/pessoas`, `/api/v1/clients` |
+| Responsável                                                       | `ClientGuardian`, `guardians`                                              | —                             |
+| Pessoa de referência                                              | `ClientReferenceContact`, `referenceContacts`                              | —                             |
+| Finalidade (Emergência, Apoio operacional, Comunicação cotidiana) | `ContactPurpose` (`emergency`, `operationalSupport`, `dailyCommunication`) | —                             |
+| Vínculo                                                           | `relationship`                                                             | —                             |
+| Observações administrativas                                       | `administrativeNotes`                                                      | —                             |
+| Etiqueta                                                          | `Tag`, `features/tags`                                                     | `/tags`, `/api/v1/tags`       |
+
+`/tags` is the one route still in English while the menu says **Etiquetas**: a known exception, left
+as is because renaming a URL is a product decision, not a refactor.
+
 ---
 
 ## 2. Talking to the backend
@@ -413,12 +431,14 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | Completed-years arithmetic lives in `shared/format/date.ts` as `fullYearsBetween(from, to)`; `shared/format/birthDate.ts` keeps only the birth-date rules (past, maximum age, minor) and the calendar's picker bounds on top of it | Asked for: `calculateAge` was a general "years elapsed between two calendar days" calculation hidden in a clients-only file. It now takes any two calendar days (`Date`s), so anniversaries, contract terms or "client since" can reuse it; validating a birth date (parse the mask, reject the future, reject over 120) is not date arithmetic, so `ageFromBirthDate` sits with the birth-date schema in `shared/form/schemas/birthDate.ts`. Written by hand rather than with `date-fns`' `differenceInYears`: `date-fns` is only a transitive dependency of `react-day-picker` (the app declares and imports nothing from it), and it moves a February 29 anniversary to March 1 in common years, while the backend (`AddYears`) moves it to February 28 — the pinned test (`2008-02-29` to `2026-02-28` is 18) is that contract. Months and days are not generalised: nothing needs them yet. |
 | `cpf.ts`, `birthDate.ts` and `contactFormats.ts` moved from `features/clients/model/` to `shared/format/`, next to `date.ts` (tests moved with them) | Asked for: none of them is specific to a client. A CPF identifies any person (the guardian's already uses it), a birth date is a person attribute any future module can carry, phone and e-mail are contact data any module can hold, and the backend already treats all of them as shared kernel (`CpfNumber`, `BirthDate`, `PhoneNumber` and `EmailAddress` in `Admin.SharedKernel.ValueObjects`). `birthDate.ts` already depended on `shared/format/date.ts`, so it now sits beside it. Pure move: no export was renamed. `birthDate.ts` is the one place where `shared/` holds a policy rather than a format (the 18 and 120 limits mirror the backend's), accepted because the backend keeps the same limits in its own shared kernel and a second copy per module would drift. `contactFormats.ts` was split into `phone.ts` and `email.ts` right after, one per backend value object (next row). |
 | A value more than one form can carry (CPF, phone, e-mail, birth date) is reused through three layers: `shared/format/` parses it, `shared/form/schemas/` turns that into a Zod field, `shared/form/fields/` renders it | Asked for: using a CPF meant assembling two unrelated halves by hand, a Zod fragment written in the slice's `clientForm.ts` (trim, refine, strip, empty to `null`, the pt-BR message) and a `MaskedField` repeating `mask`, `inputMode`, `placeholder` and `autoComplete`; the phone input, repeated three times, had its placeholder in only one of them. (1) `parseCpf`, `parsePhone` and `parseEmail` return the canonical value or `null`, mirroring the backend's `Create` (trim, strip, lowercase and validate in one step), so a caller cannot validate without normalising; the old `isValidX` plus `stripX` left the trim to the caller, which differed from the backend. `maskCpf` is the typing-time mask, named after `maskDate`. (2) `cpfSchema`, `phoneSchema`, `emailSchema` and `birthDateSchema` are built with `optionalValue(parse)`, which owns the empty-field-is-`null` rule and turns `fail(message)` into a Zod issue, so a new value type (a CNPJ) is one `parse` function and one line; `shared/` imports Zod for the first time there. The e-mail schema checks the length itself, before `parseEmail`, to keep the backend's two distinct messages without reporting the same address twice. (3) `CpfField`, `PhoneField`, `EmailField` and `BirthDateField` pin the mask, input type, limit, placeholder, label and `opcional` hint and let the call site override any of them; `BirthDateField` also owns the calendar bounds and the age hint. A call site is `<CpfField name="cpf" />`. The layers stay apart because `model/` has no React: a schema can be imported from a model file, a field only from `ui/`. The guardians section's own `age < 18` comparison was replaced, so the minor rule exists once (`isMinorOn`), and the "a minor needs a guardian" rule built on it lives in the slice's model (`needsGuardian`, two rows below); `formatAge` moved to `shared/format/age.ts`. These presets are the exception to "fields have no domain knowledge": they know a value's format, never an entity. Not built: a required variant of the schemas, since nothing needs one yet; `optionalValue` is where it would go. |
-| Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `createApiClient`'s `bodySerializer` (`serializeBody`) writes **every** `Date` in a request body as `yyyy-MM-dd`, its UTC calendar day, which is what the backend's `DateOnly` converter reads (`DateValueObjectJsonConverter` answers 400 to an instant such as `1990-05-20T00:00:00.000Z`). So a `Date` on the wire always means a calendar day; an instant (`format: date-time`) is never mapped and travels as the ISO `string` it is typed as. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in schemas reached solely from request bodies**, following `$ref`s from each operation's `requestBody`; a schema a response or a parameter also uses stays `string`, since JSON cannot return a `Date` and only the body goes through `serializeBody`. That set was first picked by name (`*Command`, `*Input`), which would have left a `*Request` DTO as `string` without a word; it is derived from the document now, and the generated file came out byte-identical. `Client.birthDate` is the response's `string | null`; the first screen that reads it converts it in its repository (`new Date(isoDate)` is midnight UTC). Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
+| Calendar dates are `Date` at midnight UTC, from the form schema to the repository; text exists only where it is shown (`dd/mm/aaaa`, via `formatMaskedDate`) | Asked for: every date reference was a `string`, so an ISO date, a masked date and any other text were the same type. `utcDate(year, month, day)` is the one constructor (1-based month); comparisons, arithmetic and display read `getUTC*`, so the day never shifts with the device's zone. No code reads the device's zone: `todayUtc` is the same UTC calendar day the backend uses (ADR 0045), so a date the form accepts is one the API accepts. `DateField` passes `timeZone="UTC"` to the calendar. `clientsRepository.create` is a pass-through: `createApiClient`'s `bodySerializer` (`serializeBody`) writes **every** `Date` in a request body as `yyyy-MM-dd`, its UTC calendar day, which is what the backend's `DateOnly` converter reads (`DateValueObjectJsonConverter` answers 400 to an instant such as `1990-05-20T00:00:00.000Z`). So a `Date` on the wire always means a calendar day; an instant (`format: date-time`) is never mapped and travels as the ISO `string` it is typed as. That typechecks because `scripts/generateApiTypes.mjs` maps `format: date` to `Date` **only in schemas reached solely from request bodies**, following `$ref`s from each operation's `requestBody`; a schema a response or a parameter also uses stays `string`, since JSON cannot return a `Date` and only the body goes through `serializeBody`. That set was first picked by name (`*Command`, `*Input`), which would have left a `*Request` DTO as `string` without a word; it is derived from the document now, and the generated file came out byte-identical; `scripts/generateApiTypes.test.mjs` pins the rule against a fixture document. `Client.birthDate` is the response's `string | null`; the first screen that reads it converts it in its repository (`new Date(isoDate)` is midnight UTC). Not branded strings and not a `{ year, month, day }` object: the native type was asked for and the calendar library already speaks it. |
 | `ClientGuardiansSection` and `ClientReferenceContactsSection` own their `useFieldArray` (control from `useFormContext`) instead of receiving `fieldIds`/`onAdd`/`onRemove` from `useClientFormPage` | Asked for. The page hook created both arrays and handed them down as `fields.map((field) => field.id)` plus callbacks, so a list's name, limit, empty factory and item paths were split across hook, section and item, the page did data shaping in its JSX, and every append/remove re-rendered the whole page. The sections already sit inside `FormProvider`, so taking `control` from it adds no coupling; item identity is `key={field.id}`, and the list-level error comes from `useFormState({ control, name })` rather than `useFormContext().formState.errors`, because the latter is the page's own `useForm` proxy (reading it re-renders the page on every error change) while `useFormState` keeps its state and subscription local to the section. `UseClientFormPageResult` lost `guardians`, `referenceContacts`, `addGuardian`, `addReferenceContact`, `age` and `isMinor` (the last two were pure derivations of `birthDate` that only the person and guardians sections consumed, so each now `useWatch`es `birthDate` itself instead of the page re-rendering on every keystroke of the date), so none of the three sections takes props. The hook's `onInvalid` and `addGuardianButtonRef` were removed too, on request: they focused the guardians' add button when the missing guardian was the only error, because RHF cannot focus a list-level error (`setFocus` needs a registered ref with `focus`; `useFieldArray` registers the array root only when given `rules`, and with a placeholder `{ name }` ref). A submit that fails only on the guardian now leaves focus on **Salvar** and the section's `role="alert"` is the signal; failures on inputs still focus the first invalid input through RHF's own `shouldFocusError`. There must be exactly one `useFieldArray` per name: keeping one in the hook as well would put two instances over the same state. |
 | An aggregate's limits and invariants live in the slice's `model/`, beside its types; the Zod schema, its pt-BR messages and the empty form values live in the page that owns the form (`ui/pages/<Page>/<entity>Form.ts`) | Asked for, in review of #174. Both form schemas had already moved from `model/<entity>Form.ts` into their pages (`tagForm.ts`, `clientForm.ts`), but the numbers and rules went with them: the limits mirrored from `Client`/`ClientContact` and the "a minor needs a guardian" invariant sat in `ClientFormPage/clientForm.ts`, and the invariant was written twice with two APIs, the schema's `refine` (`isMinorOn` over a `Date`) and the guardians section's notice (`isMinorBirthDate` over the masked text, a non-schema export of `shared/form/schemas`). The next readers of the rule (the list in #155, a detail page, editing in #156) would have imported from inside a page or copied it. Now `features/clients/model/client.ts` holds `CLIENT_FULL_NAME_MIN_LENGTH`/`_MAX_LENGTH`, `CLIENT_NOTES_MAX_LENGTH`, `MAX_GUARDIANS`, `MAX_REFERENCE_CONTACTS` and `needsGuardian(birthDate, guardianCount, today = todayUtc())`, the same check as the backend's `Client` (`birthDate.IsMinorOn(today) && guardianCount == 0`), and `model/clientContact.ts` holds the contact's name and relationship limits, which only happen to equal the person's today (`ClientContact` and `FullName` are separate in the backend). The schema composes `needsGuardian`; the section calls it on `parseMaskedDate(birthDate)`, which gives the same answer the schema-based check gave, since `isMinorOn` already requires a past date and an age under 18; `isMinorBirthDate` was deleted. `model/` stays free of React, Zod and copy: numbers and pure functions over the plain types, not entity classes, which every repository would have to hydrate. The limits are a UX pre-check; the backend's response stays the source of truth. Tags got the same move (`TAG_NAME_MAX_LENGTH`, `TAG_DESCRIPTION_MAX_LENGTH` in `model/tag.ts`). `FullName` and `AdministrativeNotes` are shared kernel in the backend; their limits stay in the clients model until a second slice needs them, then move to `shared/` as the CPF did. |
 | `widgets/form-footer` exports `DialogFormFooter` and `PageFormFooter` instead of one `FormFooter` that switched on `cancelTo` | Asked for, in review of #174. Passing `cancelTo` or not chose between two different footers, `DialogClose` inside `DialogFooter` or a `Link` back that becomes a disabled button while saving, so `<FormFooter isSaving canSubmit />` in `TagFormPage` read as generic while it only works inside a `Dialog`, and a page that forgot `cancelTo` silently got a dialog footer. Each footer now names where it belongs and `PageFormFooter` requires `cancelTo`; the **Salvar**/**Salvando…** button both render is the folder's internal `FormSubmitButton`. One folder, because it is one concept with two placements. |
 | A value more than one form carries (CPF, phone, e-mail, birth date) is one file in `shared/values/`: its `parseX`, limits, rules and Zod schema together. `shared/format/` keeps only the policy-free `date.ts` and `age.ts`; `shared/form/schemas/` is gone | Asked for, in review of #174, collapsing the first two of the three layers above. Reading or changing a CPF meant `shared/format/cpf.ts`, `shared/form/schemas/cpf.ts` with its barrel, and `cpf-field.tsx`; `format/` also held policy (`ADULT_AGE_IN_YEARS`, `MAX_AGE_IN_YEARS`), not only formatting; and `schemas/birthDate.ts` exported `ageFromBirthDate`, which is not a schema and ran Zod on every render of `BirthDateField`. `shared/values/<value>.ts` mirrors the backend's `Admin.SharedKernel.ValueObjects` one file per value object (`CpfNumber` ↔ `cpf.ts`), so a new value type (a CNPJ) is one file plus, if several forms configure it the same way, a preset field. `ageFromBirthDate(masked, today = todayUtc())` composes `parseMaskedDate`, `isInThePast` and `isWithinMaxAge` itself. The preset fields stay in `shared/form/fields/`: keeping the React half apart lets `model/` import a value's rules (`features/clients/model/client.ts` imports `isMinorOn`) without pulling React in; it does pull Zod, which the three-layer row already accepted. No barrel, as `shared/format/` never had one: imports are `@/shared/values/cpf`. Tests are merged per value (`cpf.test.ts` covers `parseCpf`, `maskCpf` and `cpfSchema`). |
 | `DateField` has no key handler of its own: the keyboard reaches the calendar through its **Abrir calendário** button (Tab, Enter or Space; Esc closes and returns focus to the button), and the arrow keys stay with the input | Asked for, in review of #174. An `onKeyDown` on the input opened the calendar on `↓`, the only key handler in `src/`, against AGENTS.md's "prefer the primitive's behaviour to a key handler of your own". `↓`-opens is the combobox pattern, which needs `role="combobox"`, `aria-expanded`, `aria-haspopup` and `aria-controls` on the input; without them a screen reader user had no way to learn it existed, and adding them would have been more hand-written behaviour, not less. It also replaced any `onKeyDown` a caller passed, since the spread came first. The input plus a button that opens the calendar as a dialog is the WAI-ARIA date picker dialog pattern, and Base UI's `PopoverTrigger` already gives it all. A test pins both halves: the keyboard path through the button, and `↓` in the input opening nothing. |
+| `ControlledField` takes the field's path as an optional second type argument, `ControlledField<T, N extends Path<T> = Path<T>>` | Asked for, in review of #174. With only `T`, `field` was typed over every path of the form, so `field.value` was the union of all its values and the reference contact's purposes needed `field.value as string[]`. Passing the path (`ControlledField<ClientFormFieldValues, \`referenceContacts.${number}.purposes\`>`) types `field.value`as that field's own value,`ContactPurpose[]`. The default keeps every other call site as it was. The cost is the second explicit argument: TypeScript does not infer one type argument when another is given. |
+| A slice names its own URL once, in `ui/<slice>Paths.ts` (`CLIENTS_PATH`, `TAGS_PATH`); `app/`keeps writing the path | Asked for, in review of #174:`/pessoas`was written three times inside`features/clients`, `/tags`twice inside`features/tags`. The constant sits in `ui/`rather than in one page's folder, because the list (#155) and editing (#156) navigate to the same place.`app/routes.tsx`, `app/shell/navigation.ts`and`app/pages/Clients.tsx`keep the literal:`app/` owns the route table, and taking the constant from the slice would mean the shell importing the slice barrel, which risks pulling a lazily loaded slice into the main bundle. Tests and e2e keep the literal too, since they check the URL contract. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.
 
@@ -477,6 +497,7 @@ because it didn't need to be yet. This is the compiled view across the whole app
 | Pagination / infinite scroll in `list-section`                                                                                       | `/tags` has no `page`/`pageSize` on the backend yet, and its spec explicitly excludes pagination (small catalog)                                                                                                                                                                                                                            | A second real list screen needs it — `/services` already returns `page`/`pageSize`/`totalCount`, unconsumed today                                                                                                |
 | `list-section`'s `renderItem` (list, no header) mode exercised by a real screen                                                      | `TagListPage` uses the `columns` mode for its own three-field table                                                                                                                                                                                                                                                                         | A listing without natural columns (e.g. a simple feed or timeline) needs it                                                                                                                                      |
 | `run()` classifying an aborted request's own `AbortError` as a distinct outcome, instead of folding it into `NETWORK_PROBLEM`        | `servicesFacade.ts`'s `CallOptions`/`buildInit` accept an optional `signal` (added for `useTagListPage`'s `fetchTags`, ADR 0033's scoped exception, §5), but the one consumer that passes one checks `controller.signal.aborted` itself, before ever looking at the `ApiResult` — it never needs `.error.code` to say "cancelled" correctly | A second `signal`-aware caller needs to tell "I cancelled this" apart from "the network actually failed" via the `ApiResult` itself, not by holding its own `AbortController` reference the way `fetchTags` does |
+| `widgets/repeatable-list`: one frame for an item of a dynamic list (`role="group"` named by an `h3`, plus a **Remover** button)      | Two items repeat that header today, `ClientGuardianItem` and `ClientReferenceContactItem`, both on the same page, and editing (#156) reuses that page, so it is not a third. Two examples are too few to fix the shape of a shared widget, and the copy is about fifteen lines of markup                                                    | A third repeatable list appears in any slice: build `RepeatableItem({ title, removeLabel, onRemove, children })` and move the two client items onto it                                                           |
 
 ---
 
diff --git a/apps/admin-frontend/scripts/generateApiTypes.mjs b/apps/admin-frontend/scripts/generateApiTypes.mjs
index 6eb9e9d1..14bbc9bb 100644
--- a/apps/admin-frontend/scripts/generateApiTypes.mjs
+++ b/apps/admin-frontend/scripts/generateApiTypes.mjs
@@ -95,14 +95,17 @@ function requestDateAsDate(requestOnly) {
   };
 }
 
-export async function generate() {
-  const document = stripTenantHeaderParam(
-    await fetch(new URL(OPENAPI_URL)).then((response) => response.json()),
-  );
+export async function typesFromDocument(openApiDocument) {
+  const document = stripTenantHeaderParam(openApiDocument);
   const ast = await openapiTS(document, {
     transform: requestDateAsDate(requestBodyOnlySchemas(document)),
   });
-  const raw = astToString(ast);
+  return astToString(ast);
+}
+
+export async function generate() {
+  const document = await fetch(new URL(OPENAPI_URL)).then((response) => response.json());
+  const raw = await typesFromDocument(document);
   const prettierConfig = (await prettier.resolveConfig(__dirname)) ?? {};
   const formatted = await prettier.format(raw, { ...prettierConfig, parser: 'typescript' });
   const banner =
diff --git a/apps/admin-frontend/scripts/generateApiTypes.test.mjs b/apps/admin-frontend/scripts/generateApiTypes.test.mjs
new file mode 100644
index 00000000..80122c92
--- /dev/null
+++ b/apps/admin-frontend/scripts/generateApiTypes.test.mjs
@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import { typesFromDocument } from './generateApiTypes.mjs';
+
+function json(schemaName) {
+  return {
+    content: { 'application/json': { schema: { $ref: `#/components/schemas/${schemaName}` } } },
+  };
+}
+
+function ok(schemaName) {
+  return { 200: { description: 'OK', ...json(schemaName) } };
+}
+
+function openApiDocument() {
+  return {
+    openapi: '3.1.1',
+    info: { title: 'fixture', version: 'v1' },
+    paths: {
+      '/people': {
+        post: { requestBody: json('CreatePersonRequest'), responses: ok('PersonResponse') },
+      },
+      '/events/{id}': {
+        put: { requestBody: json('EventBody'), responses: ok('EventBody') },
+      },
+      '/agenda': {
+        get: {
+          parameters: [
+            { name: 'filter', in: 'query', schema: { $ref: '#/components/schemas/AgendaFilter' } },
+          ],
+          responses: ok('PersonResponse'),
+        },
+        post: { requestBody: json('AgendaFilter'), responses: ok('PersonResponse') },
+      },
+    },
+    components: {
+      schemas: {
+        CreatePersonRequest: {
+          type: 'object',
+          required: ['birthDate', 'firstVisit', 'guardian', 'createdAt'],
+          properties: {
+            birthDate: { type: ['null', 'string'], format: 'date' },
+            firstVisit: { type: 'string', format: 'date' },
+            guardian: { $ref: '#/components/schemas/GuardianPayload' },
+            createdAt: { type: 'string', format: 'date-time' },
+          },
+        },
+        GuardianPayload: {
+          type: 'object',
+          required: ['since'],
+          properties: { since: { type: 'string', format: 'date' } },
+        },
+        PersonResponse: {
+          type: 'object',
+          required: ['birthDate'],
+          properties: { birthDate: { type: ['null', 'string'], format: 'date' } },
+        },
+        EventBody: {
+          type: 'object',
+          required: ['day'],
+          properties: { day: { type: 'string', format: 'date' } },
+        },
+        AgendaFilter: {
+          type: 'object',
+          required: ['from'],
+          properties: { from: { type: 'string', format: 'date' } },
+        },
+      },
+    },
+  };
+}
+
+function typeOf(types, schemaName, property) {
+  const block = types.match(new RegExp(`\\b${schemaName}: \\{([^}]*)\\}`))?.[1] ?? '';
+  return block.match(new RegExp(`\\b${property}\\??: ([^;]+);`))?.[1];
+}
+
+describe('typesFromDocument', () => {
+  it('types a date sent only in a request body as Date, whatever the schema is called', async () => {
+    const types = await typesFromDocument(openApiDocument());
+
+    expect(typeOf(types, 'CreatePersonRequest', 'birthDate')).toBe('null | Date');
+    expect(typeOf(types, 'CreatePersonRequest', 'firstVisit')).toBe('Date');
+  });
+
+  it('follows $ref from the request body into nested schemas', async () => {
+    const types = await typesFromDocument(openApiDocument());
+
+    expect(typeOf(types, 'GuardianPayload', 'since')).toBe('Date');
+  });
+
+  it('keeps a date in a response as string, since JSON cannot return a Date', async () => {
+    const types = await typesFromDocument(openApiDocument());
+
+    expect(typeOf(types, 'PersonResponse', 'birthDate')).toBe('null | string');
+  });
+
+  it.each([
+    ['a schema also used by a response', 'EventBody', 'day'],
+    ['a schema also used by a parameter', 'AgendaFilter', 'from'],
+  ])('keeps the date of %s as string', async (_, schemaName, property) => {
+    const types = await typesFromDocument(openApiDocument());
+
+    expect(typeOf(types, schemaName, property)).toBe('string');
+  });
+
+  it('never maps an instant, even in a request body', async () => {
+    const types = await typesFromDocument(openApiDocument());
+
+    expect(typeOf(types, 'CreatePersonRequest', 'createdAt')).toBe('string');
+  });
+});
diff --git a/apps/admin-frontend/src/features/clients/ui/clientsPaths.ts b/apps/admin-frontend/src/features/clients/ui/clientsPaths.ts
new file mode 100644
index 00000000..d60e0c7a
--- /dev/null
+++ b/apps/admin-frontend/src/features/clients/ui/clientsPaths.ts
@@ -0,0 +1 @@
+export const CLIENTS_PATH = '/pessoas';
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
index b6ff2506..5f62c786 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.tsx
@@ -2,12 +2,13 @@ import { FormProvider } from 'react-hook-form';
 import { FormErrorBanner } from '@/shared/form/fields';
 import { PageFormFooter } from '@/widgets/form-footer';
 import { PageHeader } from '@/widgets/page-header';
+import { CLIENTS_PATH } from '../../clientsPaths';
 import { ClientGuardiansSection } from './components/ClientGuardiansSection';
 import { ClientPersonSection } from './components/ClientPersonSection';
 import { ClientReferenceContactsSection } from './components/ClientReferenceContactsSection';
 import { useClientFormPage } from './useClientFormPage';
 
-const PAGE_PARENTS = [{ label: 'Pessoas', to: '/pessoas' }];
+const PAGE_PARENTS = [{ label: 'Pessoas', to: CLIENTS_PATH }];
 
 export function ClientFormPage() {
   const { methods, isSaving, onSubmit } = useClientFormPage();
@@ -21,7 +22,7 @@ export function ClientFormPage() {
           <ClientGuardiansSection />
           <ClientReferenceContactsSection />
           <FormErrorBanner />
-          <PageFormFooter isSaving={isSaving} cancelTo="/pessoas" />
+          <PageFormFooter isSaving={isSaving} cancelTo={CLIENTS_PATH} />
         </form>
       </FormProvider>
     </div>
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
index 9976eb13..9336f0fe 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/components/ClientReferenceContactItem.tsx
@@ -54,7 +54,7 @@ function ClientReferenceContactItem({ index, onRemove }: ClientReferenceContactI
           autoComplete="off"
         />
         <PhoneField<ClientFormFieldValues> name={`referenceContacts.${index}.phone`} />
-        <ControlledField<ClientFormFieldValues>
+        <ControlledField<ClientFormFieldValues, `referenceContacts.${number}.purposes`>
           name={`referenceContacts.${index}.purposes`}
           label="Finalidades"
           hint="escolha ao menos uma"
@@ -64,7 +64,7 @@ function ClientReferenceContactItem({ index, onRemove }: ClientReferenceContactI
             <CheckboxGroup
               ref={field.ref}
               options={CONTACT_PURPOSE_OPTIONS}
-              value={Array.isArray(field.value) ? (field.value as string[]) : []}
+              value={field.value}
               onValueChange={field.onChange}
               onBlur={field.onBlur}
               aria-label={`Finalidades da pessoa de referência ${position}`}
diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
index e74e83ff..f609575a 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/useClientFormPage.ts
@@ -5,6 +5,7 @@ import { zodResolver } from '@hookform/resolvers/zod';
 import { applyApiProblem } from '@/shared/form/applyApiProblem';
 import { toast } from '@/shared/ui/toast';
 import { clientsRepository } from '../../../api/clientsRepository';
+import { CLIENTS_PATH } from '../../clientsPaths';
 import {
   clientFormSchema,
   emptyClientFormFieldValues,
@@ -13,8 +14,6 @@ import {
 } from './clientForm';
 import type { UseClientFormPageResult } from './useClientFormPage.types';
 
-const CLIENTS_PATH = '/pessoas';
-
 export function useClientFormPage(): UseClientFormPageResult {
   const navigate = useNavigate();
   const isMountedRef = useRef(true);
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagDeletePage/useTagDeletePage.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagDeletePage/useTagDeletePage.ts
index f17e960c..2a03021f 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagDeletePage/useTagDeletePage.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagDeletePage/useTagDeletePage.ts
@@ -4,6 +4,7 @@ import { toast } from '@/shared/ui/toast';
 import { tagsRepository } from '../../../api/tagsRepository';
 import { deleteTag } from '../../../application/tagUseCases';
 import type { Tag } from '../../../model/tag';
+import { TAGS_PATH } from '../../tagsPaths';
 import type { UseTagDeletePageResult } from './useTagDeletePage.types';
 
 export function useTagDeletePage(): UseTagDeletePageResult {
@@ -18,7 +19,7 @@ export function useTagDeletePage(): UseTagDeletePageResult {
       void navigate(-1);
       return;
     }
-    void navigate({ pathname: '/tags', search: location.search }, { replace: true });
+    void navigate({ pathname: TAGS_PATH, search: location.search }, { replace: true });
   }, [navigate, canGoBack, location.search]);
 
   useEffect(() => {
diff --git a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
index 24cfc3e2..2425dfe0 100644
--- a/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
+++ b/apps/admin-frontend/src/features/tags/ui/pages/TagFormPage/useTagFormPage.ts
@@ -6,6 +6,7 @@ import { toast } from '@/shared/ui/toast';
 import { applyApiProblem } from '@/shared/form/applyApiProblem';
 import { tagsRepository } from '../../../api/tagsRepository';
 import { createTag, updateTag } from '../../../application/tagUseCases';
+import { TAGS_PATH } from '../../tagsPaths';
 import {
   tagFormSchema,
   toTagFormFieldValues,
@@ -36,7 +37,7 @@ export function useTagFormPage(): UseTagFormPageResult {
       void navigate(-1);
       return;
     }
-    void navigate({ pathname: '/tags', search: location.search }, { replace: true });
+    void navigate({ pathname: TAGS_PATH, search: location.search }, { replace: true });
   }, [navigate, canGoBack, location.search]);
 
   useEffect(() => {
diff --git a/apps/admin-frontend/src/features/tags/ui/tagsPaths.ts b/apps/admin-frontend/src/features/tags/ui/tagsPaths.ts
new file mode 100644
index 00000000..3e43aa90
--- /dev/null
+++ b/apps/admin-frontend/src/features/tags/ui/tagsPaths.ts
@@ -0,0 +1 @@
+export const TAGS_PATH = '/tags';
diff --git a/apps/admin-frontend/src/shared/form/fields/components/controlled-field.tsx b/apps/admin-frontend/src/shared/form/fields/components/controlled-field.tsx
index db3bd4bd..9c9861f8 100644
--- a/apps/admin-frontend/src/shared/form/fields/components/controlled-field.tsx
+++ b/apps/admin-frontend/src/shared/form/fields/components/controlled-field.tsx
@@ -1,18 +1,18 @@
-import { Controller, useFormContext, type FieldValues } from 'react-hook-form';
+import { Controller, useFormContext, type FieldValues, type Path } from 'react-hook-form';
 import { FormField } from '@/shared/ui/form-field';
 import type { ControlledFieldProps } from '../fields.types';
 
-export function ControlledField<T extends FieldValues>({
+export function ControlledField<T extends FieldValues, N extends Path<T> = Path<T>>({
   name,
   label,
   hint,
   labelHtmlFor,
   children,
-}: ControlledFieldProps<T>) {
+}: ControlledFieldProps<T, N>) {
   const { control } = useFormContext<T>();
 
   return (
-    <Controller
+    <Controller<T, N>
       name={name}
       control={control}
       render={({ field, fieldState }) => (
diff --git a/apps/admin-frontend/src/shared/form/fields/fields.types.ts b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
index 52dcf82e..edaabfe0 100644
--- a/apps/admin-frontend/src/shared/form/fields/fields.types.ts
+++ b/apps/admin-frontend/src/shared/form/fields/fields.types.ts
@@ -56,15 +56,12 @@ export type BirthDateFieldProps<T extends FieldValues> = WithOptionalLabel<
   Omit<DateFieldProps<T>, 'minDate' | 'maxDate'>
 >;
 
-export interface ControlledFieldProps<T extends FieldValues> {
-  name: Path<T>;
+export interface ControlledFieldProps<T extends FieldValues, N extends Path<T> = Path<T>> {
+  name: N;
   label: string;
   hint?: string | undefined;
   labelHtmlFor?: boolean | undefined;
-  children: (
-    field: ControllerRenderProps<T, Path<T>>,
-    controlProps: FormFieldControlProps,
-  ) => ReactNode;
+  children: (field: ControllerRenderProps<T, N>, controlProps: FormFieldControlProps) => ReactNode;
 }
 
 export interface ColorFieldProps<T extends FieldValues> {

From 1f459abf541b3497e85438cc3f5f32534d88f770 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 16:31:11 -0300
Subject: [PATCH 29/30] 432

---
 .claude/skills/agenza-form-field/SKILL.md | 5 ++++-
 .claude/skills/agenza-ptbr-copy/SKILL.md  | 5 +++++
 apps/admin-frontend/docs/ARCHITECTURE.md  | 2 +-
 3 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/agenza-form-field/SKILL.md b/.claude/skills/agenza-form-field/SKILL.md
index d5267f62..ee87f360 100644
--- a/.claude/skills/agenza-form-field/SKILL.md
+++ b/.claude/skills/agenza-form-field/SKILL.md
@@ -136,7 +136,10 @@ keys, the collapsed `""` key for a 409/404) lives in `formErrors.ts` alone. See
    `FieldValues`), but silently accepts any string as `name`, losing the one thing worth keeping. A
    native-input field (`register()`-bound) is `TextField`/`TextareaField`. A custom control needs
    `ControlledField` (pass a render function) or a named specialization built on top of it, per the
-   rule below.
+   rule below. When the render function needs the value's own type, pass the path as the second type
+   argument and drop any cast: with
+   ``<ControlledField<XFormFieldValues, `contacts.${number}.purposes`> …>``, `field.value` is that
+   array, not the union of every value in the form.
 
 5. **A CPF, phone, e-mail or birth date is not configured by hand: reuse the pair.** The schema half
    comes from that value's file in `@/shared/values/` (`cpfSchema` from `@/shared/values/cpf`, then
diff --git a/.claude/skills/agenza-ptbr-copy/SKILL.md b/.claude/skills/agenza-ptbr-copy/SKILL.md
index f2e17843..ba4db7a8 100644
--- a/.claude/skills/agenza-ptbr-copy/SKILL.md
+++ b/.claude/skills/agenza-ptbr-copy/SKILL.md
@@ -70,6 +70,11 @@ palette.
 | **Nenhum(a) … ainda** | Sem resultados, Lista vazia, Nada por aqui | The never-created empty state. |
 | **Não foi possível …** | Erro ao …, Falha ao …, Ops! | Names the action that failed, then the next step. |
 
+The domain nouns follow the same rule from the other side: the screen says **Pessoa**, **Responsável**,
+**Pessoa de referência**, **Etiqueta**, while the code keeps the backend's English names (`Client`,
+`ClientGuardian`, `ClientReferenceContact`, `Tag`). The full screen × code table is in
+[`docs/ARCHITECTURE.md` §1](../../../apps/admin-frontend/docs/ARCHITECTURE.md), under "Vocabulary".
+
 ## Where strings and formatters live
 
 **There is no message catalog and no `t()`.** Internationalisation beyond pt-BR is explicitly out of
diff --git a/apps/admin-frontend/docs/ARCHITECTURE.md b/apps/admin-frontend/docs/ARCHITECTURE.md
index 40b213eb..60470eab 100644
--- a/apps/admin-frontend/docs/ARCHITECTURE.md
+++ b/apps/admin-frontend/docs/ARCHITECTURE.md
@@ -437,7 +437,7 @@ Chosen, and — just as important — tried and backed out of, so nobody re-liti
 | `widgets/form-footer` exports `DialogFormFooter` and `PageFormFooter` instead of one `FormFooter` that switched on `cancelTo` | Asked for, in review of #174. Passing `cancelTo` or not chose between two different footers, `DialogClose` inside `DialogFooter` or a `Link` back that becomes a disabled button while saving, so `<FormFooter isSaving canSubmit />` in `TagFormPage` read as generic while it only works inside a `Dialog`, and a page that forgot `cancelTo` silently got a dialog footer. Each footer now names where it belongs and `PageFormFooter` requires `cancelTo`; the **Salvar**/**Salvando…** button both render is the folder's internal `FormSubmitButton`. One folder, because it is one concept with two placements. |
 | A value more than one form carries (CPF, phone, e-mail, birth date) is one file in `shared/values/`: its `parseX`, limits, rules and Zod schema together. `shared/format/` keeps only the policy-free `date.ts` and `age.ts`; `shared/form/schemas/` is gone | Asked for, in review of #174, collapsing the first two of the three layers above. Reading or changing a CPF meant `shared/format/cpf.ts`, `shared/form/schemas/cpf.ts` with its barrel, and `cpf-field.tsx`; `format/` also held policy (`ADULT_AGE_IN_YEARS`, `MAX_AGE_IN_YEARS`), not only formatting; and `schemas/birthDate.ts` exported `ageFromBirthDate`, which is not a schema and ran Zod on every render of `BirthDateField`. `shared/values/<value>.ts` mirrors the backend's `Admin.SharedKernel.ValueObjects` one file per value object (`CpfNumber` ↔ `cpf.ts`), so a new value type (a CNPJ) is one file plus, if several forms configure it the same way, a preset field. `ageFromBirthDate(masked, today = todayUtc())` composes `parseMaskedDate`, `isInThePast` and `isWithinMaxAge` itself. The preset fields stay in `shared/form/fields/`: keeping the React half apart lets `model/` import a value's rules (`features/clients/model/client.ts` imports `isMinorOn`) without pulling React in; it does pull Zod, which the three-layer row already accepted. No barrel, as `shared/format/` never had one: imports are `@/shared/values/cpf`. Tests are merged per value (`cpf.test.ts` covers `parseCpf`, `maskCpf` and `cpfSchema`). |
 | `DateField` has no key handler of its own: the keyboard reaches the calendar through its **Abrir calendário** button (Tab, Enter or Space; Esc closes and returns focus to the button), and the arrow keys stay with the input | Asked for, in review of #174. An `onKeyDown` on the input opened the calendar on `↓`, the only key handler in `src/`, against AGENTS.md's "prefer the primitive's behaviour to a key handler of your own". `↓`-opens is the combobox pattern, which needs `role="combobox"`, `aria-expanded`, `aria-haspopup` and `aria-controls` on the input; without them a screen reader user had no way to learn it existed, and adding them would have been more hand-written behaviour, not less. It also replaced any `onKeyDown` a caller passed, since the spread came first. The input plus a button that opens the calendar as a dialog is the WAI-ARIA date picker dialog pattern, and Base UI's `PopoverTrigger` already gives it all. A test pins both halves: the keyboard path through the button, and `↓` in the input opening nothing. |
-| `ControlledField` takes the field's path as an optional second type argument, `ControlledField<T, N extends Path<T> = Path<T>>` | Asked for, in review of #174. With only `T`, `field` was typed over every path of the form, so `field.value` was the union of all its values and the reference contact's purposes needed `field.value as string[]`. Passing the path (`ControlledField<ClientFormFieldValues, \`referenceContacts.${number}.purposes\`>`) types `field.value`as that field's own value,`ContactPurpose[]`. The default keeps every other call site as it was. The cost is the second explicit argument: TypeScript does not infer one type argument when another is given. |
+| `ControlledField` takes the field's path as an optional second type argument, `ControlledField<T, N extends Path<T> = Path<T>>` | Asked for, in review of #174. With only `T`, `field` was typed over every path of the form, so `field.value` was the union of all its values and the reference contact's purposes needed `field.value as string[]`. Passing the path (``ControlledField<ClientFormFieldValues, `referenceContacts.${number}.purposes`>``) types `field.value` as that field's own value, `ContactPurpose[]`. The default keeps every other call site as it was. The cost is the second explicit argument: TypeScript does not infer one type argument when another is given. |
 | A slice names its own URL once, in `ui/<slice>Paths.ts` (`CLIENTS_PATH`, `TAGS_PATH`); `app/`keeps writing the path | Asked for, in review of #174:`/pessoas`was written three times inside`features/clients`, `/tags`twice inside`features/tags`. The constant sits in `ui/`rather than in one page's folder, because the list (#155) and editing (#156) navigate to the same place.`app/routes.tsx`, `app/shell/navigation.ts`and`app/pages/Clients.tsx`keep the literal:`app/` owns the route table, and taking the constant from the slice would mean the shell importing the slice barrel, which risks pulling a lazily loaded slice into the main bundle. Tests and e2e keep the literal too, since they check the URL contract. |
 
 The palette opens from the header button. The single-use `LinkButton` wrapper was removed; its remaining link uses `buttonVariants` directly. The combobox keeps only the parts used by the palette, and those parts are in the coverage gate.

From 9f89aeaaa9b45c70a5edaa8015787cfe88b03867 Mon Sep 17 00:00:00 2001
From: Everton William Thoele Schuster <everton.schuster98@gmail.com>
Date: Mon, 12 Oct 2026 16:53:39 -0300
Subject: [PATCH 30/30] =?UTF-8?q?test(admin-frontend):=20remove=20o=20test?=
 =?UTF-8?q?e=20de=20CPF=20de=20cadastro=20exclu=C3=ADdo=20(#154)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

O teste existia para garantir que o link "Abrir cadastro existente" não
aparecesse sem meta.clientId. O link saiu em ebc59b0 e o caso nunca vem do
backend: pelo ADR 0044, excluir a pessoa libera o CPF, então uma pessoa
excluída não gera Client.DuplicateCpf. Sem a checagem do link, o teste só
repetia o anterior com uma mensagem que o backend não emite.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../ClientFormPage/ClientFormPage.test.tsx    | 24 -------------------
 1 file changed, 24 deletions(-)

diff --git a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
index 263a18f2..67f97b02 100644
--- a/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
+++ b/apps/admin-frontend/src/features/clients/ui/pages/ClientFormPage/ClientFormPage.test.tsx
@@ -559,30 +559,6 @@ describe('ClientFormPage', () => {
       expect(screen.getByTestId('location')).toHaveTextContent('/pessoas/nova');
     });
 
-    it('explains a CPF that belongs to a deleted record', async () => {
-      const user = userEvent.setup();
-      mockCreate.mockResolvedValue(
-        problem({
-          status: 409,
-          code: 'Client.DuplicateCpf',
-          errors: {
-            Cpf: [
-              {
-                code: 'Client.DuplicateCpf',
-                message:
-                  'Este CPF pertence a um cadastro excluído e não pode ser usado em um novo cadastro.',
-              },
-            ],
-          },
-        }),
-      );
-      renderPage();
-
-      await fillAndSubmit(user);
-
-      expect(await screen.findByText(/pertence a um cadastro excluído/)).toBeInTheDocument();
-    });
-
     it('shows a duplicate e-mail on the e-mail field and keeps everything typed', async () => {
       const user = userEvent.setup();
       mockCreate.mockResolvedValue(