@seedgrid/ai-toolkit 0.0.0-stage → 0.3.0

package/seedgridKB/SeedGrid/SeedGrid-components/modulos/fe-billing-platform.md

@@ -0,0 +1,132 @@
+---
+tags: [seedgrid, front, modulo, fe-billing-platform]
+fonte: front/seedgrid-fe-components/packages/modules/seedgrid-fe-billing-platform
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# @seedgrid/fe-billing-platform
+
+Módulo front de **billing da plataforma** (backoffice de planos): CRUD de planos, faixas de preço (*terms*) com publicação/arquivamento e configuração do trial. É a visão de quem opera a plataforma; a visão do assinante é o [[SeedGrid/SeedGrid-components/modulos/fe-billing-user|fe-billing-user]]. Compõe sobre o motor de sessão do [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]]. Parte dos [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]].
+
+Backend: [[SeedGrid/Extensions/billing/Visao-geral|extension billing]]. O README cita o `AdminPlanResource` do `seedgrid-report-api`; no monorepo, os mesmos paths `/admin/plans/**` estão em `java/seedgrid-quarkus-ext-billing/seedgrid-billing-core/runtime/src/main/java/br/com/seedgrid/billing/controllers/AdminPlanController.java` (`@MonoCompany`) (verbo e permissões em Limitações).
+
+## Pacote
+
+| Item | Valor |
+|---|---|
+| Nome npm / versão | `@seedgrid/fe-billing-platform` `2026.7.0` |
+| peerDependencies | `@seedgrid/fe-core: *`, `@seedgrid/fe-security: *` |
+| `files` | `dist`, `scaffold` |
+| Build | `tsc -p tsconfig.json` + `postbuild` `emit-module-manifest.mjs` → `dist/module.json` |
+| `exports` | `.` → `./dist/index.{d.ts,js}`; `./server` → `./dist/server/index.{d.ts,js}` |
+
+Dependência de módulo: **requer `security`** (usa `SecurityServer`, `PaginatedResult`; scaffold usa `toRouteResponse` de `@seedgrid/fe-security/server`).
+
+## Exports públicos
+
+| Export | Tipo | Subpath | Descrição | Fonte |
+|---|---|---|---|---|
+| `BillingPlatformPaths` | const | `.` | `plans`, `trial`, `planById`, `terms`, `termById`, `archiveTerm`, `publishTerm` | `front/seedgrid-fe-components/packages/modules/seedgrid-fe-billing-platform/src/paths.ts → BillingPlatformPaths` |
+| `PlanCurrentTerm` | interface | `.` | Term vigente embutido no plano | `.../src/billing-platform.ts → PlanCurrentTerm` |
+| `PlanEntry` | type | `.` | Plano (limiares de cota, `currentTerm`) | `.../src/billing-platform.ts → PlanEntry` |
+| `PlanTermStatus` | type | `.` | `"SCHEDULED" \| "CURRENT" \| "ENDED"` | `.../src/billing-platform.ts → PlanTermStatus` |
+| `PlanTermEntry` | type | `.` | Faixa de preço | `.../src/billing-platform.ts → PlanTermEntry` |
+| `TrialConfig` | interface | `.` | `{ planPublicId; termPublicId; monthlyRequests }` | `.../src/billing-platform.ts → TrialConfig` |
+| `CreatePlanRequest` | interface | `.` | POST/PUT de plano (`name` obrigatório) | `.../src/billing-platform.ts → CreatePlanRequest` |
+| `CreatePlanTermRequest` | interface | `.` | Criação de term (`monthlyPrice`, `overagePrice` obrigatórios) | `.../src/billing-platform.ts → CreatePlanTermRequest` |
+| `CreatePlanTermResponse` | interface | `.` | Term + `published`/`publishError` (publicação automática no provedor) | `.../src/billing-platform.ts → CreatePlanTermResponse` |
+| `PatchPlanTermRequest` | interface | `.` | Edição parcial de term agendado | `.../src/billing-platform.ts → PatchPlanTermRequest` |
+| `PatchTrialRequest` | interface | `.` | `{ monthlyRequests? }` | `.../src/billing-platform.ts → PatchTrialRequest` |
+| `billingPlatformMessages` | const | `.` | i18n `en`, `pt-BR` completos; `es`/`fr` = `en`; `pt-PT` = `pt-BR` | `.../src/messages.ts → billingPlatformMessages` |
+| `createBillingPlatformServer` | função | `./server` | `(session) => BillingPlatformServer` | `.../src/server/create-billing-platform-server.ts → createBillingPlatformServer` |
+| `BillingPlatformServer` | interface | `./server` | 13 métodos (planos, terms, trial) | idem `→ BillingPlatformServer` |
+
+Contagem: `.` = 12; `./server` = 2.
+
+## Registro no @seedgrid/fe-core (manifesto do CLI)
+
+`SeedGridCliModuleManifest` ([[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]]), `src/module.ts`:
+
+| Campo | Valor |
+|---|---|
+| `id` / `configKey` | `billing-platform` |
+| `requires` | `["security"]` |
+| `navigation` | `useBillingPlatformAppShellSections` de `@/modules/billing-platform` |
+| `messages` | `billingPlatformMessages` de `@seedgrid/fe-billing-platform` |
+
+Menu: seção `platform` (order 40) → `platform-billing` → `platform-plans` (`/platform/plans`, badge "readonly" se só leitura) e `platform-trial` (`/platform/plans/trial`); só aparece com `useCrudPermission("PLAN").canRead`.
+
+## Páginas (scaffold) e permissões
+
+| Rota | Arquivo | Permissão |
+|---|---|---|
+| `/platform/plans` | `scaffold/src/app/platform/plans/(list)/page.tsx` | `PLAN_READ` (ações via `useCrudPermission("PLAN")`) |
+| `/platform/plans/new` | `.../(create)/new/page.tsx` → `PlanEditor` | `PLAN_CREATE` |
+| `/platform/plans/[publicId]` | `.../(edit)/[publicId]/page.tsx` → `PlanEditor` + `TermsSection` | `PLAN_READ` |
+| `/platform/plans/trial` | `.../trial/page.tsx` | `PLAN_READ` |
+
+Route Handlers (proxies finos com `toRouteResponse`) em `scaffold/src/app/api/platform/plans/**`: `GET/POST /api/platform/plans`, `GET/POST /api/platform/plans/trial`, `GET/PUT/DELETE /api/platform/plans/[publicId]`, `GET/POST .../[publicId]/terms`, `PATCH/DELETE .../terms/[termId]`, `POST .../terms/[termId]/publish`, `POST .../terms/[termId]/archive`. Bootstrap: `scaffold/src/modules/billing-platform/server.ts.hbs → getBillingPlatformServer`.
+
+## APIs backend chamadas (`createBillingPlatformServer`)
+
+| Método | Path | Função |
+|---|---|---|
+| GET | `/admin/plans` | `listPlans` |
+| POST | `/admin/plans` | `createPlan` |
+| GET | `/admin/plans/{id}` | `getPlan` |
+| PUT | `/admin/plans/{id}` | `updatePlan` |
+| DELETE | `/admin/plans/{id}` | `deletePlan` |
+| GET | `/admin/plans/{id}/terms` | `listTerms` |
+| POST | `/admin/plans/{id}/terms` | `createTerm` |
+| PATCH | `/admin/plans/{id}/terms/{termId}` | `updateTerm` (sem UI) |
+| DELETE | `/admin/plans/{id}/terms/{termId}` | `deleteTerm` |
+| POST | `/admin/plans/{id}/terms/{termId}/archive` | `archiveTerm` |
+| POST | `/admin/plans/{id}/terms/{termId}/publish` | `publishTerm` |
+| GET | `/admin/plans/trial` | `getTrial` |
+| POST | `/admin/plans/trial` | `updateTrial` |
+
+13 chamadas (método+path).
+
+## Separação client/server
+
+Lib `.` client-safe; `./server` SERVER-ONLY. As telas (client) só chamam `/api/platform/plans/**` via `fetch`; os Route Handlers chamam o engine no servidor com o cookie de sessão.
+
+## Configuração
+
+Variáveis de ambiente lidas no scaffold (`server.ts.hbs`) e objeto `billingPlatformConfig`:
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_SECURITY_ACCESS_COOKIE_NAME` | string (env) | nome de cookie | `sg_{{project_slug}}_access_token` (slug substituído pelo CLI) | Não | Nome do cookie do access token usado pela sessão; `trim()`, vazio cai no padrão | `getBillingPlatformServer → createSecurityServer({ cookies.token })` | deve coincidir com o do fe-security (mesma sessão) | runtime server | `scaffold/src/modules/billing-platform/server.ts.hbs → ACCESS_COOKIE_NAME` |
+| `SEEDGRID_SECURITY_REFRESH_COOKIE_NAME` | string (env) | nome de cookie | `sg_{{project_slug}}_refresh_token` | Não | Nome do cookie do refresh token | idem `cookies.refresh` | idem | runtime server | `... → REFRESH_COOKIE_NAME` |
+| `billingPlatformConfig.pagination.defaultPageSize` | number | inteiro | `10` | Não | Página inicial | telas | — | runtime client | `scaffold/src/modules/billing-platform/config.ts → billingPlatformConfig` |
+| `billingPlatformConfig.pagination.pageSizeOptions` | number[] | inteiros | `[10, 20, 50]` | Não | Opções do paginador | telas | — | runtime client | idem |
+| `billingPlatformConfig.routes.*` | string / função | rotas | `plans=/platform/plans`, `newPlan=/platform/plans/new`, `trial=/platform/plans/trial`, `plan(id)=/platform/plans/{id}` | Não | Rotas das telas e do menu | menu e navegação | — | runtime client | idem |
+
+O cookie `passwordChangeRequired` é fixo (`sg_{{project_slug}}_password_change_required`, sem env). A base da API vem de `resolvePublicApiBaseUrl` (`@/modules/security/server/public-api-base-url`, scaffold do [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]]).
+
+## Exemplo (fonte: README)
+
+```ts
+import { createSecurityServer } from "@seedgrid/fe-security/server";
+import { createBillingPlatformServer } from "@seedgrid/fe-billing-platform/server";
+const billingPlatform = createBillingPlatformServer(createSecurityServer({ /* ... */ }));
+const planos = await billingPlatform.listPlans();
+await billingPlatform.publishTerm(planId, termId);
+```
+
+Exemplo real de composição: `scaffold/src/modules/billing-platform/server.ts.hbs`. Sem consumidor em `apps/showcase`.
+
+## Testes (não executados)
+
+`tests/module-manifest.test.mjs` — `id`, `requires`, `configKey`.
+
+## Limitações
+
+- `updateTrial` usa `POST /admin/plans/trial`; na extension billing o path é declarado como `@PATCH`.
+- O backend da extension exige `PLAN_TERM_READ/CREATE/UPDATE/DELETE/PUBLISH/ARCHIVE` para terms e trial; o front só verifica `PLAN_*`.
+- Sem UI para editar term agendado (PATCH).
+- Moeda fixa BRL; traduções `es`/`fr`/`pt-PT` são fallback.
+

package/seedgridKB/SeedGrid/SeedGrid-components/modulos/fe-billing-user.md

@@ -0,0 +1,120 @@
+---
+tags: [seedgrid, front, modulo, fe-billing-user]
+fonte: front/seedgrid-fe-components/packages/modules/seedgrid-fe-billing-user
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# @seedgrid/fe-billing-user
+
+Módulo front de **billing do assinante**: assinatura corrente, uso do ciclo, checkout (1ª assinatura), troca de plano com prévia de rateio, cancelar/reativar, customer portal e faturas. A visão de backoffice é o [[SeedGrid/SeedGrid-components/modulos/fe-billing-platform|fe-billing-platform]]. Compõe sobre o [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]]. Parte dos [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]].
+
+Backend: [[SeedGrid/Extensions/billing/Visao-geral|extension billing]]. Na extension billing, `MeBillingController`, `SubscriptionController`, `PlanCatalogController` e `UsageController` expõem os mesmos `/me/*`, **exceto** os de uso (ver Limitações).
+
+## Pacote
+
+| Item | Valor |
+|---|---|
+| Nome npm / versão | `@seedgrid/fe-billing-user` `2026.7.0` |
+| peerDependencies | `@seedgrid/fe-core: *`, `@seedgrid/fe-security: *` |
+| `files` | `dist`, `scaffold` |
+| Build | `tsc -p tsconfig.json` + `postbuild` `emit-module-manifest.mjs` |
+| `exports` | `.` → `./dist/index.{d.ts,js}`; `./server` → `./dist/server/index.{d.ts,js}` |
+
+Dependência de módulo: **requer `security`**.
+
+## Exports públicos
+
+| Export | Tipo | Subpath | Descrição | Fonte |
+|---|---|---|---|---|
+| `BillingUserPaths` | const | `.` | 13 paths `/me/*` | `front/seedgrid-fe-components/packages/modules/seedgrid-fe-billing-user/src/paths.ts → BillingUserPaths` |
+| `SubscriptionCycle`, `SubscriptionPlanRef`, `SubscriptionPlanTerm`, `SubscriptionPendingChange`, `SubscriptionResponse` | interfaces | `.` | Assinatura corrente (`pendingChange`, `cancelAtPeriodEnd`…) | `.../src/billing.ts` |
+| `UsageAlert`, `UsageSummaryResponse`, `UsageStatementEntry`, `UsageStatementResponse` | interfaces | `.` | Resumo e extrato de uso | `.../src/billing.ts` |
+| `PlanCatalogItem`, `PlansPendingChange`, `PlansCatalogResponse` | interfaces | `.` | Catálogo assinável (`checkoutEnabled`, `current`, `pendingDowngrade`) | `.../src/billing.ts` |
+| `CheckoutRequest`, `CheckoutSessionResponse` | interfaces | `.` | `{ planId }` → `checkoutUrl` | `.../src/billing.ts` |
+| `PortalSessionResponse` | interface | `.` | `portalUrl` (request sem corpo) | `.../src/billing.ts` |
+| `ChangePlanRequest`, `ChangePlanResponse` | interfaces | `.` | `PLAN_CHANGED` / `DOWNGRADE_SCHEDULED` | `.../src/billing.ts` |
+| `CancelScheduledChangeResponse`, `CancelSubscriptionResponse`, `ReactivateSubscriptionResponse` | interfaces | `.` | Status literais | `.../src/billing.ts` |
+| `ChangePreviewResponse` | interface | `.` | Prévia de rateio | `.../src/billing.ts` |
+| `UpcomingInvoiceLine`, `UpcomingInvoiceResponse` | interfaces | `.` | Próxima fatura | `.../src/billing.ts` |
+| `BillingInvoiceEnvelope` | interface | `.` | `{ invoices: Record<string, unknown>[] }` (item cru do provedor) | `.../src/billing.ts` |
+| `billingUserMessages` | const | `.` | i18n `en`/`pt-BR` completos; `es`/`fr` = `en`; `pt-PT` = `pt-BR` | `.../src/messages.ts → billingUserMessages` |
+| `createBillingUserServer` | função | `./server` | `(session) => BillingUserServer` | `.../src/server/create-billing-user-server.ts → createBillingUserServer` |
+| `BillingUserServer` | interface | `./server` | 13 métodos | idem `→ BillingUserServer` |
+
+Contagem: `.` = 26 (1 const de paths + 24 tipos + `billingUserMessages`); `./server` = 2.
+
+## Registro no @seedgrid/fe-core (manifesto do CLI)
+
+`SeedGridCliModuleManifest` ([[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]]): `id: "billing-user"`, `configKey: "billing-user"`, `requires: ["security"]`, `navigation: useBillingUserAppShellSections` (`@/modules/billing-user`), `messages: billingUserMessages` (`@seedgrid/fe-billing-user`). Sem `variantGroup`/`provider` (o teste verifica).
+
+Menu: seção `billing` (order 30) → `billing-user` → `billing-overview` (`/billing`), `billing-plans` (`/billing/plans`), `billing-invoices` (`/billing/invoices`); gated por `BILLING_READ`.
+
+## Páginas (scaffold) e permissões
+
+| Rota | Arquivo | Permissão |
+|---|---|---|
+| `/billing` | `scaffold/src/app/billing/page.tsx` | `BILLING_READ` |
+| `/billing/plans` | `scaffold/src/app/billing/plans/page.tsx` | `BILLING_READ` |
+| `/billing/invoices` | `scaffold/src/app/billing/invoices/page.tsx` | `BILLING_READ` |
+
+Route Handlers em `scaffold/src/app/api/billing/`: `GET me` (combina assinatura + resumo de uso), `GET plans`, `POST checkout`, `POST portal`, `POST change-plan`, `GET change-preview?planId=`, `POST cancel`, `POST cancel-scheduled-change`, `POST reactivate`, `GET invoices?limit=`, `GET upcoming`. Bootstrap: `scaffold/src/modules/billing-user/server.ts.hbs → getBillingUserServer`.
+
+## APIs backend chamadas (`createBillingUserServer`)
+
+| Método | Path | Função |
+|---|---|---|
+| GET | `/me/subscription` | `getSubscription` |
+| GET | `/me/plans` | `listPlans` |
+| GET | `/me/usage/summary` | `getUsageSummary` |
+| GET | `/me/usage/statement` | `getUsageStatement` (sem UI; requer `STATEMENT_READ` segundo comentário) |
+| POST | `/me/billing/checkout` | `createCheckout` |
+| POST | `/me/billing/portal` | `openPortal` |
+| POST | `/me/billing/change-plan` | `changePlan` |
+| POST | `/me/billing/cancel-scheduled-change` | `cancelScheduledChange` |
+| POST | `/me/billing/cancel` | `cancelSubscription` |
+| POST | `/me/billing/reactivate` | `reactivateSubscription` |
+| GET | `/me/billing/invoices?limit=` | `listInvoices` |
+| GET | `/me/billing/upcoming` | `getUpcomingInvoice` |
+| GET | `/me/billing/change-preview?planId=` | `getChangePreview` |
+
+13 endpoints. Na extension, esses controllers são `@Authenticated` (sem `@PermissionsAllowed`) — **Confirmado**.
+
+## Separação client/server
+
+Lib `.` client-safe; `./server` SERVER-ONLY. Telas client chamam apenas `/api/billing/*`.
+
+## Configuração
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_SECURITY_ACCESS_COOKIE_NAME` | string (env) | nome de cookie | `sg_{{project_slug}}_access_token` | Não | Cookie do access token da sessão; vazio cai no padrão | `getBillingUserServer → createSecurityServer` | igual ao fe-security | runtime server | `scaffold/src/modules/billing-user/server.ts.hbs → ACCESS_COOKIE_NAME` |
+| `SEEDGRID_SECURITY_REFRESH_COOKIE_NAME` | string (env) | nome de cookie | `sg_{{project_slug}}_refresh_token` | Não | Cookie do refresh token | idem | idem | runtime server | `... → REFRESH_COOKIE_NAME` |
+| `billingUserConfig.routes.overview` / `.plans` / `.invoices` | string | rotas | `/billing`, `/billing/plans`, `/billing/invoices` | Não | Rotas do menu | `useBillingUserAppShellSections` | — | runtime client | `scaffold/src/modules/billing-user/config.ts → billingUserConfig` |
+
+URLs de sucesso/cancelamento do checkout e retorno do portal são resolvidas **no backend** (`seedgrid.report.billing.checkout.{success,cancel}-url`, `seedgrid.report.billing.portal.return-url`, segundo comentários de `src/billing.ts`) — **Não confirmado** na extension.
+
+## Exemplo (fonte: README)
+
+```ts
+import { createBillingUserServer } from "@seedgrid/fe-billing-user/server";
+const billing = createBillingUserServer(session);
+const assinatura = await billing.getSubscription();
+const preview = await billing.getChangePreview("plan-pro");
+await billing.changePlan({ planId: "plan-pro" });
+```
+
+Sem consumidor em `apps/showcase`.
+
+## Testes (não executados)
+
+`tests/module-manifest.test.mjs` — `id`, `requires`, `configKey`, `variantGroup`/`provider` ausentes, `navigation`, `messages`.
+
+## Limitações
+
+- A extension billing expõe apenas `GET /me/usage`; `getUsageSummary` e `getUsageStatement` (`/me/usage/summary`, `/me/usage/statement`) retornariam 404 contra ela.
+- A extension tem endpoints sem contrato no front: `GET /me/billing/checkout/preview`, `GET|POST /me/billing/downgrade-user-selection`, `POST /me/billing/trial-ended`.
+- O item de fatura é cru do provedor; a tela lê campos estilo Stripe defensivamente.
+- `getUsageStatement` não tem tela; traduções `es`/`fr`/`pt-PT` em fallback.
+

package/seedgridKB/SeedGrid/SeedGrid-components/modulos/fe-login-tenancy.md

@@ -0,0 +1,119 @@
+---
+tags: [seedgrid, front, modulo, fe-login-tenancy]
+fonte: front/seedgrid-fe-components/packages/modules/seedgrid-fe-login-tenancy
+branch: main
+commit: ad30fc11de
+analisado-em: 2026-10-14
+---
+
+# @seedgrid/fe-login-tenancy
+
+Módulo front de **multiempresa por login**: URL única, o usuário escolhe a empresa após o login e o backend re-emite o par de tokens escopado; inclui o signup institucional de empresa (CNPJ) com fluxo de **vinculação** quando o e-mail já existe. Variante exclusiva com [[SeedGrid/SeedGrid-components/modulos/fe-subdomain-tenancy|fe-subdomain-tenancy]] (`variantGroup: "tenancy"`). Compõe sobre o [[SeedGrid/SeedGrid-components/modulos/fe-security|fe-security]]. Parte dos [[SeedGrid/SeedGrid-components/modulos/Visao-geral|Módulos front]].
+
+Backend: [[SeedGrid/Extensions/login-tenancy/Visao-geral|extension login-tenancy]] (signup público, `RestControllerPath` em `java/seedgrid-quarkus-ext-login-tenancy/runtime/src/main/java/br/com/seedgrid/logintenancy/controllers/`) e [[SeedGrid/Extensions/security/Visao-geral|extension security]] (`/me/companies`, `/me/select-company` em `AccountUserController`) — **Confirmado** por leitura dos `RestControllerPath`.
+
+## Pacote
+
+| Item | Valor |
+|---|---|
+| Nome npm / versão | `@seedgrid/fe-login-tenancy` `2026.7.0` |
+| peerDependencies | `@seedgrid/fe-components: *` (opcional), `@seedgrid/fe-core: *`, `@seedgrid/fe-security: *`, `react: ^18.2.0 \|\| ^19.0.0` |
+| devDependencies | workspace `fe-components`, `fe-core`, `fe-security`; `react 19.0.0`; `@types/react ^19` |
+| `files` | `dist`, `scaffold` |
+| Build | `tsc -p tsconfig.json` + `postbuild` `emit-module-manifest.mjs` |
+
+`exports`: `.` → `./dist/index.{d.ts,js}`; `./client` → `./dist/client/index.{d.ts,js}`; `./server` → `./dist/server/index.{d.ts,js}`.
+
+Dependência de módulo: **requer `security`** (usa `SecurityPaths.me`, `isLoginSuccess`, `SecurityLoginResponse`, `SecurityServer`, `applySessionCookies`).
+
+## Exports públicos
+
+| Export | Tipo | Subpath | Descrição | Fonte |
+|---|---|---|---|---|
+| `MyCompany` | interface | `.` | Empresa do usuário (`publicId`, `tradeName`, `corporateName`, `isRoot`) | `front/seedgrid-fe-components/packages/modules/seedgrid-fe-login-tenancy/src/company.ts → MyCompany` |
+| `SelectCompanyResult` | interface | `.` | `{ kind; message? }` (`"signed_in"` = sucesso) | `.../src/company.ts → SelectCompanyResult` |
+| `companyLabel` | função | `.` | `tradeName → corporateName → publicId` | `.../src/company.ts → companyLabel` |
+| `SignupRequestStatus` | type | `.` | `string` | `.../src/signup.ts` |
+| `SignupAddress`, `SignupLegalRepresentative`, `InstitutionalSignupRequest`, `SignupResponse`, `EmailExistsResponse`, `ConfirmSignupRequest`, `ConfirmSignupResponse`, `ResendSignupEmailRequest` | interfaces | `.` | DTOs do signup institucional (`plainRootPassword?` opcional por causa da vinculação) | `.../src/signup.ts` |
+| `LoginTenancyPaths` | const | `.` | `signup`, `signupEmailExists(email)`, `signupConfirmEmail`, `signupResendEmail` | `.../src/paths.ts → LoginTenancyPaths` |
+| `loginTenancyMessages` | const | `.` | i18n `en`/`pt-BR`; `es`/`fr` = `en`; `pt-PT` = `pt-BR` | `.../src/messages.ts → loginTenancyMessages` |
+| `CompanyScopePicker` | componente React | `./client` | Seletor de empresa desacoplado do transporte (props `listCompanies`, `selectCompany`, `onSignedIn`, `onCancel?`, textos, `readError?`); usa `SgCombobox`/`SgButton` | `.../src/client/company-scope-picker.tsx → CompanyScopePicker` |
+| `CompanyScopePickerProps` | interface | `./client` | Props do picker | idem |
+| `createLoginTenancyServer` | função | `./server` | `(session) => LoginTenancyServer` | `.../src/server/create-login-tenancy.ts → createLoginTenancyServer` |
+| `LoginTenancyServer` | interface | `./server` | métodos do servidor (endpoints na seção de APIs backend) | idem |
+| `SelectCompanyOutcome` | interface | `./server` | `{ signedIn; response }` | idem |
+
+Contagem: `.` = 15; `./client` = 2; `./server` = 3.
+
+## Registro no @seedgrid/fe-core (manifesto do CLI)
+
+`SeedGridCliModuleManifest` ([[SeedGrid/SeedGrid-components/pacotes/fe-core|@seedgrid/fe-core]]):
+
+| Campo | Valor |
+|---|---|
+| `id` / `configKey` | `login-tenancy` |
+| `requires` | `["security"]` |
+| `variantGroup` | `tenancy` |
+| `messages` | `loginTenancyMessages` de `@seedgrid/fe-login-tenancy` |
+| `postAuthResolver` | `resolveLoginTenancyPostAuthPath` de `@/modules/login-tenancy` |
+
+`postAuthResolver` é inserido pelo CLI no registry `resolvePostAuthPath` do `navigation.ts` do fe-security; o resolver (`scaffold/src/modules/login-tenancy/post-auth.ts`) faz `GET /api/login-tenancy/companies` e devolve `/auth/select-company` quando há mais de uma empresa (falha → `null`, cai no dashboard). **Confirmado** no código do módulo; o lado do fe-security não foi verificado aqui.
+
+## Páginas (scaffold)
+
+| Rota | Arquivo | Acesso |
+|---|---|---|
+| `/signup` | `scaffold/src/app/(public)/signup/page.tsx` | público; wizard CNPJ/ViaCEP/UF; checa e-mail existente e ativa vinculação |
+| `/auth/select-company` | `scaffold/src/app/auth/select-company/page.tsx` | pós-login; envolve `CompanyScopePicker`; sucesso → `/`, cancelar → `/auth/login` |
+
+Route Handlers em `scaffold/src/app/api/login-tenancy/`: `GET companies`, `POST select-company` (exige `companyPublicId`, 400 se ausente), `POST signup`, `GET signup/email-exists?email=`, `POST signup/confirm-email`, `POST signup/resend-email`. Nenhuma permissão (`RouteGuard`) é usada.
+
+## APIs backend chamadas (`createLoginTenancyServer`)
+
+| Método | Path | Função |
+|---|---|---|
+| GET | `/me/companies` | `listMyCompanies` |
+| POST | `/me/select-company` (body `{ companyPublicId }`) | `selectCompany` (em sucesso persiste cookies via `session.applySessionCookies`) |
+| POST | `/public/signup` | `signup` |
+| GET | `/public/signup/email-exists?email=` | `emailExists` |
+| POST | `/public/signup/confirm-email` | `confirmSignup` |
+| POST | `/public/signup/resend-email` | `resendSignupEmail` |
+
+6 endpoints.
+
+## Separação client/server
+
+`.` client-safe; `./client` React (`"use client"`, depende de `@seedgrid/fe-components`); `./server` SERVER-ONLY. O `server.ts.hbs` do scaffold é `"use server"` e não é reexportado pelo barrel client do scaffold.
+
+## Configuração
+
+| Propriedade | Tipo | Valores aceitos | Padrão | Obrigatória | Comportamento | Uso | Relações | Fase | Origem |
+|---|---|---|---|---|---|---|---|---|---|
+| `SEEDGRID_SECURITY_ACCESS_COOKIE_NAME` | string (env) | nome de cookie | `sg_{{project_slug}}_access_token` | Não | Cookie do access token; vazio cai no padrão | `getLoginTenancyServer → createSecurityServer` | deve coincidir com o fe-security; `selectCompany` regrava esse cookie | runtime server | `scaffold/src/modules/login-tenancy/server.ts.hbs → ACCESS_COOKIE_NAME` |
+| `SEEDGRID_SECURITY_REFRESH_COOKIE_NAME` | string (env) | nome de cookie | `sg_{{project_slug}}_refresh_token` | Não | Cookie do refresh token | idem | idem | runtime server | `... → REFRESH_COOKIE_NAME` |
+
+Props de texto do `CompanyScopePicker` têm padrões em pt-BR (`description`, `companyFieldLabel = "Empresa"`, `confirmLabel = "Entrar"`, `cancelLabel = "Voltar ao login"`).
+
+## Exemplos
+
+Fonte: README.
+
+```ts
+import { createLoginTenancyServer } from "@seedgrid/fe-login-tenancy/server";
+const loginTenancy = createLoginTenancyServer(session);
+const empresas = await loginTenancy.listMyCompanies();
+await loginTenancy.selectCompany(empresas[0].publicId);
+```
+
+Uso real do picker: `scaffold/src/app/auth/select-company/page.tsx`. Sem consumidor em `apps/showcase`.
+
+## Testes (não executados)
+
+`tests/module-manifest.test.mjs` — `id`, `requires`, `variantGroup`, `configKey`.
+
+## Limitações
+
+- `POST /api/login-tenancy/select-company` exige `companyPublicId` no corpo (enviar `{ publicId }` responde 400).
+- A tela `/signup` consulta `/api/locations/states` e `/api/locations/cities`, que só existem no scaffold do `fe-subdomain-tenancy` (mutuamente exclusivo); sem eles os combos de UF/cidade ficam vazios.
+- A extension tem `GET /public/signup/cnpj-status` sem contrato no front.
+