@luanpdd/kit-mcp 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -6,6 +6,69 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning:
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-05-05
+
+UI sidecar — bug fixes visuais + tokens + histórico de sessão.
+
+### Adicionado
+
+- **Tokens chip** em cada row da timeline e card de active run quando o evento traz `payload.tokens` (também aceita `payload.usage.total_tokens` e `payload.cost.tokens` para compatibilidade com diferentes wrappers). Formato `1.2k` / `5.3k` / `1.5M`.
+- **Soma cumulativa de tokens da sessão** no footer (`6.2k tokens nesta sessão`). Aparece só quando algum evento veio com tokens — quem não usa LLM continua vendo o footer enxuto.
+- **Histórico desta sessão** — drawer flutuante (botão de relógio na toolbar). Persiste em `sessionStorage` (não cross-tab, não cross-session); cada run terminada vira uma row com status (✓/✗/·), título, timestamp, duração, tokens, contagem de eventos e runId truncado. Click expande pra mostrar até os 100 últimos eventos da run com %, label e tokens. Cap em 50 runs (mais antigos são descartados).
+- **Footer mostra runs concluídas** total da sessão (`3 runs concluídas`).
+
+### Corrigido
+
+- **Mojibake (`�`) em payloads** — eventos publicados via shells com locale ruim podiam vazar U+FFFD. Helper `safeStr()` agora limpa esses bytes antes de qualquer renderização.
+- **Rows vazias na timeline** — `milestone` event que vinha com `payload.label` mas sem `payload.name` rendia em branco. Cascata defensiva agora tenta `name → title → label → name → tipo humanizado` em todos os tipos. Garantia: nenhuma row sai sem texto.
+- **Active card sem título** — antes mostrava `—` sozinho se `payload.tool` estava vazio. Helper `runTitle(run)` cascata `humanizeTool(tool) → lastTitle → lastLabel → lastName → "Processo"`.
+- **Tool inline mostrava `—` em vez de fallback** — `escapeHtml(safeStr(run.tool) || "processo")` no rc-tool, `escapeHtml(safeStr(run.tool) || "")` no rc-foot.
+
+### Removido
+
+- **Painel "Cenário (mock)" do Tweaks** — apenas cenários reais agora; sem botões de demo.
+- **Botão "▸ replay"** — dependia de mock.
+- **Funções `scenarioSync` / `scenarioMulti` / `scenarioError` / `scenarioIdle` / `runScenario` / `mockTimers` / `later` / `clearMock`** — toda infraestrutura de mock event generator (~80 LOC). `EventSource('/events')` é a única fonte de verdade.
+- **Fallback `file://` boot** — sidecar não é mais aberto via `file://`; só via servidor.
+
+### Sem mudanças de API runtime
+
+Mudanças concentradas em `src/ui/static/index.html`. `src/core/`, `src/cli/`, `src/mcp-server/`, `src/ui/server.js` intocados. Stable API v1.0+ preservada.
+
+### Migration
+
+Wrappers que quiserem expor cost/tokens podem agora popular `payload.tokens` (number) em qualquer evento. Quem não popula continua funcionando idêntico — chips não aparecem, footer não mostra a linha de tokens. Histórico é per-tab via `sessionStorage` — fechar a aba apaga (intencional, não persistir é a feature).
+
+## [1.4.0] - 2026-05-05
+
+Framework velocity — 7 melhorias para os comandos / agentes do kit, focadas em reduzir fricção, evitar conflitos com main, e auto-detectar configs que hoje exigem env var manual.
+
+### Adicionado
+
+- **`/publicar-rapido`** — variante leve de `/publicar` para hotfix / quick-task. Não exige ROADMAP arquivado, MILESTONE-AUDIT.md nem `STATE.md`. Infere `TIPO_MUDANCA` (`fix:`/`feat:`/`refactor:`/...) do prefix do commit, gera Notion enxuto + PR + nota Obsidian em ~30s. Pre-flight de sync com `main` herdado do `/publicar`. (REQ F-01) `kit/commands/publicar-rapido.md`, ~210 LOC.
+
+- **Pre-flight `main` sync no `/publicar` (Passo 0)** — antes de criar PR, faz `git fetch origin main` e detecta commits novos. Se houver, apresenta a lista e pergunta via `AskUserQuestion`: integrar via rebase (recomendado), via merge, ignorar (com flag `SYNC_SKIPPED` registrada na descrição do PR), ou cancelar. Trava de segurança contra conflitos tardios em times com vários devs em paralelo. (REQ F-07)
+
+- **Auto-detect `notion-config.json` (Passo 0.5)** — se o config está ausente, em vez de encerrar com erro, busca a página do projeto via `notion-search`, apresenta candidatos via `AskUserQuestion`, lista subpáginas via `notion-fetch`, e gera o config automaticamente. `/setup-notion` continua existindo para quando a estrutura Notion ainda não existe. (REQ F-02)
+
+- **Auto-detect cofre Obsidian (Passo 0.7)** — se `$OBSIDIAN_TEAM_VAULT` está ausente, tenta caminhos canônicos antes de pular o passo: `~/Documentos/Obsidian/chat-trynux`, `~/Documents/Obsidian/chat-trynux`, variantes `$USERPROFILE` (Windows), `/mnt/c/Users/$USER/...` (WSL). Funciona out-of-the-box em qualquer máquina (Linux/macOS/Windows/WSL) que siga o layout padrão `Documentos/Obsidian/chat-trynux`. (REQ F-03)
+
+- **`schema-checker` agent** — sub-agente novo invocável via `Task(subagent_type="schema-checker")`. Lê uma migration SQL, extrai FKs / JOINs / refs implícitas, consulta o schema real em produção via Supabase MCP (`information_schema` + `pg_constraint`), cruza, e devolve veredito GO / NO-GO / NEEDS-REVIEW com diff por referência. Pega o caso clássico do "comentário do dev errado" (`contact_id → conversations.id` em comentário, mas em prod aponta para `contacts.id`) ANTES de aplicar a migration e ver falhar silenciosamente. (REQ F-04) `kit/agents/schema-checker.md`, ~160 LOC.
+
+- **Hook `post-apply-migration` (PostToolUse)** — dispara automaticamente depois de qualquer `apply_migration` bem-sucedido via Supabase MCP e faz os 3 passos manuais que devs sempre esquecem: (a) escreve a SQL em `supabase/migrations/{TIMESTAMP}_{name}.sql`, (b) cria stub no cofre Obsidian em `07 - Banco de Dados/Migrations/{YYYY}/{TIMESTAMP}_{name}.md` (se vault detectado), (c) `git add` no projeto. Soft-fails — nunca bloqueia o tool call. (REQ F-05) `kit/hooks/post-apply-migration.js`, ~190 LOC.
+
+### Alterado
+
+- **Heurística de gatilho do `/publicar`** — documentada explicitamente: "publicar" depois de aplicar mudança = pipeline completo, NÃO apenas push. Para push isolado em outra branch sem cerimônia, dev precisa pedir explicitamente "só fazer push" OU usar `/publicar-rapido`. (REQ F-06)
+
+### Sem mudanças de API runtime
+
+Todas as adições são em `kit/` (templates de prompt distribuídos). `src/core/`, `src/cli/`, `src/mcp-server/`, e `src/ui/` permanecem intocados. Stable API v1.0+ preservada literalmente.
+
+### Migration
+
+Usuários da v1.3 não precisam fazer nada — re-rodar `kit sync install <ide>` no projeto puxa as adições. Quem usa `/publicar` em produção colhe os 3 passos novos automaticamente (pre-flight sync, auto-detect notion-config, auto-detect Obsidian) sem mudar workflow.
+
 ## [1.3.0] - 2026-05-05
 
 UI redesign completo entregue por handoff do Claude Design (claude.ai/design). Layout repensado, paleta OKLCH, painel de tweaks (acento/densidade/movimento) acessível, timeline com rail + nó por evento, hero card de active runs com borda cônica animada e barra com gradient + shimmer, empty state com heartbeat bars, e cenários de demo (`Sync` / `Multi` / `Erro` / `Idle`) mockáveis pelo painel de tweaks.

