wendkeep 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.27.0] — 2026-07-08
+
+### Fixed
+- **Re-running `wendkeep init` no longer re-asks for the vault (or language) — and can't split your
+  data.** On a project already set up, init now reads the registered vault from
+  `.claude/settings.json` (`OBSIDIAN_VAULT_PATH`) and the locked locale from the vault's
+  `.brain/config.json`, reuses both, and skips the prompts. Previously a re-run (e.g. after
+  `npm i -D wendkeep@latest`) offered the *derived* default (`.<project>-vault`); accepting it — or
+  mistyping the name — created a **second, divergent vault**. `--vault` / `--locale` still override.
+  New exported `detectRegisteredVault()` / `readVaultLocale()`. `src/init.mjs`.
+
+### Note
+- You do **not** need `wendkeep init` for a routine update: the hooks live in the package
+  (`settings.json` calls `npx wendkeep hook …`), so `npm i -D wendkeep@latest` updates them.
+  Re-run `init` only when a release adds new wiring (the CHANGELOG says so); it's idempotent.
+
+## [0.26.0] — 2026-07-08
+
+### Fixed
+- **`wendkeep init` output now follows the chosen vault language.** Picking Português left the
+  whole summary + `[n/4]` steps + "Next steps" block in English; only the interactive prompts were
+  localized. All init output is now driven by a locale message set (pt-BR / en) resolved from the
+  language answer — "Próximos passos", "taxonomia do vault", "sensores semeados", etc. `src/init.mjs`.
+
+## [0.25.1] — 2026-07-08
+
+### Added
+- **Landing page in the repo**: a static SVG hero (`docs/assets/wendkeep-hero.svg`, the knowledge
+  graph) embedded at the top of the README, plus the self-contained interactive landing at
+  `docs/index.html` (live Canvas graph; serve `docs/` via GitHub Pages for a public URL).
+
+### Changed
+- `wendkeep stats` now says **"N dias ativos (first→last)"** — the count is distinct days *with
+  activity*, not the calendar span; the old "N dia(s)" read as calendar days.
+
 ## [0.25.0] — 2026-07-08
 
 Cost trend/projection + shareable stats + launch assets.

package/README.md

@@ -1,5 +1,7 @@
 # wendkeep
 
