diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..0f2ca1d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,299 @@
+# portal-modumfiscal-web — Contexto para IA
+
+Portal público de autoatendimento fiscal do contribuinte. SaaS multi-tenant: cada
+prefeitura cliente tem seu próprio subdomínio (`tutoia.modumfiscal.com.br`) e uma
+identidade visual distinta (cor primária + foto de fundo + logo).
+
+Projeto irmão: `core-modumfiscal-web` (backoffice interno da prefeitura, outra repo).
+Backend compartilhado: API REST Spring Boot em `https://sistema.modumfiscal.com.br`.
+
+---
+
+## Stack
+
+| Dependência | Versão | Observação |
+|---|---|---|
+| Vue | 3.5 | `<script setup>` obrigatório |
+| Vite | 8 | Plugin `@tailwindcss/vite` (sem PostCSS) |
+| PrimeVue | 4.5 | Tema Aura, auto-importado via `unplugin-vue-components` |
+| `@primeuix/themes` | 2 | `updatePreset`, `updateSurfacePalette`, `definePreset` |
+| TailwindCSS | 4 | `@import "tailwindcss"` no CSS — **sem `tailwind.config.js`** |
+| Vue Router | 5 | `createWebHistory` |
+| Pinia | 3 | `pinia-plugin-persistedstate` |
+| Axios | 1.x | Dois clientes: público e autenticado |
+| Zod | 4 | Validação de formulários (usar nos wizards) |
+
+---
+
+## Arquitetura Multi-Tenant
+
+```
+subdomínio (ex: tutoia.modumfiscal.com.br)
+    └── getTenant() → 'tutoia'
+          └── bootstrapPrefeitura() → GET /api/v1/publico/prefeitura/tutoia
+                └── prefeituraStore.$patch({ nomePrefeitura, template, pathLogo, ... })
+                      └── App.vue onMounted → applyTemplate('tutoia')
+                            └── PrimeVue recebe cor primária laranja (tutoia)
+```
+
+**Ordem de inicialização em `main.js` (crítica — não alterar):**
+1. `createPinia()` + `pinia.use(persistedstate)`
+2. `await bootstrapPrefeitura(pinia)` — busca config da prefeitura antes de montar
+3. `app.use(router)`
+4. `app.use(PrimeVue, primeVueConfig)`
+5. `app.mount('#app')`
+6. `App.vue onMounted` → `applyTemplate(prefeitura.template)` — aplica cor dinâmica
+
+> **Por que `applyTemplate` fica no `onMounted` e não no bootstrap?**
+> `updatePreset()` exige que o PrimeVue já esteja inicializado. No bootstrap,
+> o `app.use(PrimeVue)` ainda não rodou. Chamá-la antes causa erro silencioso.
+
+---
+
+## Detecção de Tenant
+
+```js
+// src/utils/tenant.js
+getTenant() → hostname.split('.')[0]
+           → localStorage('current_dominio')  // fallback
+           → 'sistema'                         // último fallback
+```
+
+`localhost` é inválido propositalmente — em dev, o bootstrap falha graciosamente
+e o app sobe sem tema personalizado (usa `blue` como padrão).
+
+---
+
+## Theming Dinâmico
+
+Templates disponíveis em `src/config/theme.config.js`:
+`sistema · tutoia · amber · blue · indigo · violet · emerald · teal · rose`
+
+O campo `template` retornado pela API (ex: `"tutoia"`) determina a paleta primary.
+A superfície é sempre `slate` — não mudar.
+
+Para adicionar novo município com foto de fundo:
+1. Colocar a imagem em `src/assets/images/bg-NOME.jpeg`
+2. Importar em `HomeView.vue` e adicionar ao `heroBgMap`
+3. Cadastrar o `template` correspondente em `theme.config.js` se precisar de cor nova
+
+---
+
+## Dark Mode
+
+- Classe `.app-dark` no `<html>` ativa o dark mode
+- PrimeVue: `darkModeSelector: '.app-dark'` em `primevue.config.js`
+- Tailwind: `@variant dark (&:where(.app-dark, .app-dark *))` em `main.css`
+- O widget `AccessibilityWidget.vue` gerencia a classe e persiste no `localStorage`
+
+**Toda view nova deve incluir `dark:` nos utilitários Tailwind.** Referência rápida:
+
+| Light | Dark |
+|---|---|
+| `bg-white` | `dark:bg-slate-900` |
+| `bg-slate-50` | `dark:bg-slate-950` |
+| `bg-slate-100` | `dark:bg-slate-800` |
+| `border-slate-200` | `dark:border-slate-700` |
+| `text-slate-800` | `dark:text-slate-100` |
+| `text-slate-600` | `dark:text-slate-300` |
+| `text-slate-500` | `dark:text-slate-400` |
+| `hover:bg-slate-100` | `dark:hover:bg-slate-800` |
+
+---
+
+## Clientes HTTP
+
+```js
+// src/config/apiClient.js
+apiClientPublico   // sem Authorization — para bootstrap e serviços públicos
+apiClient          // com Bearer token + headers tenant — para /portal/*
+```
+
+Interceptors adicionam automaticamente `X-Municipio` e `X-Dominio` em toda requisição.
+`apiClient` redireciona para `/` em resposta 401.
+
+**Regra:** nunca chamar `apiClient` diretamente em componente — sempre via Service.
+
+---
+
+## Estrutura de Pastas
+
+```
+src/
+├── assets/
+│   ├── main.css              ← Tailwind v4 directives + @variant dark
+│   ├── layout/layout.scss    ← Focus ring, skip link, prefers-reduced-motion, classes a11y
+│   └── images/               ← Logos e fotos de fundo (importação estática Vite)
+├── bootstrap/
+│   └── prefeituraBoot.js     ← Busca config da prefeitura antes de montar o app
+├── components/
+│   ├── common/
+│   │   ├── AppHeader.vue     ← Header público (logo dinâmica, nav)
+│   │   ├── AppFooter.vue     ← Footer com links institucionais
+│   │   ├── ServiceCard.vue   ← Card reutilizável de serviço (público e autenticado)
+│   │   └── AccessibilityWidget.vue  ← Botão flutuante: fonte, dark, alto contraste
+│   └── auth/
+│       └── DocumentoInput.vue  ← Input CPF/CNPJ com máscara automática
+├── composables/
+│   └── useMotion.js          ← prefers-reduced-motion reativo
+├── config/
+│   ├── apiClient.js          ← Axios clients (público + autenticado)
+│   ├── primevue.config.js    ← Aura preset + locale pt-BR
+│   └── theme.config.js       ← Paletas e applyTemplate()
+├── layouts/
+│   ├── PublicLayout.vue      ← Header + Footer + RouterView (rotas públicas)
+│   └── PortalLayout.vue      ← Header autenticado com nav + Sair
+├── router/index.js           ← Rotas + guard requiresAuth
+├── services/
+│   ├── prefeituraService.js  ← GET /publico/prefeitura/{dominio}
+│   └── authService.js        ← Keycloak PKCE (estrutura pronta, integração pendente)
+├── stores/
+│   ├── prefeituraStore.js    ← Config da prefeitura (persiste localStorage)
+│   └── authStore.js          ← Token + userInfo (persiste localStorage)
+├── utils/
+│   └── tenant.js             ← getTenant / setTenant / clearTenant
+└── views/
+    ├── public/               ← Home, Login, PrimeiroAcesso, Credenciamento
+    ├── servicos/             ← ServicosHub, Certidao, Iptu
+    └── portal/               ← Painel, Debitos, Certidoes, Alvaras, Pagamentos, Dados
+```
+
+---
+
+## Rotas
+
+| Path | Nome | Layout | Auth |
+|---|---|---|---|
+| `/` | `home` | Public | ✗ |
+| `/login` | `login` | Public | ✗ |
+| `/primeiro-acesso` | `primeiro-acesso` | Public | ✗ |
+| `/credenciamento` | `credenciamento` | Public | ✗ |
+| `/servicos` | `servicos` | Public | ✗ |
+| `/servicos/certidao` | `certidao` | Public | ✗ |
+| `/servicos/iptu` | `iptu` | Public | ✗ |
+| `/portal/painel` | `painel` | Portal | ✓ |
+| `/portal/debitos` | `debitos` | Portal | ✓ |
+| `/portal/certidoes` | `certidoes-portal` | Portal | ✓ |
+| `/portal/alvaras` | `alvaras` | Portal | ✓ |
+| `/portal/pagamentos` | `pagamentos` | Portal | ✓ |
+| `/portal/dados` | `dados` | Portal | ✓ |
+
+Guard no router: rotas `requiresAuth: true` redirecionam para `home` se não autenticado.
+
+---
+
+## Fluxo de Login (2 etapas)
+
+```
+Home (captura CPF/CNPJ)
+  └── router.push({ name: 'login', query: { doc: documento } })
+        └── LoginView.vue exibe o doc mascarado + campo senha
+              └── entrar() → Keycloak PKCE (a implementar em authService.js)
+                    └── authStore.setSession(token, userInfo)
+                          └── router.push({ name: 'painel' })
+```
+
+O documento trafega como query param (`?doc=01234567890`) — apenas os dígitos,
+sem formatação. `LoginView` faz a máscara localmente.
+
+---
+
+## Variáveis de Ambiente
+
+```bash
+# .env.development.local  (GIT IGNORADO — crie localmente)
+VITE_API_URL=https://sistema.modumfiscal.com.br
+VITE_KEYCLOAK_URL=https://keycloakprod.modumfiscal.com.br
+VITE_KEYCLOAK_REALM=modumfiscal-dev
+VITE_KEYCLOAK_CLIENT_ID=portal-modumfiscal-web
+```
+
+Os arquivos `.env.development` e `.env.production` estão no repo mas vazios —
+servem de template. Os valores reais ficam apenas nos arquivos `.local`.
+
+---
+
+## Regras Críticas de Código
+
+- **`<script setup>` obrigatório** — Options API proibida (exceto `prefeituraStore` que usa Options API por compatibilidade com o padrão do core)
+- **PrimeVue auto-importado** — não adicionar `import Button from 'primevue/button'` manualmente
+- **CSS:** TailwindCSS inline no template — `@apply` proibido — SCSS só em `assets/layout/`
+- **`dark:` em toda view nova** — ver tabela acima
+- **Máximo 300 linhas por componente** — extrair subcomponentes se ultrapassar
+- **Nunca `apiClient` direto em componente** — sempre via Service
+- **`router.push({ name: 'home' })` para "voltar"** — nunca `router.back()` em fluxos críticos (histórico inesperado)
+- **Componentes PrimeVue com `dark:` manual nos wrappers** — PrimeVue já adapta seus internos, mas divs externas precisam de dark: Tailwind
+
+---
+
+## Acessibilidade
+
+Widget flutuante (`AccessibilityWidget.vue`) disponível em todas as telas via `App.vue`.
+Persiste preferências no `localStorage` (chaves: `a11y-fonte`, `a11y-contraste`, `a11y-escuro`).
+
+Classes aplicadas no `<html>`:
+- `a11y-font-lg` → fonte 18px
+- `a11y-font-xl` → fonte 20px
+- `a11y-contrast` → `filter: contrast(1.45)`
+- `app-dark` → dark mode (PrimeVue + Tailwind)
+
+ARIA implementada: skip link, `aria-label`, `aria-current`, `role="alert"`, `aria-live`,
+`aria-hidden` em ícones decorativos, `role="contentinfo"` no footer.
+
+---
+
+## Como Adicionar Nova Tela Pública
+
+1. Criar `src/views/servicos/MinhaView.vue`
+2. Adicionar rota em `src/router/index.js` dentro do bloco `PublicLayout`
+3. Incluir botão voltar (`router.push({ name: 'home' })`) no topo
+4. Adicionar `dark:` em todos os utilitários Tailwind
+5. (Opcional) Adicionar no `servicosPublicos` de `HomeView.vue`
+
+---
+
+## Como Adicionar Nova Tela Autenticada
+
+1. Criar `src/views/portal/MinhaView.vue`
+2. Adicionar rota em `src/router/index.js` dentro do bloco `PortalLayout` com `meta: { requiresAuth: true }` já herdado do pai
+3. Criar serviço em `src/services/` que use `apiClient` (nunca `apiClientPublico`)
+4. Adicionar no `navItems` de `PortalLayout.vue` se entrar na navegação principal
+5. Adicionar `dark:` em todos os utilitários Tailwind
+
+---
+
+## O Que Está Pendente
+
+| Feature | Arquivos envolvidos | Observações |
+|---|---|---|
+| Keycloak PKCE real | `authService.js`, `LoginView.vue` | Estrutura pronta, falta integrar `pkce-challenge` |
+| Wizard Credenciamento | `CredenciamentoView.vue` | 6 etapas: dados pessoais, endereço, documentos, representante, confirmação |
+| Wizard Primeiro Acesso | `PrimeiroAcessoView.vue` | 4 etapas: identificação, código, nova senha, confirmação |
+| Certidão (implementação real) | `CertidaoView.vue` | Input CPF/CNPJ → POST API → download PDF |
+| IPTU (implementação real) | `IptuView.vue` | Input inscrição imobiliária → GET débitos → carnê PDF |
+| Endpoint avisos carousel | `HomeView.vue` | `GET /api/v1/publico/avisos/{dominio}` (dados mockados atualmente) |
+| Campo `pathBackground` na API | `prefeituraBoot.js` | Backend ainda não retorna — mapeamento estático por `template` como POC |
+
+---
+
+## Comandos
+
+```bash
+npm run dev      # dev server (http://localhost:5173)
+npm run build    # build produção
+npm run lint     # ESLint + fix
+```
+
+---
+
+## Pitfalls Conhecidos
+
+| Erro | Correto |
+|---|---|
+| `applyTemplate()` no bootstrap | Chamar no `App.vue onMounted` — PrimeVue precisa estar inicializado |
+| `router.back()` no botão voltar | `router.push({ name: 'home' })` — back usa histórico do browser |
+| `import Button from 'primevue/button'` | Não importar — PrimeVue é auto-importado |
+| `@apply` no template | TailwindCSS inline — `@apply` só em `layout.scss` e nunca |
+| Utilitário Tailwind sem `dark:` | Sempre adicionar par dark: para qualquer bg/text/border |
+| `apiClient` direto na view | Criar Service e chamar pela view |
+| Path relativo de logo/foto da API | `resolverUrl()` em `prefeituraBoot.js` converte para URL absoluta |
