# AGENTS.md — Comunidade 360

Instruções obrigatórias para qualquer agente de código (Codex, Copilot, Claude Code ou similar) trabalhando neste projeto.

---

## Identidade do projeto

Plataforma de gestão para comunidades de fé. PHP/MySQL multi-tenant. Começa pelo módulo musical e expande para a instituição como um todo.

---

## Regras absolutas — nunca violar

1. **Sem scraping.** Nunca buscar letras, cifras, partituras ou repertórios de sites externos (Cifra Club, Ultimate Guitar, Letras, Vagalume, YouTube etc.).
2. **Sem conteúdo protegido nativo.** Nunca inserir músicas no acervo nativo sem documentação de domínio público, licença aberta compatível ou autorização direta.
3. **Isolamento multi-tenant obrigatório.** Toda query em tabela operacional deve filtrar por `organization_id`. Sem exceção.
4. **Nunca usar `church_id`.** O campo de isolamento é sempre `organization_id`.
5. **Vocabulário institucional.** Nunca hardcodar "culto", "missa", "ministério", "louvor", "pastoral" ou termos religiosos em módulos genéricos. Usar sempre `term('chave')`.
6. **Sem Node em produção.** Assets devem ser estáticos ou compilados antes do deploy.
7. **Sem credenciais no repositório.** `.env` nunca entra no Git.
8. **Sem módulo de cuidado pastoral/pedidos sensíveis** no MVP sem avaliação jurídica específica.

---

## Padrões de código

### Isolamento tenant
```php
// CORRETO
$songs = $db->query(
    "SELECT * FROM songs WHERE organization_id = ? AND status = 'active'",
    [$orgId]
);

// ERRADO — nunca fazer query sem organization_id em tabela operacional
$songs = $db->query("SELECT * FROM songs");
```

### Vocabulário institucional
```php
// CORRETO
echo term('event');       // exibe "Culto", "Missa", "Serviço" conforme instituição
echo term('team');        // exibe "Ministério", "Pastoral", "Grupo"
echo term('repertoire');  // exibe "Louvor", "Cantos", "Repertório"

// ERRADO
echo "Culto";
echo "Ministério";
```

### Auditoria
```php
// Registrar em ações sensíveis
AuditLog::record($orgId, $userId, 'song.created', ['song_id' => $songId]);
AuditLog::record($orgId, $userId, 'license.updated', ['song_id' => $songId]);
AuditLog::record($orgId, $userId, 'setlist.published', ['setlist_id' => $setlistId]);
AuditLog::record($orgId, $userId, 'vocabulary.changed', ['term_key' => $key]);
```

### Segurança
```php
// CSRF em formulários POST
echo csrf_field();

// Sanitização de saída
echo e($userInput);  // htmlspecialchars wrapper

// Prepared statements — sempre
$db->query("SELECT * FROM users WHERE email = ?", [$email]);
```

---

## Nomenclatura de tabelas

| Contexto | Padrão |
|---|---|
| Isolamento | `organization_id` (nunca `church_id`) |
| Timestamps | `created_at`, `updated_at` |
| Soft delete | `deleted_at` nullable |
| Status | `status` ENUM ou VARCHAR |
| Criador | `created_by` (user_id) |
| Atualizador | `updated_by` (user_id) |

---

## Checklist antes de commit

- [ ] Código roda sem erro fatal?
- [ ] Nenhuma credencial no repositório?
- [ ] `.env` fora do Git?
- [ ] Queries filtram por `organization_id`?
- [ ] Telas usam `term()` em vez de termos religiosos fixos?
- [ ] Entradas validadas e sanitizadas?
- [ ] Saídas HTML escapadas com `e()`?
- [ ] Formulários com `csrf_field()`?
- [ ] Uploads validados (extensão + MIME + tamanho)?
- [ ] Ações sensíveis registradas em `audit_logs`?
- [ ] README/AGENTS atualizados se criou padrão novo?

---

## Módulos e responsabilidades

| Módulo | Pasta | Responsabilidade |
|---|---|---|
| Organizations | `app/Modules/Organizations/` | CRUD de instituições, planos, status |
| CommunityProfiles | `app/Modules/CommunityProfiles/` | Tipos de comunidade e perfis de vocabulário |
| Vocabulary | `app/Modules/Vocabulary/` | Termos institucionais, helper `term()` |
| Users | `app/Modules/Users/` | Auth, perfis, permissões, convites |
| Teams | `app/Modules/Teams/` | Equipes, líderes, integrantes |
| Songs | `app/Modules/Songs/` | Repertório, licenças, editor ChordPro |
| Setlists | `app/Modules/Setlists/` | Setlists, itens, publicação |
| Schedules | `app/Modules/Schedules/` | Escalas, convites, confirmação |
| Events | `app/Modules/Events/` | Eventos/celebrações |
| Messages | `app/Modules/Messages/` | Avisos, comunicados |
| Audit | `app/Modules/Audit/` | Logs de auditoria |
| Settings | `app/Modules/Settings/` | Configurações por instituição |

---

## Serviços

| Serviço | Pasta | Responsabilidade |
|---|---|---|
| ChordTransposer | `app/Services/ChordTransposer/` | Transposição de acordes ChordPro |
| LicenseValidator | `app/Services/LicenseValidator/` | Validação de status jurídico de músicas |

---

## Expandindo o projeto

Ao criar módulo novo:
1. Criar pasta em `app/Modules/NomeDoModulo/`
2. Criar `Controller.php`, `Model.php`, `Repository.php`
3. Criar views em `app/Views/nomedomodulo/`
4. Criar migration em `database/migrations/`
5. Registrar rotas em `config/routes.php`
6. Atualizar este AGENTS.md
7. Usar `organization_id` em todas as tabelas operacionais
8. Usar `term()` em todas as labels visíveis