@evertonferreira96/agents 0.0.0-stage → 0.1.0

package/.claude/skills/arch-app/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: arch-app
+description: "Implementa, revisa e refatora apps React Native Expo: boundaries navigation/screens/modules/common, grupos de tela em `src/screens/(public|private)/` com screen fina e `modules.tsx`, services como application layer que devolvem `ServiceResponse` e chamam o client OpenAPI gerado via request autenticado, entities derivadas do contrato, gateways só para fonte fora do OpenAPI, sessão em `expo-secure-store`, env `EXPO_PUBLIC_*` validado com Zod, observabilidade, tema/tokens e testes de regra pura. Use ao criar ou revisar telas, navigators, rotas e deep links, features em `src/modules`, services, auth/sessão, env ou testes de qualquer app Expo. Não use para APIs NestJS (`arch-api`) nem para o web Next.js (`arch-web`); visual e design system vão para `/ui`."
+---
+
+# arch-app
+
+Arquitetura de apps React Native Expo: telas agrupadas e finas, services que são o caso de uso e falam com o client OpenAPI gerado, sessão segura no dispositivo, env validado e observabilidade desde o primeiro service.
+
+```text
+App compõe providers e o root navigator; navigator registra rotas.
+Screen é fina: compõe `Module.*` do seu grupo e, quando orquestra, um controller hook.
+Module interage: estado de UI, chama o service, trata `status`, dá feedback.
+Service é o caso de uso: regra, mock, request autenticado, `ServiceResponse`.
+Entities derivam do contrato gerado: a API é a fonte única do contrato.
+`common` não conhece produto.
+```
+
+Fluxo: `App -> root.navigator -> <nome>.screen -> Module.* -> service -> authedRequest -> api.<org>.<api>.client.<operationId> -> API`.
+
+Placeholders: `<pm>`, `<org>`, `<api>`, `<feature>`, `<acao>`, `<screen>`, `<secao>`; exemplos usam `invoices` e `customers`. ADRs e `AGENTS.md` do repo vencem esta skill.
+
+## Assunto -> reference
+
+| Abra quando for | Reference |
+|---|---|
+| criar ou alterar service, entities, domains, schemas, store da feature, mock, gateway ou query | [references/services.md](references/services.md) |
+| criar ou alterar uma tela: grupo, `modules.tsx`, module, controller hook, service local, Safe Area, teclado, lista, permissão de dispositivo | [references/screens.md](references/screens.md) |
+| mexer em boot, navigator, rota, params, deep link, login/logout/refresh, `secureStorage` ou env | [references/navigation-session.md](references/navigation-session.md) |
+| mexer em componente comum, tema/tokens, marca, formulário, acessibilidade, performance ou observabilidade | [references/ui-mobile.md](references/ui-mobile.md) |
+| testar, revisar PR, propor ADR ou fechar o critério de entrega | [references/review.md](references/review.md) |
+
+## Antes de editar
+
+Levante no repo, nesta ordem:
+
+```txt
+1. package.json do app e da raiz: pm, scripts reais, lint/test vindos do monorepo
+2. versões: Expo, React Native, React Navigation ou expo-router, Zod, TanStack Query, store
+3. aliases: tsconfig.json, babel.config.js, metro.config.js
+4. App.tsx e index.ts: ordem de boot, providers raiz, overlays globais
+5. src/navigation: root/public/private, types.ts, linking.ts, hook de bootstrap
+6. screens.md (inventário de telas) e um grupo vizinho em src/screens/(private)/(<screen>)/
+7. uma feature vizinha em src/modules/<feature>: services, entities, domains
+8. common/services (ServiceResponse, api-error, dedupe, mappers comuns) e common/observability
+9. common/openapi/api.ts (fachada), types.ts e openapi-ts.config.ts (input e output)
+10. sessão: auth store, authedRequest, secureStorage, settings.storage.keys
+11. env: common/env/app.env.ts, .env.example, modo mock
+12. UI comum: common/components, common/theme, common/hooks, common/permissions
+13. testes existentes (*.unit.spec.ts) e onde o runner está configurado
+14. ADRs e AGENTS.md do app
+```
+
+Pronto quando cada item tem um caminho no repo ou "não existe". O que não existe não é importado; script ausente vira lacuna declarada, não comando inventado.
+
+### Onde o repo varia
+
+| Ponto | Padrão desta skill | Repo diferente: siga o repo |
+|---|---|---|
+| Navegação | React Navigation em `src/navigation` | expo-router: `app/_layout.tsx` faz o papel do navigator ([navigation-session.md](references/navigation-session.md)) |
+| Fachada do client | `api.<org>.<api>.{client, settings}` em `common/openapi/api.ts` | outro nome: o critério é um ponto único para `baseUrl`, `cache` e headers globais |
+| Request autenticado | `authedRequest` em `modules/auth/services/` | helper do repo; sem helper, o service lê o token do `secureStorage` |
+| Modo mock | `environment.DATA_SOURCE_MODE === "MOCK"` | sem modo mock: o service não tem o ramo |
+| Store | zustand em `*.store.hook.ts` | store do repo |
+| Cache de servidor | TanStack Query (`AppQueryProvider`) | ausente: estado local + service; adotar pede ADR |
+| Chaves de storage | `settings.storage.keys` | registro de chaves do repo |
+| Testes | `*.unit.spec.ts` ao lado, runner do monorepo | outro runner ou nenhum: [review.md](references/review.md) |
+| Marca dinâmica | `common/brand` | ausente: tokens do tema |
+| `code` de erro | UPPER_SNAKE | formato do repo |
+
+## Mapa
+
+```txt
+App.tsx  index.ts  app.config.ts  app.json  openapi-ts.config.ts  screens.md (inventário de telas)
+src/
+  navigation/
+    root.navigator.tsx          splash até sessão e bootstrap resolverem; Public x Private; providers do fluxo privado
+    public.navigator.tsx  private.navigator.tsx  settings.navigator.tsx  tab-routes.tsx
+    linking.ts  types.ts  use-app-bootstrap.hook.ts  components/
+  screens/(public)/(<screen>)/  screens/(private)/(<screen>)/
+    <nome>.screen.tsx                   uma ou mais telas do grupo; fina: layout, safe area, Module.*
+    modules.tsx                         export const Module = { <Secao>: <Nome>Module }
+    modules/<secao>/<nome>.module.tsx   composição visual da seção
+    modules/<secao>/*.component.tsx     componente local da tela
+    hooks/use-<x>.hook.ts               controller da tela: estado e chamadas a services, quando a tela orquestra vários
+    services/<x>.service.ts             service LOCAL só quando a regra é exclusiva desta tela
+  modules/<feature>/
+    services/<acao>.<feature>.service.ts   application layer: authedRequest + api.<org>.<api>.client.<operationId>; ServiceResponse
+                                           (algumas features usam <acao>-<objeto>.service.ts; ver "Nomes")
+    entities/<feature>.entities.ts         namespace <Feature>.Model / .DTO derivado de Api.<Org>.<Api>.*
+    domains/<feature>.domain.ts (+ .unit.spec.ts)   regra pura
+    schemas/<feature>.schemas.ts           Zod para input de formulário e deep link
+    hooks/<x>.store.hook.ts  hooks/use-<x>.hook.ts   estado da feature compartilhado por telas
+    components/<x>.component.tsx           componente de domínio usado por 2+ telas
+    mappers/<x>.mapper.ts                  tradução entre API e UI
+    mocks/                                 dados do modo mock
+    gateways/<x>.gateway.ts                EXCEÇÃO: fonte fora do contrato OpenAPI (fetch nativo, nunca lança)
+  common/
+    components/<nome>/<nome>.component.tsx + index.ts
+    env/app.env.ts   hooks/{feedbacks,loading,query,pagination,motion}/   observability/   permissions/   brand/   realtime/
+    openapi/api.ts  client.ts  types.ts  <org>/<api>/setup/ (gerado)
+    providers/app.providers.tsx
+    services/service-response.ts  api-error.ts  in-flight-dedupe.ts
+    settings/{routes,storage,times}   storage/secure-storage.ts   theme/{default.theme.ts, tokens/}
+    utils/<tipo>/<nome>.<tipo>.util.ts (+ .unit.spec.ts)
+```
+
+Colocação, do mais local ao mais compartilhado:
+
+- Usado por uma tela: fica no grupo `screens/(…)/(<screen>)/` (`modules/`, `hooks/`, `services/`).
+- Regra, chamada ou tipo usado por 2+ telas: `modules/<feature>/`. Feature é domínio, não tela.
+- Componente de domínio usado por 2+ telas: `modules/<feature>/components/`.
+- Visual sem domínio, reutilizável: `common/components/<nome>/`.
+- Infra sem produto (client, env, storage, observabilidade, tema, permissões): `common/`.
+- Promover é mover no segundo consumidor; até lá, local.
+
+## Camadas
+
+| Camada | Arquivo | Responsabilidade |
+|---|---|---|
+| App | `App.tsx`, `index.ts` | ordem de boot, providers raiz, root navigator, overlays globais (status bar, loader, toast) |
+| Navigation | `src/navigation/*` | rotas, ParamLists, linking, bootstrap de sessão, gate public/private |
+| Screen | `<nome>.screen.tsx` | fina: Safe Area, layout, `Module.*`, controller hook; despacha variante por param |
+| Mapa local | `modules.tsx` | `export const Module = { ... }` com os modules do grupo |
+| Module | `modules/<secao>/<nome>.module.tsx` | interação da seção: estado de UI, chama service, trata `status`, feedback |
+| Componente local | `modules/<secao>/<nome>.component.tsx`, `.modal.tsx` | visual da tela: props entram, eventos saem |
+| Controller | `hooks/use-<x>.hook.ts` (no grupo) | estado e efeitos da tela (foco, polling, realtime), chama services, devolve dados e ações |
+| Service local | `services/<x>.service.ts` (no grupo) | view model e chamadas exclusivas do grupo, com o contrato do service da feature |
+| Service da feature | `services/<acao>.<feature>.service.ts` | um caso de uso por arquivo: regra, mock, request autenticado, `ServiceResponse` |
+| Entities | `entities/<feature>.entities.ts` | `<Feature>.Model` / `.DTO` derivados de `Api.<Org>.<Api>.*` (fonte única) e tipos de UI que a API não tem |
+| Domains | `domains/<feature>.domain.ts` | regra pura, limites, opções |
+| Schemas | `schemas/<feature>.schemas.ts` | Zod do input de formulário, deep link e texto livre |
+| Mappers | `mappers/<x>.mapper.ts` | tradução API ↔ UI |
+| Hooks da feature | `hooks/<x>.store.hook.ts`, `hooks/use-<x>.hook.ts` | store de fluxo entre telas; hook reutilizado por 2+ telas |
+| Components da feature | `components/<x>.component.tsx` | componente ou provider de domínio usado por 2+ telas |
+| Mocks | `mocks/` | massa de dados do modo mock |
+| Gateway (exceção) | `gateways/<x>.gateway.ts` | fonte fora do OpenAPI: `fetch` com timeout, resultado discriminado |
+| Common | `src/common/*` | infra sem produto |
+
+## Nomes
+
+| Arquivo | Export / formato |
+|---|---|
+| `<nome>.screen.tsx` | `<Nome>Screen`; props por `<Area>ScreenProps<"<Rota>">` |
+| `<nome>.module.tsx` | `<Nome>Module`, registrado em `Module.<Secao>` |
+| `<nome>.overview.module.tsx` | module principal da tela ou da aba de visão geral |
+| `<nome>.component.tsx`, `<nome>.modal.tsx` | componente local; modal ou sheet local |
+| `<nome>.step.tsx`, `<nome>.items.ts`, `<nome>.storage.ts` | etapa de fluxo multi-step; itens estáticos da tela (menu, opções); flag local não sensível |
+| `use-<x>.hook.ts` | `use<X>` (controller: `use<X>Controller`) |
+| `<x>.store.hook.ts` | `use<X>Store` |
+| `<acao>.<feature>.service.ts` (feature no singular para item, plural para lista: `create.invoice`, `list.invoices`); algumas features usam `<acao>-<objeto>.service.ts` | `<nome em camelCase>Service`; na feature existente, siga a forma dela |
+| `<feature>.entities.ts` | `namespace <Feature> { Model; DTO.<Acao>.{Input, ApiBody, Output} }` |
+| `<feature>.schemas.ts` | `<feature>Schemas = { <acao>: z.object(...) }` + `namespace <Feature>Schema` |
+| `<feature>.domain.ts` | constantes `UPPER_SNAKE` e funções puras |
+| `<x>.mapper.ts` | `map<X>` (função pura) |
+| `<x>.gateway.ts` | `fetch<X>Gateway`, tipo `<X>GatewayResult` |
+| `<area>.navigator.tsx` | `<Area>Navigator` |
+| `<nome>.<tipo>.util.ts` | utilitário em `common/utils/<tipo>/`, com `index.ts` |
+| `*.unit.spec.ts` | teste ao lado do arquivo testado |
+| evento de observabilidade | `<feature>.<acao>` (`invoices.create`) |
+| `code` de erro | `<FEATURE>_<ACAO>_FAILED` ou o motivo de negócio (`INVOICE_REQUIRES_LINES`) |
+
+## Caminho de uma ação
+
+```txt
+module ou controller (onPress)
+  -> <acao>.<feature>.service.ts
+       withServiceObservability("<feature>.<acao>", async () => {
+         regra de negócio     -> serviceFailure("<CODE>", mensagem)          (inline ou domains/)
+         modo mock?           -> serviceSuccess(mock)
+         authedRequest((accessToken) => api.<org>.<api>.client.<operationId>({
+           baseUrl, cache, headers: Authorization, path, query, body }))
+         res.error            -> serviceFailure("<FEATURE>_<ACAO>_FAILED", apiErrorMessage(res.error, fallback))
+                                 (ou o mapper de falha comum, quando a API devolve uma família de erro conhecida)
+         sucesso              -> serviceSuccess(res.data.data)                 (envelope desembrulhado)
+       })
+  <- ServiceResponse
+module ou controller
+  status "success" -> atualiza estado, navega, feedback de sucesso
+  status "error"   -> useFeedbackHook.show({ message, mode: "error" }); fieldErrors no formulário
+  espera           -> ação que trava a tela: useLoadingHook.show() e hide() no finally
+                      ação local: estado submitting do próprio module
+```
+
+Leitura de tela: `screen -> controller (efeito de foco) -> list service (dedupe em voo) -> estado -> Module.<Lista>`.
+
+## Regras não negociáveis
+
+1. **Screen fina.** Screen e module falam com services; `common/openapi` é importado só por services (da feature ou locais) e por entities (`import type`).
+2. **Request pelo service.** O service chama `api.<org>.<api>.client.<operationId>` com `baseUrl` e `cache` de `api.<org>.<api>.settings`; rota autenticada vai dentro de `authedRequest`, que entrega o token e renova a sessão no 401; rota pública (login, cadastro, recuperação) chama o client sem token.
+3. **Gateway é exceção.** `gateways/` serve só fonte fora do contrato OpenAPI: `fetch` com timeout, devolve `{ data } | { error }` e nunca lança. Operação que existe no contrato vai pelo client gerado.
+4. **`ServiceResponse` sempre.** Todo service roda dentro de `withServiceObservability("<feature>.<acao>", ...)` e devolve `serviceSuccess` ou `serviceFailure`; a UI decide por `status`.
+5. **Erro com `code` estável e mensagem útil.** `code` UPPER_SNAKE do app; mensagem da API (`apiErrorMessage(error, fallback)`) quando ela explica o motivo, texto do service quando não; status HTTP e corpo do erro ficam fora da tela (diagnóstico vai para o log). App com i18n segue o web: mensagem traduzida pelo `code`; a da API fica no log.
+6. **Input tipado e validado.** O service recebe o DTO de `entities`; formulário, deep link e texto livre passam pelo Zod de `schemas/` antes de chegar ao service; regra que barra a chamada é `serviceFailure` antes do request.
+7. **Mock dentro do service.** O ramo do modo mock vive só no service, depois das regras e antes do request; module e screen chamam o service igual nos dois modos.
+8. **Sessão no `secureStorage`.** Token e usuário da sessão ficam só no `secureStorage` (wrapper de `expo-secure-store`) com chaves de `settings.storage.keys`; o header `Authorization` nasce no callback do `authedRequest`.
+9. **Gate no root.** O root navigator segura o splash até o bootstrap resolver a sessão e escolhe `Public` ou `Private`; providers do fluxo privado envolvem só o `PrivateNavigator`.
+10. **Params tipados e leves.** Toda rota tem ParamList em `navigation/types.ts`; params levam ids e dicas leves de exibição (título, thumbnail, estado vindo da lista); objeto inteiro e dado sensível ficam fora, e o resto vem do service.
+11. **Env fail-closed.** `EXPO_PUBLIC_*` vai inteiro para o bundle: só valor não secreto. Schema Zod em `common/env/app.env.ts`, `assertAppEnv()` no `AppProviders`, leitura no uso (getter ou função), https fora de local/dev.
+12. **Log com redaction.** Logs passam pelo `logger` de `common/observability`; `console.*` e devtools ficam sob `__DEV__` (exceção: o diagnóstico de env inválido, que precisa aparecer em release).
+13. **Tela completa.** Safe Area, teclado e estados loading/error/empty em toda tela; lista longa em `FlatList`/`FlashList` (pelo wrapper de `common/components`, quando existe).
+14. **Gerado não se edita.** `common/openapi/<org>/<api>/setup/` sai do `openapi-ts.config.ts`; operação faltando, contrato errado ou `operationId` ruim se corrige na API (`arch-api`) e se regenera com `openapi:generate`.
+15. **Boundaries.** `common` não importa `screens` nem `modules`; `domains` e `entities` não importam React/RN.
+16. **Gate de entrega.** Cada script da tabela "Comandos" roda no seu gatilho; o inventário `screens.md` do app reflete as telas do diff; mudança nativa declara iOS e Android testados ou "não testado".
+
+## Protocolo: nova tela
+
+```txt
+1. Leia o inventário screens.md do app e um grupo vizinho de complexidade parecida.
+   Pronto: você cita o path do grupo que serve de modelo.
+2. Escolha o grupo: rotas que dividem modules, controller ou service local (lista e detalhe, etapas de um
+   fluxo, variantes) ficam no mesmo grupo; assunto sem nada em comum ganha (<screen>)/ novo.
+   Variante da mesma rota por param: "Variantes da mesma rota" em references/screens.md.
+   Pronto: o grupo escolhido e o motivo cabem em uma frase.
+3. Registre a rota: ParamList em types.ts, Stack.Screen ou tab no navigator, linking.ts se há deep link.
+   Pronto: navigation.navigate("<Rota>", params) compila sem cast.
+4. Crie <nome>.screen.tsx fina, modules.tsx e os modules por seção.
+   Pronto: a screen só importa Module, o controller (se houver), tipos de navegação e componentes de layout.
+5. Controller hook e service local: só pelo critério de [references/screens.md](references/screens.md).
+6. Service: reutilize ou crie em modules/<feature> (protocolo abaixo).
+7. Feche a regra 13 com a mecânica de references/screens.md.
+   Pronto: cada fluxo assíncrono da tela tem carregando, erro, vazio e conteúdo.
+8. Atualize o inventário screens.md do app. Pronto: a linha da tela aponta grupo, rota e status.
+9. Rode typecheck. Pronto: verde, ou o erro relatado com arquivo e linha.
+```
+
+## Protocolo: novo service
+
+```txt
+1. Confirme a operação no client gerado (sdk.gen.ts / operationId); faltando ou errada: regra 14.
+   Pronto: api.<org>.<api>.client.<operationId> existe e tipa.
+2. DTO em entities: <Feature>.DTO.<Acao>.{Input, ApiBody, Output} derivados de Api.<Org>.<Api>.*.
+   Pronto: o service não declara tipo de request ou response à mão.
+3. Regra pura reutilizável ou que merece teste: domains/ (+ .unit.spec.ts).
+4. Escreva <acao>.<feature>.service.ts pelo template de [references/services.md](references/services.md):
+   observabilidade -> regra -> mock -> authedRequest -> erro -> sucesso.
+5. Leitura que várias telas ou efeitos disparam ao mesmo tempo: dedupe em voo (references/services.md).
+6. Integre no module ou controller pelo "Caminho de uma ação". Pronto: os dois status têm tratamento na UI.
+7. Spec da regra pura quando há runner. Pronto: typecheck verde e spec verde (ou lacuna declarada).
+```
+
+## Comandos
+
+Descubra os nomes reais no `package.json`; em monorepo, `<pm> --filter <app> <script>`.
+
+| Script | Gatilho |
+|---|---|
+| `typecheck` | toda mudança TypeScript (gate mínimo) |
+| `openapi:generate` | operação nova ou alterada na API |
+| `openapi:check` | contrato ou client gerado mudou |
+| `deps:check`, `doctor` | dependência, plugin Expo, `app.json`/`app.config`, asset nativo |
+| `start`, `prebuild`, builds de plataforma | validar em device ou simulador |
+| lint e test | os do monorepo, quando existirem |
+
+## Anti-padrões
+
+Sintomas que aparecem no diff, cada um com a regra que resolve.
+
+- `import { api }` ou `fetch(` num module, screen ou controller → regras 1 e 3.
+- `if (environment.DATA_SOURCE_MODE` fora de um service → regra 7 (o app de referência tem uma exceção num module de upload; não copie).
+- Service devolvendo `res.data` com o envelope quando o consumidor espera o item → "Caminho de uma ação".
+- `throw` num service para erro esperado da API → regra 4.
+- Objeto inteiro do recurso passado em `navigation.navigate` → regra 10.
+- `environment.<X>` ou `appEnv.<X>` lido no escopo do módulo → regra 11.
+- `ScrollView` com `.map` numa lista que cresce → regra 13.
+- Arquivo em `common/openapi/<org>/<api>/setup/` alterado sem `openapi:generate` → regra 14.
+- Componente, hook ou service duplicado entre grupos de tela → colocação.
+
+## Critério de entrega
+
+```txt
+[ ] inventário feito; o padrão do vizinho foi seguido (path citado)
+[ ] regras 1-16 conferidas no diff, cada uma ok ou "não se aplica"
+[ ] protocolo da mudança (tela, service) completo até o último passo
+[ ] scripts rodados no gatilho, com resultado, ou lacuna declarada
+[ ] divergências do repo em relação a esta skill registradas, com migração incremental
+[ ] resumo com paths concretos e o que não foi testado em device
+```

