wendkeep 0.69.0 → 0.71.1

package/CHANGELOG.md

@@ -4,6 +4,49 @@ 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.71.1] — 2026-08-17
+
+### Added
+
+- **Observer memory authority.** O container local agora recebe a cópia integral das sessões,
+  decisões, bugs, aprendizados, specs, changes, CORE, DIGEST, SHARED_MEMORY e estado do brain.
+  A API oferece árvore, leitura completa, busca por corpo, sincronização, modos
+  `mirror`/`container-read`/`container-authority` e exportação read-only.
+- **Workspace de memória no navegador.** O painel local navega por projeto, sessões, memória,
+  changes, sincronização e leitor Markdown completo, sem formulário ou token no loopback.
+- **Importação do WendKeep.** `observer memory import` registra a carga inicial e informa paridade
+  por arquivo e hash; o volume Docker permanece preservado em rebuild e reinício.
+
+### Fixed
+
+- **Observer local abre diretamente.** O dashboard não exige mais token, formulário ou
+  `Authorization` para consultar a projeção no loopback; o compose também inicia sem variável de
+  token obrigatória.
+
+## [0.71.0] — 2026-08-17
+
+### Added
+
+- **Painel web local do Observer.** O servidor agora entrega uma interface read-only no navegador
+  para consultar projetos, saúde, sessões, changes e snapshots sanitizados da última captura. A interface é empacotada no
+  npm e na imagem Docker, exige o token local para consultar `/v1`, mantém o token somente no
+  `sessionStorage` da aba e
+  não amplia o contrato de dados sanitizados.
+
+## [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

@@ -78,16 +78,17 @@ npx wendkeep import                          # backfill past Claude + Codex sess
 
 ## The problem: the context dies when the window closes
 
-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.
+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 local capture plus an optional Docker Observer that keeps complete memory browsable without depending on Obsidian.
 
 | | |
 |---|---|
 | **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 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. |
 
 ## 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

@@ -78,16 +78,17 @@ npx wendkeep import                          # backfill past Claude + Codex sess
 
 ## The problem: the context dies when the window closes
 
-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.
+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 local capture plus an optional Docker Observer that keeps complete memory browsable without depending on Obsidian.
 
 | | |
 |---|---|
 | **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 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. |
 
 ## 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,130 @@
+# Local Observer
+
+**English** · [Português](../../pt-BR/commands/observer.md)
+
+## 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.
+
+## 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.
+
+## 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.
+
+## Prerequisites
+
+Initialize projects with WendKeep and explicitly register each project before starting the HTTP
+server. The default local mode has no token to configure.
+
+## 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 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>
+```
+
+## 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 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.
+- Exit `0` means success; exit `1` means configuration or operation failure; the publisher hook
+  also returns `0` when the Observer is unavailable.
+
+## Examples
+
+```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_URL = 'http://127.0.0.1:8787'
+```
+
+For local Docker:
+
+```powershell
+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
+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.
+
+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.
+
+## 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.
+
+## 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.
+
+## 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
+
+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.
+
+## 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` — explicit local registration.
+- `POST /v1/projects/:project_id/snapshot` — idempotent local ingestion.
+- `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.
+- `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.

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,131 @@
+# 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 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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 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>
+```
+
+## 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 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.
+- 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
+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
+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
+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.
+
+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.
+
+## 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.
+
+## 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.
+
+## 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 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.
+
+## 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 local.
+- `POST /v1/projects/:project_id/snapshot` — ingestão local idempotente.
+- `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.
+- `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.

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',