wendkeep 0.71.1 → 0.72.1

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.72.1] — 2026-08-20
+
+### Added
+
+- **Proveniência verificável de release.** A publicação gera um receipt com commit, versão, tag,
+  integridade npm, execução do workflow e GitHub Release, e recusa divergências entre o SHA testado,
+  a tag e o tarball publicado.
+- **Contrato seguro do Observer.** O Keep Core permanece em Node.js 18+, enquanto comandos SQL
+  diagnosticam `WENDKEEP_OBSERVER_NODE_UNSUPPORTED` abaixo do Node.js 22.13. Mutações exigem Bearer,
+  non-loopback exige token e requisições validam Host e Origin.
+- **Níveis de captura.** `metadata` é o padrão sem mensagens; `messages` e `full-transcript` são
+  opt-in. Caminhos absolutos não são publicados e init recomenda ignorar state e outbox SQL.
+
+### Changed
+
+- **Release somente após CI verde.** O workflow publica o SHA aprovado pela matriz Core (Node 18/20)
+  e Observer (Node 22.13/24), cria a tag no mesmo commit e pode reconciliar execuções repetidas.
+- **Dogfooding pelo working tree.** O repositório não depende mais de `wendkeep` em devDependencies;
+  seus hooks chamam `node ./bin/wendkeep.mjs`, enquanto projetos consumidores usam
+  `npx --no-install wendkeep` e o tarball continua testado isoladamente.
+
+### Fixed
+
+- **Identidade de arquivos de memória no Windows.** A revalidação compara o índice do arquivo como
+  inteiro exato e tolera a inconsistência conhecida do serial de volume do libuv antigo, evitando
+  falsos `VAULT_PATH_UNSAFE` no Node.js 22.13 sem relaxar a rejeição de hardlinks ou reparses.
+- **Ingestão SQL grande em runners lentos.** O timeout HTTP cresce com o tamanho bruto do lote até
+  120 segundos, preservando 15 segundos para payloads vazios/pequenos e evitando outbox falsa para
+  lotes gzip válidos acima de 64 MB.
+- **Trusted Publisher preservado após o gate de CI.** `auto-tag.yml`, o workflow já autorizado no
+  npm, passa a executar a matriz da `main` e mantém o publish em um job com `needs: test`;
+  `test.yml` fica exclusivo para pull requests.
+
+## [0.72.0] — 2026-08-17
+
+### Added
+
+- **Observer SQL authority.** O volume Docker agora usa `/data/observer.sqlite` como
+  autoridade única para documentos, sessões, agentes, uso, chamadas LLM e transcripts
+  comprimidos; as migrações SQL são versionadas e idempotentes.
+- **Ingestão resiliente.** Hooks de sessão e subagentes enviam eventos idempotentes ao
+  Observer, preservam custos registrados e usam outbox local quando o container está
+  indisponível.
+- **Dashboard de Consumo.** Cada projeto ganhou resumo de tokens/custos, filtros,
+  hierarquia agente/subagente/modelo, tendência diária, chamadas e leitura de transcript.
+- **Migração sem perda.** Conteúdo legado do volume, `MEMORY_EVENTS.jsonl`, frontmatter de
+  custo e históricos sem transcript são importados sem apagar as fontes existentes;
+  históricos incompletos são marcados como `summary_only`; divergências entre frontmatter e
+  ledger ficam em linhas explícitas de reconciliação e `session_id` duplicado é desambiguado
+  por arquivo.
+
+### Changed
+
+- Markdown deixou de ser autoridade operacional no container. Ele permanece armazenado como
+  conteúdo documental no SQLite e só é materializado por exportação explícita.
+- O transporte divide lotes por quantidade e tamanho, reconhece retries do hash legado e
+  preserva transcripts grandes dentro do limite HTTP do Observer.
+- Lotes SQL agora usam gzip no transporte e são expandidos com limite controlado no Observer,
+  permitindo importar transcripts históricos que excedem 64 MB em JSON puro sem aumentar
+  indiscriminadamente o limite de requisição.
+
 ## [0.71.1] — 2026-08-17
 
 ### Added
@@ -1001,7 +1062,7 @@ All notable changes to **wendkeep** are documented here. Format based on
   enum de eventos de hook do Codex.
 - A projeção Codex tem três diferenças em relação ao formato do `settings.json`, todas
   **silenciosas quando erradas** — daí valerem registro. (1) A chave de timeout é `timeoutSec`,
