wendkeep 0.69.0 → 0.70.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.70.0] — 2026-08-17
+
+### Added
+
+- **Observer local multi-projeto.** O WendKeep agora expõe snapshots sanitizados, ingestão HTTP
+  loopback, índice append-only reconstruível, CLI `observer`, outbox fail-open nos hooks e um
+  compose Docker que persiste somente a projeção; os vaults locais continuam sendo a autoridade.
+
+### Fixed
+
+- **Modelos research preview agora são distinguidos de modelos desconhecidos.** O Spark é
+  reconhecido sem preço inventado, o `doctor` mantém o custo não estimado e a cobertura de
+  preços passa a ser validada por sensor crítico.
+
 ## [0.69.0] — 2026-08-16
 
 ### Added

package/README.en.md

@@ -85,9 +85,10 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 | **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 | Canonical `CORE` + operational `SHARED_MEMORY`, with explicit budgets, are injected on `startup`, `/clear`, and `/compact`; `DIGEST` remains a deep-recall index and legacy fallback. |
-| **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. |
+| **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 a local HTTP index of sanitized, idempotent snapshots; vaults remain local, the container does not mount them, and unavailable hooks use an outbox without blocking the session. |
 
 ## Requirements
 
@@ -110,7 +111,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`** — eight of the twelve: `brain-inject` + `session-start` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `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. 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`** — 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**.
 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`.
@@ -235,6 +236,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Local Observer** | `observer serve`, registration, snapshots, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and

package/README.md

@@ -85,9 +85,10 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 | **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 | Canonical `CORE` + operational `SHARED_MEMORY`, with explicit budgets, are injected on `startup`, `/clear`, and `/compact`; `DIGEST` remains a deep-recall index and legacy fallback. |
-| **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. |
+| **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 a local HTTP index of sanitized, idempotent snapshots; vaults remain local, the container does not mount them, and unavailable hooks use an outbox without blocking the session. |
 
 ## Requirements
 
@@ -110,7 +111,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`** — eight of the twelve: `brain-inject` + `session-start` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `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. 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`** — 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**.
 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`.
@@ -235,6 +236,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+| **Local Observer** | `observer serve`, registration, snapshots, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and

package/docs/en/commands/changes-and-verification.md

@@ -77,6 +77,10 @@ tool runs, it compares the session, project, Git root, remote, branch, and workt
 recorded in `SESSION_REGISTRY.json`. Missing, ambiguous, concurrent, or cross-project targets are
 blocked before the tool.
 
+The [local Observer](observer.md) is a read-only observability projection: the vault and change
+remain local authorities. Observer queries do not complete, archive, repair, or promote state in a
+vault.
+
 Codex blocks with `permissionDecision: "deny"`; `ask` is not a valid `PreToolUse` decision.
 `commit`, `push`, `pull`, `merge`, `publish`, and destructive operations remain separate capabilities,
 including when one command contains multiple actions. Switching projects requires a new explicit

package/docs/en/commands/costs-and-observability.md

@@ -19,7 +19,8 @@ projects whose registries are mixed.
 
 ## Prerequisites
 
-A consistent registry, complete price table, and transcript access for rebuilt sessions.
+A consistent registry, a price table for models with published rates, and transcript access for
+rebuilt sessions. A research preview without a final rate must remain explicitly unestimated.
 
 ## Syntax
 
@@ -64,9 +65,17 @@ returns `complete`, `none`, or `degraded`, plus a frontier, manifest, and saniti
 Run and review the dry-run before repeating the same command with `--apply`; a semantically
 identical second apply preserves the note, checkpoint, report, and mtime.
 
+## Models without a final rate
+
+`doctor` separates a model that is truly missing from the table from a known
+`research-preview` model. The former remains actionable and asks for an update to
+`hooks/pricing.json`; the latter is reported as **final rate not published** and **cost not
+estimated**. Do not copy another model's price into the gap.
+
 ## Common errors and diagnosis
 
-- Model without a price: update the table before accepting totals.
+- Unknown model without a price: update the table before accepting totals.
+- Research preview without a final rate: keep the cost unestimated; do not invent a rate.
 - Wrong-provider costs: validate the session identity chain.
 - Missing transcript: do not estimate silently; keep the gap visible.
 - Duplicated parent/subagent/fork totals: verify registry relationships and deduplication.

