Verify live Kitchen installs and make the public setup clear

.github/workflows/kitchen.yml

@@ -7,12 +7,14 @@ on:
       - 'docs/kitchen/**'
       - 'examples/kitchen-workflow/**'
       - '.github/workflows/kitchen.yml'
+      - 'README.md'
   pull_request:
     paths:
       - 'packages/kitchen/**'
       - 'docs/kitchen/**'
       - 'examples/kitchen-workflow/**'
       - '.github/workflows/kitchen.yml'
+      - 'README.md'
 
 permissions:
   contents: read
@@ -23,7 +25,11 @@ jobs:
       fail-fast: false
       matrix:
         node: [20, 22, 24]
-    runs-on: ubuntu-latest
+        os: [ubuntu-latest]
+        include:
+          - node: 22
+            os: macos-latest
+    runs-on: ${{ matrix.os }}
     defaults:
       run:
         working-directory: packages/kitchen

CONTRIBUTING.md

@@ -33,7 +33,7 @@ npm pack
 node scripts/check-package.mjs ./agenttrail-kitchen-0.1.0-alpha.2.tgz
 ```
 
-Keep fixtures synthetic, small and focused on a real failure mode. The package smoke check verifies a clean install with no development dependencies or lifecycle scripts. Run `node --check bin/agenttrail.mjs` at the repository root for changes touching the existing map daemon, and manually check the relevant view.
+Keep fixtures synthetic, small and focused on a real failure mode. The package smoke check verifies a clean install with no development dependencies or lifecycle scripts, then appends synthetic native logs and checks the live event stream: one session contributes through multiple chefs to one dish, completion reaches its table, and repo file changes are observed. It never uses real home-directory transcripts. Run `node --check bin/agenttrail.mjs` at the repository root for changes touching the existing map daemon, and manually check the relevant view.
 
 ## Preserve the meaning of activity
 

PLAN.md

@@ -181,10 +181,17 @@ links: [plan-reader, runs, map]
   by: codex
   from: agent
   tech: resolve the executable symlink before detecting the CLI entry point; verify actual npm exec rather than only the underlying file
+- [x] Verify the public install observes a fresh working repo {#kitchen-public-readiness}
+  by: codex
+  from: agent
+  tech: downloaded the exact public alpha.2 archive without GitHub credentials, matched its checksum, launched with a fresh npm cache, and observed this real working repo in the browser. All 71 tests pass. Expanded the package check to verify fresh logs over SSE, one session contributing through multiple chefs, native dish completion, and file observation; the public archive passes it.
 
 ## Ship to GitHub and npm {#ship}
 needs: [map, explorer]
 files: [README.md, docs/**, package.json, CONTRIBUTING.md, examples/**, .github/**]
+- [~] Show Kitchen clearly and document the verified setup {#ship-kitchen-readiness-docs}
+  by: codex
+  from: agent
 - [x] Explain how to try and contribute to the kitchen {#ship-kitchen-guide}
   by: codex
   from: agent
@@ -245,6 +252,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-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.
 - 2026-09-08: The owner approved bringing Kitchen into Agenttrail and releasing an experimental preview. Add the kitchen component because the working scene, observers and packaging own packages/kitchen/** and the release now depends on them. Keep the existing map package unchanged; share more runtime code in subsequent work. Import runtime assets, tests and relevant docs, excluding personal logs, reference screenshots and music. A separate video-editing sub-agent is preparing smooth camera moves from the real footage.
 - 2026-09-08: Prepare a release-structure recommendation for bringing the built kitchen into Agenttrail. The proposal keeps one repository and an optional kitchen package; package migration and publication are not part of this planning change.

docs/kitchen/CONNECTING.md

@@ -36,3 +36,26 @@ The companion reads a bounded metadata header from recent local Codex/Claude log
 Default stores are `~/.codex/sessions` and `~/.claude/projects`; the production observer also honors `CODEX_HOME` and `CLAUDE_CONFIG_DIR`. Remote/cloud sessions whose logs are not on this machine are not automatically visible.
 
 Discovery refreshes about every five seconds. It considers files modified within 24 hours, examines up to 240 recent metadata candidates, retains up to 120 observation streams, and suggests up to 24 folders (eight in the picker). Each initial replay is bounded to the last 2 MiB. Larger archives can hit these bounds; `discoveryLimited` appears in the local state response. Missing older history stays unknown. Quiet activity is not presented as continuously working, and native orders are reconstructed from available observations after restart.
+
+## VS Code and Cursor
+
+Kitchen currently opens in a browser. There is no Agenttrail Kitchen VS Code Marketplace extension or VSIX release. Run the [preview command](README.md#start-with-your-repo) in your editor's integrated terminal and keep the browser beside it. The editor does not need a separate extension to run the companion.
+
+Use **Connect agents → Cursor** to review and install `.cursor/hooks.json` for the selected repo. This connects Cursor agent events; it does not install an editor panel. Claude's optional hooks use `.claude/settings.local.json`. Existing unrelated hooks are preserved. Removal is available from the same panel. After a Kitchen upgrade or clearing npm's cache, reconnect hooks if their saved executable path is no longer available.
+
+## Troubleshooting
+
+| What you see | What to check |
+| --- | --- |
+| The project map opens instead of a kitchen | `npx agenttrail` is the Map. Use the full Kitchen archive command in the [quick start](README.md). The short `npx agenttrail-kitchen` registry command is not published yet. |
+| A kitchen appears but nobody works | Select **Live**, choose the same local repo as the agent, and check **Connect agents**. Allow about five seconds for discovery. An idle agent does not generate work. |
+| Codex or Claude is running but not listed | Confirm that logs are on this machine and their recorded working directory belongs to the selected repo. Custom `CODEX_HOME` / `CLAUDE_CONFIG_DIR` must be set in the terminal that launches Kitchen. Cloud-only logs are not discovered. |
+| Cursor activity is missing | Install its optional hooks through **Connect agents**, then start a new conversation if the current one does not load them. Native Cursor live validation is still pending. |
+| Progress is unknown or there are no dishes | The session has not supplied a supported native todo list. File activity and durable `PLAN.md` tasks do not become invented native todos. |
+| Several chefs are waiting | They are persistent responsibilities, not independently launched agents. One session can work through them sequentially. |
+| No plate passes between agents | Confirmed transfers need explicit artifact/revision/receipt metadata. Similar filenames and ordinary reads do not establish a handoff. See [the contract](HANDOFFS.md). |
+| The scene stays blank | Use an up-to-date browser with WebGL enabled. From source, run the graphics build first; the release archive already includes it. |
+| The browser does not open automatically | Open the localhost URL printed by the terminal. Keep that terminal running. |
+| Port 4780 is occupied | Kitchen reuses its registered local service or tries the next free port. Use the URL it prints. |
+
+For a connection-independent check, add `--example` to the launch command and advance **Next example step**. Example is scripted and labeled; it verifies the scene, not your live provider connection. Include your OS, Node version, package version and whether Example works when [reporting an issue](https://github.com/sodiumsun/agenttrail/issues).

docs/kitchen/README.md

@@ -2,7 +2,7 @@
 
 Watch coding agents work through a shared 3D kitchen. Agenttrail's map shows project structure; Kitchen shows the current work as chefs, order tickets, ingredients and deliveries. Both belong to the same open-source project. Kitchen is an experimental, independently installed package.
 
-![Chefs contributing to a shared task in a recorded Codex and Claude collaboration](preview.png)
+![Full kitchen with chefs contributing to a shared task in a recorded Codex and Claude collaboration](overview.jpg)
 
 ## Start with your repo
 
@@ -54,6 +54,8 @@ Click a chef or ticket to inspect the evidence. Drag to pan, scroll to zoom, and
 
 Formats can change, and missing observations remain unknown. Only sessions with accessible local metadata can be discovered. [Connection details](CONNECTING.md) explain discovery limits and optional hook setup.
 
+VS Code and Cursor can launch the browser companion from their integrated terminal. There is no Agenttrail Kitchen Marketplace extension or VSIX release yet. [Editor setup and troubleshooting](CONNECTING.md#vs-code-and-cursor)
+
 ## Customize and contribute
 
 An optional `.office/kitchen.json` names responsibilities and groups rooms. The [portable workflow example](../../examples/kitchen-workflow) contains role/file mappings with no personal sessions or paths. Opening a project does not create this configuration automatically.

docs/kitchen/RELEASE.md

@@ -22,6 +22,9 @@ The existing map daemon, interface and package metadata are unchanged. The root
 - The archive installs offline into a fresh folder with no lifecycle scripts or development dependencies. Its installed launcher attaches a folder containing spaces and shell metacharacters correctly, serves its bundled assets and opens the labeled example URL.
 - Browser verification from the isolated installed archive shows the 3D scene, a Researcher → Writer contribution on the same dish, and completion moving that dish to the deliverable collection. The scene correctly reports five roles and one example session.
 - The exact public GitHub-download command was exercised after publication: help prints correctly and a new isolated kitchen starts successfully in Example mode.
+- The public archive was downloaded again without GitHub authentication and its SHA-256 matched the release. A fresh npm cache and empty npm user configuration launched that exact archive against an existing working repo; current Codex activity appeared in the browser without changing repo settings.
+- The expanded installed-package check appends synthetic native logs after attachment and verifies new events over SSE, one actual session moving between role chefs on one shared dish, native completion reaching the deliverable table, and file changes appearing independently. This check passes against the published alpha.2 archive, not only source imports.
+- The public install's browser was checked in both Live and Example: the 3D scene renders, source labels remain explicit, Researcher → Writer contribution is preserved, and a completed dish reaches the table. No browser errors were reported.
 - The 71 tests and clean-package check also pass in CI on Linux with Node 20, 22 and 24. See the release's associated commit checks for their results.
 
 Earlier native Codex/Claude collaboration was recorded before this import. Native Cursor validation and Windows-specific browser/CLI validation remain pending. No broader support claim is implied by the example mode.

packages/kitchen/README.md

@@ -1,5 +1,7 @@
 # Agenttrail Kitchen
 
+[![Agenttrail Kitchen overview](https://raw.githubusercontent.com/sodiumsun/agenttrail/main/docs/kitchen/overview.jpg)](https://github.com/sodiumsun/agenttrail/tree/main/docs/kitchen)
+
 Your coding agents, cooking together. An experimental 3D view in [Agenttrail](https://github.com/sodiumsun/agenttrail), a local, open-source monitor for coding agents.
 
 Native todos become order tickets, project responsibilities become chefs, and completed todos travel to the deliverable table. Several chefs can contribute to one dish. A chef is a role, so one actual session can work through several chefs; the interface keeps session counts separate. Confirmed artifact receipts can animate plates moving between contributors.
@@ -30,6 +32,8 @@ Local file watching remains available without native todos. Missing tasks or pro
 
 Choose **Connect agents** to review optional Claude or Cursor hook changes. Installation is additive, reversible and explicit. The kitchen never sends prompts, approves actions or changes task status in your agents.
 
+VS Code and Cursor users can run the command in their integrated terminal and keep Kitchen's browser beside the editor. There is no Agenttrail Kitchen Marketplace extension or VSIX release yet. Cursor hooks are a provider connection, not an editor extension. See [troubleshooting](https://github.com/sodiumsun/agenttrail/blob/main/docs/kitchen/CONNECTING.md#troubleshooting).
+
 ## Develop from source
 
 From the repository root:
@@ -50,7 +54,7 @@ npm pack
 node scripts/check-package.mjs ./agenttrail-kitchen-0.1.0-alpha.2.tgz
 ```
 
-The package smoke check installs into an isolated temporary folder without lifecycle scripts or development dependencies, launches the installed command, verifies bundled assets and checks repo attachment. It does not use your real agent logs or saved kitchen state.
+The package smoke check installs into an isolated temporary folder without lifecycle scripts or development dependencies, launches the installed command, verifies bundled assets and checks repo attachment. Synthetic local logs then verify fresh events over the live stream, one session moving through multiple chefs on one dish, completion at the table, and file observation. It does not use your real agent logs or saved kitchen state.
 
 ## Learn more