package/kit/agents/schema-checker.md

@@ -0,0 +1,159 @@
+---
+name: schema-checker
+description: Valida foreign keys, colunas e tabelas referenciadas em uma migration SQL ANTES de aplicá-la em produção. Lê a SQL, extrai refs (FK, JOIN, INSERT INTO ... SELECT), consulta o schema real via Supabase MCP, e devolve um veredito GO/NO-GO com diff entre o que a migration assume e o que existe. Invocar antes de qualquer `apply_migration` que toque dados existentes.
+tools: Read, Bash, Grep, Glob, mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__execute_sql, mcp__0a712001-6cbb-44ef-a5f4-a24ea40894fa__list_tables
+color: red
+---
+
+Você é um schema-checker pré-migration. O caller (orquestrador, geralmente Claude) entrega um caminho de arquivo `.sql` (ou conteúdo cru de SQL) e o `project_id` Supabase. Você responde com um veredito estruturado **antes** que a migration seja aplicada.
+
+## Por que existe
+
+Migrations escritas com base em comentário ou memória do dev frequentemente assumem schema que não bate com produção. Ex: comentário diz `contact_id → conversations.id`, mas a tabela real tem `contact_id → contacts.id`. Aplicar e ver falhar custa 1 retry no melhor caso, dados sujos no pior. Este agente faz a validação cruzada antes do apply.
+
+## Inputs esperados (do caller)
+
+- `migration_path`: caminho do arquivo SQL (ou string com a SQL inline).
+- `project_id`: identificador do projeto Supabase (ex: `cqxmojtvfqxyvkuljkzs`).
+- (Opcional) `expected_branch`: se a migration deve rodar em uma branch Supabase específica.
+
+## Passos
+
+### 1. Ler a migration
+
+- Ler arquivo SQL via Read.
+- Normalizar (remover comentários `--` e `/* */`, lowercase).
+
+### 2. Extrair referências
+
+Identifique três classes de referências que podem estar erradas:
+
+#### 2.1 — Foreign keys declaradas
+Patterns:
+- `references <schema>.<table>(<col>)`
+- `references <table>(<col>)`
+- `foreign key (<col>) references <table>`
+
+Para cada uma, capture: `(local_col, target_table, target_col)`.
+
+#### 2.2 — JOINs
+Patterns:
+- `join <table> on <alias>.<col> = <other_alias>.<col>`
+- `join <table> using (<col>)`
+
+Para cada JOIN, capture: `(left_table, left_col, right_table, right_col)`.
+
+#### 2.3 — INSERT/UPDATE/DELETE com refs implícitas
+Patterns:
+- `insert into <table> (...)` — verifique se `<table>` existe.
+- `update <table> set <col> = ... where <col2> = ...` — verifique `<col>` e `<col2>` existem em `<table>`.
+- `delete from <table> where ...` — idem.
+
+### 3. Consultar schema real (via Supabase MCP)
+
+Para cada referência extraída no passo 2:
+
+#### 3.1 — Existência de tabela e coluna
+
+```sql
+SELECT
+  EXISTS (SELECT 1 FROM information_schema.tables WHERE table_schema = 'public' AND table_name = '{table}') AS table_exists,
+  EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = '{table}' AND column_name = '{col}') AS col_exists;
+```
+
+Use `mcp__0a712001-...__execute_sql` com o `project_id`.
+
+#### 3.2 — Tipo da coluna referenciada (FK target)
+
+```sql
+SELECT data_type, is_nullable, column_default
+FROM information_schema.columns
+WHERE table_schema = 'public' AND table_name = '{target_table}' AND column_name = '{target_col}';
+```
+
+#### 3.3 — FK existente vs FK proposta
+
+Para cada FK que a migration declara, busque se já existe uma constraint similar:
+
+```sql
+SELECT conname, conrelid::regclass AS local_table,
+       confrelid::regclass AS target_table,
+       a.attname AS local_col, b.attname AS target_col
+FROM pg_constraint c
+JOIN pg_attribute a ON a.attrelid = c.conrelid AND a.attnum = ANY(c.conkey)
+JOIN pg_attribute b ON b.attrelid = c.confrelid AND b.attnum = ANY(c.confkey)
+WHERE c.contype = 'f' AND c.conrelid::regclass::text = '{local_table}';
+```
+
+### 4. Cruzar e diferenciar
+
+Para cada referência da migration:
+
+- **OK** — tabela existe, coluna existe, tipo bate, e (se FK declarada) o target da FK na migration bate com o que `pg_constraint` reporta.
+- **MISMATCH-TARGET** — coluna existe, mas a FK aponta para `<X>.<Y>` na migration enquanto produção tem essa coluna referenciando `<W>.<Z>`. Este é o caso clássico do "comentário do dev errado".
+- **MISSING-TABLE** — tabela citada não existe no schema.
+- **MISSING-COLUMN** — coluna citada não existe na tabela.
+- **TYPE-MISMATCH** — coluna existe mas tipo bate diferente do que a migration assume (ex: `uuid` vs `bigint`).
+- **WARN-ONLY** — referência a sistema (ex: `auth.users`) onde permissions podem complicar — registre como warning sem bloquear.
+
+### 5. Veredito
+
+Imprima um relatório estruturado:
+
+```
+═══════════════════════════════════════════════════════════
+SCHEMA-CHECK · {migration_path}
+projeto: {project_id} · validado em {timestamp}
+═══════════════════════════════════════════════════════════
+
+VEREDITO: GO | NO-GO | NEEDS-REVIEW
+
+Resumo:
+  - {N} referências analisadas
+  - {OK} ok
+  - {WARN} warnings
+  - {FAIL} falhas
+
+═══════════════════════════════════════════════════════════
+DETALHES POR REFERÊNCIA
+═══════════════════════════════════════════════════════════
+
+[1] LINHA 7 — FK declarada: contact_prefs.contact_id → conversations.id
+    STATUS: ✗ MISMATCH-TARGET
+    Em produção: contact_prefs.contact_id → contacts.id (constraint: fk_contact_prefs_contact)
+    Comentário da migration sugere conversations.id mas o schema real liga contacts.id.
+    AÇÃO: corrigir comentário OU mudar a migration se a intenção era de fato ligar a conversations.
+
+[2] LINHA 14 — JOIN: contact_prefs.user_id = users.id
+    STATUS: ⚠ WARN-ONLY
+    users é tabela de auth — permissions podem aplicar. Verificar `current_user` ou usar `service_role`.
+
+[3] LINHA 22 — INSERT INTO contact_prefs (channel, value)
+    STATUS: ✓ OK
+
+═══════════════════════════════════════════════════════════
+RECOMENDAÇÃO
+═══════════════════════════════════════════════════════════
+{Texto curto: aplicar agora? aplicar com mudanças? não aplicar?}
+```
+
+### 6. Regras de veredito
+
+- **GO**: 0 falhas, 0 mismatches. Warnings podem existir mas com mitigação clara.
+- **NEEDS-REVIEW**: 1+ mismatches OU 1+ warns sem mitigação clara. Devolva o relatório e DEVOLVA o controle ao caller — não bloqueie, mas peça revisão humana.
+- **NO-GO**: 1+ MISSING-TABLE / MISSING-COLUMN / TYPE-MISMATCH. A migration vai falhar no apply de qualquer forma. Recomende corrigir antes.
+
+### 7. Saída
+
+Apenas o relatório. Sem preâmbulo. Sem "vou analisar agora". Sem "espero ter ajudado". Direto ao ponto — o caller precisa do veredito pra decidir.
+
+## Quando o caller deve invocar
+
+- Antes de chamar `mcp__0a712001-...__apply_migration` em qualquer migration que toque dados existentes.
+- Antes de mergear PR que contém migration que vai pra produção.
+- Manualmente, quando o dev pediu uma sanity check ("essa migration tá OK?").
+
+**Não invocar para:**
+- Migrations vazias / só de schema novo (sem FK ou JOIN).
+- DROP TABLE / TRUNCATE — nada a checar de schema.
+- Seeds / fixtures — schema-checker valida estrutura, não dados.