package/docs/en/commands/observer.md

@@ -0,0 +1,104 @@
+# Local Observer
+
+**English** · [Português](../../pt-BR/commands/observer.md)
+
+## Purpose
+
+The Observer consolidates observability for multiple WendKeep projects in a local service without
+copying or taking ownership of their vaults.
+
+## When to use
+
+Use it to query summarized changes, sessions, tasks, and health across projects through one local
+projection while each vault remains authoritative.
+
+## When not to use
+
+Do not use the Observer to edit, complete, or archive changes, curate memory, store transcripts,
+or replace local hooks. Do not expose it to the network in this version.
+
+## Prerequisites
+
+Initialize projects with WendKeep, explicitly register each project, and set a local token before
+starting the HTTP server.
+
+## Syntax
+
+```bash
+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 serve --host 127.0.0.1 --port 8787 --data-dir <directory>
+```
+
+## Options and exit codes
+
+- `--data-dir` selects the local event and index directory; the default is
+  `WENDKEEP_OBSERVER_DATA_DIR` or `~/.wendkeep-observer`.
+- `--project` and `--vault` identify a project only for `register` and `publish`.
+- `--host` accepts only `127.0.0.1`, `localhost`, or `::1`; other hosts are rejected before
+  listening.
+- `--token` or `WENDKEEP_OBSERVER_TOKEN` protects `/v1`; `GET /healthz` exposes no project data.
+- Exit `0` means success; exit `1` means configuration or operation failure; the publisher hook
+  also returns `0` when the Observer is unavailable.
+
+## Examples
+
+```powershell
+$env:WENDKEEP_OBSERVER_TOKEN = '<local-token>'
+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_URL = 'http://127.0.0.1:8787'
+```
+
+For local Docker:
+
+```powershell
+$env:WENDKEEP_OBSERVER_TOKEN = '<local-token>'
+docker compose -f docker/wendkeep-observer/compose.yaml up -d --build
+```
+
+## Expected result
+
+`register` stores only `project_id`, name, version, and registration time. `publish` reads the
+local vault, produces a sanitized snapshot, and sends an idempotent event. The container stores
+only `EVENTS.jsonl` and `INDEX.json` in the `observer-data` volume; it does not mount `C:\GitHub`
+or any `.WendKeep-vault`.
+
+`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 to
+`.brain/observer-outbox/` and does not block the session; a later run retries pending events.
+
+## Common errors and diagnosis
+
+- `project_not_registered`: run `observer register` before publishing.
+- `unauthorized`: check `Authorization: Bearer <token>` and `WENDKEEP_OBSERVER_TOKEN`.
+- `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.
+- The Observer does not read raw content, paths, transcripts, or memory; such rejections are
+  expected and should be investigated at the snapshot source.
+
+## Next steps
+
+Read the `local-observer` change for the `OBS-1` through `OBS-8` contract. Do not remove the Docker
+volume with `docker compose down -v` during normal operation because it deletes the local
+projection.
+
+## Data authority
+
+Each project vault remains authoritative for sessions, changes, tasks, memory, and evidence. The
+Observer is a read-only, rebuildable projection; its queries do not complete, archive, repair, or
+promote state in a vault.
+
+## Minimal API
+
+- `GET /healthz` — availability without project data.
+- `GET /v1/projects` — projects with an accepted snapshot.
+- `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` — authenticated explicit registration.
+- `POST /v1/projects/:project_id/snapshot` — authenticated idempotent ingestion.
+
+The `/v1` routes reject oversized bodies and never accept vault paths, transcripts, secrets, or raw
+memory content.

package/docs/pt-BR/commands/changes-and-verification.md

@@ -77,6 +77,10 @@ uma ferramenta de escrita suportada, ele compara sessão, projeto, raiz Git, rem
 worktree com a lease registrada no `SESSION_REGISTRY.json`. Um alvo ausente, ambíguo, concorrente ou
 fora do projeto é bloqueado antes da ferramenta.
 
+O [Observer local](observer.md) é uma projeção read-only da observabilidade: o vault e a change
+continuam autoridades locais. Consultas do Observer não concluem, arquivam, reparam ou promovem
+estado no vault.
+
 No Codex o bloqueio usa `permissionDecision: "deny"`; `ask` não é uma decisão válida de
 `PreToolUse`. `commit`, `push`, `pull`, `merge`, `publish` e operações destrutivas continuam
 capacidades separadas, inclusive quando um comando contém mais de uma ação. A troca de projeto

