diff --git a/CLAUDE.md b/CLAUDE.md
index 35ccaa9..766d139 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -97,7 +97,7 @@ src/
 │   ├── api/
 │   ├── globals.css
 │   └── layout.tsx
-├── features/
+├── features/                      # cada feature segue: actions.ts, queries.ts, actions/, components/, hooks/, lib/
 │   ├── auth/
 │   ├── landing/
 │   ├── dashboard/
@@ -117,9 +117,12 @@ src/
 │   └── settings/
 ├── shared/
 │   ├── components/
-│   │   ├── ui/
-│   │   ├── navigation/
-│   │   ├── providers/
+│   │   ├── ui/                # shadcn/ui primitives
+│   │   ├── navigation/        # navbar, sidebar, breadcrumbs
+│   │   ├── providers/         # React context providers
+│   │   ├── brand/             # logos do app (logo, logo-icon, logo-text)
+│   │   ├── widgets/           # widget-card, widget-empty-state, expandable-widget-card
+│   │   ├── feedback/          # empty-state, status-dot, payment-success
 │   │   ├── month-picker/
 │   │   ├── logo-picker/
 │   │   ├── calculator/
@@ -134,34 +137,56 @@ src/
 │   │   ├── calculator/
 │   │   ├── categories/
 │   │   ├── email/
+│   │   ├── import/
 │   │   ├── installments/
 │   │   ├── invoices/
 │   │   ├── logo/
+│   │   ├── notifications/
 │   │   ├── payers/
 │   │   ├── schemas/
+│   │   ├── storage/
 │   │   ├── transfers/
 │   │   ├── types/
+│   │   ├── version/
 │   │   └── db.ts
 │   └── utils/
 │       ├── period/
+│       ├── calculator.ts
+│       ├── calendar.ts
+│       ├── category-colors.ts
 │       ├── currency.ts
 │       ├── date.ts
+│       ├── export-branding.ts
+│       ├── fetch-json.ts
 │       ├── financial-dates.ts
-│       ├── percentage.ts
-│       ├── category-colors.ts
-│       ├── calendar.ts
+│       ├── icons.tsx
+│       ├── id.ts
+│       ├── initials.ts
 │       ├── math.ts
 │       ├── number.ts
+│       ├── percentage.ts
 │       ├── string.ts
-│       ├── initials.ts
-│       ├── icons.tsx
-│       ├── export-branding.ts
-│       ├── ui.ts
-│       └── calculator.ts
+│       └── ui.ts
 └── db/
     └── schema.ts
 ```
 
+### Estrutura interna padrão de uma feature
+
+Toda feature em `src/features/<nome>/` segue:
+
+```text
+<feature>/
+├── actions.ts        # entry point de Server Actions (barrel quando há actions/)
+├── queries.ts        # entry point de leitura do banco
+├── actions/          # (opcional) Server Actions divididas por domínio quando o volume cresce
+├── components/       # componentes de UI da feature
+├── hooks/            # React hooks específicos da feature
+└── lib/              # helpers, types, sub-queries e constantes internas
+```
+
+`actions.ts` e `queries.ts` são as portas de entrada da feature. Tudo que é helper interno fica em `lib/`. Componentes e hooks ficam nas pastas com nome óbvio.
+
 ---
 
 ## Import Patterns
@@ -299,9 +324,11 @@ export async function fetchData(userId: string, period: string) {
 2. Criar a feature em `src/features/<feature>/`
 3. Separar:
    - `components/`
-   - `queries.ts`
-   - `actions.ts`
-   - `types.ts` ou `schemas.ts` quando fizer sentido
+   - `queries.ts` (entry point de leitura)
+   - `actions.ts` (entry point de Server Actions; vira barrel quando crescer e migrar para `actions/`)
+   - `lib/` para helpers internos, sub-queries por tópico, types e constantes da feature
+   - `types.ts` ou `schemas.ts` quando fizer sentido (alternativa a `lib/`)
+   - `hooks/` quando houver hooks específicos da feature
 4. Extrair para `src/shared/` tudo que for reutilizavel
 5. Atualizar navegacao e `revalidateForEntity()` se a feature tiver CRUD
 6. Rodar:
diff --git a/README.md b/README.md
index 3d4dd96..a1c1d9b 100644
--- a/README.md
+++ b/README.md
@@ -507,7 +507,18 @@ openmonetis/
 │   │   └── auth/                  # Formulários de autenticação
 │   │
 │   ├── shared/                    # Código reutilizado entre features
-│   │   ├── components/            # UI compartilhada (shadcn/ui, navigation, skeletons...)
+│   │   ├── components/            # UI compartilhada
+│   │   │   ├── ui/                #   shadcn/ui primitives
+│   │   │   ├── navigation/        #   navbar, sidebar, breadcrumbs
+│   │   │   ├── brand/             #   logos do app
+│   │   │   ├── widgets/           #   widget-card e variantes
+│   │   │   ├── feedback/          #   empty-state, status-dot, payment-success
+│   │   │   ├── entity-avatar/     #   avatares de categoria/estabelecimento
+│   │   │   ├── month-picker/      #   seletor de período
+│   │   │   ├── logo-picker/       #   seletor de logos
+│   │   │   ├── calculator/        #   calculadora de cálculos rápidos
+│   │   │   ├── skeletons/         #   loading skeletons
+│   │   │   └── providers/         #   React context providers
 │   │   ├── hooks/                 # React hooks globais
 │   │   ├── lib/                   # Helpers de domínio (auth, db, payers, schemas, email...)
 │   │   └── utils/                 # Utilitários (currency, date, period, math, string...)
@@ -523,6 +534,22 @@ openmonetis/
 └── proxy.ts                       # Middleware (auth + multi-domínio)
 ```
 
+### Estrutura interna de uma feature
+
+Toda feature em `src/features/<nome>/` segue o mesmo padrão:
+
+```
+<feature>/
+├── actions.ts        # Server Actions (entry point — barrel re-export quando há actions/)
+├── queries.ts        # Funções de leitura do banco (entry point)
+├── actions/          # (opcional) Server Actions divididas por domínio quando o volume cresce
+├── components/       # Componentes de UI da feature
+├── hooks/            # React hooks específicos da feature
+└── lib/              # Helpers, types, sub-queries e constantes
+```
+
+A regra é: `actions.ts` e `queries.ts` são as portas de entrada da feature. Tudo que é helper interno fica em `lib/`. Componentes e hooks ficam nas pastas com nome óbvio.
+
 ---
 
 ## 🤝 Contribuindo