package/kit/commands/publicar-rapido.md

@@ -0,0 +1,207 @@
+---
+name: publicar-rapido
+description: Variante leve de /publicar para hotfix/quick-task — sem dependência de ROADMAP/MILESTONE-AUDIT. Infere tipo do commit, gera Notion + cofre + PR cross-linkados.
+argument-hint: "[branch destino opcional, padrão: detectado/sugerido]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+  - Write
+  - AskUserQuestion
+  - mcp__claude_ai_Notion__notion-create-pages
+  - mcp__claude_ai_Notion__notion-search
+  - mcp__claude_ai_Notion__notion-fetch
+---
+
+# /publicar-rapido — Pipeline Notion + PR + Cofre, sem cerimônia de milestone
+
+Variante de `/publicar` para mudanças que **não passaram pelo fluxo completo de milestone**: hotfix em produção, fix expresso (1 migration / 1 PR), refatoração curta, mudança trivial que precisa cross-link Notion + Obsidian + PR mesmo sem ROADMAP arquivado.
+
+## Quando usar
+
+- Hotfix em produção: 1-3 commits, branch curta, sem milestone aberto.
+- Pequena feature isolada que não justificou abrir milestone.
+- Correção de bug urgente que precisa ir documentada mas o overhead do `/publicar` não compensa.
+
+**Não use** quando o trabalho foi um milestone de várias fases — use `/publicar` (que valida MILESTONE-AUDIT.md, ROADMAP arquivado, etc).
+
+## Diferenças vs /publicar
+
+| Aspecto | `/publicar` | `/publicar-rapido` |
+|---|---|---|
+| Pré-requisitos de planejamento | ROADMAP + MILESTONE-AUDIT obrigatórios | Apenas commit(s) na branch |
+| Detecção de versão | De `STATE.md` | De `package.json` ou git tag mais recente |
+| Detecção de tipo | Inferido do milestone | **Inferido do commit message** (`fix:`/`feat:`/`refactor:`/`chore:` prefix) |
+| Notion | Página de changelog do milestone | Entrada curta na página de **changelog** com 1 parágrafo |
+| Cofre Obsidian | Nota de PR + Changelog completo + componentes afetados | Apenas nota de PR + entrada no Changelog |
+| Pre-flight sync com `main` | Sim (Passo 0) | **Sim — herdado** |
+| Tempo médio | 60-90s | **~30s** |
+
+## Processo
+
+### Passo 0 — Pre-flight: sincronizar com main (obrigatório, herdado de /publicar)
+
+Igual ao Passo 0 do `/publicar`: `git fetch origin main`, lista commits novos, oferece rebase/merge/ignorar/cancelar via `AskUserQuestion`. **Não pule** — esse é exatamente o cenário onde dev paralelo causa conflito tardio em hotfix.
+
+### Passo 1 — Detectar contexto
+
+#### 1.1 — Tipo do commit
+
+Leia o commit mais recente (`git log -1 --format=%B`). Se houver múltiplos commits desde `origin/main`, leia todos (`git log origin/main..HEAD --format=%B`).
+
+Inferir `TIPO_MUDANCA` por prefix do **primeiro commit** ou pelo padrão majoritário se múltiplos:
+
+| Prefix | TIPO_MUDANCA | Notion section |
+|---|---|---|
+| `fix:` / `bugfix:` | `Corrigido` | Bug fix |
+| `feat:` / `feature:` | `Adicionado` | Feature |
+| `perf:` | `Melhorado` | Performance |
+| `refactor:` | `Alterado` | Refactor |
+| `chore:` / `docs:` / `style:` | `Alterado` | Manutenção |
+| `revert:` | `Removido` | Revert |
+| Sem prefix | `Alterado` | (perguntar via AskUserQuestion) |
+
+Se não conseguir inferir (nenhum prefix), use `AskUserQuestion`:
+- **header:** "Tipo"
+- **question:** "Tipo da mudança?"
+- **options:** "Correção (fix)", "Feature (feat)", "Refator (refactor)", "Outro"
+
+#### 1.2 — Título resumido
+
+Extraia o **primeiro commit message** sem o prefix. Se múltiplos commits, use o **mais descritivo** (mais longo). Limite a 60 chars.
+
+Exemplos:
+- `fix: corrige FK em contact_prefs migration` → `Corrige FK em contact_prefs migration`
+- `feat: adiciona índice em contacts.phone` → `Adiciona índice em contacts.phone`
+
+Apresente ao user via `AskUserQuestion`:
+- **question:** "Título sugerido: \"{TITULO}\". Confirma?"
+- **options:** Confirmar, Editar (text input)
+
+#### 1.3 — Versão
+
+Detecte `VERSION` (ordem de prioridade):
+1. `package.json` campo `version` (incremente o patch — ex: `1.2.3` → `1.2.4`)
+2. Tag git mais recente: `git describe --tags --abbrev=0` (incremente patch)
+3. Sem fonte: use timestamp `YYYY-MM-DD-HHMMSS`
+
+Apresente via `AskUserQuestion`:
+- **question:** "Próxima versão: {VERSION}. Confirma ou pula bump de package.json?"
+- **options:** Bump+commit, Sem bump (só Notion+PR)
+
+Se "Bump+commit", execute:
+```bash
+npm version patch --no-git-tag-version
+git add package.json package-lock.json
+git commit -m "chore: bump {VERSION}"
+```
+
+### Passo 2 — Decidir branch
+
+Igual ao `/publicar` Passo 2 — usar branch atual ou criar nova baseada no `TIPO_MUDANCA`. Sugestão de nome:
+
+- `fix:` → `fix-{slug-do-titulo}`
+- `feat:` → `feat-{slug-do-titulo}`
+- `refactor:` → `refactor-{slug-do-titulo}`
+
+### Passo 3 — Criar página Notion (curta)
+
+Carregue `.claude/notion-config.json` (com fallback do auto-detect — Passo 0.5 do `/publicar`).
+
+Use `notion-create-pages` com `parent.page_id = NOTION_CHANGELOG_PAGE_ID`.
+
+**Template enxuto (não confundir com o template completo do /publicar):**
+
+```
+Título: {VERSION} — {TITULO}
+Ícone: 🩹 (fix) | ✨ (feat) | 🔧 (refactor) | 🧹 (chore)
+
+[Callout cinza] Quick fix · {DATA} · Branch: `{BRANCH}` · Tipo: {TIPO_MUDANCA}
+
+## O que mudou
+
+{1 parágrafo descrevendo a mudança em linguagem direta — extraia do commit body se houver, senão use o título expandido.}
+
+## Arquivos tocados
+
+[Tabela: Arquivo | O que mudou]
+{lista de `git diff origin/main..HEAD --stat` resumida — primeiros 10 arquivos}
+
+## Como verificar
+
+{Se TIPO_MUDANCA = fix: instrução curta de smoke test do bug. Se feat: passo a passo de uso. Se refactor: nota dizendo "sem mudança de comportamento esperada".}
+
+## Referências
+
+- Commit(s): `{lista de hashes curtos}`
+- Branch: `{BRANCH}`
+- PR: (será preenchido pelo dev após o passo 4)
+```
+
+Armazene `NOTION_URL`.
+
+Se houver `PENDENTE_COMMIT = true` (Passo 2), execute o commit agora com o link incluído:
+
+```bash
+git commit -m "{TIPO_MUDANCA_PREFIX}: {TITULO}
+
+Notion: {NOTION_URL}"
+```
+
+### Passo 4 — Push + PR
+
+```bash
+git push origin {BRANCH}
+
+gh pr create \
+  --title "{TIPO_MUDANCA_PREFIX}: {TITULO}" \
+  --body "..."
+```
+
+**Body do PR (template enxuto):**
+
+```markdown
+## {TITULO}
+
+{1 parágrafo do que mudou}
+
+### Arquivos
+{lista de até 5 paths}
+
+### Documentação
+📄 Notion: {NOTION_URL}
+{Se OBSIDIAN_URL definido: 📚 Cofre: {OBSIDIAN_URL}}
+
+### Sync com main
+{Se SYNC_SKIPPED = true: ⚠️ PR aberto sem rebase com origin/main — possível conflito ao revisar.}
+{Senão: ✓ Sincronizado com main em {timestamp}.}
+```
+
+Sem rodapé de IA. Sem assinatura de tooling.
+
+### Passo 5 — Cofre Obsidian (curto)
+
+Igual ao Passo 0.7 + 5 do `/publicar`, mas com escrita reduzida:
+
+- **Nota de PR** (obrigatória): `01 - PRs/YYYY/YYYY-MM-DD-pr-{PR_NUMBER}-{slug}.md` com frontmatter `notion: {NOTION_URL}`.
+- **Changelog**: adicionar 1 linha em `03 - Changelog/YYYY.md` na seção apropriada (`### Corrigido` / `### Adicionado` / etc baseado em `TIPO_MUDANCA`), referenciando PR.
+- **Componentes afetados**: PULAR. /publicar-rapido não atualiza notas de componente — usar `/publicar` quando o escopo justificar.
+
+Mesma cerimônia de commit + push do cofre.
+
+### Passo 6 — Reportar
+
+```
+🩹 Quick publish concluída em ~{TEMPO_TOTAL}s
+
+📄 Notion:   {NOTION_URL}
+🔗 PR:       {PR_URL}
+📚 Obsidian: {OBSIDIAN_URL}      ← ou ⚠️ pulado: {motivo}
+🌿 Branch:   {BRANCH}
+🏷  Tipo:     {TIPO_MUDANCA}
+```
+
+## Para projetos novos
+
+Mesmo `notion-config.json` do `/publicar`. Auto-detect (Passo 0.5 herdado) cobre o caso de config ausente — basta a página existir no Notion.