package/docs/pt-BR/commands/costs-and-observability.md

@@ -19,7 +19,9 @@ projetos com registries misturados.
 
 ## Pré-requisitos
 
-Registry consistente, tabela de preços completa e acesso aos transcripts das sessões reconstruídas.
+Registry consistente, tabela de preços para os modelos com tarifa publicada e acesso aos transcripts
+das sessões reconstruídas. Um research preview sem tarifa final deve permanecer explicitamente
+como custo não estimado.
 
 ## Sintaxe
 
@@ -64,9 +66,17 @@ tri-state devolve `complete`, `none` ou `degraded`, mais frontier, manifest e di
 sanitizados. Rode e revise o dry-run antes de repetir o mesmo comando com `--apply`; uma segunda
 aplicação semanticamente idêntica preserva nota, checkpoint, relatório e mtime.
 
+## Modelos sem tarifa final
+
+O `doctor` separa um modelo realmente ausente da tabela de um modelo conhecido em
+`research-preview`. O primeiro continua acionável e pede atualização de
+`hooks/pricing.json`; o segundo aparece como **tarifa final não publicada** e **custo não
+estimado**. Não copie o preço de outro modelo para preencher essa lacuna.
+
 ## Erros comuns e diagnóstico
 
-- Modelo sem preço: atualize a tabela antes de aceitar o total.
+- Modelo desconhecido sem preço: atualize a tabela antes de aceitar o total.
+- Research preview sem tarifa final: mantenha o custo não estimado; não invente uma tarifa.
 - Custos de provider errado: valide a cadeia de identidade da sessão.
 - Transcript ausente: não estime silenciosamente; mantenha a lacuna visível.
 - Total duplicado por subagent/fork: confirme relação pai/subagent e deduplicação do registry.

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

@@ -0,0 +1,105 @@
+# Observer local
+
+**PT-BR** · [English](../../en/commands/observer.md)
+
+## Objetivo
+
+O Observer consolida a observabilidade de vários projetos WendKeep em um serviço local, sem
+copiar ou assumir a propriedade dos vaults.
+
+## Quando usar
+
+Use para consultar changes, sessões, tarefas resumidas e saúde de vários projetos em uma única
+projeção local, mantendo cada vault como fonte oficial.
+
+## Quando não usar
+
+Não use o Observer para editar, concluir ou arquivar changes, curar memória, armazenar transcripts
+ou substituir os hooks locais. Não o exponha na rede nesta versão.
+
+## Pré-requisitos
+
+Tenha os projetos inicializados com WendKeep, registre explicitamente cada projeto e defina um
+token local antes de iniciar o servidor HTTP.
+
+## Sintaxe
+
+```bash
+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 serve --host 127.0.0.1 --port 8787 --data-dir <diretório>
+```
+
+## Opções e códigos de saída
+
+- `--data-dir` escolhe o diretório local de eventos e índice; o padrão é
+  `WENDKEEP_OBSERVER_DATA_DIR` ou `~/.wendkeep-observer`.
+- `--project` e `--vault` identificam o projeto somente nos comandos `register` e `publish`.
+- `--host` aceita somente `127.0.0.1`, `localhost` ou `::1`; outros hosts são recusados antes do
+  listen.
+- `--token` ou `WENDKEEP_OBSERVER_TOKEN` protege as rotas `/v1`; `GET /healthz` permanece sem
+  dados de projeto.
+- 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.
+
+## Exemplos
+
+```powershell
+$env:WENDKEEP_OBSERVER_TOKEN = '<token-local>'
+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_URL = 'http://127.0.0.1:8787'
+```
+
+Para Docker local:
+
+```powershell
+$env:WENDKEEP_OBSERVER_TOKEN = '<token-local>'
+docker compose -f docker/wendkeep-observer/compose.yaml up -d --build
+```
+
+## Resultado esperado
+
+`register` grava apenas `project_id`, nome, versão e data de registro. `publish` lê o vault local,
+produz um snapshot sanitizado e envia um evento idempotente. O container mantém somente
+`EVENTS.jsonl` e `INDEX.json` no volume `observer-data`; não monta `C:\GitHub` nem qualquer
+`.WendKeep-vault`.
+
+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 em
+`.brain/observer-outbox/` e não bloqueia a sessão; uma execução posterior tenta reenviar eventos
+pendentes.
+
+## Erros comuns e diagnóstico
+
+- `project_not_registered`: rode `observer register` antes de publicar.
+- `unauthorized`: confira `Authorization: Bearer <token>` e `WENDKEEP_OBSERVER_TOKEN`.
+- `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.
+- O Observer não lê conteúdo bruto, caminhos, transcripts ou memória; rejeições desse tipo são
+  esperadas e devem ser investigadas na origem do snapshot.
+
+## Próximos passos
+
+Leia a change `local-observer` para o contrato `OBS-1` a `OBS-8`. O volume Docker não deve ser
+removido com `docker compose down -v` durante a operação normal, pois isso apaga a projeção local.
+
+## Autoridade dos dados
+
+O vault de cada projeto continua sendo a fonte oficial de sessões, changes, tarefas, memória e
+evidências. O Observer é uma projeção read-only reconstruível; suas consultas não concluem,
+arquivam, reparam ou promovem estado no vault.
+
+## API mínima
+
+- `GET /healthz` — disponibilidade sem dados de projeto.
+- `GET /v1/projects` — projetos com snapshot aceito.
+- `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 autenticado.
+- `POST /v1/projects/:project_id/snapshot` — ingestão autenticada e idempotente.
+
+As rotas `/v1` rejeitam corpo acima do limite e nunca aceitam caminho de vault, transcript, segredo
+ou conteúdo bruto de memória.

