diff --git a/CONTEXT-MAP.md b/CONTEXT-MAP.md
index 72998b24f..687fea251 100644
--- a/CONTEXT-MAP.md
+++ b/CONTEXT-MAP.md
@@ -9,15 +9,17 @@ This is a modular monorepo (`internachi/modular`). Each bounded context lives un
 
 ## Contexts
 
-| Context             | Path                               | Description                                                                                                    |
-| ------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Moderation          | `app-modules/moderation/`          | Content moderation pipeline — classification, routing, enforcement, appeals                                    |
-| Bot Discord         | `app-modules/bot-discord/`         | Discord bot runtime (Laracord websocket, slash commands, event handlers)                                       |
-| Integration Discord | `app-modules/integration-discord/` | Discord platform transport (REST API via Saloon), OAuth, ETL                                                   |
-| Identity            | `app-modules/identity/`            | Users, tenants, external identities, authentication                                                            |
-| Panel Admin         | `app-modules/panel-admin/`         | Filament admin panel — dashboards, resources, moderation UI, marketing                                         |
-| Integration Twitch  | `app-modules/integration-twitch/`  | Twitch platform transport (Helix API via Saloon), OAuth, EventSub webhooks                                     |
-| Integration GitHub  | `app-modules/integration-github/`  | GitHub transport (REST via Saloon), OAuth, community contribution ingestion (backfill + webhooks) + event lake |
+| Context             | Path                               | Description                                                                                                                |
+| ------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Moderation          | `app-modules/moderation/`          | Content moderation pipeline — classification, routing, enforcement, appeals                                                |
+| Bot Discord         | `app-modules/bot-discord/`         | Discord bot runtime (Laracord websocket, slash commands, event handlers)                                                   |
+| Integration Discord | `app-modules/integration-discord/` | Discord platform transport (REST API via Saloon), OAuth, ETL                                                               |
+| Identity            | `app-modules/identity/`            | Users, tenants, external identities, authentication                                                                        |
+| Panel Admin         | `app-modules/panel-admin/`         | Filament admin panel — dashboards, resources, moderation UI, marketing                                                     |
+| Integration Twitch  | `app-modules/integration-twitch/`  | Twitch platform transport (Helix API via Saloon), OAuth, EventSub webhooks                                                 |
+| Integration GitHub  | `app-modules/integration-github/`  | GitHub transport (REST via Saloon), OAuth, community contribution ingestion (backfill + webhooks) + event lake             |
+| Onboarding          | `app-modules/onboarding/`          | Universal, mandatory entry layer — polymorphic onboarding state machines by type; owns the per-type completion gate (APTO) |
+| Squads              | `app-modules/squads/`              | Squad lifecycle, membership and governance (captain/sub-captain, elections, removal, reallocation)                         |
 
 ## Relationships
 
@@ -49,3 +51,5 @@ This is a modular monorepo (`internachi/modular`). Each bounded context lives un
 - **Integration Twitch** depends on Identity (OAuth user resolution, ExternalIdentity for tenant linking). It never imports from Moderation, Integration Discord, or Bot Discord.
 - **Integration GitHub** depends on Identity (OAuth user resolution; future `Character` seam via `ExternalIdentity`). It never imports from Activity, Economy, Moderation or any Bot/runtime module — it only emits the `GithubContributionRecorded` domain event. The community presentation (in `portal`) and the allowlist admin UI (in `panel-admin`) depend on it, never the reverse.
 - **Identity** has no upstream dependencies on other contexts listed here.