package/.claude/skills/arch-app/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Arch App"
+  short_description: "Implementa, revisa e refatora apps React Native Expo: boundaries..."

package/.claude/skills/arch-app/references/navigation-session.md

@@ -0,0 +1,257 @@
+# Navegação, sessão e env
+
+Abra ao mexer em boot, navigator, rota, params, deep link, login/logout/refresh, `secureStorage` ou env. As regras (gate no root, params leves, sessão no `secureStorage`, env fail-closed) estão no SKILL.md; aqui fica a mecânica.
+
+## Ordem de boot
+
+```txt
+index.ts
+  1. import do handler global de erro (primeira linha: erro JS não tratado vira alerta nativo, não tela branca)
+  2. polyfills que outros módulos exigem no import (ex.: crypto.getRandomValues)
+  3. devtools só em __DEV__ (require dentro do if)
+  4. registerRootComponent(App)
+App.tsx
+  GestureHandlerRootView > KeyboardProvider > ErrorBoundary > AppProviders >
+    RootNavigator + StatusBar + overlays globais (loader, toast)
+AppProviders (common/providers/app.providers.tsx)
+  assertAppEnv() -> SafeAreaProvider -> AppQueryProvider -> children
+```
+
+`assertAppEnv()` roda dentro do `ErrorBoundary`: env inválido mostra a mensagem do schema na tela em vez de derrubar o app no import.
+
+## Root navigator
+
+```tsx
+// src/navigation/root.navigator.tsx
+const Stack = createNativeStackNavigator<RootStackParamList>();
+
+export function RootNavigator() {
+  const isAuthenticated = useAuthStore((state) => state.isAuthenticated);
+  const isLoading = useAuthStore((state) => state.isLoading);
+  const { minSplashElapsed, onboardingSeen } = useAppBootstrap();
+
+  // Splash até sessão, onboarding e tempo mínimo resolverem: o Public não mostra um segundo splash.
+  if (isLoading || !minSplashElapsed || onboardingSeen === null) return <SplashScreen />;
+
+  return (
+    <NavigationContainer linking={linking}>
+      <Stack.Navigator screenOptions={{ headerShown: false }}>
+        {!isAuthenticated ? (
+          <Stack.Screen name="Public" navigationKey="public">
+            {() => <PublicNavigator onboardingSeen={onboardingSeen} />}
+          </Stack.Screen>
+        ) : (
+          <Stack.Screen name="Private" navigationKey="private">
+            {() => (
+              <RealtimeProvider>
+                <DomainProvider>{/* provider de domínio de uma feature */}
+                  <PrivateNavigator />
+                  <NotificationBanner />
+                </DomainProvider>
+              </RealtimeProvider>
+            )}
+          </Stack.Screen>
+        )}
+      </Stack.Navigator>
+    </NavigationContainer>
+  );
+}
+```
+
+- A troca `Public` ↔ `Private` acontece pelo `isAuthenticated` da auth store; `navigationKey` descarta o histórico da outra pilha.
+- Providers do fluxo privado (regra 9): realtime, provider de domínio de uma feature (`modules/<feature>/components/`), e overlays que dependem deles (banner de notificação) como irmãos do `PrivateNavigator`.
+- Telas e services chamam `setUser`/`clearUser` da store; nenhuma tela navega para `Public`/`Private` à mão.
+
+## Navigators
+
+```txt
+public.navigator.tsx    pilha anônima (onboarding, login, cadastro, recuperação)
+private.navigator.tsx   pilha privada: rota de bottom tabs (`MainTabs`) + rotas empilhadas sobre as tabs
+settings.navigator.tsx  pilha aninhada de configurações, registrada como uma rota do private
+tab-routes.tsx          TAB_ROUTES (name, component, label, onPress?), ícones e a rota central
+components/             peças só da navegação (tab bar customizada, header de pilha)
+```
+
+- Rota nova em pilha: `<Stack.Screen name="<Rota>" component={<Nome>Screen} options={{ animation }} />` no navigator da área; a screen vem do grupo em `src/screens/(…)/(<screen>)/`.
+- Opções visuais (`animation`, `presentation: "fullScreenModal"`, `contentStyle`) ficam no `Stack.Screen`; cor por token do tema.
+- Tab nova: entrada em `TAB_ROUTES` e chave em `PrivateTabParamList`.
+- Overlay de todas as telas privadas que não depende de provider do root (assistente flutuante) é irmão do `Stack.Navigator` dentro do `PrivateNavigator`.
+
+## `types.ts`
+
+```ts
+export type PublicStackParamList = { Welcome: undefined; SignIn: undefined };
+export type PrivateTabParamList = { Dashboard: undefined; CustomersTab: undefined };
+export type PrivateStackParamList = {
+  MainTabs: NavigatorScreenParams<PrivateTabParamList>;
+  Invoices: { customer?: string } | undefined;
+  InvoiceDetail: {
+    invoice: string;
+    kind?: "draft" | "issued";
+    /** dica de exibição enquanto o detalhe carrega */
+    title?: string;
+  };
+  CreateInvoice: { customer?: string } | undefined;
+};
+export type RootStackParamList = { Public: undefined; Private: undefined };
+
+export type PrivateScreenProps<T extends keyof PrivateStackParamList> = NativeStackScreenProps<PrivateStackParamList, T>;
+```
+
+- Uma ParamList por pilha ou tab; um alias `<Area>ScreenProps<T>` por ParamList.
+- Param opcional: `{ ... } | undefined`, para a rota abrir sem params (menus que navegam por `keyof` exigem).
+- A dica de exibição pinta a tela antes do service responder; quando o service responde, vale o dado dele.
+- Param que decide permissão ou estado sensível é conferido pela API na chamada do service.
+
+## `linking.ts`
+
+```ts
+function resolvePrefixes(): string[] {
+  try {
+    return [Linking.createURL("/")];
+  } catch {
+    return []; // build sem scheme: deep link desligado, app sobe
+  }
+}
+
+export const linking: LinkingOptions<RootStackParamList> = {
+  prefixes: resolvePrefixes(),
+  config: {
+    screens: {
+      Public: { screens: { SignIn: "sign-in" } },
+      Private: {
+        screens: {
+          MainTabs: { screens: { Dashboard: "dashboard" } },
+          InvoiceDetail: "invoices/:invoice",
+        },
+      },
+    },
+  },
+};
+```
+
+- `createURL` roda no import e lança em build sem scheme; o `try/catch` mantém o app de pé.
+- A árvore de `config.screens` espelha a árvore de navigators; rota com deep link entra aqui no mesmo PR.
+- Deep link para rota privada com usuário anônimo cai no `Public`; param de deep link chega como string (regra 6).
+
+## Bootstrap de sessão
+
+`src/navigation/use-app-bootstrap.hook.ts` roda uma vez no root:
+
+```txt
+1. tempo mínimo de splash (timer)
+2. sincronizações com fallback embutido (ex.: manifesto de marca): fire-and-forget, o splash não espera
+3. flags locais (onboarding visto) lidas do storage
+4. sessão:
+   a. identidade de instalação: instalação nova ou restore em outro aparelho descarta a sessão herdada do keychain
+   b. access token no secureStorage e não expirado -> restaura o usuário salvo
+   c. senão -> refresh; autenticado -> restaura o usuário; falhou -> clearUser()
+   d. qualquer exceção -> clearUser(); finally -> setLoading(false)
+```
+
+Usuário salvo é JSON no `secureStorage`; parse inválido vira `clearUser()`.
+
+## Auth store e `secureStorage`
+
+- Auth store (`modules/auth/hooks/auth.store.hook.ts`): `user`, `isAuthenticated`, `isLoading`, `setUser`, `clearUser`, `setLoading`. Guarda o usuário para a UI; tokens ficam fora dela.
+- `common/storage/secure-storage.ts` envolve `expo-secure-store` com cache em memória:
+
+```ts
+const cache = new Map<string, string | null>();
+
+export const secureStorage = {
+  get: async (key: string) => {
+    const cached = cache.get(key);
+    if (cached !== undefined) return cached;                 // `null` lido também é memorizado
+    const value = await SecureStore.getItemAsync(key);
+    cache.set(key, value);
+    return value;
+  },
+  set: async (key: string, value: string) => {
+    try { await SecureStore.setItemAsync(key, value); cache.set(key, value); }
+    catch (error) { cache.delete(key); throw error; }       // write nativo falhou: o cache não afirma nada
+  },
+  delete: async (key: string) => {
+    try { await SecureStore.deleteItemAsync(key); cache.set(key, null); }
+    catch (error) { cache.delete(key); throw error; }
+  },
+  clearCache: () => cache.clear(),
+};
+```
+
+- O cache evita idas ao keychain a cada request; ele só fica coerente porque todo write da aplicação passa pelo wrapper. Módulo que precisa de chave própria fora do wrapper usa chaves próprias e documenta.
+- Chaves em `common/settings/storage/keys.storage.ts`, expostas como `settings.storage.keys.<chave>` (`accessToken`, `refreshToken`, `user`, ...).
+- Flag não sensível (onboarding visto, preferência local) pode usar storage comum, num `<nome>.storage.ts` ao lado de quem lê.
+
+## Refresh, 401 e logout
+
+- O retry no 401 é do `authedRequest` ([services.md](services.md)); ele e o bootstrap usam o mesmo service de refresh (`refresh-session.auth.service.ts`).
+- Renovação única: requests concorrentes com 401 esperam a mesma promise de refresh (requisito e lacuna em [services.md](services.md)).
+- Refresh que falha limpa tokens e usuário; a auth store volta a anônimo e o root troca para `Public`.
+- Logout resiliente: tenta revogar na API sem bloquear; apaga `accessToken`, `refreshToken` e `user` do `secureStorage`; `clearUser()`.
+
+```ts
+export async function logoutAuthService(): Promise<ServiceResponse<null>> {
+  return withServiceObservability("auth.logout", async () => {
+    const refreshToken = await secureStorage.get(settings.storage.keys.refreshToken);
+    if (refreshToken) {
+      // Revogação na API pelo client gerado; API fora do ar não bloqueia o logout local.
+      await api.<org>.<api>.client.<logoutOperationId>({ baseUrl: api.<org>.<api>.settings.url, body: { refreshToken } })
+        .catch(() => undefined);
+    }
+    await Promise.all([
+      secureStorage.delete(settings.storage.keys.accessToken),
+      secureStorage.delete(settings.storage.keys.refreshToken),
+      secureStorage.delete(settings.storage.keys.user),
+    ]);
+    useAuthStore.getState().clearUser();
+    return serviceSuccess(null);
+  });
+}
+```
+
+## Env
+
+```ts
+// src/common/env/app.env.ts
+const schema = z
+  .object({
+    API_URL: z.string().url(),
+    APP_ENV: z.enum(["local", "development", "staging", "production"]).default("production"),
+    OBSERVABILITY_ENABLED: z.enum(["true", "false"]).default("true").transform((v) => v === "true"),
+    DATA_SOURCE_MODE: z.enum(["MOCK", "REAL"]).default("REAL"),
+  })
+  .refine((env) => env.APP_ENV === "local" || env.APP_ENV === "development" || env.API_URL.startsWith("https://"), {
+    path: ["API_URL"],
+    message: "API_URL deve usar https:// quando APP_ENV é staging ou production.",
+  });
+
+const raw = {
+  API_URL: process.env.EXPO_PUBLIC_API_URL,           // acesso estático: é o que o bundler inlina
+  APP_ENV: process.env.EXPO_PUBLIC_APP_ENV,
+  OBSERVABILITY_ENABLED: process.env.EXPO_PUBLIC_OBSERVABILITY_ENABLED,
+  DATA_SOURCE_MODE: process.env.EXPO_PUBLIC_DATA_SOURCE_MODE,
+};
+const result = schema.safeParse(raw);
+
+export const error: Error | null = result.success ? null : new Error(/* issues + valores recebidos */);
+
+// Válido: objeto plano. Inválido: Proxy que lança com a mensagem acima em qualquer leitura.
+export const environment = result.success
+  ? result.data
+  : (new Proxy({}, { get: (_t, key) => { throw new Error(`[environment] leitura de "${String(key)}" com env inválido.\n\n${error?.message}`); } }) as z.infer<typeof schema>);
+
+export function assertAppEnv(): void {
+  if (error) throw error;
+}
+```
+
+- A mensagem de erro lista as issues e os valores crus recebidos no bundle, para o diagnóstico apontar a variável ausente (o default de `APP_ENV` esconde um `undefined`).
+- Além do getter da regra 11: código que roda em todo service e lê uma flag (`withServiceObservability`) envolve a leitura em `try/catch` e assume o valor seguro.
+- `common/env/index.ts` reexporta o mesmo objeto validado (na referência, como `appEnv`); siga o nome que o vizinho importa.
+- Variável nova: schema, `raw`, `.env.example` e configuração de build no mesmo PR.
+- Segredo que o app precisa vem da API ou da sessão em tempo de execução.
+
+## expo-router
+
+Repo com expo-router: siga o repo. `app/_layout.tsx` faz o papel do root navigator (providers, splash até o bootstrap resolver, redirecionamento por sessão), o `_layout.tsx` dos grupos `(public)`/`(private)` faz o papel dos navigators de área, e cada arquivo de rota em `app/` delega para a screen em `src/screens/(…)/(<screen>)/`. Params chegam por `useLocalSearchParams` como string e passam pelo schema antes de uso sensível. `screens`, `modules`, `common`, services e sessão seguem esta skill sem mudança.