+[Português](README.pt-BR.md) · **English**
+
 > **Your AI coding agent forgets every session. wendkeep makes it remember — in the Obsidian vault you already use.**
 
 [![npm](https://img.shields.io/npm/v/wendkeep.svg)](https://www.npmjs.com/package/wendkeep)
@@ -7,6 +9,10 @@
 ![zero deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)
 ![node](https://img.shields.io/badge/node-%E2%89%A518-blue)
 
+[![wendkeep — persistent memory for AI coding agents, shown as a knowledge graph of sessions, decisions, bugs, learnings and changes](docs/assets/wendkeep-hero.svg)](docs/index.html)
+
+**In the graph:** 🔵 session · 🟣 decision · 🔴 bug · 🟢 learning · 🟡 change — every note, backlinked.
+
 **A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code / Codex session is captured turn‑by‑turn into local Markdown — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. On top of that memory core sits a native, zero‑dependency **change lifecycle** (spec → change → TDD → sensor‑gated archive) that keeps intent, work and proof wikilinked in one graph. 100% local, open‑core.
 
 ```bash
@@ -14,24 +20,28 @@ npm i -D wendkeep && npx wendkeep init      # captures from the next session on
 npx wendkeep import                          # backfill past Claude + Codex sessions
 ```
 
-<!-- SCREENSHOT: Obsidian graph of a wendkeep vault (sessions ↔ decisions ↔ bugs ↔ changes). Drop a PNG/GIF at docs/assets/graph.png and reference it here. -->
+**▶ Interactive demo:** [`docs/index.html`](docs/index.html) — a self-contained page with the live knowledge‑graph hero. Open it locally (or serve `docs/` on any static host). The image above is a static render of it.
+
+> **From one real production vault** (`npx wendkeep stats`): **308** sessions · **1,696** prompts · **$4,836** captured across **46 active days** (Jan–Jul 2026) · **15** models — every one a note in the graph.
+
+<!-- Optional: drop a real Obsidian graph screenshot at docs/assets/graph.png and add it here (see docs/21-graph-screenshot.md). -->
 
 > Extracted from a system in daily production use: the capture engine, cost tracking and graph wiring are battle‑tested; the cross‑platform installer (`wendkeep init`) and the native change loop are the newer parts. See [`docs/`](https://github.com/rogersialves/wendkeep/tree/main/docs) for the project's strategy and decision log.
 
 ---
 
-## Why
-
-The pieces to give a coding agent durable memory exist, but fragmented (qmd‑sessions, memsearch, Nexus, hand‑written hooks). wendkeep ships them as one turnkey package that lands the memory **inside the Obsidian graph you already use** — no manual setup, no snapshot to keep in sync.
+## The problem: the context dies when the window closes
 
-## What you get
+Decisions, dead ends, the reason you chose X over Y — gone next session. The pieces to fix that exist but are scattered (qmd‑sessions, memsearch, Nexus, hand‑written hooks). wendkeep ships them as one turnkey package that writes into a knowledge graph **inside the Obsidian vault you already use** — no manual setup, no snapshot to keep in sync.
 
-- **Automatic session capture** — `SessionStart` / `UserPromptSubmit` / `Stop` hooks write each session to `02-Sessões/<year>/<month>/DIA <dd>/` as Markdown with YAML frontmatter, turn‑by‑turn iterations, and wikilinks.
-- **Multi‑agent** — detects the real provider (Claude Code, Codex, Copilot) at runtime; one install covers all.
-- **Token & cost tracking** — per‑model, cache‑aware pricing (`pricing.json`) with a per‑session usage table.
-- **Auto‑extracted derived notes** — decisions (ADR‑style), bugs and learnings pulled from the transcript into `04-Decisões/`, `05-Bugs/`, `06-Aprendizados/`, backlinked to the session.
-- **Curated memory** — a cold frontmatter index (`.brain/`) plus a budget‑capped `CORE` + `DIGEST` injected at the next `SessionStart`.
-- **Local‑first** — everything is plain Markdown on your disk. The optional MCP server (`@bitbonsai/mcpvault`) lets the agent read/write the vault; no cloud, no account.
+| | |
+|---|---|
+| **Capture** — every turn, on disk | `SessionStart` / `Stop` hooks write each session to a dated Markdown note: prompts, iterations, files touched, wikilinks. |
+| **Derive** — decisions, bugs, learnings | Pulled from the transcript into their own notes, backlinked to the session. Your history becomes navigable, not archival. |
+| **Recall** — injected back | A budget‑capped `CORE` + `DIGEST` and the active change are fed to the agent at the next `SessionStart`. It resumes where it left off. |
+| **Cost** — what it all cost | Per‑model, cache‑aware token pricing per session — plus `cost --trend` with a run‑rate projection across the whole vault. |
+| **Multi‑agent** — one install, all agents | Detects the real provider (Claude Code, Codex, Copilot) at runtime. |
+| **Local‑first** — no cloud, no account | Everything is plain Markdown on your disk. An optional MCP server (`@bitbonsai/mcpvault`) lets the agent read/write the vault. |
 
 ## Requirements
 
@@ -114,9 +124,9 @@ No re‑copying, no snapshot to re‑sync — the package is the single source o
 | `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
 | `wendkeep --version` / `--help` | Version / usage. |
 
-## Retroactive memory (`import`)
+## Retroactive memory (`import`) — install today, remember yesterday
 
-Install wendkeep into an existing project and it only remembers sessions **from now on**. `wendkeep import` fixes that: it reads the project's past **Claude Code and Codex** transcripts and rebuilds each one as a full session note in its **real** date folder — frontmatter (tagged with the transcript's real provider), one iteration block per turn, cost + subagent telemetry, derived decision/bug/learning notes, finalized closing. It is an offline replay of the live capture flow, so an imported note is indistinguishable from a captured one.
+Install wendkeep into an existing project and it only remembers sessions **from now on**. `wendkeep import` fixes that: one command backfills your project's past **Claude & Codex** sessions into the vault — deduped, dated, with cost — so the graph starts full, not empty. It rebuilds each transcript as a full session note in its **real** date folder — frontmatter (tagged with the transcript's real provider), one iteration block per turn, cost + subagent telemetry, derived decision/bug/learning notes, finalized closing. An offline replay of the live capture flow, so an imported note is indistinguishable from a captured one.
 
 ```bash
 wendkeep import --vault .myproject-vault --dry-run   # preview what would be imported (both agents)
@@ -143,6 +153,8 @@ explore → propose → apply (TDD) → verify → archive
 - **Verify** — `wendkeep verify` runs the sensors your tasks declared (from `wendkeep.sensors.json` at the project root) and records `evidencia.json`. A critical red fails the gate; a `warning` red is advisory.
 - **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each capability's spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md`, moves the change to `_arquivo/`, and mints an ADR in `04-Decisões/`.
 
+> The gate blocks unless the scaffold is filled, no task is open, evidence is fresh, and every declared requirement is covered. **`--force` is the human's call — never the agent's.**
+
 `wendkeep init` also seeds **native process skills** (`wk-workflow`, `wk-tdd`, `wk-debugging`, `wk-brainstorming`, `wk-planning`, `wk-verify`) into `.brain/skills` and delivers them to `.claude/skills` — the *how* layer, zero‑dep. Optional companions (`context-mode`, `dotcontext`, `understand-anything`, `caveman`) remain an opt‑in extra layer.
 
 ### The loop in five minutes
@@ -193,6 +205,16 @@ The archive **gate** blocks unless: the change scaffold is filled (G0), no task
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
 - Installer wires **Claude Code** settings + `.mcp.json`. Codex hooks run on the same scripts but are not auto‑wired yet (import already covers past Codex sessions via `--source codex`).
 
+---
+
+## Stop re‑explaining your codebase every morning
+
+```bash
+npm i -D wendkeep && npx wendkeep init
+```
+
+**[Install from npm](https://www.npmjs.com/package/wendkeep)** · **[Star on GitHub](https://github.com/rogersialves/wendkeep)** — MIT · open‑core · your data never leaves your disk.
+
 ## License
 
 MIT

package/README.pt-BR.md

@@ -0,0 +1,189 @@
+# wendkeep
+
+**Português** · [English](README.md)
+
+> **Seu agente de código esquece cada sessão. O wendkeep faz ele lembrar — no cofre Obsidian que você já usa.**
+
+[![npm](https://img.shields.io/npm/v/wendkeep.svg)](https://www.npmjs.com/package/wendkeep)
+![test](https://github.com/rogersialves/wendkeep/actions/workflows/test.yml/badge.svg)
+![zero deps](https://img.shields.io/badge/deps%20de%20runtime-0-brightgreen)
+![node](https://img.shields.io/badge/node-%E2%89%A518-blue)
+
+[![wendkeep — memória persistente para agentes de código, mostrada como um grafo de sessões, decisões, bugs, aprendizados e mudanças](docs/assets/wendkeep-hero.pt.svg)](docs/index.pt.html)
+
+**No grafo:** 🔵 sessão · 🟣 decisão · 🔴 bug · 🟢 aprendizado · 🟡 mudança — cada nota, com backlink.
+
+**Um harness de memória persistente para agentes de código, construído sobre o seu cofre Obsidian.** Cada sessão do Claude Code / Codex é capturada turno a turno em Markdown local — com rastreio de tokens/custo, decisões, bugs e aprendizados extraídos automaticamente, e uma camada de memória curada injetada de volta no início da próxima sessão. Sobre esse núcleo de memória fica um **ciclo de mudança** nativo e sem dependências (spec → change → TDD → archive com gate por sensor) que mantém intenção, trabalho e prova wikilinkados num só grafo. 100% local, open‑core.
+
+```bash
+npm i -D wendkeep && npx wendkeep init      # captura a partir da próxima sessão
+npx wendkeep import                          # importa sessões passadas do Claude + Codex
+```
+
+**▶ Demo interativo:** [`docs/index.pt.html`](docs/index.pt.html) — uma página autocontida com o herói de grafo vivo. Abra local (ou sirva `docs/` em qualquer host estático). A imagem acima é um render estático dele.
+
+> **De um cofre de produção real** (`npx wendkeep stats`): **308** sessões · **1.696** prompts · **US$ 4.836** capturados em **46 dias ativos** (jan–jul 2026) · **15** modelos — cada uma delas uma nota no grafo.
+
+> Extraído de um sistema em uso diário de produção: o motor de captura, o rastreio de custo e a fiação do grafo são testados em batalha; o instalador multiplataforma (`wendkeep init`) e o ciclo de mudança nativo são as partes mais novas. Veja [`docs/`](https://github.com/rogersialves/wendkeep/tree/main/docs) para a estratégia e o log de decisões do projeto.
+
+---
+
+## O problema: o contexto morre quando a janela fecha
+
+Decisões, becos sem saída, o motivo de você ter escolhido X em vez de Y — some na próxima sessão. As peças pra resolver existem, mas espalhadas (qmd‑sessions, memsearch, Nexus, hooks feitos à mão). O wendkeep entrega tudo num pacote turnkey que escreve num grafo de conhecimento **dentro do cofre Obsidian que você já usa** — sem setup manual, sem snapshot pra manter sincronizado.
+
+| | |
+|---|---|
+| **Captura** — cada turno, no disco | Os hooks `SessionStart` / `Stop` escrevem cada sessão numa nota Markdown datada: prompts, iterações, arquivos tocados, wikilinks. |
+| **Deriva** — decisões, bugs, aprendizados | Puxados do transcript pra notas próprias, com backlink pra sessão. Seu histórico fica navegável, não arquivístico. |
+| **Recall** — injetado de volta | Um `CORE` + `DIGEST` com budget capado e a change ativa são injetados no agente no próximo `SessionStart`. Ele retoma de onde parou. |
+| **Custo** — quanto tudo custou | Preço por modelo, ciente de cache, por sessão — mais `cost --trend` com projeção run‑rate no cofre inteiro. |
+| **Multi‑agente** — uma instalação, todos os agentes | Detecta o provedor real (Claude Code, Codex, Copilot) em runtime. |
+| **Local‑first** — sem nuvem, sem conta | Tudo é Markdown puro no seu disco. Um MCP opcional (`@bitbonsai/mcpvault`) deixa o agente ler/escrever o cofre. |
+
+## Requisitos
+
+- Node.js ≥ 18
+- Um agente de código com hooks (Claude Code hoje; Codex atendido pelos mesmos hooks)
+- Obsidian (pra ver o grafo) — opcional, mas é o ponto
+
+## Instalar & configurar
+
+```bash
+# no seu projeto
+npm install --save-dev wendkeep   # ou: npm install -g wendkeep
+npx wendkeep init
+```
+
+O `wendkeep init` é interativo e **idempotente**. Ele:
+
+1. Cria a taxonomia de pastas do cofre e um `README.md` templado (cofre padrão: `<projeto>/.<nome-do-projeto>-vault`, ex.: `.MeuApp-vault`; sobrescreva com `--vault`).
+2. **Mescla** os três hooks de sessão e o `OBSIDIAN_VAULT_PATH` no `.claude/settings.json` — sem atropelar suas configs (salva um `.bak`; arquivo ilegível fica intocado e um `.new` é escrito pra você mesclar).
+3. Adiciona o servidor MCP **`wendkeep-vault`** ao `.mcp.json` pro agente ler/escrever o cofre. Pule com `--no-mcp` — ex.: quando o agente já tem um MCP de cofre. (`--no-mcp` pula *só o MCP do próprio wendkeep*; os MCPs de companion seguem `--companions`.)
+4. Oferece fixar plugins/MCP **companion** (múltipla escolha; **nenhum** pré-marcado). Cada um é wirado do jeito mais agnóstico que suporta:
+   - **`context-mode`** — otimizador de contexto + memória FTS5, como servidor MCP no `.mcp.json` (qualquer agente).
+   - **`understand-anything`** — grafo de domínio do projeto, via um hook `understand-inject` no SessionStart que injeta o grafo quando gerado.
+   - **`caveman`** — modo de compressão de tokens; roda seu próprio instalador cross‑agent em agentes não‑Claude.
+   - **`dotcontext`** — *legado, não recomendado.* O loop a2 nativo do wendkeep (`change` / `verify` / gate) já faz o trabalho dele, então instalar **duplica o harness**. Ainda selecionável via `--companions dotcontext` pra quem já usa (ajuste com `--dotcontext-mcp` / `--dotcontext-hooks`), mas off por padrão.
+
+   Controle com `--companions <csv>` ou `--no-companions`. A camada de plugin do Claude Code (`extraKnownMarketplaces` + `enabledPlugins`) é wirada como bônus onde o companion tiver uma.
+5. Instala um **sistema de cores** no `.obsidian/` do cofre: um snippet CSS que colore notas por tipo (sessão/decisão/bug/aprendizado, via as `cssclasses` que os hooks emitem) mais grupos de cor do grafo por pasta. Merge não‑destrutivo em `appearance.json`/`graph.json`; pule com `--no-colors`.
+6. Semeia a **camada de memória curada**: `.brain/CORE.md` (a camada quente curada à mão, com as 3 seções obrigatórias) e `.brain/COMPACTION_PROTOCOL.md` (o guia do protocolo). As camadas automáticas (`DIGEST.md`, `index.jsonl`) são geradas pelos hooks. Valide a camada curada com `wendkeep validate-memory` (cap 25 linhas, 3 seções, sem segredos/PII).
+7. Semeia a **camada de definições + skills**: `.brain/agents/` + `.brain/skills/` (fonte da verdade versionada), incluindo as skills de processo nativas `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning` / `wk-verify` (algumas trazem templates, ex.: o `verdict-template.json` + prompt de revisor da `wk-verify`). O `init` roda o `wendkeep sync-defs` pra você, entregando em `.codex/agents/` + `.claude/skills/` (rode `sync-defs` de novo após editar o `.brain`).
+8. Semeia o **ciclo change/spec**: as pastas `07-Specs/` + `08-Mudanças/` e um `wendkeep.sensors.json` nativo (um sensor `validate-memory` mais um por script detectado no `package.json`). Move o `wendkeep change` / `wendkeep verify` — veja **Ciclo de mudança** abaixo.
+
+```bash
+npx wendkeep init --vault "~/vaults/work" --project . --yes   # não-interativo
+npx wendkeep init --companions "context-mode,understand-anything" --yes
+npx wendkeep init --no-companions --no-mcp --yes              # zero companions, sem MCP do wendkeep
+```
+
+### Opções do `init`
+
+| Flag | O que faz |
+|---|---|
+| `--vault <path>` | Pasta do cofre. Padrão `<projeto>/.<nome-do-projeto>-vault`; o init interativo pergunta. Aponte pra um cofre existente pra instalar nele. |
+| `--project <path>` | Raiz do projeto a wirar (padrão: diretório atual). |
+| `--locale <pt-BR\|en>` | Idioma do cofre — nomes das pastas, scaffold, skills. O init interativo pergunta; travado no init. |
+| `--companions <csv>` | Companions a fixar: `context-mode,caveman,understand-anything` (padrão: **nenhum** — opte explicitamente; `dotcontext` é legado). |
+| `--no-companions` | Não fixa nenhum companion. |
+| `--no-mcp` | Pula o MCP de cofre **do próprio wendkeep** (`wendkeep-vault`). Os MCPs de companion seguem `--companions`. |
+| `--no-colors` | Pula o sistema de cores do Obsidian (snippet `.obsidian` + grupos do grafo). |
+| `--yes`, `-y` | Não-interativo; aceita os padrões (pula os prompts de idioma / cofre / companion). |
+| `--force` | Sobrescreve os blocos de config do wendkeep existentes. |
+
+Depois abra o cofre no Obsidian, mande um prompt de teste no seu agente e confirme que uma nota aparece em `02-Sessões/…` (ou `02-Sessions/…` num cofre `en`).
+
+## Atualizar
+
+Como os hooks vivem dentro do pacote instalado (o settings.json chama `npx wendkeep hook <name>`), atualizar é só:
+
+```bash
+npm update wendkeep
+```
+
+Sem recopiar, sem snapshot pra re‑sincronizar — o pacote é a única fonte da verdade.
+
+## Comandos
+
+| Comando | O que faz |
+|---|---|
+| `wendkeep init` | Configura o wendkeep num projeto (taxonomia do cofre + settings + MCP + skills). |
+| `wendkeep hook <name>` | Roda um hook de sessão; invocado pelo `settings.json` (lê o JSON do agente no stdin). |
+| `wendkeep change <sub>` | Ciclo de mudança: `new [--simple]` / `list` / `show` / `status` / `done <id>` / `undone <id>` / `diff` / `archive [--force]`. |
+| `wendkeep verify [--deep]` | Roda os sensores das tarefas da change; `--deep` monta o pacote de verificação independente. |
+| `wendkeep spec <sub>` | Specs vivos: `list` / `show <capability>`. |
+| `wendkeep sensors <sub>` | `list` / `add <id> "<comando>"` — vê/edita `wendkeep.sensors.json` (JSON Schema incluso). |
+| `wendkeep cost [opts]` | Agrega o gasto de IA nas sessões do cofre — total, por modelo, por dia · `--top [N]` · `--trend [day\|week\|month]` (+ projeção) · `--write` (gera `00-Custo.md`) · `--json`. |
+| `wendkeep stats [--vault P]` | Uma linha compartilhável: sessões · prompts · gasto · período · modelos (`--json`). |
+| `wendkeep import [opts]` | **Memória retroativa** — importa sessões passadas de **Claude + Codex** pro cofre (dedup por `session_id`). `--source all\|claude\|codex` / `--from <dir>` / `--codex-from <dir>` / `--stamp-ids` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
+| `wendkeep dashboard [--force]` | (Re)gera os Bases filtrados por pasta + o MOC `00-Dashboard`. |
+| `wendkeep lesson add "t" "l"` | Registra uma lição local do projeto (injetada no próximo SessionStart). |
+| `wendkeep sync-defs` | Copia `.brain/agents\|skills` pro projeto (`.codex/agents`, `.claude/skills`). |
+| `wendkeep validate-memory [path]` | Valida `.brain/CORE.md` (cap 25, 3 seções, sem segredos/PII). |
+| `wendkeep doctor [--vault P]` | Roda um check de saúde do cofre (integridade de sessões, registry, links). |
+| `wendkeep --version` / `--help` | Versão / uso. |
+
+## Memória retroativa (`import`) — instale hoje, lembre de ontem
+
+Instale o wendkeep num projeto existente e ele só lembra sessões **a partir de agora**. O `wendkeep import` conserta isso: um comando importa as sessões passadas de **Claude & Codex** do projeto pro cofre — dedup, datadas, com custo — então o grafo começa cheio, não vazio. Reconstrói cada transcript como uma nota de sessão completa na pasta datada **real** — frontmatter (taggeado com o provedor real), um bloco de iteração por turno, custo + telemetria de subagents, notas derivadas de decisão/bug/aprendizado, encerramento finalizado. Um replay offline do fluxo de captura vivo, então uma nota importada é indistinguível de uma capturada.
+
+```bash
+wendkeep import --vault .meuprojeto-vault --dry-run   # prévia do que seria importado (os dois agentes)
+wendkeep import --vault .meuprojeto-vault             # escreve as notas
+wendkeep import --vault .meuprojeto-vault --source codex   # só Codex
+```
+
+- **Os dois agentes por padrão** (`--source all`). As sessões do Claude vêm de `~/.claude/projects/<slug>/`; os rollouts do Codex de `~/.codex/sessions/**`, escopados pro projeto pelo `cwd` gravado em cada sessão (insensível a case e separador, subpastas inclusas). Estreite com `--source claude` / `--source codex`.
+- Toda nota grava o **`session_id`** e o **`provider`** no frontmatter (captura live e import iguais). Carimbe notas antigas com `wendkeep import --stamp-ids` (preenche o id a partir do registry; idempotente).
+- **Dedup** por `session_id` contra o `SESSION_REGISTRY` do cofre **e** o frontmatter das notas existentes — só importa sessões ausentes e nunca sobrescreve. Rodar de novo é no‑op.
+- Depois de importar, o `wendkeep cost` agrega seu histórico inteiro — retroativamente, nos dois agentes.
+
+## Ciclo de mudança — o loop a2 (spec‑driven, nativo)
+
+Além de capturar sessões, o wendkeep é um **harness**: um loop nativo e sem dependências que mantém *intenção* (specs), *trabalho* (changes) e *prova* (sensores) juntos no cofre, wikilinkados no grafo Obsidian.
+
+```
+explore → propose → apply (TDD) → verify → archive
+```
+
+- **Propose** — `wendkeep change new <slug>` faz o scaffold de `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md` e um delta `specs/`). A change vira *ativa* e é injetada no próximo `SessionStart`, então o agente retoma o trabalho em curso.
+- **Apply** — implemente cada tarefa de `tarefas.md`. Taggeie a tarefa que precisa de prova de máquina com `[sensor:<id>]`.
+- **Verify** — `wendkeep verify` roda os sensores que suas tarefas declararam (do `wendkeep.sensors.json` na raiz do projeto) e grava `evidencia.json`. Um vermelho crítico falha o gate; um vermelho `warning` é aviso.
+- **Archive** — `wendkeep change archive <slug>` faz **gate** na evidência (bloqueia a não ser que todo sensor crítico declarado esteja verde), promove o delta de cada capability (`ADDED`/`MODIFIED`/`REMOVED`) pro `07-Specs/<capability>.md` vivo, move a change pro `_arquivo/` e cunha um ADR em `04-Decisões/`.
+
+> O gate bloqueia a não ser que o scaffold esteja preenchido, nenhuma tarefa aberta, evidência fresca e todo requisito declarado coberto. **`--force` é decisão do humano — nunca do agente.**
+
+O `wendkeep init` também semeia **skills de processo nativas** (`wk-workflow`, `wk-tdd`, `wk-debugging`, `wk-brainstorming`, `wk-planning`, `wk-verify`) em `.brain/skills` e as entrega em `.claude/skills` — a camada do *como*, zero‑dep. Companions opcionais (`context-mode`, `dotcontext`, `understand-anything`, `caveman`) ficam como camada extra opt‑in.
+
+## Como funciona
+
+```
+sessão do agente ──hooks──▶ wendkeep ──▶ Markdown no cofre ──▶ índice .brain + grafo Obsidian
+   (Claude/Codex)           (Node)      (02-Sessões/…)         (CORE+DIGEST, backlinks)
+```
+
+O settings.json do agente aponta cada hook pra `npx wendkeep hook …`. No `Stop`, o wendkeep parseia o transcript, anexa o turno, atualiza a tabela de tokens/custo e (idempotentemente) emite qualquer nota de decisão/bug/aprendizado. Em todo `SessionStart`, o `brain-inject` injeta de volta a memória curada (CORE + DIGEST), a change ativa, as lições do projeto e um roteador `<wk_process>` que roteia qualquer tarefa não‑trivial pelo loop a2 (planejar → `change new` + preencher o scaffold → TDD → verify → archive).
+
+O **gate** do archive bloqueia a não ser que: o scaffold da change esteja preenchido (G0), nenhuma tarefa esteja aberta (G1), todo sensor crítico declarado esteja verde (com evidência fresca) e — quando a change declara `[req:]` — um `verdict.json` independente cubra eles. O `--force` é a saída de emergência humana; o agente é instruído a nunca usar por conta própria.
+
+## Notas & roadmap
+
+- **Nomes das pastas do cofre são em Português por padrão** (`02-Sessões`, `04-Decisões`, …). Passe `wendkeep init --locale en` pra um cofre em inglês (`02-Sessions`, `04-Decisions`, scaffold/skills em inglês). O locale é uma propriedade do cofre, travada no init; os parsers são bilíngues, então conteúdo misto nunca quebra.
+- **Busca é scoring por keyword/frontmatter**, não embeddings on‑device (isso está no roadmap).
+- **Formatos de transcript são internos ao agente** e podem mudar entre versões; o parsing é isolado mas pode precisar de atualizações.
+- O instalador wira settings do **Claude Code** + `.mcp.json`. Os hooks do Codex rodam nos mesmos scripts mas ainda não são auto‑wirados (o import já cobre sessões Codex passadas via `--source codex`).
+
+---
+
+## Pare de reexplicar seu código toda manhã
+
+```bash
+npm i -D wendkeep && npx wendkeep init
+```
+
+**[Instalar do npm](https://www.npmjs.com/package/wendkeep)** · **[Deixar uma star no GitHub](https://github.com/rogersialves/wendkeep)** — MIT · open‑core · seus dados nunca saem do seu disco.
+
+## Licença
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {

package/src/init.mjs

@@ -223,6 +223,65 @@ export function promptStrings(localeId) {
   return PROMPTS[localeId] || PROMPTS['pt-BR'];
 }
 
+// Output messages by locale — the summary, the [n/4] steps and the next-steps block follow the
+// chosen vault language (before this, a pt-BR install still printed English output).
+const MESSAGES = {
+  'pt-BR': {
+    header: '\nwendkeep init',
+    lProject: '  projeto    ', lVault: '  vault      ', lMcp: '  mcp        ',
+    lCompanions: '  companions ', lColors: '  cores      ',
+    skipped: 'ignorado', none: 'nenhum',
+    colorsOn: 'wendkeep-colors (snippet + grupos do grafo)',
+    taxonomy: (n, c, loc, readme, views) => `  [1/4] taxonomia do vault: ${n} pastas (${c} criadas, locale ${loc})${readme}, .brain + change/spec + sensores semeados${views}`,
+    readmeCreated: ', README.md criado', viewsNote: (n) => `, ${n} view(s) + dashboard`,
+    defs: (s, a) => `        defs entregues: ${s} skill(s) -> .claude/skills, ${a} agent(s) -> .codex/agents`,
+    settingsBadJson: (p) => `  [2/4] settings.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
+    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wirados, OBSIDIAN_VAULT_PATH setado${bak})`,
+    mcpBadJson: (p) => `  [3/4] .mcp.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
+    mcp: (verb, names, bak) => `  [3/4] .mcp.json ${verb} (${names}${bak})`,
+    mcpSkipped: '  [3/4] .mcp.json ignorado (--no-mcp, sem companions MCP)',
+    colorsSkipped: '  [4/4] cores ignoradas (--no-colors)',
+    colors: (r) => `  [4/4] cores: ${r}`,
+    merged: 'mesclado', created: 'criado', bakSaved: ', .bak salvo',
+    nextSteps: '\nPróximos passos:',
+    step1: (v) => `  1. Abra o vault no Obsidian: "Abrir pasta como cofre" -> ${v}`,
+    step2: '  2. Garanta que o wendkeep está instalado onde o agente roda (npm i -D wendkeep, ou -g).',
+    step3: '  3. Abra o Claude Code neste projeto e envie um prompt de teste.',
+    step4: '  4. Confirme que uma nota aparece em 02-Sessões/<ano>/<mês>/DIA <dd>/ no vault.',
+    updateLater: '  Atualize depois com: npm update wendkeep  (sem recopiar — os hooks vivem no pacote).\n',
+    vaultRegistered: (v, loc) => `\n  cofre já registrado neste projeto: ${v} (locale ${loc}) — pergunta pulada. Use --vault para mudar.`,
+  },
+  en: {
+    header: '\nwendkeep init',
+    lProject: '  project    ', lVault: '  vault      ', lMcp: '  mcp        ',
+    lCompanions: '  companions ', lColors: '  colors     ',
+    skipped: 'skipped', none: 'none',
+    colorsOn: 'wendkeep-colors (snippet + graph groups)',
+    taxonomy: (n, c, loc, readme, views) => `  [1/4] vault taxonomy: ${n} folders (${c} created, locale ${loc})${readme}, .brain + change/spec + sensors seeded${views}`,
+    readmeCreated: ', README.md created', viewsNote: (n) => `, ${n} view(s) + dashboard`,
+    defs: (s, a) => `        defs delivered: ${s} skill(s) -> .claude/skills, ${a} agent(s) -> .codex/agents`,
+    settingsBadJson: (p) => `  [2/4] settings.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
+    settings: (verb, added, bak) => `  [2/4] settings.json ${verb} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${bak})`,
+    mcpBadJson: (p) => `  [3/4] .mcp.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
+    mcp: (verb, names, bak) => `  [3/4] .mcp.json ${verb} (${names}${bak})`,
+    mcpSkipped: '  [3/4] .mcp.json skipped (--no-mcp, no MCP companions)',
+    colorsSkipped: '  [4/4] colors skipped (--no-colors)',
+    colors: (r) => `  [4/4] colors: ${r}`,
+    merged: 'merged', created: 'created', bakSaved: ', .bak saved',
+    nextSteps: '\nNext steps:',
+    step1: (v) => `  1. Open the vault in Obsidian: "Open folder as vault" -> ${v}`,
+    step2: '  2. Make sure wendkeep is installed where the agent runs (npm i -D wendkeep, or -g).',
+    step3: '  3. Open Claude Code in this project and send a test prompt.',
+    step4: '  4. Confirm a note appears under 02-Sessões/<year>/<month>/DIA <dd>/ in the vault.',
+    updateLater: '  Update later with: npm update wendkeep  (no re-copying — hooks live in the package).\n',
+    vaultRegistered: (v, loc) => `\n  vault already registered for this project: ${v} (locale ${loc}) — prompt skipped. Use --vault to change.`,
+  },
+};
+
+export function initMessages(localeId) {
+  return MESSAGES[localeId] || MESSAGES['pt-BR'];
+}
+
 // Map the language answer to a locale id. 2/en → en; 1/pt/empty/unknown → pt-BR.
 export function parseLocaleAnswer(ans) {
   const a = String(ans || '').trim().toLowerCase();
@@ -230,23 +289,53 @@ export function parseLocaleAnswer(ans) {
   return 'pt-BR';
 }
 
+// The vault path this project was set up with — read from .claude/settings.json's
+// OBSIDIAN_VAULT_PATH (written by a prior init). Empty when the project isn't configured yet.
+export function detectRegisteredVault(projectPath) {
+  try {
+    const s = JSON.parse(readFileSync(join(projectPath, '.claude', 'settings.json'), 'utf8'));
+    const v = s && s.env && s.env.OBSIDIAN_VAULT_PATH;
+    return typeof v === 'string' && v ? v : '';
+  } catch { return ''; }
+}
+
+// The locale locked in a vault's .brain/config.json (empty if absent/invalid).
+export function readVaultLocale(vaultPath) {
+  try {
+    const c = JSON.parse(readFileSync(join(vaultPath, '.brain', 'config.json'), 'utf8'));
+    return c && LOCALES[c.locale] ? c.locale : '';
+  } catch { return ''; }
+}
+
 export async function runInit(argv) {
   const args = parseArgs(argv);
   const projectPath = resolve(args.project || process.cwd());
   const log = (s) => process.stdout.write(`${s}\n`);
 
-  // Language first (i18n): an interactive TTY without --locale is asked the vault language;
-  // folders, prompts and scaffold all follow the answer.
+  // Recognize an already-configured project: the vault is registered in the project's
+  // settings.json (OBSIDIAN_VAULT_PATH) and its locale is locked in the vault's config.json.
+  // On re-run (e.g. after `npm i -D wendkeep@latest`) we reuse both and SKIP the language + vault
+  // prompts — asking again risks a divergent vault from a mistyped name. `--vault` / `--locale`
+  // override; the vault question is a once-per-project thing.
+  const registeredVault = args.vault ? '' : detectRegisteredVault(projectPath);
+  if (registeredVault && !args.locale) args.locale = readVaultLocale(registeredVault) || args.locale;
+
+  // Language first (i18n): an interactive TTY without --locale (and not already registered) is
+  // asked the vault language; folders, prompts and scaffold all follow the answer.
   if (!args.locale && process.stdin.isTTY && !args.yes) {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     const ans = await rl.question('Idioma do vault / Vault language:\n  [1] Português (pt-BR)   [2] English (en)\n> ');
     rl.close();
     args.locale = parseLocaleAnswer(ans);
   }
-  const P = promptStrings(args.locale && LOCALES[args.locale] ? args.locale : DEFAULT_LOCALE);
+  const resolvedLocale = args.locale && LOCALES[args.locale] ? args.locale : DEFAULT_LOCALE;
+  const P = promptStrings(resolvedLocale);
+  const M = initMessages(resolvedLocale);
 
-  let vaultPath = args.vault;
-  if (!vaultPath) {
+  let vaultPath = args.vault || registeredVault;
+  if (registeredVault) {
+    log(M.vaultRegistered(registeredVault, resolvedLocale));
+  } else if (!vaultPath) {
     const fallback = join(projectPath, deriveVaultDirName(projectPath));
     if (process.stdin.isTTY && !args.yes) {
       const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -285,12 +374,12 @@ export async function runInit(argv) {
     companions = resolveCompanions({});
   }
 
-  log('\nwendkeep init');
-  log(`  project    : ${projectPath}`);
-  log(`  vault      : ${vaultPath}`);
-  log(`  mcp        : ${args.mcp ? 'mcpvault (wendkeep-vault)' : 'skipped'}`);
-  log(`  companions : ${companions.length ? companions.join(', ') : 'none'}`);
-  log(`  colors     : ${args.noColors ? 'skipped' : 'wendkeep-colors (snippet + graph groups)'}\n`);
+  log(M.header);
+  log(`${M.lProject}: ${projectPath}`);
+  log(`${M.lVault}: ${vaultPath}`);
+  log(`${M.lMcp}: ${args.mcp ? 'mcpvault (wendkeep-vault)' : M.skipped}`);
+  log(`${M.lCompanions}: ${companions.length ? companions.join(', ') : M.none}`);
+  log(`${M.lColors}: ${args.noColors ? M.skipped : M.colorsOn}\n`);
 
   // dotcontext controls (only relevant when selected): hook level + MCP placement.
   // Skip the project MCP entry when dotcontext is already global (avoids a duplicate
@@ -329,7 +418,7 @@ export async function runInit(argv) {
   let readmeNote = '';
   if (!existsSync(readmePath)) {
     writeFileSync(readmePath, renderVaultReadme({ projectName: basename(projectPath), vaultPath, withMcp: args.mcp, locale: loc.id }), 'utf8');
-    readmeNote = ', README.md created';
+    readmeNote = M.readmeCreated;
   }
   // Seed the curated memory layer (CORE.md) + the compaction-protocol doc. The
   // DIGEST/index are auto-generated by the hooks; CORE is hand-curated, so we
@@ -369,14 +458,14 @@ export async function runInit(argv) {
   let viewsNote = '';
   try {
     const views = seedVaultViews(vaultPath);
-    if (views.length) viewsNote = `, ${views.length} view(s) + dashboard`;
+    if (views.length) viewsNote = M.viewsNote(views.length);
   } catch { /* views são bônus — nunca derrubam o init */ }
-  log(`  [1/4] vault taxonomy: ${folders.length} folders (${created} created, locale ${loc.id})${readmeNote}, .brain + change/spec + sensors seeded${viewsNote}`);
+  log(M.taxonomy(folders.length, created, loc.id, readmeNote, viewsNote));
   // Deliver the seeded defs (agents + wk process skills) to the project so they're
   // usable immediately — no separate `wendkeep sync-defs` step needed.
   const synced = syncDefs(vaultPath, projectPath);
   if (synced.skills.length || synced.agents.length) {
-    log(`        defs delivered: ${synced.skills.length} skill(s) -> .claude/skills, ${synced.agents.length} agent(s) -> .codex/agents`);
+    log(M.defs(synced.skills.length, synced.agents.length));
   }
 
   // 2. .claude/settings.json --------------------------------------------------
@@ -386,13 +475,13 @@ export async function runInit(argv) {
     // Unparseable existing file — never clobber. Drop a .new for manual merge.
     const fresh = mergeSettings(null, { vaultPath, withMcp: args.mcp, force: true, companions, skipMcp, dotcontextHookLevel }).settings;
     writeJson(`${settingsPath}.new`, fresh);
-    log(`  [2/4] settings.json exists but is not valid JSON -> wrote ${settingsPath}.new (merge by hand)`);
+    log(M.settingsBadJson(settingsPath));
   } else {
     const hadFile = settingsRead.data !== null;
     const { settings, added } = mergeSettings(settingsRead.data, { vaultPath, withMcp: args.mcp, force: args.force, companions, skipMcp, dotcontextHookLevel });
     if (hadFile) backup(settingsPath);
     writeJson(settingsPath, settings);
-    log(`  [2/4] settings.json ${hadFile ? 'merged' : 'created'} (${added} hook(s) wired, OBSIDIAN_VAULT_PATH set${hadFile ? ', .bak saved' : ''})`);
+    log(M.settings(hadFile ? M.merged : M.created, added, hadFile ? M.bakSaved : ''));
   }
 
   // 3. .mcp.json --------------------------------------------------------------
@@ -405,22 +494,22 @@ export async function runInit(argv) {
     const names = [args.mcp && MCP_SERVER_KEY, ...Object.keys(companionMcp)].filter(Boolean).join(', ');
     if (!mcpRead.ok) {
       writeJson(`${mcpPath}.new`, mergeMcp(null, mcpOpts));
-      log(`  [3/4] .mcp.json exists but is not valid JSON -> wrote ${mcpPath}.new (merge by hand)`);
+      log(M.mcpBadJson(mcpPath));
     } else {
       const hadFile = mcpRead.data !== null;
       if (hadFile) backup(mcpPath);
       writeJson(mcpPath, mergeMcp(mcpRead.data, mcpOpts));
-      log(`  [3/4] .mcp.json ${hadFile ? 'merged' : 'created'} (${names}${hadFile ? ', .bak saved' : ''})`);
+      log(M.mcp(hadFile ? M.merged : M.created, names, hadFile ? M.bakSaved : ''));
     }
   } else {
-    log('  [3/4] .mcp.json skipped (--no-mcp, no MCP companions)');
+    log(M.mcpSkipped);
   }
 
   // 4. Vault color system (.obsidian) -----------------------------------------
   if (args.noColors) {
-    log('  [4/4] colors skipped (--no-colors)');
+    log(M.colorsSkipped);
   } else {
-    log(`  [4/4] colors: ${installVaultColors(vaultPath)}`);
+    log(M.colors(installVaultColors(vaultPath)));
   }
 
   // caveman has no MCP / agnostic-hook path: on non-Claude agents its skills come
@@ -437,10 +526,10 @@ export async function runInit(argv) {
     log(`  [!] add to .gitignore (wendkeep não toca git): ${DOTCONTEXT_GITIGNORE.join(' ')}`);
   }
 
-  log('\nNext steps:');
-  log(`  1. Open the vault in Obsidian: "Open folder as vault" -> ${vaultPath}`);
-  log('  2. Make sure wendkeep is installed where the agent runs (npm i -D wendkeep, or -g).');
-  log('  3. Open Claude Code in this project and send a test prompt.');
-  log('  4. Confirm a note appears under 02-Sessões/<year>/<month>/DIA <dd>/ in the vault.');
-  log('  Update later with: npm update wendkeep  (no re-copying — hooks live in the package).\n');
+  log(M.nextSteps);
+  log(M.step1(vaultPath));
+  log(M.step2);
+  log(M.step3);
+  log(M.step4);
+  log(M.updateLater);
 }

package/src/stats.mjs

@@ -22,7 +22,8 @@ export function statsFrom(agg) {
 }
 
 export function statsLine(s) {
-  const span = s.firstDay && s.lastDay ? ` · ${s.spanDays} dia(s) (${s.firstDay}→${s.lastDay})` : '';
+  // "dias ativos" = distinct days WITH activity, not the calendar span (shown in parens).
+  const span = s.firstDay && s.lastDay ? ` · ${s.spanDays} dias ativos (${s.firstDay}→${s.lastDay})` : '';
   return `wendkeep: ${num(s.sessions)} sessão(ões) · ${num(s.prompts)} prompts · ${usd(s.cost)} capturado${span} · ${s.models} modelo(s)`;
 }