-  não `timeout`. (2) O comando é sempre `npx wendkeep hook <nome>`, nunca a forma node-direta:
+  não `timeout`. (2) O comando é sempre `npx --no-install wendkeep hook <nome>`, nunca a forma node-direta:
   aquela emite `${CLAUDE_PROJECT_DIR}`, que não existe no Codex, então a flag `preferLocal` é
   ignorada de propósito na projeção. (3) As chaves de evento são PascalCase — o snake_case que
   se vê em `[hooks.state]` no `~/.codex/config.toml` é o rótulo interno do evento, não a chave
@@ -1585,7 +1646,7 @@ they only read + append.
 
 ### 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.
+  (`settings.json` calls `npx --no-install 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
@@ -1765,7 +1826,7 @@ Fix: memory + active-change injection wired by default.
 
 ### Upgrade
 - Existing installs pick it up by re-running `wendkeep init --force` (idempotent — it only adds the
-  missing hook), or by adding `npx wendkeep hook brain-inject` to the SessionStart hooks manually.
+  missing hook), or by adding `npx --no-install wendkeep hook brain-inject` to the SessionStart hooks manually.
 
 ## [0.18.0] — 2026-07-06
 

package/README.en.md

@@ -88,7 +88,11 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 | **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; research previews without a final rate remain unestimated. |
 | **Multi‑agent** — one vault, both agents | `init` wires the session hooks into `.claude/settings.json` *and* `.codex/hooks.json`, and every note is tagged with the agent that wrote it: Claude Code is detected from its environment, anything else is recorded as Codex. One shared graph, whichever agent you are in. |
 | **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. |
-| **Local Observer** — many projects, one view | `wendkeep observer` keeps snapshots plus a complete copy of sessions, decisions, bugs, learnings, specs, and changes in the Docker volume; the read-only dashboard opens directly at `http://127.0.0.1:8787/`, local mode has no token, and unavailable hooks use an outbox without blocking the session. |
+| **Local Observer** — many projects, one view | `wendkeep observer` keeps documents, sessions, agents, tokens, costs, calls, and transcripts in the Docker volume SQLite database; every project gets a **Consumption** tab in the read-only dashboard at `http://127.0.0.1:8787/`, loopback has no token, and unavailable hooks use a gzip outbox without blocking the session, including large transcripts. |
+
+During historical migration, the Observer preserves differences between frontmatter totals and the
+ledger as explicit reconciliation rows, and disambiguates duplicate `session_id` values per file
+without inventing calls.
 
 ## Requirements
 
@@ -111,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — ten compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. `observer-publish` only publishes a sanitized, fail-open projection; it does not replace the local lifecycle. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — eleven compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. `observer-publish` keeps the sanitized index projection and also sends the local SQL authority with documents, consumption, and transcripts; it does not replace the local lifecycle. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.

package/README.md

@@ -88,7 +88,11 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 | **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; research previews without a final rate remain unestimated. |
 | **Multi‑agent** — one vault, both agents | `init` wires the session hooks into `.claude/settings.json` *and* `.codex/hooks.json`, and every note is tagged with the agent that wrote it: Claude Code is detected from its environment, anything else is recorded as Codex. One shared graph, whichever agent you are in. |
 | **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. |
-| **Local Observer** — many projects, one view | `wendkeep observer` keeps snapshots plus a complete copy of sessions, decisions, bugs, learnings, specs, and changes in the Docker volume; the read-only dashboard opens directly at `http://127.0.0.1:8787/`, local mode has no token, and unavailable hooks use an outbox without blocking the session. |
+| **Local Observer** — many projects, one view | `wendkeep observer` keeps documents, sessions, agents, tokens, costs, calls, and transcripts in the Docker volume SQLite database; every project gets a **Consumption** tab in the read-only dashboard at `http://127.0.0.1:8787/`, loopback has no token, and unavailable hooks use a gzip outbox without blocking the session, including large transcripts. |
+
+During historical migration, the Observer preserves differences between frontmatter totals and the
+ledger as explicit reconciliation rows, and disambiguates duplicate `session_id` values per file
+without inventing calls.
 
 ## Requirements
 
@@ -111,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — ten compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. `observer-publish` only publishes a sanitized, fail-open projection; it does not replace the local lifecycle. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — eleven compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. `observer-publish` keeps the sanitized index projection and also sends the local SQL authority with documents, consumption, and transcripts; it does not replace the local lifecycle. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.

package/docs/en/commands/observer.md

@@ -4,25 +4,29 @@
 
 ## Purpose
 
-The Observer consolidates observability for multiple WendKeep projects in a local service and
-stores a complete copy of the memory published by hooks in the Docker volume. The content can be
-browsed and searched in the container without depending on Obsidian for queries.
+The Observer consolidates observability for multiple WendKeep projects in a local service. The
+Docker volume keeps `/data/observer.sqlite` as the single authority for documents, sessions,
+agents, usage, and calls. Complete transcripts are optional and require explicit capture. The content can be browsed and searched in the
+container without depending on Obsidian for queries.
 
 ## When to use
 
-Use it to query changes, sessions, decisions, bugs, learnings, specs, brain documents, and health
-across projects through one local memory. During the transition, the vault is preserved as a
-recovery copy; the Observer is authoritative for queries made through its container.
+Use it to query changes, sessions, decisions, bugs, learnings, specs, brain documents, per-agent
+and per-model consumption, and health across projects through one local memory. During the
+transition, the vault and legacy Markdown files remain a recovery copy; the Observer is
+authoritative for queries made through its container.
 
 ## When not to use
 
-Do not use the Observer to edit, complete, or archive changes, curate memory, store transcripts,
-or expose the service to the network. Edits still go through local WendKeep hooks.
+Do not use the Observer to edit, complete, or archive changes, curate memory, automatically export
+the authority back to Markdown, or expose the service to the network. Edits still go through local
+WendKeep hooks.
 
 ## Prerequisites
 
-Initialize projects with WendKeep and explicitly register each project before starting the HTTP
-server. The default local mode has no token to configure.
+Use Node.js 22.13 or newer for the SQL Observer. Keep Core and the remaining commands continue to
+support Node.js 18 or newer. Explicitly register each project and set `WENDKEEP_OBSERVER_TOKEN`;
+loopback reads remain open, while every mutation requires a Bearer token.
 
 ## Syntax
 
@@ -30,8 +34,8 @@ server. The default local mode has no token to configure.
 npx wendkeep observer status --data-dir <directory> --json
 npx wendkeep observer register --project <project> --vault <vault> --data-dir <directory>
 npx wendkeep observer publish --project <project> --vault <vault> --data-dir <directory>
-npx wendkeep observer memory import --project <project> --vault <vault> --url http://127.0.0.1:8787 --json
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory>
+npx wendkeep observer memory import --project <project> --vault <vault> --url http://127.0.0.1:8787 --token <token> --json
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory> --token <token>
 ```
 
 ## Options and exit codes
@@ -41,8 +45,9 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory>
 - `--project` and `--vault` identify a project for `register`, `publish`, and `memory import`.
 - `--host` accepts only `127.0.0.1`, `localhost`, or `::1`; other hosts are rejected before
   listening.
-- `/v1` is open in the default local mode; keep `--host 127.0.0.1` and do not publish the port on
-  a network address.
+- `--token` or `WENDKEEP_OBSERVER_TOKEN` authenticates mutations; `--allow-non-loopback` fails without one.
+- `WENDKEEP_OBSERVER_CAPTURE_LEVEL` accepts `metadata` (default, no messages), `messages`, or
+  `full-transcript`. Absolute local paths are never published.
 - Exit `0` means success; exit `1` means configuration or operation failure; the publisher hook
   also returns `0` when the Observer is unavailable.
 
@@ -50,7 +55,8 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory>
 
 ```powershell
 npx wendkeep observer register --project C:\GitHub\WendKeep --vault C:\GitHub\WendKeep\.WendKeep-vault --data-dir C:\WendKeepObserver
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver
+$env:WENDKEEP_OBSERVER_TOKEN = '<strong-local-token>'
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN
 $env:WENDKEEP_OBSERVER_URL = 'http://127.0.0.1:8787'
 ```
 
@@ -63,14 +69,15 @@ docker compose -f docker/wendkeep-observer/compose.yaml up -d --build
 ## Local web dashboard
 
 With the server running, open [http://127.0.0.1:8787/](http://127.0.0.1:8787/) in a browser. The
-dashboard is served by the same process and opens directly, without a form or token. Keep the port
+dashboard is served by the same process and opens directly for reads, without a form or token. Keep the port
 bound to the computer loopback; do not expose this address on a network interface.
 
 The dashboard shows the multi-project list, version, health, latest session, active change, change
-count, and last capture time. Opening a project exposes Overview, Sessions, Memory, Changes, and
-Sync screens. Each list opens the complete Markdown document in a read-only reader, with local
-filtering, body search, and a source toggle. Loading, empty, unavailable-server, conflict, and
-stale-data states are visible, with manual refresh and an automatic 15-second refresh.
+count, and last capture time. Opening a project exposes Overview, Consumption, Sessions, Memory,
+Changes, and Sync screens. Consumption shows total cost, token categories, primary agents,
+subagents, providers, models, daily trend, historical coverage, and calls with prompt, response,
+and transcript content according to the selected capture level. Loading, empty, unavailable-server, conflict, no-pricing, and stale-data
+states are visible, with manual refresh and an automatic 15-second refresh.
 
 If the browser shows the shell but the list fails, check the service health at
 `http://127.0.0.1:8787/healthz` and confirm that the container is running.
@@ -78,25 +85,34 @@ If the browser shows the shell but the list fails, check the service health at
 ## Expected result
 
 `register` stores `project_id`, name, version, and registration time. `publish` reads the local
-vault, produces the snapshot, and also sends idempotent events containing the complete content of
-sessions, decisions, bugs, learnings, specs, changes, CORE, DIGEST, SHARED_MEMORY, and brain
-state. The container stores Markdown under `/data/memory` plus `MEMORY_EVENTS.jsonl` and
-`MEMORY_INDEX.json` in the `observer-data` volume; it does not mount `C:\GitHub` or any
-`.WendKeep-vault`. `memory import` performs the initial load and returns file/hash parity.
-
-`init` projects `observer-publish` into `SessionStart` and `Stop` after the primary hooks. Without
-`WENDKEEP_OBSERVER_URL`, the hook is a no-op. When the server is stopped, it writes snapshots to
-`.brain/observer-outbox/` and complete memory to `.brain/observer-memory-outbox/` without blocking
-the session; a later run retries both event types.
+vault, produces the snapshot, and sends idempotent events to SQLite containing the complete content
+of sessions, decisions, bugs, learnings, specs, changes, CORE, DIGEST, SHARED_MEMORY, brain state,
+agent sessions, cost rollups, and calls. Messages and transcripts are only sent by capture levels
+that explicitly enable them. The container stores everything in
+`/data/observer.sqlite`; it does not mount `C:\GitHub` or any `.WendKeep-vault`. Markdown is only
+the text held in SQL and is recreated as files only by an explicit read-only export.
+`memory import` performs the initial load and returns file/hash parity. During migration, the
+cost/token total recorded in frontmatter is preserved through an explicit reconciliation row when
+the detailed ledger does not add up; that row does not invent calls. Historical sessions sharing
+one `session_id` receive a canonical per-file identity so one rollup cannot overwrite the other.
+
+`init` projects `observer-publish` into `SessionStart`, `Stop`, and `SubagentStop` after the primary
+hooks. When the server is unavailable, it writes snapshots to `.brain/observer-outbox/` and SQL
+events to `.brain/observer-sql-outbox/` without blocking the session; a later run retries the
+batches. SQL batches use gzip so complete transcripts larger than 64 MB as plain JSON remain within
+the transport limit; the Observer decompresses and validates the body before ingesting it. The
+outbox is temporary transport, not authority.
 
 ## Common errors and diagnosis
 
 - `project_not_registered`: run `observer register` before publishing.
 - `host loopback`: replace `0.0.0.0` or a LAN address with `127.0.0.1`.
-- Pending outbox: the service was unavailable; preserve `.brain/observer-outbox/` and rerun the
-  publisher. Do not delete events manually.
-- If memory is incomplete, check the Sync screen, preserve the outbox, and run
-  `observer memory import` to rebuild the copy from the vault.
+- Pending outbox: the service was unavailable; preserve `.brain/observer-outbox/` and
+  `.brain/observer-sql-outbox/`, then rerun the publisher. Also ignore
+  `.brain/observer-sql-state.json` and `.brain/observer-sql-outbox/` in a versioned vault. Do not delete events manually.
+- `WENDKEEP_OBSERVER_NODE_UNSUPPORTED`: run the Observer on Node.js 22.13 or newer.
+- If memory or usage is incomplete, check the Sync screen, preserve the outbox, and run
+  `observer memory import` to rebuild the load from the vault.
 
 ## Next steps
 
@@ -106,25 +122,34 @@ projection.
 
 ## Data authority
 
-The container is canonical for Observer queries and stores the complete published content. The
-vault remains preserved locally during migration as a transition and recovery copy; Observer
-screens do not complete, archive, repair, or promote state.
+The container SQLite database is canonical for Observer queries and stores the complete published
+content. The vault and any legacy `/data/memory` remain preserved during migration as a transition
+and recovery copy; hooks do not update container Markdown after cutover. Observer screens do not
+complete, archive, repair, or promote state.
 
 ## Minimal API
 
-- `GET /healthz` — availability without project data.
-- `GET /v1/projects` — projects with an accepted snapshot.
+- `GET /healthz` — availability, SQLite migration version, and legacy migration state.
+- `GET /v1/projects` — projects registered in SQLite, with a snapshot when available.
 - `GET /v1/projects/:project_id` — the latest project snapshot.
 - `GET /v1/projects/:project_id/changes` — change summary from the snapshot.
 - `PUT /v1/projects/:project_id` — explicit local registration.
 - `POST /v1/projects/:project_id/snapshot` — idempotent local ingestion.
+- `POST /v1/projects/:project_id/ingest` — idempotent batches of documents, sessions, agents,
+  rollups, calls, and transcripts.
 - `GET /v1/projects/:project_id/memory/tree` — document tree and metadata.
 - `GET /v1/projects/:project_id/memory/document?path=...` — complete Markdown content.
 - `GET /v1/projects/:project_id/memory/search?q=...` — path and body search.
 - `GET /v1/projects/:project_id/sync` — mode, counts, conflicts, and latest event.
-- `PUT /v1/projects/:project_id/sync` — explicitly changes the local mode.
+- `PUT /v1/projects/:project_id/sync` — compatibility configuration; SQL remains authoritative.
 - `GET /v1/projects/:project_id/memory/export` — read-only export with complete content.
 - `POST /v1/projects/:project_id/memory/events` — idempotent batch ingestion.
-
-The `/v1` routes reject oversized bodies and validate project, path, revision, hash, and
-isolation before writing content to the volume.
+- `GET /v1/projects/:project_id/usage/summary` — filterable totals by period, change, session,
+  agent, provider, model, and role.
+- `GET /v1/projects/:project_id/usage/breakdown` — agent, subagent, and model hierarchy.
+- `GET /v1/projects/:project_id/usage/calls` — individual calls with prompt and response.
+- `GET /v1/projects/:project_id/transcripts/:transcript_id` — compressed transcript validated by hash.
+
+The `/v1` routes reject transported or expanded bodies above their limits and validate project,
+path, revision, hash, idempotency, and isolation before writing to SQLite. Use `memory/export` for
+a Markdown copy; it does not alter SQL authority.

package/docs/en/commands/sessions-and-import.md

@@ -26,11 +26,11 @@ and a vault bound to the correct project.
 ## Syntax
 
 ```bash
-npx wendkeep hook <name>
+npx --no-install wendkeep hook <name>
 npx wendkeep session list
 npx wendkeep session show <id>
 npx wendkeep session use <id>
-npx wendkeep hook session-backfill --session <id> [--write]
+npx --no-install wendkeep hook session-backfill --session <id> [--write]
 npx wendkeep import [options]
 ```
 
@@ -96,8 +96,8 @@ npx wendkeep import [options]
 ```bash
 npx wendkeep session list
 npx wendkeep session show 019abc-session-id
-npx wendkeep hook session-backfill --session 019abc-session-id
-npx wendkeep hook session-backfill --session 019abc-session-id --write
+npx --no-install wendkeep hook session-backfill --session 019abc-session-id
+npx --no-install wendkeep hook session-backfill --session 019abc-session-id --write
 npx wendkeep import --source codex --since 2026-07-01 --dry-run --json
 ```
 

package/docs/pt-BR/commands/observer.md

@@ -4,26 +4,29 @@
 
 ## Objetivo
 
-O Observer consolida a observabilidade de vários projetos WendKeep em um serviço local e grava no
-volume Docker uma cópia integral da memória publicada pelos hooks. O conteúdo fica disponível
-para navegação e busca no próprio container, sem depender do Obsidian para consulta.
+O Observer consolida a observabilidade de vários projetos WendKeep em um serviço local. O volume
+Docker mantém o SQLite `/data/observer.sqlite` como autoridade única para documentos, sessões,
+agentes, uso e chamadas. Transcripts completos são opcionais e exigem captura explícita. O conteúdo fica disponível para navegação e busca
+no próprio container, sem depender do Obsidian para consulta.
 
 ## Quando usar
 
-Use para consultar changes, sessões, decisões, bugs, aprendizados, specs, documentos do brain e
-saúde de vários projetos em uma única memória local. Durante a transição, o vault continua sendo
-preservado como cópia de origem para recuperação; o Observer é a autoridade de consulta do seu
-container.
+Use para consultar changes, sessões, decisões, bugs, aprendizados, specs, documentos do brain,
+consumo por agente/modelo e saúde de vários projetos em uma única memória local. Durante a
+transição, o vault e os arquivos Markdown legados continuam preservados como cópia de origem para
+recuperação; o Observer é a autoridade de consulta do seu container.
 
 ## Quando não usar
 
-Não use o Observer para editar, concluir ou arquivar changes, curar memória, armazenar transcripts
-ou expor o serviço na rede. As edições continuam passando pelos hooks e pelo WendKeep local.
+Não use o Observer para editar, concluir ou arquivar changes, curar memória, exportar a autoridade
+de volta para Markdown automaticamente ou expor o serviço na rede. As edições continuam passando
+pelos hooks e pelo WendKeep local.
 
 ## Pré-requisitos
 
-Tenha os projetos inicializados com WendKeep e registre explicitamente cada projeto antes de
-iniciar o servidor HTTP. No modo local padrão não há token para configurar.
+Tenha Node.js 22.13 ou mais recente para executar o Observer SQL. O Keep Core e os demais comandos
+continuam compatíveis com Node.js 18 ou mais recente. Registre explicitamente cada projeto e defina
+`WENDKEEP_OBSERVER_TOKEN`; leituras no loopback permanecem abertas, mas toda mutação exige Bearer.
 
 ## Sintaxe
 
@@ -31,8 +34,8 @@ iniciar o servidor HTTP. No modo local padrão não há token para configurar.
 npx wendkeep observer status --data-dir <diretório> --json
 npx wendkeep observer register --project <projeto> --vault <vault> --data-dir <diretório>
 npx wendkeep observer publish --project <projeto> --vault <vault> --data-dir <diretório>
-npx wendkeep observer memory import --project <projeto> --vault <vault> --url http://127.0.0.1:8787 --json
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório>
+npx wendkeep observer memory import --project <projeto> --vault <vault> --url http://127.0.0.1:8787 --token <token> --json
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório> --token <token>
 ```
 
 ## Opções e códigos de saída
@@ -42,8 +45,9 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório>
 - `--project` e `--vault` identificam o projeto nos comandos `register`, `publish` e `memory import`.
 - `--host` aceita somente `127.0.0.1`, `localhost` ou `::1`; outros hosts são recusados antes do
   listen.
-- as rotas `/v1` ficam abertas no modo local padrão; mantenha `--host 127.0.0.1` e não publique a
-  porta em um endereço de rede.
+- `--token` ou `WENDKEEP_OBSERVER_TOKEN` autentica mutações; `--allow-non-loopback` falha sem token.
+- `WENDKEEP_OBSERVER_CAPTURE_LEVEL` aceita `metadata` (padrão, sem mensagens), `messages` ou
+  `full-transcript`. Caminhos locais absolutos nunca são publicados.
 - Exit `0` indica sucesso; exit `1` indica falha de configuração ou operação; o hook publisher
   também retorna `0` quando o Observer está indisponível.
 
@@ -51,7 +55,8 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <diretório>
 
 ```powershell
 npx wendkeep observer register --project C:\GitHub\WendKeep --vault C:\GitHub\WendKeep\.WendKeep-vault --data-dir C:\WendKeepObserver
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver
+$env:WENDKEEP_OBSERVER_TOKEN = '<token-local-forte>'
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN
 $env:WENDKEEP_OBSERVER_URL = 'http://127.0.0.1:8787'
 ```
 
@@ -64,15 +69,16 @@ docker compose -f docker/wendkeep-observer/compose.yaml up -d --build
 ## Painel web local
 
 Com o servidor em execução, abra [http://127.0.0.1:8787/](http://127.0.0.1:8787/) no navegador.
-O painel é servido pelo mesmo processo e abre diretamente, sem formulário ou token. A porta fica
+O painel é servido pelo mesmo processo e abre diretamente para consultas, sem formulário ou token. A porta fica
 presa ao loopback do computador; não coloque o endereço em uma interface de rede.
 
 O painel mostra a lista multi-projeto, versão, saúde, sessão mais recente, change ativa, contagem
-de changes e data da última captura. Ao abrir um projeto, o workspace oferece as telas Overview,
-Sessões, Memória, Changes e Sincronização. Cada lista abre o documento Markdown completo em um
-leitor read-only, com filtro local, busca no corpo e alternância para a fonte. Os estados de
-carregamento, vazio, servidor indisponível, conflito e dados desatualizados ficam visíveis, e a
-atualização pode ser manual ou automática a cada 15 segundos.
+de changes e data da última captura. Ao abrir um projeto, o workspace oferece Overview, Consumo,
+Sessões, Memória, Changes e Sincronização. A aba Consumo mostra custo total, tokens por categoria,
+agentes principais, subagentes, provedores, modelos, tendência diária, cobertura histórica e
+chamadas conforme o nível de captura escolhido. Os estados de carregamento, vazio, servidor
+indisponível, conflito, modelo sem tarifa e dados desatualizados ficam visíveis, e a atualização
+pode ser manual ou automática a cada 15 segundos.
 
 Se o navegador mostrar a tela mas a lista falhar, confirme a saúde em
 `http://127.0.0.1:8787/healthz` e verifique se o container está em execução.
@@ -80,25 +86,35 @@ Se o navegador mostrar a tela mas a lista falhar, confirme a saúde em
 ## Resultado esperado
 
 `register` grava `project_id`, nome, versão e data de registro. `publish` lê o vault local,
-produz o snapshot e também envia eventos idempotentes com o conteúdo integral das sessões,
-decisões, bugs, aprendizados, specs, changes, CORE, DIGEST, SHARED_MEMORY e estado do brain. O
-container grava os Markdown em `/data/memory` e mantém `MEMORY_EVENTS.jsonl` e
-`MEMORY_INDEX.json` no volume `observer-data`; não monta `C:\GitHub` nem qualquer
-`.WendKeep-vault`. `memory import` faz a carga inicial e retorna a paridade por arquivo e hash.
-
-O `init` projeta `observer-publish` para `SessionStart` e `Stop` depois dos hooks principais. Sem
-`WENDKEEP_OBSERVER_URL`, o hook é no-op. Com o servidor parado, ele grava os snapshots em
-`.brain/observer-outbox/` e a memória integral em `.brain/observer-memory-outbox/`, sem bloquear a
-sessão; uma execução posterior tenta reenviar os dois tipos de evento.
+produz o snapshot e envia eventos idempotentes para o SQLite com o conteúdo integral das sessões,
+decisões, bugs, aprendizados, specs, changes, CORE, DIGEST, SHARED_MEMORY, estado do brain,
+sessões de agentes, rollups de custo e chamadas. Mensagens e transcripts só são enviados nos
+níveis de captura que os habilitam. O container grava tudo em
+`/data/observer.sqlite`; não monta `C:\GitHub` nem qualquer `.WendKeep-vault`. Markdown é aceito
+somente como conteúdo de uma coluna SQL e volta a existir como arquivo apenas pela exportação
+read-only sob demanda. `memory import` faz a carga inicial e retorna a paridade por arquivo e hash.
+Na migração, o total de custo/token registrado no frontmatter é preservado por uma linha de
+reconciliação quando o ledger detalhado não fecha com ele; essa linha não inventa chamadas.
+Sessões históricas com o mesmo `session_id` recebem uma identidade canônica por arquivo para
+evitar que um rollup sobrescreva o outro.
+
+O `init` projeta `observer-publish` para `SessionStart`, `Stop` e `SubagentStop` depois dos hooks
+principais. Sem servidor disponível, ele grava snapshots em `.brain/observer-outbox/` e eventos
+SQL em `.brain/observer-sql-outbox/`, sem bloquear a sessão; uma execução posterior tenta
+reenviar os lotes. Os lotes SQL são enviados com gzip para que transcripts completos maiores que
+64 MB em JSON puro continuem dentro do limite do transporte; o Observer descomprime e valida o
+corpo antes de ingerir. O outbox é transporte temporário, não autoridade.
 
 ## Erros comuns e diagnóstico
 
 - `project_not_registered`: rode `observer register` antes de publicar.
 - `host loopback`: troque `0.0.0.0` ou endereço LAN por `127.0.0.1`.
-- Outbox pendente: o serviço estava indisponível; preserve `.brain/observer-outbox/` e repita o
-  publisher. Não apague eventos manualmente.
-- Se a memória ficar incompleta, verifique a tela Sincronização, preserve o outbox e rode
-  `observer memory import` para reconstruir a cópia a partir do vault.
+- Outbox pendente: o serviço estava indisponível; preserve `.brain/observer-outbox/` e
+  `.brain/observer-sql-outbox/` e repita o publisher. Adicione também
+  `.brain/observer-sql-state.json` e `.brain/observer-sql-outbox/` ao ignore do Vault. Não apague eventos manualmente.
+- `WENDKEEP_OBSERVER_NODE_UNSUPPORTED`: execute o Observer em Node.js 22.13 ou mais recente.
+- Se a memória ou o consumo ficarem incompletos, verifique a tela Sincronização, preserve o
+  outbox e rode `observer memory import` para reconstruir a carga a partir do vault.
 
 ## Próximos passos
 
@@ -107,25 +123,34 @@ removido com `docker compose down -v` durante a operação normal, pois isso apa
 
 ## Autoridade dos dados
 
-O container é a memória canônica para consultas do Observer e guarda o conteúdo integral
-publicado. O vault continua preservado localmente durante a migração como cópia de transição e
-fonte de recuperação; as telas do Observer não concluem, arquivam, reparam ou promovem estado.
+O SQLite do container é a memória canônica para consultas do Observer e guarda o conteúdo integral
+publicado. O vault e qualquer `/data/memory` legado continuam preservados durante a migração como
+cópia de transição e fonte de recuperação; os hooks não atualizam Markdown no container depois do
+corte. As telas do Observer não concluem, arquivam, reparam ou promovem estado.
 
 ## API mínima
 
-- `GET /healthz` — disponibilidade sem dados de projeto.
-- `GET /v1/projects` — projetos com snapshot aceito.
+- `GET /healthz` — disponibilidade, versão das migrações SQLite e estado da migração legada.
+- `GET /v1/projects` — projetos registrados no SQLite, com snapshot quando houver.
 - `GET /v1/projects/:project_id` — último snapshot do projeto.
 - `GET /v1/projects/:project_id/changes` — resumo das changes do snapshot.
 - `PUT /v1/projects/:project_id` — registro explícito local.
 - `POST /v1/projects/:project_id/snapshot` — ingestão local idempotente.
+- `POST /v1/projects/:project_id/ingest` — lote idempotente de documentos, sessões, agentes, rollups,
+  chamadas e transcripts.
 - `GET /v1/projects/:project_id/memory/tree` — árvore e metadados dos documentos.
 - `GET /v1/projects/:project_id/memory/document?path=...` — conteúdo Markdown integral.
 - `GET /v1/projects/:project_id/memory/search?q=...` — busca no caminho e no corpo.
 - `GET /v1/projects/:project_id/sync` — modo, contagem, conflitos e último evento.
-- `PUT /v1/projects/:project_id/sync` — altera explicitamente o modo local.
+- `PUT /v1/projects/:project_id/sync` — compatibilidade de configuração; a autoridade continua SQL.
 - `GET /v1/projects/:project_id/memory/export` — exportação read-only com conteúdo completo.
 - `POST /v1/projects/:project_id/memory/events` — ingestão idempotente em lote.
-
-As rotas `/v1` rejeitam corpo acima do limite e validam projeto, caminho, revisão, hash e
-isolamento antes de gravar o conteúdo no volume.
+- `GET /v1/projects/:project_id/usage/summary` — totais filtráveis por período, change, sessão,
+  agente, provedor, modelo e papel.
+- `GET /v1/projects/:project_id/usage/breakdown` — hierarquia de agentes, subagentes e modelos.
+- `GET /v1/projects/:project_id/usage/calls` — chamadas individuais com prompt e resposta.
+- `GET /v1/projects/:project_id/transcripts/:transcript_id` — transcript comprimido, validado por hash.
+
+As rotas `/v1` rejeitam corpo transportado ou expandido acima do limite e validam projeto, caminho,
+revisão, hash, idempotência e isolamento antes de gravar o conteúdo no SQLite. Para preservar uma
+cópia Markdown, use a rota `memory/export`; ela não altera a autoridade SQL.

package/docs/pt-BR/commands/sessions-and-import.md

@@ -26,11 +26,11 @@ Claude/Codex e um vault vinculado ao projeto correto.
 ## Sintaxe
 
 ```bash
-npx wendkeep hook <nome>
+npx --no-install wendkeep hook <nome>
 npx wendkeep session list
 npx wendkeep session show <id>
 npx wendkeep session use <id>
-npx wendkeep hook session-backfill --session <id> [--write]
+npx --no-install wendkeep hook session-backfill --session <id> [--write]
 npx wendkeep import [opções]
 ```
 
@@ -95,8 +95,8 @@ npx wendkeep import [opções]
 ```bash
 npx wendkeep session list
 npx wendkeep session show 019abc-session-id
-npx wendkeep hook session-backfill --session 019abc-session-id
-npx wendkeep hook session-backfill --session 019abc-session-id --write
+npx --no-install wendkeep hook session-backfill --session 019abc-session-id
+npx --no-install wendkeep hook session-backfill --session 019abc-session-id --write
 npx wendkeep import --source codex --since 2026-07-01 --dry-run --json
 ```
 

package/hooks/observer-publish.mjs

@@ -9,6 +9,7 @@ async function main() {
   const result = await publishObserverSnapshot({
     vaultBase: resolved.base,
     projectRoot: resolved.projectRoot,
+    input,
   });
   if (!result.ok && result.error) debugLog('Observer publish fail-open:', result.error);
 }

package/hooks/understand-inject.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// understand-inject — SessionStart hook (agent-agnostic, run via `npx wendkeep hook
+// understand-inject — SessionStart hook (agent-agnostic, run via `npx --no-install wendkeep hook
 // understand-inject`). If the Understand-Anything domain graph has been generated
 // (`.understand-anything/knowledge-graph.json` at the project root), inject a cheap
 // slice of it into the session; otherwise stay silent. Never breaks the session.