# 📖 The Manifest

> Assim como o manifesto de carga registra tudo o que navega, o **The Manifest** registra tudo o que evolui no TABEX.

Central de documentação automática do TABEX: quando uma task é concluída no Notion, o Claude gera a documentação técnica (que fica organizada diretamente no Notion, dentro das pastas e diretrizes do time) e a release note do usuário, publicada neste site — público, sem login.

**Stack:** Laravel 12 · Notion API · Claude API (Anthropic) · Blade · Font Awesome

## O site

The Manifest é público, sem login. Mostra release notes em linguagem simples,
agrupadas por **🚀 Novos Projetos**, **✨ Melhorias** e **🐞 Correções**, além do
**Pátio do Porto** (`/porto`) — a mesma documentação navegável pela metáfora
Vessel = Sprint / Container = Card.

A documentação técnica (contexto, causa raiz, correção, cenários de QA) **não
é exibida no site** — ela é gerada e organizada diretamente no Notion, dentro
da estrutura de pastas do time de dev. Só o e-mail de release, uma ferramenta
administrativa, fica atrás de senha (`MANIFEST_DEV_PASSWORD`).

## A rota da documentação

```
Task concluída no Notion (Dev-Status: Done)
        │  webhook
        ▼
┌─ document-this ─────────────────────────────────────┐
│  Skill Claude: lê a task inteira (relato do suporte, │
│  análise do dev, correção, QA) e escreve a doc       │
│  técnica + a release note do usuário                 │
└──────────────┬───────────────────────────────────────┘
               │
     ┌─────────┴──────────┐
     ▼                    ▼
┌─ manifest-it ─┐   ┌─ (Notion) ─────────────────┐
│ Publica a     │   │ A doc técnica fica          │
│ versão do     │   │ organizada direto no        │
│ usuário no    │   │ Notion, nas pastas do       │
│ site público  │   │ time — sem passar pelo site │
└───────────────┘   └────────────────────────────┘
```

No fim de cada sprint, o e-mail de release notes é gerado agregando tudo o que foi documentado:

```bash
php artisan release:generate-email "Sprint 30"        # CLI
# ou pelo browser: /releases/{sprint}/preview  →  regenerar → aprovar → salvar no Notion
```

## Rodando o projeto

```bash
composer install
# configure o .env (chaves do Notion/Anthropic, banco, senha admin)
php artisan key:generate

php artisan serve        # o site
php artisan queue:work   # jobs de documentação (Claude leva 5–15s)
```

### Modo demo (mockup)

Com `MANIFEST_DEMO=true` no `.env`, o site inteiro renderiza com dados fake
([app/Support/DemoManifest.php](app/Support/DemoManifest.php)) — sem Notion e
sem Claude. Ideal para apresentações; o Font Awesome é servido localmente,
então funciona offline. Desligue com `MANIFEST_DEMO=false` + `php artisan config:clear`.

### Conectando ao Notion (modo real)

1. **Compartilhe** as databases **Tasks** e **Sprints** e a página raiz **The Manifest**
   (criada manualmente) com a integração do Notion cujo token está no `.env`
   (⋯ → *Connections* → adicionar a integração).
2. Rode o setup — cria as seções, adiciona as propriedades de rastreio na Tasks
   (`Documentation Status`, `Technical Doc`, `Release Note`) e preenche o `.env`:
   ```bash
   php artisan manifest:setup <rootPageId>
   ```
3. **Webhook:** nas configurações da integração, registre
   `https://seudominio.com/webhooks/notion` (evento `page.properties_updated`).
   O `verification_token` da primeira entrega aparece em `storage/logs/laravel.log`;
   use-o como `NOTION_WEBHOOK_SECRET`.
4. Preencha `ANTHROPIC_API_KEY` e defina uma senha real em `MANIFEST_DEV_PASSWORD`
   (protege apenas a ferramenta de e-mail de release, em `/releases/...`).

### Variáveis principais (`.env`)

| Variável | O que é |
|----------|---------|
| `NOTION_API_KEY` | Token da integração interna do Notion |
| `NOTION_TASKS_DATABASE_ID` | Database Tasks do time |
| `NOTION_TRIGGER_STATUS` | Dev-Status que dispara a documentação (padrão: `Done`) |
| `NOTION_TECHNICAL_PARENT_PAGE_ID` | Seção 🔒 Documentação Técnica no Notion (via `manifest:setup`) — não aparece no site |
| `NOTION_RELEASES_PARENT_PAGE_ID` | Seção 📖 Release Notes (via `manifest:setup`) — alimenta o site |
| `ANTHROPIC_API_KEY` | Chave da API do Claude |
| `ANTHROPIC_MODEL` | `claude-sonnet-4-5` (custo-eficiente) ou `claude-opus-4-5` |
| `MANIFEST_DEV_PASSWORD` | Senha da ferramenta de e-mail de release (`/releases/...`) |
| `MANIFEST_DEMO` | `true` = dados fake para mockup |

## Estrutura do código

```
app/
├── Http/Controllers/
│   ├── ManifestController.php        # o site público (knowledge base + Pátio do Porto)
│   ├── NotionWebhookController.php   # recebe eventos do Notion
│   ├── ReleaseEmailController.php    # e-mail de release da sprint
│   └── ReleasePreviewController.php  # preview interativo do e-mail
├── Jobs/GenerateDocumentationJob.php # pipeline: task → Claude → páginas no Notion
├── Services/
│   ├── NotionService.php             # API do Notion (queries, páginas, blocos)
│   ├── ClaudeService.php             # API do Claude (docs + e-mail)
│   └── NotionRenderer.php            # blocos Notion → HTML do site
├── Support/
│   ├── NotionTask.php                # mapeia o schema real da database Tasks
│   └── DemoManifest.php              # dados fake do modo demo
├── Prompts/DocumentationPrompt.php   # prompts centralizados (pt-BR)
└── Console/Commands/
    ├── SetupManifest.php             # manifest:setup
    └── GenerateReleaseEmail.php      # release:generate-email
```

Documentação detalhada de arquitetura e segurança: [config/README.md](config/README.md).

## Segurança

- Webhook com verificação HMAC (`hash_equals`) e handshake de verificação do Notion
- Rotas de documento validam a seção-mãe da página antes de renderizar — só a
  seção Release Notes é servida, nunca uma página arbitrária do Notion
- A ferramenta de e-mail de release (`/releases/...`) fica atrás de senha —
  é o único ponto protegido do site, já que dispara chamadas pagas ao Claude
  e escreve no Notion
- Jobs idempotentes (entregas duplicadas de webhook não geram doc duas vezes)
- Chaves de API nunca são logadas