package/kit/commands/publicar.md

@@ -20,10 +20,11 @@ Publica o milestone atual: cria documentação no Notion, abre PR no GitHub e in
 
 Após concluir e arquivar um milestone com `/concluir-marco`.
 
+**Heurística de gatilho (importante):** quando o usuário diz "publicar" depois de aplicar mudanças de código (commits novos, migration aplicada, branch atual com diff vs `main`), interprete como **pipeline completo** — não apenas `git push`. Faça Notion + PR + Obsidian. Para push isolado em outra branch sem cerimônia, o usuário deve pedir explicitamente "só fazer push" ou usar `git push` ele mesmo. Para fix expresso sem milestone, use `/publicar-rapido` (variante leve sem dependência de ROADMAP/MILESTONE-AUDIT).
+
 ## Dependências obrigatórias
 
-- `.claude/notion-config.json` presente e preenchido — se não existir, encerre com:
-  > "⛔ notion-config.json não encontrado. Execute /setup-notion para configurar o Notion deste projeto."
+- `.claude/notion-config.json` presente e preenchido — **fluxo de fallback novo (1.4):** se ausente, NÃO encerre. Em vez disso, vá para o **Passo 0.5 (auto-detect Notion)** abaixo: tente buscar a página do projeto via Notion MCP `notion-search` no workspace e ofereça gerar o config automaticamente. Encerrar é fallback de último recurso.
 - Notion MCP configurado na sessão Claude Code
 - `gh` CLI autenticado (`gh auth status`)
 - Milestone arquivado com `/concluir-marco`
