wendkeep 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.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.
+
+### Added
+- **`wendkeep cost --trend [day|week|month]`** — cost bucketed over time plus a run-rate
+  **projection** (recent-window daily average × horizon). `wendkeep cost --write` generates a
+  `00-Custo.md` trend note in the vault (by-month table + projection + top models). `src/cost.mjs`.
+- **`wendkeep stats`** — one shareable line: sessions · prompts · spend · date span · models
+  (`--json` too). For the npm page, a README badge line, or a post. `src/stats.mjs`.
+- **Launch assets** (`docs/`): README hero (tagline, badges, quickstart, screenshot slot),
+  Show HN / r/ObsidianMD / X post drafts (`docs/20-launch-posts.md`), and a repeatable
+  graph-screenshot guide (`docs/21-graph-screenshot.md`).
+
 ## [0.24.0] — 2026-07-08
 
 ### Changed

package/README.md

@@ -1,25 +1,47 @@
 # 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)
 ![test](https://github.com/rogersialves/wendkeep/actions/workflows/test.yml/badge.svg)
+![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
+npm i -D wendkeep && npx wendkeep init      # captures from the next session on
+npx wendkeep import                          # backfill past Claude + Codex sessions
+```
+
+**▶ 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 problem: the context dies when the window closes
 
-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.
+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.
 
-## What you get
-
-- **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
 
@@ -102,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)
@@ -131,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
@@ -181,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/bin/wendkeep.mjs

@@ -48,7 +48,9 @@ Usage:
   wendkeep spec <sub>          Living specs: list | show <capability>.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
   wendkeep cost [opts]         Aggregate AI-coding spend across the vault's sessions.
-                           --since <date> · --top [N] (priciest sessions) · --json.
+                           --since <date> · --top [N] (priciest) · --trend [day|week|month]
+                           (+ run-rate projection) · --write (generate 00-Custo.md) · --json.
+  wendkeep stats [--vault P]   One shareable line: sessions · prompts · spend · span · models (--json).
   wendkeep import [opts]       Backfill: import this project's past Claude + Codex sessions into
                            the vault (deduped by session_id). --source all|claude|codex (default
                            all) · --stamp-ids (backfill session_id in existing notes) ·
@@ -144,6 +146,11 @@ async function main() {
       runCost(rest);
       break;
     }
+    case 'stats': {
+      const { runStats } = await import('../src/stats.mjs');
+      runStats(rest);
+      break;
+    }
     case 'import': {
       const { runImportCli } = await import('../src/import.mjs');
       runImportCli(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.24.0",
+  "version": "0.26.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/cost.mjs

@@ -1,12 +1,16 @@
 // `wendkeep cost` — aggregate AI-coding spend across every session note in the vault.
 // Each session note carries cost in its frontmatter (main + subagents since 0.10.0); this
 // rolls the whole vault up: total, by day, by model. Pure aggregation + a thin CLI.
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { getLocale } from '../hooks/locale.mjs';
 
 const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
 const usd = (n) => `$${(Number(n) || 0).toFixed(4)}`;
+const today = () => {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+};
 
 function fmValue(content, key) {
   const m = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
@@ -24,6 +28,7 @@ export function parseSessionCost(content) {
     wasted: Number(fmValue(content, 'subagents_wasted_usd')) || 0,
     tokens: Number(fmValue(content, 'tokens_total')) || 0,
     subTokens: Number(fmValue(content, 'subagents_tokens_total')) || 0,
+    prompts: Number(fmValue(content, 'prompts')) || 0,
   };
 }
 
@@ -35,8 +40,9 @@ export function aggregateCosts(entries) {
   let wasted = 0;
   let tokens = 0;
   let subTokens = 0;
+  let prompts = 0;
   for (const e of entries) {
-    main += e.mainCost; sub += e.subCost; wasted += e.wasted || 0; tokens += e.tokens; subTokens += e.subTokens;
+    main += e.mainCost; sub += e.subCost; wasted += e.wasted || 0; tokens += e.tokens; subTokens += e.subTokens; prompts += e.prompts || 0;
     const d = e.date || '?';
     (byDay[d] = byDay[d] || { cost: 0, count: 0 }).cost += e.mainCost + e.subCost;
     byDay[d].count += 1;
@@ -48,12 +54,93 @@ export function aggregateCosts(entries) {
     count: entries.length,
     main: round4(main), sub: round4(sub), total: round4(total), wasted: round4(wasted),
     avg: round4(entries.length ? total / entries.length : 0),
-    tokens, subTokens,
+    tokens, subTokens, prompts,
     byDay: Object.entries(byDay).sort().map(([date, v]) => ({ date, cost: round4(v.cost), count: v.count })),
     byModel: Object.entries(byModel).sort((a, b) => b[1].cost - a[1].cost).map(([model, v]) => ({ model, cost: round4(v.cost), count: v.count })),
   };
 }
 
+// Shift a 'YYYY-MM-DD' string by `delta` days (UTC, pure).
+function shiftDate(dateStr, delta) {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + delta);
+  return d.toISOString().slice(0, 10);
+}
+
+// ISO-ish week key 'YYYY-Www' for a 'YYYY-MM-DD' string (pure).
+function isoWeek(dateStr) {
+  const d = new Date(`${dateStr}T00:00:00Z`);
+  const day = (d.getUTCDay() + 6) % 7; // Mon=0
+  d.setUTCDate(d.getUTCDate() - day + 3); // nearest Thursday
+  const firstThu = new Date(Date.UTC(d.getUTCFullYear(), 0, 4));
+  const week = 1 + Math.round(((d - firstThu) / 86400000 - 3 + ((firstThu.getUTCDay() + 6) % 7)) / 7);
+  return `${d.getUTCFullYear()}-W${String(week).padStart(2, '0')}`;
+}
+
+// Group the per-day cost series (agg.byDay) into day|week|month buckets. Pure.
+export function trendBuckets(byDay, bucket = 'month') {
+  const keyOf = (date) => (bucket === 'day' ? date : bucket === 'week' ? isoWeek(date) : String(date).slice(0, 7));
+  const map = {};
+  for (const d of byDay || []) {
+    if (!d.date || d.date === '?') continue;
+    const k = keyOf(d.date);
+    (map[k] = map[k] || { period: k, cost: 0, count: 0 }).cost += d.cost;
+    map[k].count += d.count;
+  }
+  return Object.values(map).sort((a, b) => a.period.localeCompare(b.period)).map((b) => ({ ...b, cost: round4(b.cost) }));
+}
+
+// Run-rate projection from the last `windowDays` of activity. Pure; nowStr = 'YYYY-MM-DD'
+// (defaults to the latest day seen). Honest: a flat run-rate, not a fitted forecast.
+export function projectSpend(byDay, { nowStr, windowDays = 30, horizonDays = 30 } = {}) {
+  const days = (byDay || []).filter((d) => d.date && d.date !== '?');
+  if (!days.length) return { dailyRate: 0, projected: 0, windowDays, horizonDays, basisDays: 0, basisTotal: 0 };
+  const now = nowStr || days[days.length - 1].date;
+  const cutoff = shiftDate(now, -windowDays);
+  const recent = days.filter((d) => d.date > cutoff);
+  const basisTotal = recent.reduce((s, d) => s + d.cost, 0);
+  const dailyRate = basisTotal / windowDays;
+  return { dailyRate: round4(dailyRate), projected: round4(dailyRate * horizonDays), windowDays, horizonDays, basisDays: recent.length, basisTotal: round4(basisTotal) };
+}
+
+// A generated vault note: cost by month + projection + top models. Overwrites (it is generated).
+export function renderTrendNote(agg, proj, dateStr) {
+  const rows = trendBuckets(agg.byDay, 'month').map((b) => `| ${b.period} | ${usd(b.cost)} | ${b.count} |`).join('\n');
+  const models = agg.byModel.slice(0, 8).map((m) => `| ${m.model} | ${usd(m.cost)} | ${m.count} |`).join('\n');
+  return `---
+type: cost-trend
+date: ${dateStr}
+cssclasses:
+  - topic-dashboard
+tags:
+  - custo
+---
+
+# Custo — tendência
+
+> Gerado por \`wendkeep cost --write\`. ${agg.count} sessão(ões) · total ${usd(agg.total)} · ${usd(agg.avg)}/sessão.
+
+## Por mês
+
+| Mês | Custo | Sessões |
+|---|---|---|
+${rows || '| — | — | — |'}
+
+## Projeção (run-rate ${proj.windowDays}d)
+
+Base: ${usd(proj.basisTotal)} nos últimos ${proj.windowDays} dias (${proj.basisDays} dia(s) com atividade) → **${usd(proj.dailyRate)}/dia**.
+Projeção próximos ${proj.horizonDays} dias: **${usd(proj.projected)}**.
+
+> Run-rate simples (média diária × horizonte), não previsão ajustada.
+
+## Por modelo
+
+| Modelo | Custo | Sessões |
+|---|---|---|
+${models || '| — | — | — |'}
+`;
+}
+
 function walkNotes(dir) {
   const out = [];
   let names;
@@ -111,6 +198,24 @@ export function runCost(argv) {
     process.exit(0);
   }
 
+  const trendIdx = argv.indexOf('--trend');
+  if (trendIdx >= 0) {
+    const bucket = ['day', 'week', 'month'].includes(argv[trendIdx + 1]) ? argv[trendIdx + 1] : 'month';
+    const proj = projectSpend(agg.byDay);
+    process.stdout.write(`Tendência de custo (por ${bucket}):\n`);
+    for (const b of trendBuckets(agg.byDay, bucket)) process.stdout.write(`  ${b.period}  ${usd(b.cost).padStart(11)}  (${b.count})\n`);
+    process.stdout.write(`\nRun-rate ${proj.windowDays}d: ${usd(proj.dailyRate)}/dia · projeção ${proj.horizonDays}d: ${usd(proj.projected)} (base ${usd(proj.basisTotal)} em ${proj.basisDays} dia(s))\n`);
+    process.exit(0);
+  }
+
+  if (argv.includes('--write')) {
+    const proj = projectSpend(agg.byDay);
+    const rel = '00-Custo.md';
+    writeFileSync(join(vaultBase, rel), renderTrendNote(agg, proj, today()), 'utf8');
+    process.stdout.write(`cost --write: ${rel} (nota de tendência gerada)\n`);
+    process.exit(0);
+  }
+
   process.stdout.write(`Custo total (vault): ${usd(agg.total)} — ${agg.count} sessão(ões) · ${usd(agg.avg)}/sessão\n`);
   process.stdout.write(`  main: ${usd(agg.main)} · subagents: ${usd(agg.sub)}\n`);
   if (agg.wasted) process.stdout.write(`  desperdiçado (runs killed/failed): ${usd(agg.wasted)}\n`);

package/src/init.mjs

@@ -223,6 +223,63 @@ 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',
+  },
+  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',
+  },
+};
+
+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();
@@ -243,7 +300,9 @@ export async function runInit(argv) {
     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) {
@@ -285,12 +344,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 +388,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 +428,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 +445,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 +464,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 +496,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

@@ -0,0 +1,46 @@
+// `wendkeep stats` — one shareable line about what the vault has captured. For the npm page,
+// a README badge line, or a tweet. Read-only; reuses the cost aggregation.
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { collectVaultCost } from './cost.mjs';
+
+const usd = (n) => `$${(Number(n) || 0).toFixed(2)}`;
+const num = (n) => String(Math.round(Number(n) || 0)).replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+
+// Pure: derive the shareable stats from a collectVaultCost aggregate.
+export function statsFrom(agg) {
+  const days = (agg.byDay || []).map((d) => d.date).filter((d) => d && d !== '?').sort();
+  return {
+    sessions: agg.count,
+    prompts: agg.prompts || 0,
+    cost: agg.total,
+    models: (agg.byModel || []).length,
+    firstDay: days[0] || '',
+    lastDay: days[days.length - 1] || '',
+    spanDays: days.length,
+  };
+}
+
+export function statsLine(s) {
+  // "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)`;
+}
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+export function runStats(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep stats: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep stats: vault not found: ${vaultBase}\n`); process.exit(2); }
+  const s = statsFrom(collectVaultCost(vaultBase));
+  if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(s, null, 2)}\n`); process.exit(0); }
+  process.stdout.write(`${statsLine(s)}\n`);
+  process.exit(0);
+}