# Spec: Agent-Session-Speaker Model — Part 2 (Documentação Completa)

> Generated via /vibeflow:gen-spec on 2026-03-26
> Budget: ≤ 30 files (docs cross-cutting)

## Objective

Atualizar TODA a documentação (EN + PT-BR) pra refletir o modelo `agent_id` + `session_id` + `speaker_name`, incluindo explicação conceitual do modelo mental, exemplos atualizados, e CHANGELOG v0.8.0.

## Context

Part 1 renomeia user_id → agent_id no código. Part 2 atualiza a documentação pra refletir a mudança e, mais importante, explicar POR QUE o modelo é agent_id/session_id/speaker_name.

## Definition of Done

1. **[ ] Zero ocorrências de `user_id` nos docs** — grep em `docs/` retorna vazio (exceto CHANGELOG entries históricas de versões anteriores).
2. **[ ] Seção conceitual "Agent, Session, Speaker"** — Nova seção no Getting Started (EN + PT-BR) explicando o modelo mental com exemplos de cada caso de uso (1:1, multi-speaker, observer).
3. **[ ] Todos os exemplos de código atualizados** — `agent_id` em vez de `user_id` em getting-started, cookbook, concepts, reference, configuration (EN + PT-BR).
4. **[ ] `llms-full.txt` sincronizado** — EN + PT-BR refletem todas as mudanças.
5. **[ ] CHANGELOG v0.8.0** — Entry explicando a breaking change com guia de migração inline.
6. **[ ] Walkthroughs atualizados** — Todos os `??? example` usam `agent_id` e mencionam `session_id` onde relevante.

## Scope

### 1. Getting Started (EN + PT-BR)
- Nova seção "Understanding Agent, Session, and Speaker" antes do Quick Start
- Explicação com diagrama: memória é do agente, contexto é da sessão, identidade é do speaker
- Exemplos: caso simples (1 campo obrigatório), caso multi-speaker, caso observador
- Todos os code examples: `user_id` → `agent_id`, adicionar `session_id` onde relevante

### 2. Concepts (EN + PT-BR)
- write-pipeline.md: `user_id` → `agent_id` em texto, exemplos, walkthroughs
- read-pipeline.md: idem
- background-jobs.md: idem

### 3. Advanced (EN + PT-BR)
- configuration.md: `user_id` → `agent_id`
- data-types.md: column tables, ER diagram (renomear user_id → agent_id nos modelos)
- read-api.md, write-api.md: function signatures

### 4. Reference + Cookbook + Custom Providers (EN + PT-BR)
- Todos os exemplos de código atualizados

### 5. llms-full.txt (EN + PT-BR)
- Regenerar com todas as mudanças acima

### 6. CHANGELOG.md
- Entry v0.8.0 com:
  - Breaking: `user_id` → `agent_id`
  - New: `session_id` parameter
  - Conceitual: Agent owns memory, Session is context, Speaker is identity

## Anti-scope

- **Código** — Part 1 cuida do código. Este spec é só docs.
- **Migration guide pra usuários externos** — Não tem usuários.
- **Tradução de neuroscience parallels** — Manter como estão, só renomear user_id.

## Technical Decisions

### TD-1: Seção conceitual como "first thing you read"
A explicação de agent/session/speaker vai ANTES do Quick Start no Getting Started. O dev precisa entender o modelo mental antes de escrever código. É a mudança mais importante — não é rename, é reframing.

### TD-2: Manter `user_id` em CHANGELOG entries históricas
Entries de v0.6.x e v0.7.x mencionam `user_id` porque era o campo na época. Não retroativamente renomear — é registro histórico.

## Applicable Patterns

Nenhum — docs only.

## Risks

1. **Doc desincronizada com código** — Se Part 1 e Part 2 forem implementados em paralelo, pode haver inconsistência. Mitigação: Part 1 primeiro, Part 2 depois.
2. **llms-full.txt incompleto** — Já aconteceu várias vezes. Mitigação: regenerar do zero a partir dos docs individuais, não incremental.

## Dependencies

- `.vibeflow/specs/agent-session-speaker-part-1.md` — código precisa estar renomeado antes de atualizar docs.