+- **Onboarding** depends on Identity (User, tenant scoping, GitHub `ExternalIdentity` link) and listens to `integration-github`'s `GithubPullRequestApproved` domain event (reads the `challenge` repos in the allowlist). It never imports from `squads` — `squads` is a consumer of its completion gate, never the reverse.
+- **Squads** depends on Onboarding (reads the `Squads`-completion gate, "APTO") and Identity (users/tenants). It never imports from presentation; the panels depend on it.
diff --git a/app-modules/onboarding/CONTEXT.md b/app-modules/onboarding/CONTEXT.md
new file mode 100644
index 000000000..1b017dc82
--- /dev/null
+++ b/app-modules/onboarding/CONTEXT.md
@@ -0,0 +1,75 @@
+# Onboarding Context
+
+The universal, mandatory entry layer of the ecosystem. Owns the polymorphic onboarding state
+machines that a person walks through, and the per-type **completion** status that other contexts
+consume as an access gate. Today it powers community entry (`Welcome`) and squad entry (`Squads`),
+but it is designed so new onboarding types are added without touching consumers.
+
+## Glossary
+
+| Term               | Definition                                                                                                                                                                      | Not to be confused with                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| **Onboarding**     | One person's journey through one typed flow, scoped to a tenant. One row per `(tenant, user, type)`. Holds lifecycle `status`, not the per-step detail.                         | The UI wizard (presentation) — the Onboarding is the persisted state machine   |
+| **OnboardingType** | The discriminator enum (`Welcome`, `Squads`, …). Resolves the polymorphic behaviour via `handler(): OnboardingFlow` — same idiom as `IdentityProvider::getClient`.              | A step — a type _has_ steps                                                    |
+| **OnboardingFlow** | The per-type handler (a class behind the `OnboardingFlow` contract). Declares `steps()`, `prerequisites()`, `advance()`, `isComplete()`. All type-specific rules live here.     | The model — the Flow is stateless behaviour; the Onboarding is the state       |
+| **OnboardingStep** | One auditable stage of a flow, one row in `onboarding_steps`. Carries its own `status` + `data` (jsonb) + `completed_at`. Enables pause/resume and history.                     | A prerequisite (another _type_ that must be complete first)                    |
+| **Prerequisite**   | Another `OnboardingType` that must be **completed** before this one can start (e.g. `Squads` requires `Welcome`). Declared by the flow, enforced on start.                      | A step (intra-type) — a prerequisite is inter-type                             |
+| **APTO**           | Domain shorthand for "completed the `Squads` onboarding". The condition that unlocks squad candidacy and squad creation. It is _not_ a global flag — it is `Squads` completion. | A generic "active member" — APTO is specifically squad-eligible                |
+| **Challenge**      | The Git step of the `Squads` flow: open a PR (with the mandatory template) on a `challenge` repo; a human reviewer approves it on GitHub. Curation happens entirely on GitHub.  | A contribution (the gamification record) — challenge repos do **not** award XP |
+| **Gate**           | A pre-condition checked at a transition without being a step of its own. The `Squads` flow gates `git_challenge` on having a linked GitHub `ExternalIdentity`.                  | A step — a gate produces no `onboarding_steps` row                             |
+
+## State machine (shape)
+
+`status` is a generic lifecycle: `in_progress` · `paused` · `completed` · `rejected`. The _steps_ are
+type-specific and defined by the flow. The `Squads` flow:
+
+```
+[prereq: Welcome completed?]
+        │ yes
+        ▼
+   step: form ──(submit, auto-advance, no curation)──►  [gate: GitHub linked?]
+                                                           │ no  -> blocked + CTA "link GitHub"
+                                                           │ yes
+                                                           ▼
+                                          step: git_challenge ──(PR approved on challenge repo)──► completed = APTO
+```
+
+Pause/resume is orthogonal: `status = paused` + `paused_at`, resumable from the current step.
+
+## Structure (proposed)
+
+```
+src/
+├── Models/            ← Onboarding · OnboardingStep
+├── Enums/             ← OnboardingType · OnboardingStatus · OnboardingStepStatus
+├── Contracts/         ← OnboardingFlow
+├── Flows/             ← WelcomeOnboardingFlow · SquadsOnboardingFlow
+├── Actions/           ← StartOnboarding · AdvanceStep · PauseOnboarding · ResumeOnboarding
+├── DTOs/              ← per-step payload contracts (validated by the flow)
+└── Listeners/         ← GithubPullRequestApproved -> advance the challenge step
+```
+
+## Module Boundaries
+
+### This module owns:
+
+- The onboarding state machines (one polymorphic model + steps) and their lifecycle.
+- The per-type **completion** status other modules read as a gate (`Onboarding::isCompleted(user, tenant, type)`).
+- The inter-type prerequisite chain.
+
+### This module does NOT own:
+
+- Squad lifecycle, membership, governance — belongs to `squads` (a consumer of the gate).
+- Any HTTP communication with GitHub or the raw event lake — belongs to `integration-github`. This
+  module **listens to** `GithubPullRequestApproved` and reads `GithubRepository` (`purpose = challenge`).
+- GitHub account linking — belongs to `identity` (`ExternalIdentity`, provider `github`).
+
+## Dependencies
+
+- **Identity** — `User`, tenant scoping, and the GitHub `ExternalIdentity` link (the `git_challenge` gate).
+- **Integration GitHub** — consumes the `GithubPullRequestApproved` domain event and the `challenge`
+  repo allowlist. Never the reverse.
+- Presentation (`panel-app`) drives the UI and calls the module's Actions.
+
+See `docs/adr/0001-onboarding-polimorfico-por-tipo.md` and
+`docs/adr/0002-sinal-de-pr-aprovado-via-evento-de-dominio.md`.
diff --git a/app-modules/onboarding/composer.json b/app-modules/onboarding/composer.json
new file mode 100644
index 000000000..dc3cc0266
--- /dev/null
+++ b/app-modules/onboarding/composer.json
@@ -0,0 +1,27 @@
+{
+    "name": "he4rt/onboarding",
+    "description": "",
+    "type": "library",
+    "version": "1.0.0",
+    "license": "proprietary",
+    "autoload": {
+        "psr-4": {
+            "He4rt\\Onboarding\\": "src/",
+            "He4rt\\Onboarding\\Database\\Factories\\": "database/factories/",
+            "He4rt\\Onboarding\\Database\\Seeders\\": "database/seeders/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "He4rt\\Onboarding\\Tests\\": "tests/"
+        }
+    },
+    "minimum-stability": "stable",
+    "extra": {
+        "laravel": {
+            "providers": [
+                "He4rt\\Onboarding\\Providers\\OnboardingServiceProvider"
+            ]
+        }
+    }
+}
diff --git a/app-modules/onboarding/database/factories/.gitkeep b/app-modules/onboarding/database/factories/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/onboarding/database/migrations/.gitkeep b/app-modules/onboarding/database/migrations/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/onboarding/database/seeders/.gitkeep b/app-modules/onboarding/database/seeders/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/onboarding/docs/adr/0001-onboarding-polimorfico-por-tipo.md b/app-modules/onboarding/docs/adr/0001-onboarding-polimorfico-por-tipo.md
new file mode 100644
index 000000000..f6f5af3b8
--- /dev/null
+++ b/app-modules/onboarding/docs/adr/0001-onboarding-polimorfico-por-tipo.md
@@ -0,0 +1,110 @@
+# ADR-0001: Onboarding polimórfico por tipo, com etapas auditáveis
+
+**Status:** Accepted
+**Date:** 2026-06-15
+**Deciders:** danielhe4rt
+
+## Contexto
+
+Os Squads da He4rt rodam hoje no informal (grupos de WhatsApp, sem liderança formal). A primeira
+entrega de software ataca **governança** (capitão/subcapitão, eleição, etc.) e, antes dela, uma
+camada de **Entrada** que filtra quem realmente quer integrar a comunidade e contribuir.
+
+Essa Entrada — chamada no documento da P.O. de "pré-triagem" — é **universal e obrigatória**:
+ninguém se candidata a um squad nem propõe um squad novo sem concluí-la. Duas perguntas de fronteira
+apareceram:
+
+1. **Esse onboarding é específico de um squad ou global da comunidade?** A pré-triagem é sobre pertencer à comunidade, não a um squad específico, e reusa
+   pesado o `identity` (vínculo GitHub via `ExternalIdentity`). Colocá-la dentro de `squads`
+   amarraria um conceito universal a um consumidor específico.
+2. **Quantos formatos?** O time já enxerga **mais de um tipo de entrada** — `Welcome` (entrada na
+   comunidade) e `Squads` (entrada no programa) — e quer outros no futuro, cada um com seu próprio
+   contrato de payload e processamento.
+
+Modelar a pré-triagem como uma máquina de estados fixa (form → desafio) resolveria o `Squads` de
+hoje, mas não comportaria novos tipos sem refator.
+
+## Decisão
+
+**Criar um módulo de domínio novo, `onboarding`, dono de máquinas de onboarding polimórficas por
+tipo.** `squads` (e futuros consumidores) apenas leem o gate de conclusão.
+
+### Polimorfismo (enum → handler)
+
+- `OnboardingType` (enum) discrimina o tipo e resolve o comportamento via `handler(): OnboardingFlow`
+  — mesmo idioma que `IdentityProvider::getClient()` já usa no `identity`.
+- `OnboardingFlow` (contrato) declara `steps()`, `prerequisites()`, `advance()`, `isComplete()`.
+  Toda regra específica do tipo vive no handler; nenhum consumidor conhece os tipos concretos.
+
+### Persistência (modelo + etapas)
+
+Modelo único discriminado por `type` + tabela de etapas (opção "C" avaliada):
+
+`onboardings` — uma linha por `(tenant_id, user_id, type)`:
+
+| Coluna         | Tipo                         | Notas                                                                 |
+| -------------- | ---------------------------- | --------------------------------------------------------------------- |
+| `id`           | uuid (PK)                    | `HasUuids`                                                            |
+| `tenant_id`    | uuid (FK)                    | tenant-scoped (convenção do repo, multi-tenant-ready)                 |
+| `user_id`      | uuid (FK)                    |                                                                       |
+| `type`         | string                       | `OnboardingType` (`welcome` \| `squads` \| …)                         |
+| `status`       | string                       | ciclo de vida genérico: `in_progress`/`paused`/`completed`/`rejected` |
+| `completed_at` | timestamptz?                 |                                                                       |
+| `paused_at`    | timestamptz?                 |                                                                       |
+| timestamps     | tz                           |                                                                       |
+| UNIQUE         | `(tenant_id, user_id, type)` |                                                                       |
+
+`onboarding_steps` — uma linha por etapa do fluxo:
+
+| Coluna          | Tipo                        | Notas                                             |
+| --------------- | --------------------------- | ------------------------------------------------- |
+| `id`            | uuid (PK)                   |                                                   |
+| `onboarding_id` | uuid (FK)                   |                                                   |
+| `step_key`      | string                      | semântica do handler (`form`, `git_challenge`, …) |
+| `status`        | string                      | `pending`/`done`/…                                |
+| `data`          | jsonb                       | payload da etapa, validado pelo DTO do tipo       |
+| `completed_at`  | timestamptz?                |                                                   |
+| timestamps      | tz                          |                                                   |
+| UNIQUE          | `(onboarding_id, step_key)` |                                                   |
+
+A tabela de etapas (em vez de só um `payload` JSON no modelo) foi escolhida por dar **auditoria e
+histórico por etapa de graça** — relevante pro desafio Git, que tem reenvio com evolução e
+pausa/retoma.
+
+### Cadeia entre tipos
+
+`prerequisites()` declara dependências **inter-tipo**: `Squads` exige `Welcome` concluído para poder
+iniciar. O gate que o `squads` consome é `Onboarding::isCompleted(user, tenant, Squads)` — apelidado
+de **APTO** no domínio.
+
+## Alternativas consideradas
+
+- **Pré-triagem dentro de `identity`** (membership): conceitualmente limpo, mas mistura onboarding
+  evolutivo com o núcleo de autenticação e força `identity` a depender de `integration-github`.
+- **Pré-triagem dentro de `squads`**: entrega rápida, mas amarra um conceito universal a um consumidor
+  e exigiria migração quando outro módulo (eventos, etc.) quiser o mesmo gate.
+- **STI / modelo por tipo**: Laravel não tem STI nativo (exige pacote/boilerplate), foge do idioma
+  `enum→resolve` do repo e incha o schema com colunas nuláveis por tipo. Descartado.
+- **Modelo único só com `payload` JSON (sem tabela de etapas)**: mais simples, mas perde auditoria
+  por etapa. É o passo anterior natural; promovido para a tabela de etapas por causa do desafio Git.
+
+## Consequências
+
+### Positivas
+
+- Somar um tipo novo = +1 case no enum + 1 classe `Flow`. Consumidores intactos.
+- Auditoria etapa-a-etapa nativa (início/fim de cada etapa, tentativas de reenvio).
+- Pausa/retoma natural (estado vive na etapa + `status=paused`).
+- Núcleo do jogo (futuro) pode virar mais um tipo, ou consumir o gate, sem acoplar.
+
+### Negativas / diferidas
+
+- `status`/`step_key` são strings genéricas — a disciplina de transição fica no handler, não no banco.
+- Dois lugares de verdade (`onboardings` + `onboarding_steps`); o `isComplete()` precisa ser a única
+  fonte que decide conclusão para não divergirem.
+- Validação do payload é só de aplicação (DTO), não de schema.
+
+## Review trigger
+
+Revisitar quando (a) o Núcleo do jogo for refinado e a gente decidir se ele é um `OnboardingType` ou
+um consumidor do gate; ou (b) surgir um tipo cujo estado de etapa não caiba no par modelo+steps.
diff --git a/app-modules/onboarding/docs/adr/0002-sinal-de-pr-aprovado-via-evento-de-dominio.md b/app-modules/onboarding/docs/adr/0002-sinal-de-pr-aprovado-via-evento-de-dominio.md
new file mode 100644
index 000000000..8ab15d34e
--- /dev/null
+++ b/app-modules/onboarding/docs/adr/0002-sinal-de-pr-aprovado-via-evento-de-dominio.md
@@ -0,0 +1,87 @@
+# ADR-0002: Sinal de "PR aprovado" via evento de domínio do integration-github
+
+**Status:** Accepted
+**Date:** 2026-06-15
+**Deciders:** danielhe4rt
+**Relates to:** [ADR-0001](0001-onboarding-polimorfico-por-tipo.md); `integration-github`
+
+## Contexto
+
+O step `git_challenge` do `SquadsOnboarding` conclui quando um **revisor humano aprova, no GitHub, o
+PR do candidato** num repo de desafio. A plataforma precisa reagir a essa aprovação.
+
+O `integration-github` já é o **único** ponto que fala com o GitHub: `GithubWebhookController` recebe
+todos os webhooks, grava no `GithubEventLog` (lake, dedup por `delivery_id`), e o `ProjectGithubEvent`
+projeta eventos de repos da allowlist (`GithubRepository`) em `github_contributions`, emitindo
+`GithubContributionRecorded`. A regra de fronteira do módulo é: ele **só emite eventos de domínio e
+nunca importa de outros módulos**.
+
+Duas decisões de acoplamento precisavam ser tomadas:
+
+1. Como o sinal de aprovação chega ao `onboarding` sem duplicar a infra de webhook/HMAC/dedup nem
+   acoplar os módulos.
+2. Como distinguir um "repo de desafio" de um repo de contribuições — sem que o `git_challenge` vire
+   XP de gamification.
+
+## Decisão
+
+### Sinal por evento de domínio
+
+O `integration-github` passa a emitir um **segundo evento de domínio**,
+`GithubPullRequestApproved` (`author_login`, `repo`, `pr_number`, `approved_at`), ao observar
+`pull_request_review` com `state = approved`. O `onboarding` registra um **listener** que resolve o
+`author_login` para um `User` (via `ExternalIdentity` github) e avança o step `git_challenge`.
+
+O transporte continua centralizado num lugar só; HMAC e dedup são reusados; nenhum módulo passa a
+falar com o GitHub além do `integration-github`. É a mesma costura do `GithubContributionRecorded`.
+
+### Repo de desafio via `purpose` na allowlist
+
+`GithubRepository` ganha um campo **`purpose`** (`contributions` | `challenge`):
+
+- Repos `challenge` **não** geram `GithubContributionRecorded` (fazer o desafio não vira XP).
+- O `onboarding` resolve o repo de desafio lendo `GithubRepository::query()->where('purpose', 'challenge')`
+  (tenant-scoped), e ignora aprovações de repos que não sejam de desafio.
+
+O `purpose` é uma **categoria de projeção** legítima do próprio `integration-github` (ele já decide o
+que projetar). O `integration-github` nunca precisa conhecer a palavra "onboarding".
+
+### Vínculo do GitHub é gate, não há reconciliação
+
+O vínculo da conta GitHub (`ExternalIdentity` provider `github`) é **pré-requisito** (gate) para o
+step `git_challenge`. Logo o `author_login` do webhook **sempre** casa um `User`, e o cenário
+"aprovação de conta não vinculada → retém e reconcilia" **deixa de existir** — sem buffer, sem tabela
+de pendências, sem reconciliação. Isso diverge do BDD original da P.O., que previa reconciliação.
+
+## Alternativas consideradas
+
+- **Webhook próprio do `onboarding`** só pro repo de desafio: desacoplaria 100%, mas duplicaria
+  HMAC/dedup e criaria um segundo ponto que fala com o GitHub. Descartado.
+- **`onboarding` relendo o lake (`GithubEventLog`)**: inverteria a dependência (`onboarding` →
+  consulta interna do `integration-github`) e furaria o encapsulamento do lake. Descartado.
+- **Config de repo de desafio dentro do `onboarding`** (em vez do `purpose` na allowlist): manteria o
+  `integration-github` sem nenhuma categoria nova, mas duplicaria o cadastro de repos e perderia o
+  benefício de excluir o repo de desafio da projeção de contribuições num lugar só. Trade-off aceito
+  a favor do `purpose`.
+
+## Consequências
+
+### Positivas
+
+- Um único ponto de integração com o GitHub; HMAC/dedup reusados.
+- Repos de desafio ficam fora da gamification por construção (`purpose`).
+- Sem reconciliação: a máquina de estados fica drasticamente mais simples.
+
+### Negativas / diferidas
+
+- `integration-github` ganha um rótulo (`purpose=challenge`) que existe por causa de um consumidor —
+  acoplamento mínimo e consciente, mitigado por ser categoria de projeção, não lógica de onboarding.
+- O repo de desafio precisa ter o webhook do GitHub instalado apontando pro endpoint do
+  `integration-github` (setup de infra, não de código).
+- Diverge do BDD original (reconciliação removida) — o documento da P.O. precisa ser atualizado.
+
+## Review trigger
+
+Revisitar se algum dia um onboarding precisar reagir a aprovações de conta ainda não vinculada
+(reintroduziria o buffer/reconciliação), ou se mais de um repo de desafio por tenant exigir
+roteamento por tipo de desafio.
diff --git a/app-modules/onboarding/phpstan.ignore.neon b/app-modules/onboarding/phpstan.ignore.neon
new file mode 100644
index 000000000..f51e71c3f
--- /dev/null
+++ b/app-modules/onboarding/phpstan.ignore.neon
@@ -0,0 +1,2 @@
+parameters:
+    ignoreErrors: []
diff --git a/app-modules/onboarding/phpstan.neon b/app-modules/onboarding/phpstan.neon
new file mode 100644
index 000000000..b577d0f29
--- /dev/null
+++ b/app-modules/onboarding/phpstan.neon
@@ -0,0 +1,6 @@
+includes:
+    - phpstan.ignore.neon
+
+parameters:
+    paths:
+        - src/
diff --git a/app-modules/onboarding/src/Providers/OnboardingServiceProvider.php b/app-modules/onboarding/src/Providers/OnboardingServiceProvider.php
new file mode 100644
index 000000000..1558f42d5
--- /dev/null
+++ b/app-modules/onboarding/src/Providers/OnboardingServiceProvider.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace He4rt\Onboarding\Providers;
+
+use Illuminate\Support\ServiceProvider;
+
+class OnboardingServiceProvider extends ServiceProvider
+{
+    public function register(): void {}
+
+    public function boot(): void {}
+}
diff --git a/app-modules/onboarding/tests/Feature/.gitkeep b/app-modules/onboarding/tests/Feature/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/onboarding/tests/Unit/.gitkeep b/app-modules/onboarding/tests/Unit/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/squads/CONTEXT.md b/app-modules/squads/CONTEXT.md
new file mode 100644
index 000000000..d7d7ae514
--- /dev/null
+++ b/app-modules/squads/CONTEXT.md
@@ -0,0 +1,80 @@
+# Squads Context
+
+The system of record for squads: their lifecycle, membership and in-squad roles, plus an append-only
+audit trail of membership events. Governance decisions (elections, removals, reallocation) happen
+**off-system** (Discord/WhatsApp/conversation); this module records their _outcome_ and owns the
+resulting state — it is a ledger, not a workflow engine. Entry into a squad (candidacy) is the one
+flow it actively conducts.
+
+## Glossary
+
+| Term                          | Definition                                                                                                                                                                                      | Not to be confused with                                                           |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **Squad**                     | A tenant-scoped crew with a clear objective. Lifecycle `status`: `draft` → `active` → `inactive` → `archived`. Created by a super-admin (the bottom-up proposal/validation happens off-system). | A WhatsApp group (the informal precursor) — the Squad is the formalized record    |
+| **SquadMember**               | A row in the `squad_members` pivot: one person's standing in one squad. Carries `role`, `joined_at`, `left_at`.                                                                                 | A community member generally — this is squad-scoped standing                      |
+| **Role (in squad)**           | The `squad_members.role` enum: `Captain` · `SubCaptain` · `Member` · `ExMember`. Confers power on the platform: Captain/Sub manage their own squad.                                             | A governance role (super-admin) — that is platform-wide, config-driven            |
+| **Captain / SubCaptain**      | The squad's leadership. They conduct their own squad on the platform: approve/reject candidacy, promote a sub, mark an `ExMember`.                                                              | The Head dos Squads (an off-system human role; in software it is the super-admin) |
+| **ExMember**                  | A person who left (or was removed from) a squad. A role value, not a deletion. Does **not** count toward exclusivity. `left_at` dates the exit.                                                 | A `Member` on leave — there is no "paused membership" state                       |
+| **Application (candidatura)** | An APTO person's request to join a squad (`squad_applications`, `pending`/`approved`/`rejected`). The captain decides; approval creates the membership in a transaction.                        | An onboarding (community/program entry) — that is upstream, in `onboarding`       |
+| **Exclusivity**               | A person may hold at most one _active_ membership (role in `Captain`/`SubCaptain`/`Member`) across all squads. Enforced on join.                                                                | A hard unique DB constraint — `ExMember` rows are allowed to pile up              |
+| **Vacancy**                   | A squad with no active `Captain`. It is the **absence** of a Captain in the pivot, not a status of its own.                                                                                     | The `inactive` squad status (the whole squad is dormant)                          |
+| **Super-admin**               | Platform governance authority, sourced from `config('he4rt.admins')` via `User::isAdmin()`. Creates squads, sets captains, overrides any squad action. Stands in for the "Head/Gestão" roles.   | A Captain — a Captain's power is scoped to their own squad                        |
+| **APTO**                      | The gate this module consumes from `onboarding`: the person completed the `Squads` onboarding. Required to apply or to be in a squad.                                                           | An `active` Squad — APTO is about a person, not a squad                           |
+
+## What this module records vs. conducts
+
+| Flow (P.O. doc)             | In this module (model B — record-keeping)                                                                      |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Candidacy to existing squad | **Conducted**: application → captain decides → membership created (exclusivity checked).                       |
+| Squad creation (bottom-up)  | **Recorded**: super-admin registers the squad (draft→active) with its captain. Proposal/validation off-system. |
+| Captain election            | **Recorded**: runs off-system; the outcome is registered (set captain/sub via promote).                        |
+| Captain exit                | **Recorded**: mark `ExMember` / promote the sub (sub assumes) or leave the seat vacant.                        |
+| Captain removal             | **Recorded**: runs off-system (moderator→management→Head); outcome registered (mark ExMember).                 |
+| Leadership reallocation     | **Recorded**: super-admin moves a leader to another squad.                                                     |
+
+Human rules that stay **out of software** this delivery: ≥1-delivery eligibility, tie-break by Head,
+single-candidate handling, proportional vote minimum, and the "no direct re-election" rule. They are
+applied by humans off-system; only results are recorded. (The open "definition of a delivery" is thus
+not blocking.)
+
+## State & audit
+
+- `squads` — squad state (`status`, `objective`, `slug`, tenant-scoped).
+- `squad_members` — current standing per (squad, user): `role`, `joined_at`, `left_at`.
+- `squad_membership_events` — append-only trail: `action` (`join`/`leave`/`promote`/`demote`/…),
+  `actor_id`, `reason`, `occurred_at`, `metadata`. Answers "who held what, when, and why".
+- `squad_applications` — candidacy requests and their decision.
+
+## Structure (proposed)
+
+```
+src/
+├── Models/      ← Squad · SquadMember · SquadMembershipEvent · SquadApplication
+├── Enums/       ← SquadStatus · SquadRole · MembershipAction · ApplicationStatus
+├── Actions/     ← CreateSquad · ApplyToSquad · DecideApplication · PromoteToSubCaptain ·
+│                  AssignCaptain · MarkExMember · ReallocateLeader · ArchiveSquad
+├── Policies/    ← SquadPolicy (captain/sub of the squad, or super-admin)
+└── DTOs/
+```
+
+## Module Boundaries
+
+### This module owns:
+
+- Squad lifecycle, membership, in-squad roles, and the membership audit trail.
+- The candidacy flow and exclusivity enforcement.
+
+### This module does NOT own:
+
+- The onboarding/APTO gate — it **reads** `Onboarding::isCompleted(user, tenant, Squads)` from `onboarding`.
+- UI — Filament lives in `panel-app` (captain/member) and `panel-admin` (super-admin).
+- Conducting elections/removals — those happen off-system; only outcomes are recorded.
+- The squad game core (all-or-nothing project, scoring, season, redemption) — deferred, not here yet.
+
+## Dependencies
+
+- **Onboarding** — reads the `Squads`-completion gate (APTO). Never the reverse.
+- **Identity** — users, tenants, and super-admin authority (`config('he4rt.admins')`).
+- Presentation panels depend on this module, never the reverse.
+
+See `docs/adr/0001-governanca-como-registro.md`.
diff --git a/app-modules/squads/composer.json b/app-modules/squads/composer.json
new file mode 100644
index 000000000..c7b79a4c9
--- /dev/null
+++ b/app-modules/squads/composer.json
@@ -0,0 +1,27 @@
+{
+    "name": "he4rt/squads",
+    "description": "",
+    "type": "library",
+    "version": "1.0.0",
+    "license": "proprietary",
+    "autoload": {
+        "psr-4": {
+            "He4rt\\Squads\\": "src/",
+            "He4rt\\Squads\\Database\\Factories\\": "database/factories/",
+            "He4rt\\Squads\\Database\\Seeders\\": "database/seeders/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "He4rt\\Squads\\Tests\\": "tests/"
+        }
+    },
+    "minimum-stability": "stable",
+    "extra": {
+        "laravel": {
+            "providers": [
+                "He4rt\\Squads\\Providers\\SquadsServiceProvider"
+            ]
+        }
+    }
+}
diff --git a/app-modules/squads/database/factories/.gitkeep b/app-modules/squads/database/factories/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/squads/database/migrations/.gitkeep b/app-modules/squads/database/migrations/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/squads/database/seeders/.gitkeep b/app-modules/squads/database/seeders/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/squads/docs/adr/0001-governanca-como-registro.md b/app-modules/squads/docs/adr/0001-governanca-como-registro.md
new file mode 100644
index 000000000..70d1ba04b
--- /dev/null
+++ b/app-modules/squads/docs/adr/0001-governanca-como-registro.md
@@ -0,0 +1,85 @@
+# ADR-0001: Governança de squads como registro (record-keeping), não workflow engine
+
+**Status:** Accepted
+**Date:** 2026-06-15
+**Deciders:** danielhe4rt
+**Relates to:** `onboarding/docs/adr/0001` (o gate APTO que este módulo consome)
+
+## Contexto
+
+Os Squads da He4rt rodam hoje no informal — grupos de WhatsApp, **sem liderança formal**
+(capitão/subcapitão). A dor principal é **governança**: dar estrutura de liderança e ter uma fonte da
+verdade de quem é o quê.
+
+O documento da P.O. (camada Governança) ainda está **em validação** e descreve sete fluxos, vários
+deles fortemente humanos: eleição com votação aberta e apuração, remoção que passa por
+moderador→gestão→Head, realocação por análise de encaixe, regras de elegibilidade ("≥1 entrega",
+ainda sem definição fechada), desempate pelo Head e proibição de reeleição direta.
+
+A pergunta de escopo foi: **quanto desses processos o software deve conduzir?** Avaliamos três níveis:
+
+- **Workflow engine completo** — cada fluxo vira processo orquestrado (etapas, fila por papel, SLA,
+  notificações, trilha por etapa).
+- **Registro + automação + eleição na plataforma** — o sistema conduz o determinístico e a votação;
+  decisões discricionárias são ações registradas.
+- **Só registro (record-keeping)** — o sistema é o livro-razão dos estados; os processos acontecem
+  fora e o resultado é lançado.
+
+## Decisão
+
+**Adotar record-keeping (o nível mais enxuto): o `squads` é a fonte da verdade do _estado_, não um
+motor de processo.** Eleição, remoção, saída e realocação acontecem off-system; o módulo registra o
+**resultado** e aplica a mudança de estado, com trilha de auditoria.
+
+A única exceção é a **candidatura a um squad existente** (camada Entrada), que é simples o bastante
+para ser conduzida no sistema: pessoa APTO pede → capitão decide → membership criada.
+
+### Autoridade
+
+- **Super-admins** (de `config('he4rt.admins')`, via `User::isAdmin()`) fazem a gestão: criam squads,
+  definem capitão, e fazem override de qualquer ação. Eles encarnam, no software, os papéis humanos
+  de "Head dos Squads" e "Gestão". Não introduzimos spatie/permission nem Discord-roles para isto.
+- **Capitão / Subcapitão** têm poder **sobre o próprio squad**: aprovar/recusar candidatura, promover
+  sub, marcar `ExMember`. O `role` do pivot, portanto, concede permissão (via `SquadPolicy`).
+
+### Modelo
+
+- `squads` (`status`: `draft`/`active`/`inactive`/`archived`, `objective`, `slug`, tenant-scoped).
+- `squad_members` (pivot): `role` (`Captain`/`SubCaptain`/`Member`/`ExMember`), `joined_at`, `left_at`.
+  Saída/remoção viram `ExMember` (não deleção); vaga de capitania = ausência de `Captain` ativo.
+- `squad_membership_events` (append-only): `action` (`join`/`leave`/`promote`/`demote`/…), `actor_id`,
+  `reason`, `occurred_at`, `metadata` — o "como se chegou aqui".
+- `squad_applications`: candidatura e sua decisão.
+- **Exclusividade**: no máximo uma membership ativa por pessoa (role em Captain/SubCaptain/Member);
+  `ExMember` não conta. Enforçada na Action de entrada.
+
+### Fora do software nesta entrega
+
+Cédula/apuração, candidatura-a-capitão, elegibilidade automática (≥1 entrega), desempate pelo Head,
+mínimo de votos proporcional e "sem reeleição direta" são **regras humanas aplicadas off-system** —
+o sistema apenas registra o desfecho. Isso destrava a entrega sem depender de regras ainda em validação.
+
+## Consequências
+
+### Positivas
+
+- Entrega enxuta, focada na dor real (estrutura de liderança + fonte da verdade).
+- Não acopla o software a regras que a P.O. ainda está validando — mudou a regra, muda o processo
+  humano, o registro continua válido.
+- Trilha de auditoria responde "quem foi capitão quando e por quê".
+- Caminho de evolução claro: promover fluxo a fluxo para condução/automação (ou workflow) se o volume
+  justificar, sem refazer o modelo de estado.
+
+### Negativas / diferidas
+
+- A eleição (apontada como "caos") **continua fora do sistema**; ganhamos o registro do resultado, não
+  a condução. Risco de o estado lançado divergir do que aconteceu de fato (mitigado pela trilha + por
+  o lançamento ser feito por super-admin/capitão).
+- Regras como "sem reeleição direta" não são impedidas pelo sistema — dependem de disciplina humana.
+- Vários cenários BDD do documento da P.O. não viram testes de software nesta fase.
+
+## Review trigger
+
+Revisitar quando (a) o volume de eleições/casos justificar conduzir/automatizar na plataforma; (b) a
+P.O. fechar as regras de elegibilidade/eleição; ou (c) o Núcleo do jogo exigir que o estado de squad
+seja derivado de processos, não lançado.
diff --git a/app-modules/squads/docs/adr/0002-modelo-de-dados.md b/app-modules/squads/docs/adr/0002-modelo-de-dados.md
new file mode 100644
index 000000000..a023de779
--- /dev/null
+++ b/app-modules/squads/docs/adr/0002-modelo-de-dados.md
@@ -0,0 +1,88 @@
+# ADR-0002: Modelo de dados de squads (estado + trilha + exclusividade)
+
+**Status:** Accepted
+**Date:** 2026-06-15
+**Deciders:** danielhe4rt
+**Relates to:** [ADR-0001](0001-governanca-como-registro.md)
+
+## Contexto
+
+Sob o modelo de governança como registro (ADR-0001), o `squads` precisa de um esquema que seja a
+fonte da verdade do **estado** (quem é o quê em cada squad) e que carregue uma **trilha de auditoria**
+de tudo que muda em membership/papéis (join/leave/promote/demote), tudo tenant-scoped. Algumas
+invariantes de negócio (capitão único, "1 squad ativo") merecem ser garantidas no banco, não só na
+aplicação.
+
+## Decisão
+
+Quatro tabelas, todas com `id` UUIDv7 (`HasUuids`) e `tenant_id`.
+
+### `squads`
+
+`name`, `slug`, `objective` (text, nullable — `draft` pode não ter), `status` (`SquadStatus`
+`draft`/`active`/`inactive`/`archived`, default `draft`), timestamps.
+
+- `UNIQUE (tenant_id, slug)`, `INDEX (tenant_id, status)`.
+- **Sem `captain_id` denormalizado** — o capitão é derivado do pivot (`role = captain`). Fonte única.
+- **Sem `SoftDeletes`** — `archived` é o encerramento lógico.
+
+### `squad_members` (pivot com id próprio)
+
+`squad_id`, `user_id`, `role` (`SquadRole` `captain`/`sub_captain`/`member`/`ex_member`),
+`joined_at`, `left_at` (nullable, datado ao virar `ExMember`), timestamps.
+
+- `UNIQUE (squad_id, user_id)` — uma linha por pessoa por squad.
+- **Capitão único:** `UNIQUE (squad_id) WHERE role = 'captain'` (partial index).
+- **Exclusividade (1 squad ativo, por tenant):** `UNIQUE (tenant_id, user_id) WHERE role IN
+('captain','sub_captain','member')`. `ex_member` não conta. Defense-in-depth com a validação na Action.
+
+### `squad_membership_events` (append-only)
+
+`squad_id`, `user_id` (sujeito), `actor_id` (nullable; null = sistema), `action`
+(`MembershipAction`), `from_role`/`to_role` (`SquadRole`, nullable), `reason` (text, nullable),
+`metadata` (jsonb, nullable), `occurred_at`, timestamps.
+
+- `INDEX (squad_id, occurred_at)`, `INDEX (user_id, occurred_at)`.
+- Nunca atualizado/deletado — é a trilha.
+
+### `squad_applications`
+
+`squad_id`, `user_id` (candidato), `status` (`ApplicationStatus`
+`pending`/`approved`/`rejected`/`withdrawn`, default `pending`), `message` (text, nullable),
+`decided_by` (nullable), `decided_at` (nullable), timestamps.
+
+- `INDEX (squad_id, status)`.
+- `UNIQUE (squad_id, user_id) WHERE status = 'pending'` — ≤1 candidatura pendente por pessoa/squad.
+
+### Enums
+
+`SquadStatus`, `SquadRole`, `ApplicationStatus`, `MembershipAction` — backed string, cast nos models.
+PHPDoc `@property` em todos os models conforme `.ai/04-model-phpdoc-sync`.
+
+## Alternativas consideradas
+
+- **`captain_id` denormalizado em `squads`**: query de listagem mais barata, mas vira 2ª fonte da
+  verdade a sincronizar a cada troca. Descartado a favor de derivar do pivot.
+- **Exclusividade só na Action** (sem partial unique): mais simples, mas sem rede contra corrida/bug.
+  Descartado a favor de defense-in-depth.
+- **Estado-only (sem tabela de eventos)**: descartado — a trilha de join/leave/promote/demote é
+  requisito explícito.
+
+## Consequências
+
+### Positivas
+
+- Invariantes críticas (capitão único, 1 squad ativo) garantidas pelo Postgres.
+- Capitão sem risco de divergir (fonte única no pivot).
+- Auditoria completa de membership/papéis.
+
+### Negativas / diferidas
+
+- Listar squads com o capitão custa um join (sem denormalização).
+- Partial unique indexes são Postgres-específicos (o repo já é Postgres — aceitável).
+- A trilha cresce indefinidamente (append-only); particionamento/arquivamento é problema futuro.
+
+## Review trigger
+
+Revisitar se a listagem de squads+capitão virar gargalo (considerar projeção/denormalização), ou se a
+exclusividade deixar de ser "1 por tenant" (ex.: 1 global, ou N squads por pessoa no futuro).
diff --git a/app-modules/squads/phpstan.ignore.neon b/app-modules/squads/phpstan.ignore.neon
new file mode 100644
index 000000000..f51e71c3f
--- /dev/null
+++ b/app-modules/squads/phpstan.ignore.neon
@@ -0,0 +1,2 @@
+parameters:
+    ignoreErrors: []
diff --git a/app-modules/squads/phpstan.neon b/app-modules/squads/phpstan.neon
new file mode 100644
index 000000000..b577d0f29
--- /dev/null
+++ b/app-modules/squads/phpstan.neon
@@ -0,0 +1,6 @@
+includes:
+    - phpstan.ignore.neon
+
+parameters:
+    paths:
+        - src/
diff --git a/app-modules/squads/src/Providers/SquadsServiceProvider.php b/app-modules/squads/src/Providers/SquadsServiceProvider.php
new file mode 100644
index 000000000..c9437e8e2
--- /dev/null
+++ b/app-modules/squads/src/Providers/SquadsServiceProvider.php
@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace He4rt\Squads\Providers;
+
+use Illuminate\Support\ServiceProvider;
+
+class SquadsServiceProvider extends ServiceProvider
+{
+    public function register(): void {}
+
+    public function boot(): void {}
+}
diff --git a/app-modules/squads/tests/Feature/.gitkeep b/app-modules/squads/tests/Feature/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/app-modules/squads/tests/Unit/.gitkeep b/app-modules/squads/tests/Unit/.gitkeep
new file mode 100644
index 000000000..e69de29bb
diff --git a/composer.json b/composer.json
index 3169d8210..581d26b3d 100644
--- a/composer.json
+++ b/composer.json
@@ -29,10 +29,12 @@
         "he4rt/integration-twitch": ">=1",
         "he4rt/integration-whatsapp": ">=1",
         "he4rt/moderation": "^1.0",
+        "he4rt/onboarding": "*",
         "he4rt/panel-admin": ">=1",
         "he4rt/panel-app": ">=1",
         "he4rt/portal": ">=1",
         "he4rt/profile": ">=1",
+        "he4rt/squads": "*",
         "internachi/modular": "^3.0.2",
         "laracord/framework": "dev-next#e7b64d6",
         "laravel/framework": "^13.15.0",