package/hooks/harness-doctor.mjs

@@ -212,9 +212,11 @@ export function checkStackedFrontmatter(vaultBase) {
 }
 
 // Um modelo fora de `pricing.json` faz `priceForModel` devolver null e a parcela dele do custo
-// virar zero — sem erro, sem aviso. Modelo novo (claude-opus-5, claude-mythos-5) cai nisso por
-// default. A checagem é sobre o vault, não sobre o caminho de cálculo: o cálculo roda em hook a
-// cada turno, onde avisar viraria ruído e lançar derrubaria a captura da sessão.
+// virar zero — sem erro, sem aviso. Modelos conhecidos sem tarifa final (por exemplo, um
+// research preview) ficam na tabela com status explícito e são reportados separadamente: isso
+// evita tanto o silêncio quanto a sugestão de inventar um preço. A checagem é sobre o vault, não
+// sobre o caminho de cálculo: o cálculo roda em hook a cada turno, onde avisar viraria ruído e
+// lançar derrubaria a captura da sessão.
 //
 // Cada modelo citado na nota é consultado direto em `priceForModel` — NÃO se infere pelo
 // sintoma "custo zerado". Numa sessão multi-modelo (`modelo: "claude-opus-4.8 + claude-opus-5"`)
@@ -222,6 +224,7 @@ export function checkStackedFrontmatter(vaultBase) {
 // motivou esta change, a nota fecha com $415 e a fatia do Opus 5 é a única zerada.
 export function checkUnpricedModels(vaultBase) {
   const counts = new Map();
+  const researchPreview = new Map();
 
   const modelsOf = (frontmatter) => {
     // `modelos:` é a lista canônica; `modelo:` é o rótulo agregado (junta com " + ").
@@ -247,23 +250,34 @@ export function checkUnpricedModels(vaultBase) {
       for (const raw of modelsOf(fm[1])) {
         const model = raw.trim().replace(/^["']|["']$/g, '');
         if (!model || model === 'unknown') continue;
-        if (priceForModel(model)) continue;
-        counts.set(model, (counts.get(model) || 0) + 1);
+        const price = priceForModel(model);
+        if (price?.pricingStatus === 'research-preview') {
+          researchPreview.set(model, (researchPreview.get(model) || 0) + 1);
+        } else if (!price) {
+          counts.set(model, (counts.get(model) || 0) + 1);
+        }
       }
     }
   };
 
   walk(join(vaultBase, '02-Sessões'));
-  return { models: [...counts].map(([model, notes]) => ({ model, notes })) };
+  return {
+    models: [...counts].map(([model, notes]) => ({ model, notes })),
+    researchPreview: [...researchPreview].map(([model, notes]) => ({ model, notes })),
+  };
 }
 
 export function renderUnpricedModelLines(unpriced) {
+  const preview = unpriced.researchPreview || [];
   const lines = [`[preços] ${unpriced.models.length} modelo(s) sem preço na tabela`];
   for (const { model, notes } of unpriced.models) {
     lines.push(`  ✗ ${model} (${notes} nota(s) com custo zerado)`);
   }
   if (unpriced.models.length) lines.push('  → adicione o modelo em hooks/pricing.json');
-  else lines.push('  tabela de preços completa ✓');
+  else if (!preview.length) lines.push('  tabela de preços completa ✓');
+  for (const { model, notes } of preview) {
+    lines.push(`  ! ${model} (${notes} nota(s)): research preview sem tarifa final; custo não estimado`);
+  }
   return lines;
 }
 

package/hooks/observer-publish.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { pathToFileURL } from 'node:url';
+import { debugLog, readHookInput, resolveVault } from './obsidian-common.mjs';
+import { publishObserverSnapshot } from '../src/observer-publish.mjs';
+
+async function main() {
+  const input = readHookInput();
+  const resolved = resolveVault(input);
+  const result = await publishObserverSnapshot({
+    vaultBase: resolved.base,
+    projectRoot: resolved.projectRoot,
+  });
+  if (!result.ok && result.error) debugLog('Observer publish fail-open:', result.error);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    debugLog('Observer hook falhou de forma fail-open:', error);
+    process.exitCode = 0;
+  });
+}

package/hooks/pricing.json

@@ -1,6 +1,6 @@
 {
   "_nota": "Preços API por milhão de tokens. cachedInput = cache read. Cache write aplica multiplicador no código: 5m = 1.25x input, 1h = 2x input. Editar aqui quando o provedor mudar preços (sem mexer no .mjs). Se o arquivo sumir ou ficar inválido, o hook usa a tabela embutida em token-usage.mjs.",
-  "_fonte": "OpenAI https://openai.com/index/gpt-5-6/ e https://help.openai.com/en/articles/20001325-a-preview-of-gpt-56-sol-terra-and-luna; Anthropic https://www.anthropic.com/pricing — conferido 2026-07-11",
+  "_fonte": "OpenAI https://openai.com/index/gpt-5-6/, https://openai.com/index/introducing-gpt-5-3-codex-spark/ e https://help.openai.com/en/articles/20001106-codex-rate-card; Anthropic https://www.anthropic.com/pricing — conferido 2026-08-16",
   "models": {
     "gpt-5.6-sol": { "label": "GPT-5.6 Sol API", "provider": "openai", "input": 5, "cachedInput": 0.5, "output": 30 },
     "gpt-5.6-terra": { "label": "GPT-5.6 Terra API", "provider": "openai", "input": 2.5, "cachedInput": 0.25, "output": 15 },
@@ -12,6 +12,15 @@
       "cachedInput": 0.5,
       "output": 30
     },
+    "gpt-5.3-codex-spark": {
+      "label": "GPT-5.3-Codex-Spark (research preview)",
+      "provider": "openai",
+      "pricingStatus": "research-preview",
+      "pricingNote": "Tarifa final não publicada; custo não estimado.",
+      "input": null,
+      "cachedInput": null,
+      "output": null
+    },
     "claude-opus-4.7": {
       "label": "Claude Opus 4.7 API",
       "provider": "anthropic",

package/hooks/token-usage.mjs

@@ -30,6 +30,15 @@ const DEFAULT_PRICE_REFERENCE = {
   'gpt-5.6-sol': { label: 'GPT-5.6 Sol API', provider: 'openai', input: 5, cachedInput: 0.5, output: 30 },
   'gpt-5.6-terra': { label: 'GPT-5.6 Terra API', provider: 'openai', input: 2.5, cachedInput: 0.25, output: 15 },
   'gpt-5.6-luna': { label: 'GPT-5.6 Luna API', provider: 'openai', input: 1, cachedInput: 0.1, output: 6 },
+  'gpt-5.3-codex-spark': {
+    label: 'GPT-5.3-Codex-Spark (research preview)',
+    provider: 'openai',
+    pricingStatus: 'research-preview',
+    pricingNote: 'Tarifa final não publicada; custo não estimado.',
+    input: null,
+    cachedInput: null,
+    output: null,
+  },
   'gpt-5.5': {
     label: 'GPT-5.5 API',
     provider: 'openai',
@@ -122,6 +131,10 @@ const MODEL_ALIASES = {
   'gpt-5.3-codex': 'gpt-5.5',
   'gpt-5.3': 'gpt-5.5',
   'openai/gpt-5.4': 'gpt-5.5',
+  'gpt-5.3-codex-spark': 'gpt-5.3-codex-spark',
+  'gpt-5-3-codex-spark': 'gpt-5.3-codex-spark',
+  'openai/gpt-5.3-codex-spark': 'gpt-5.3-codex-spark',
+  'openai/gpt-5-3-codex-spark': 'gpt-5.3-codex-spark',
   'claude-opus-4.7': 'claude-opus-4.7',
   'claude-opus-4-7': 'claude-opus-4.7',
   'anthropic/claude-opus-4.7': 'claude-opus-4.7',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -40,7 +40,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
+    "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check hooks/observer-publish.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run",
@@ -70,6 +70,6 @@
   },
   "devDependencies": {
     "acorn": "^8.18.0",
-    "wendkeep": "^0.68.6"
+    "wendkeep": "^0.69.0"
   }
 }

package/packages/cli/src/index.mjs

@@ -49,6 +49,7 @@ Usage:
                            cannot replace itself. · --vault P · --profile <name> · --yes.
 
   wendkeep doctor [--vault P]  Run a vault health check.
+  wendkeep observer <sub>     Local multi-project Observer: serve | register | publish | status.
   wendkeep change <sub>        Change lifecycle: new [--simple] | use | bind <slug> --session <id> | continue | list | show |
                            status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
                            archive exige verdict (rode verify --deep); abandon descarta sem ADR.
@@ -199,7 +200,7 @@ async function main(argv) {
     // `sync` starts with `init` and resolves the freshly bound Vault itself. Pre-resolving
     // here would prevent that repair step from reporting a corrupt binding as its own
     // first-stage failure (and could never make it as far as the guarded init).
-    && !['init', 'sync', 'hook', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
+    && !['init', 'sync', 'hook', 'observer', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
     await preferProjectVault(rest);
   }
   switch (cmd) {
@@ -216,6 +217,12 @@ async function main(argv) {
       process.exit(runDoctor(rest));
       break;
     }
+    case 'observer': {
+      const { runObserver } = await import('../../../src/observer.mjs');
+      const observerExitCode = await runObserver(rest);
+      if (rest[0] !== 'serve') process.exit(observerExitCode);
+      break;
+    }
     case 'sync': {
       const { runSync } = await import('../../../src/sync.mjs');
       process.exit(await runSync(rest));

package/packages/integrations/src/host-hooks.mjs

@@ -13,7 +13,11 @@ export const SESSION_HOOKS = [
   // memory injection for the whole session.
   { event: 'SessionStart', matcher: 'startup|clear|compact', name: 'brain-inject', timeout: 45, order: -10, codex: true, statusMessage: 'wendkeep: injecting memory + active change' },
   { event: 'SessionStart', matcher: 'startup', name: 'session-start', timeout: 30, codex: true, statusMessage: 'wendkeep: opening Obsidian session' },
+  // Observer publication is a derived, fail-open projection and therefore runs only after
+  // the local lifecycle hook has written its authoritative session state.
+  { event: 'SessionStart', matcher: 'startup|resume|clear|compact', name: 'observer-publish', timeout: 5, order: 20, codex: true, statusMessage: 'wendkeep: publishing local observer snapshot' },
   { event: 'Stop', matcher: null, name: 'session-stop', timeout: 60, codex: true, statusMessage: 'wendkeep: writing session checkpoint' },
+  { event: 'Stop', matcher: null, name: 'observer-publish', timeout: 5, order: 20, codex: true, statusMessage: 'wendkeep: publishing local observer snapshot' },
   { event: 'UserPromptSubmit', matcher: null, name: 'session-ensure', timeout: 30, codex: true, statusMessage: 'wendkeep: ensuring active session' },
   // Capture an interactive decision (AskUserQuestion) — options + the user's choice — into 04-Decisões.
   // codex: AskUserQuestion is a Claude-only tool; there is nothing to match on.