Explain Agenttrail observability and compare Map with Kitchen

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to Agenttrail
 
-Agenttrail has a lightweight project map and an experimental 3D kitchen. Both use the same repository and issue tracker. The map's existing command remains independent of the kitchen's graphics dependencies.
+Agenttrail provides local observability for AI coding agents through two views: **Map**, a lightweight project map, and **Kitchen**, an experimental 3D view of current tasks and role contributions. Both use the same repository and issue tracker. They observe agents running in their existing tools; they do not orchestrate those agents. [Product and data model](docs/OBSERVABILITY.md)
 
 ## Find the relevant code
 

PLAN.md

@@ -111,6 +111,10 @@ tech: claude code hooks adapter — PostToolUse/TodoWrite → POST /events
 needs: [plan-reader]
 links: [map]
 files: [bin/**, public/**]
+- [ ] Restrict Map actions to trusted local requests {#runs-request-boundary}
+  tech: repository review reproduced missing Host/Origin validation and mutation authentication; add coverage for UI actions, hooks and cross-board relays.
+- [ ] Keep Map and Kitchen hook setup independent {#runs-distinct-hooks}
+  tech: Map's substring detection mistakes Kitchen's relay for its own; verify both installation orders and preserve unrelated hooks.
 - [x] Receive hook events and track sessions {#runs-endpoint}
   by: claude
   tech: /events endpoint; per-session todos, current tool, recent calls
@@ -168,6 +172,10 @@ files: [bin/**, public/**]
 tech: optional kitchen package, local observers, workflow model and Three.js renderer
 files: [packages/kitchen/**]
 links: [plan-reader, runs, map]
+- [ ] Preserve native todos when Map reports newer activity {#kitchen-native-plan-precedence}
+  tech: Projects.enrich currently lets a newer general Map event replace a confirmed native task list with empty board todos and withdraw its dishes.
+- [ ] Confirm plan updates before serving completed dishes {#kitchen-plan-acknowledgements}
+  tech: wait for successful Codex update_plan and legacy TodoWrite results; failed or interrupted calls must retain the last confirmed plan.
 - [x] Bring the runnable kitchen into this repository {#kitchen-import}
   by: codex
   from: agent
@@ -189,6 +197,14 @@ links: [plan-reader, runs, map]
 ## Ship to GitHub and npm {#ship}
 needs: [map, explorer]
 files: [README.md, docs/**, package.json, CONTRIBUTING.md, examples/**, .github/**]
+- [x] Review reliability and explain the two observability views {#ship-observability-review}
+  by: codex
+  from: agent
+  tech: reproduced four issues using real source modules and an isolated Map server; captured a local review with repro steps and suggested fixes. All 71 existing Kitchen tests pass. README and docs/OBSERVABILITY.md explain Map/Kitchen data sources, roles versus sessions, independent services, setup changes and different privacy policies; fixes remain open under runs and kitchen.
+- [~] Publish the clarified observability guide {#ship-observability-guide}
+  by: codex
+  from: agent
+  tech: verify documentation links and merge the overview, accurate provider coverage and setup guidance into the public repository.
 - [x] Show Kitchen clearly and document the verified setup {#ship-kitchen-readiness-docs}
   by: codex
   from: agent
@@ -257,6 +273,7 @@ files: [README.md, docs/**, package.json, CONTRIBUTING.md, examples/**, .github/
   tech: README definition, sentence-case headings, npm metadata, GitHub description and topics
 
 ## decisions
+- 2026-09-09: Review the public repository for concrete reliability and setup issues, recording reproducible findings separately from planned features. Describe Agenttrail as the local observability project with two views: Agenttrail Map for project structure and activity, and Agenttrail Kitchen for native tasks and role contributions. Document their current independent services and differing provider support rather than implying a unified event backend or agent orchestration.
 - 2026-09-08: Publish Kitchen to npm now that the owner has restored registry login. Use alpha.3 for the refreshed package README instead of changing the existing alpha.2 archive; keep the experimental version explicit and use the latest tag so npx agenttrail-kitchen . works. Verify the exact public package from a fresh consumer environment, then publish matching GitHub release assets and setup instructions. The owner chose browser setup first; no editor extension is being added.
 - 2026-09-08: Audit the downloadable public Kitchen release from an isolated consumer install, verify real repo observation and adapter behavior, fix launch gaps, and refresh the root README with Kitchen screenshots and exact install/support instructions. No editor extension currently exists; clarify whether the owner wants one built or wants the working browser setup documented. Keep unknown integration status explicit.
 - 2026-09-08: The public archive check exposed a symlink entry-point bug: invoking the underlying file worked, but npm's installed command exited without calling main. Fix the entry-point detection and test actual npm exec. Supersede the first preview with alpha.2 rather than silently replacing the published archive.

README.md

@@ -7,7 +7,7 @@
 
 # agenttrail
 
-**See what your coding agents are doing—in a live project map or a shared 3D kitchen.**
+**Local observability for AI coding agents.**
 
 [![Kitchen on npm](https://img.shields.io/npm/v/agenttrail-kitchen?color=e9a23b&label=kitchen%20on%20npm)](https://www.npmjs.com/package/agenttrail-kitchen)
 [![Map on npm](https://img.shields.io/npm/v/agenttrail?color=e9a23b&label=map%20on%20npm)](https://www.npmjs.com/package/agenttrail)
@@ -16,7 +16,25 @@
 
 </div>
 
-Agenttrail is a local, open-source monitor for AI coding agents. **Agenttrail Kitchen** turns their current work into chefs, shared dishes and deliveries. **Agenttrail Map** shows the durable plan, file activity and dependencies. Both live in this repository; each has its own command.
+Agenttrail watches your coding agents' available activity and turns it into a live view of their work. See which part of a project is changing, what tasks an agent has reported, and where it needs your attention—without piecing together several terminal windows.
+
+Your agents keep running in tools such as Codex and Claude Code. Agenttrail observes local files, plans and supported agent events; it visualizes that evidence for you. It does not run the agents, assign their work or decide that a task is finished.
+
+## One project, two views
+
+**Agenttrail** is the open-source project. **Map** and **Kitchen** are its two views:
+
+| | Agenttrail Map | Agenttrail Kitchen |
+| --- | --- | --- |
+| Helps you follow | Project structure, progress and which components are changing | Current tasks, role contributions and completed work |
+| Visualizes work as | Components, dependencies, file activity and session trails | Chefs, order tickets, cooking and deliveries |
+| Main sources | `PLAN.md`, file changes and optional Claude Code hooks | Available native todos, local Codex/Claude activity and optional Claude/Cursor hooks |
+| Start in your repo | `npx agenttrail` | `npx agenttrail-kitchen .` |
+| Plan needed? | Optional for file activity; needed for the component map | Optional; native todos supply order tickets when available |
+
+Choose Map for the project overview and Kitchen to follow the work as a shared cooking scene. Each runs independently in your browser. They currently have separate local services and provider adapters; Kitchen can also read a running Map's context. Their activity coverage and history are not identical. [How observability works](docs/OBSERVABILITY.md)
+
+## Agenttrail Kitchen
 
 [![Agenttrail Kitchen overview: six project responsibilities working together, with shared dishes and a delivery conveyor](docs/kitchen/overview.jpg)](docs/kitchen/README.md)
 
@@ -80,9 +98,9 @@ npx agenttrail
 
 ![Agenttrail Map showing live sessions, component progress and file changes](docs/demo.gif)
 
-The Map combines declared intent in `PLAN.md` with observed file changes. A completed component lights up when its files change again. Current Claude Code runs and their todos appear through optional local hooks. Codex, Cursor and other tools contribute through file observation and the shared plan convention.
+The Map combines declared intent in `PLAN.md` with observed file changes. A completed component lights up when its files change again. Claude Code hooks add session and tool activity plus legacy `TodoWrite` lists. Map does not yet parse Claude's newer `TaskCreate`/`TaskUpdate` lists. Codex, Cursor and other tools contribute through file observation and the shared plan convention; their native session adapters currently belong to Kitchen.
 
-For the full component map, run `npx agenttrail init`, review the setup, then give your agent the backfill prompt from the board. It adds the convention to `CLAUDE.md` and `AGENTS.md`, creates a starter plan, and installs additive local Claude Code hooks. **Setup writes these files; normal watching does not.**
+For the full component map, run `npx agenttrail init`, review the setup, then give your agent the backfill prompt from the board. It adds the convention to `CLAUDE.md` and `AGENTS.md`, creates a starter plan, offers local Claude Code hooks, and adds `.agenttrail/` to `.gitignore`. **Setup writes these files; normal watching does not.** In an interactive terminal, starting Map without a plan also offers this setup. Noninteractive `init` assumes yes, so run it only when you intend to configure the repo.
 
 The map has a live file tree, dependency links, session trails and an overview of multiple repos. `npx agenttrail up` relaunches saved boards after a reboot; `npx agenttrail autostart` configures startup at login.
 
@@ -135,12 +153,16 @@ Rebuild after frontend changes. The source, tests, original scene assets and thi
 
 ## Local by construction
 
-Both services bind to **127.0.0.1**. No account, telemetry, transcript upload, model calls or cloud service is required. Fonts and graphics are bundled locally. Kitchen reads bounded local metadata and sends only allowlisted activity fields to its browser; task titles and project paths can still be visible on screen.
+Both services bind to **127.0.0.1**. No account, telemetry, transcript upload, model calls or cloud service is required. Fonts and graphics are available locally. Kitchen reads bounded local metadata and sends only allowlisted activity fields to its browser. Map's Claude hook view can display shortened command text, search terms and other tool details, and saves recent activity under `~/.agenttrail`. Review visible task titles, paths and tool details before sharing a recording. [Data sources and local storage](docs/OBSERVABILITY.md#what-stays-on-your-machine)
 
 The Map is a dependency-free Node daemon and a static page. Kitchen is a separate package with a bundled Three.js frontend. Neither controls your agents, sends prompts, approves actions or marks their tasks complete.
 
 ## FAQ
 
+**Is Agenttrail an agent framework?** It is an observability tool. You run agents in their existing tools; Agenttrail visualizes available evidence of what they are doing. It does not coordinate execution or send prompts. The focus is task and project activity; token billing and full model traces are not implemented.
+
+**Are Map and Kitchen separate projects?** They are two views in this repository, with separate installable packages and local services. You can use either on its own. Kitchen is the experimental 3D view; the original `agenttrail` command opens Map.
+
 **Will this work in an existing repo?** Yes, run the Kitchen command from its folder. Git and `PLAN.md` are optional. A live coding session needs accessible local Codex/Claude logs or configured Cursor hooks. If no activity is available, the chefs wait; use Example to explore the interface.
 
 **Why is the kitchen quiet?** Check **Live**, the selected repo and **Connect agents**. Discovery can take about five seconds. Unsupported remote sessions, missing log history and agents waiting for input can all produce a quiet view. [Troubleshooting](docs/kitchen/CONNECTING.md#troubleshooting)

docs/OBSERVABILITY.md

@@ -0,0 +1,81 @@
+# How Agenttrail observes your agents
+
+Agenttrail is a local observability tool for AI coding agents. It reads available evidence of their work and presents it in two views: **Agenttrail Map** and **Agenttrail Kitchen**. You continue to prompt, run and approve your agents in their existing tools.
+
+The project focuses on what is changing, which tasks are reported, who contributed and where attention is needed. It does not currently provide token billing, model-quality evaluations or a complete trace of every model request.
+
+## One project, two views
+
+| | Map | Kitchen |
+| --- | --- | --- |
+| Question it helps answer | Which parts of this project are changing, and how do they relate? | What work is happening now, and which responsibilities contribute? |
+| Unit of structure | A durable component in `PLAN.md` | A project responsibility, shown as a chef |
+| Unit of work | Plan tasks, file activity and supported run events | An available native todo, shown as a dish |
+| Presentation | Components, dependencies, activity and session trails | Chefs, order tickets, cooking and deliveries |
+| Command | `npx agenttrail` | `npx agenttrail-kitchen .` |
+| Default local port | 5330 | 4780 |
+
+Both are browser companions in this repository. Each has its own package, local service, adapters and history. Either can run independently. Kitchen can read context from a running Map, but there is not yet one shared event backend or a synchronized view switcher.
+
+## Where the information comes from
+
+```mermaid
+flowchart LR
+  P["PLAN.md: declared structure and progress"] --> M["Agenttrail Map"]
+  F["Local file changes"] --> M
+  H["Claude Code hooks"] --> M
+  P --> K["Agenttrail Kitchen"]
+  F --> K
+  L["Local Codex and Claude logs"] --> K
+  C["Optional Claude and Cursor hooks"] --> K
+  M -. "Available board context" .-> K
+```
+
+`PLAN.md` describes durable project components and declared task status. File watching supplies evidence of edits, including changes to a component whose plan already says it is done. File changes alone do not identify an agent or prove that a task succeeded.
+
+Provider logs and hooks add session identity, tool activity, lifecycle events and native tasks where supported. Native tasks are the agent's temporary work list; they can change as a session progresses. Kitchen uses these for order tickets rather than inventing a task breakdown from the project plan.
+
+| Available evidence | Map | Kitchen |
+| --- | --- | --- |
+| Local file changes | Yes | Yes |
+| Durable `PLAN.md` | Component map and declared progress | Project context and role associations |
+| Codex native activity and plans | No direct adapter; file/plan observation remains available | Experimental local log adapter |
+| Claude Code session/tool activity | Optional hooks | Local logs and optional hooks |
+| Claude native task lists | Legacy `TodoWrite`; newer `TaskCreate`/`TaskUpdate` are not parsed | Legacy lists and supported modern task results |
+| Cursor native activity | No direct adapter; file/plan observation remains available | Optional hooks; native live validation pending |
+| Confirmed artifact transfer | No receipt model; trails may suggest a handoff from timing | Explicit artifact revision and receipt metadata |
+
+Local Codex and Claude collaboration has been exercised. The automated Kitchen checks run on Linux and macOS; Windows and native Cursor validation remain pending. Cloud sessions need accessible local logs or an explicit integration. [Kitchen discovery and connection limits](kitchen/CONNECTING.md)
+
+## What the kitchen means
+
+Suppose an agent reports “Implement the endpoint” and “Test validation” while building an API. These can appear as two order tickets. As the session researches, edits and runs checks, its contributions can be associated with different role chefs. When the native task reports completion, its dish travels to the deliverable table.
+
+A chef is a responsibility, not necessarily a separate agent process. A single session can contribute through several chefs in sequence. The interface keeps the real provider/session identity available separately. Multiple sessions sharing a dish and passing confirmed artifacts require explicit bindings and receipt metadata; matching filenames or similar task names do not prove collaboration.
+
+Treat the visuals as different kinds of evidence:
+
+- **Reported:** plan status, native todos and supported lifecycle events supplied by the source.
+- **Observed:** local file changes and recognized operations.
+- **Inferred:** a responsibility or component associated with a file, task or operation. The interface labels these matches.
+- **Unknown:** unavailable native tasks, missing history or an unsupported event format. Missing progress is not a fabricated percentage.
+
+A completed dish means a native todo was reported complete. A deployment or published outcome needs its own evidence. Example mode is explicitly labeled and scripted.
+
+## Current integration limits
+
+Map and Kitchen have not yet consolidated their provider handling. The repository review identified two coexistence bugs: newer Map activity can override Kitchen's native todo list, and Map hook setup can mistake an existing Kitchen hook for its own. Until these are corrected, use Kitchen independently when relying on its native-task display. Running both commands does not guarantee matching task histories.
+
+Some legacy plan adapters also accept a proposed list when its tool call starts, before observing a successful result. These need acknowledgement handling so rejected updates cannot look completed. See the open reliability tasks in [PLAN.md](../PLAN.md).
+
+## What stays on your machine
+
+Both services bind to `127.0.0.1`. They require no Agenttrail account, telemetry service, transcript upload or extra model call. The local browser uses bundled graphics/fonts or system fonts.
+
+Kitchen processes bounded local log data and sends allowlisted activity metadata to its browser. Task titles and project paths can be visible; raw prompts, reasoning, command bodies and arbitrary tool outputs are excluded from that browser feed. Saved repo selection and connector registration live under `~/.agent-office` by default. Its order history is held in memory and reconstructed from available observations after restart.
+
+Map's Claude hook relay sends hook payloads to local Map services. The Map view can show shortened command text, search terms and other tool details, and saves recent activity and cycle summaries under `~/.agenttrail`. It does not have Kitchen's narrower browser-field policy. Check visible details before sharing screenshots or recordings.
+
+Normal watching does not edit your repo. Explicit Map setup creates plan/instruction files and a `.gitignore` entry, and offers Claude hooks; noninteractive `init` assumes yes. Kitchen's optional **Connect agents** flow writes the reviewed provider hook configuration. Neither view sends agent prompts, approves provider actions or changes native task status.
+
+[Start Kitchen](kitchen/README.md) · [Start Map](../README.md#run-the-project-map) · [Contribute](../CONTRIBUTING.md)