@@ -31,10 +32,129 @@ Após concluir e arquivar um milestone com `/concluir-marco`.
 ## Dependências opcionais
 
 - `$OBSIDIAN_TEAM_VAULT` — caminho absoluto do cofre Obsidian do time (sincronizado via Git).
-  - Se ausente ou inválido: o **Passo 5 (Obsidian)** é pulado com aviso, sem quebrar PR/Notion.
+  - **Fallback novo (1.4):** se ausente, antes de pular o Passo 5, o **Passo 0.7 (auto-detect Obsidian)** tenta caminhos canônicos (`~/Documentos/Obsidian/chat-trynux/`, `~/Documents/Obsidian/chat-trynux/`, e variantes Windows). Só se nenhum bater é que o Passo 5 é pulado com aviso.
 
 ## Processo
 
+### Passo 0 — Pre-flight: sincronizar com `main` ⚠️ NOVO 1.4
+
+**Por que isso existe:** vários devs trabalhando no mesmo projeto significa que `origin/main` pode ter avançado desde sua última sincronização. Antes de abrir PR, descubra se há trabalho novo e dê ao dev a chance de integrar (evita conflitos grandes mais tarde).
+
+**Quando pular:** se `BRANCH = main` (vai pushar direto pra main, sem PR), pode pular este passo. Em qualquer outro fluxo, execute.
+
+#### 0.1 — Buscar atualizações de origin
+
+```bash
+git fetch origin main 2>&1
+```
+
+#### 0.2 — Detectar commits novos em main
+
+```bash
+NEW_COMMITS=$(git log HEAD..origin/main --oneline 2>/dev/null)
+COUNT=$(echo "$NEW_COMMITS" | grep -c . 2>/dev/null || echo 0)
+```
+
+#### 0.3 — Roteamento
+
+**Se `COUNT == 0`:** sem commits novos. Continue silenciosamente para o Passo 1.
+
+**Se `COUNT > 0`:** apresente a lista ao usuário e pergunte como prosseguir.
+
+```
+⚠️ {COUNT} commit(s) novo(s) em origin/main desde sua última sync:
+
+{lista dos commits, primeiros 10}
+
+Como deseja prosseguir?
+```
+
+Use `AskUserQuestion`:
+- **header:** "Sync"
+- **question:** "Há {COUNT} commit(s) novo(s) em main. Como prosseguir antes de abrir PR?"
+- **options:**
+  - **"Integrar agora (Recomendado)"** — `git rebase origin/main` na branch atual. Se conflito: pausa, instrui resolver, retoma.
+  - **"Mesclar via merge commit"** — `git merge origin/main` (preserva histórico ao custo de um merge commit no PR).
+  - **"Ignorar e continuar"** — segue direto para Passo 1 (assume responsabilidade pelo conflito tardio).
+  - **"Cancelar publicação"** — exit limpo. Dev integra manualmente, depois reroda /publicar.
+
+**Em "Integrar agora":**
+```bash
+git rebase origin/main
+```
+- Se exit 0: continue para Passo 1 com confirmação `✓ Rebase OK`.
+- Se conflito: imprima `⚠️ Conflito durante rebase. Resolva os arquivos listados, rode \`git rebase --continue\` (ou \`git rebase --abort\` para desfazer), e reinvoque /publicar.` e exit limpo.
+
+**Em "Mesclar":**
+```bash
+git merge origin/main --no-edit
+```
+- Mesmo tratamento de conflito.
+
+**Em "Ignorar":** registre `SYNC_SKIPPED = true` (será mencionado na descrição do PR como heads-up: "PR aberto sem sync com main — possível conflito ao revisar").
+
+**Em "Cancelar":** exit limpo, sem efeito colateral.
+
+### Passo 0.5 — Auto-detect notion-config.json (se ausente) ⚠️ NOVO 1.4
+
+Se `.claude/notion-config.json` existe, pule para Passo 0.7.
+
+Se ausente:
+
+#### 0.5.1 — Buscar página do projeto via Notion MCP
+
+```
+notion-search { query: "{NOME_PROJETO}", filter: "page" }
+```
+
+Onde `{NOME_PROJETO}` vem do `.planning/PROJECT.md` (campo `name` ou primeira frase).
+
+#### 0.5.2 — Apresentar candidatos
+
+Filtre resultados pra páginas com título que contenha o nome do projeto (case-insensitive). Mostre top 3 com URL e last-edited.
+
+Use `AskUserQuestion`:
+- **question:** "Encontrei essas páginas no Notion. Qual é a página raiz deste projeto?"
+- **options:** uma por candidato + "Nenhuma — abrir /setup-notion"
+
+Em candidato escolhido:
+- Use `notion-fetch` na página escolhida pra listar subpáginas (espera-se `changelog/`, `features/`, `adr/`, `runbooks/`).
+- Para cada subpágina conhecida, capture o ID.
+- Gere `.claude/notion-config.json` com o template do `/setup-notion`.
+- Confirme: "✓ notion-config.json criado a partir das páginas existentes."
+
+Em "Nenhuma": exit limpo com mensagem `⛔ Execute /setup-notion para criar a estrutura Notion deste projeto, depois rerun /publicar.`
+
+### Passo 0.7 — Auto-detect cofre Obsidian (se env var ausente) ⚠️ NOVO 1.4
+
+Se `$OBSIDIAN_TEAM_VAULT` está definida E o caminho existe, pule para Passo 1.
+
+Se ausente, tente caminhos canônicos em ordem (primeiro que existir vence):
+
+| Plataforma | Caminho |
+|---|---|
+| Linux/macOS | `$HOME/Documentos/Obsidian/chat-trynux` |
+| Linux/macOS | `$HOME/Documents/Obsidian/chat-trynux` |
+| Windows | `$USERPROFILE/Documentos/Obsidian/chat-trynux` |
+| Windows | `$USERPROFILE/Documents/Obsidian/chat-trynux` |
+| WSL | `/mnt/c/Users/$USER/Documents/Obsidian/chat-trynux` |
+
+```bash
+for CANDIDATE in \
+  "$HOME/Documentos/Obsidian/chat-trynux" \
+  "$HOME/Documents/Obsidian/chat-trynux" \
+  "$USERPROFILE/Documentos/Obsidian/chat-trynux" \
+  "$USERPROFILE/Documents/Obsidian/chat-trynux" \
+  "/mnt/c/Users/$USER/Documents/Obsidian/chat-trynux"; do
+  [ -n "$CANDIDATE" ] && [ -d "$CANDIDATE" ] && { export OBSIDIAN_TEAM_VAULT="$CANDIDATE"; break; }
+done
+```
+
+- Se uma das variantes bateu: registre `OBSIDIAN_AUTO_DETECTED = true` e prossiga normalmente para Passo 1.
+- Se nenhuma bateu: comportamento legado (Passo 5 será pulado com `OBSIDIAN_SKIP_REASON = "OBSIDIAN_TEAM_VAULT não configurada e nenhum caminho canônico encontrado"`).
+
+> **Nota:** o nome `chat-trynux` é o cofre canônico padrão. Para usar outro nome, defina `$OBSIDIAN_TEAM_VAULT` explicitamente — a auto-detecção não tenta diretórios alternativos.
+
 ### Passo 1 — Ler contexto
 
 Leia os seguintes arquivos: