Add Agenttrail Kitchen as an optional experimental view

.github/ISSUE_TEMPLATE/kitchen.yml

@@ -0,0 +1,36 @@
+name: Kitchen problem
+description: Report a scene, provider connection or first-run issue in Agenttrail Kitchen.
+labels: [kitchen, bug]
+body:
+  - type: input
+    id: version
+    attributes:
+      label: Kitchen version
+      description: Include the release tag or source commit.
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: OS, Node version, browser and coding agent.
+    validations:
+      required: true
+  - type: dropdown
+    id: mode
+    attributes:
+      label: Which view is affected?
+      options:
+        - Live
+        - Example
+        - Both
+        - Installation or startup
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: What happened?
+      description: Steps to reproduce, expected behavior and actual behavior. Redact private paths and task titles. Do not attach native transcripts or credentials.
+    validations:
+      required: true

.github/workflows/kitchen.yml

@@ -0,0 +1,43 @@
+name: Kitchen preview
+
+on:
+  push:
+    paths:
+      - 'packages/kitchen/**'
+      - 'docs/kitchen/**'
+      - 'examples/kitchen-workflow/**'
+      - '.github/workflows/kitchen.yml'
+  pull_request:
+    paths:
+      - 'packages/kitchen/**'
+      - 'docs/kitchen/**'
+      - 'examples/kitchen-workflow/**'
+      - '.github/workflows/kitchen.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22, 24]
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/kitchen
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+          cache-dependency-path: packages/kitchen/package-lock.json
+      - run: npm ci
+      - run: npm run build
+      - run: npm run check
+      - run: npm test
+      - run: npm pack
+      - run: node scripts/check-package.mjs ./agenttrail-kitchen-0.1.0-alpha.1.tgz
+      - run: node --check ../../bin/agenttrail.mjs

.gitignore

@@ -2,3 +2,9 @@
 node_modules/
 .DS_Store
 .claude/settings.local.json
+promo-gifs/
+packages/kitchen/public/build/
+*.tgz
+recordings/
+.runs/
+.office/

CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# 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.
+
+## Find the relevant code
+
+| Area | Location |
+| --- | --- |
+| Map daemon, plans, hooks and fleet | `bin/agenttrail.mjs` |
+| Map interface | `public/index.html` |
+| Kitchen launcher and local relays | `packages/kitchen/bin/` |
+| Provider adapters and workflow state | `packages/kitchen/src/` |
+| Kitchen scene, characters and interface | `packages/kitchen/public/src/` |
+| Kitchen automated checks | `packages/kitchen/test/` |
+
+The views currently have separate local services. The kitchen can read the map's local board context; it also has standalone observation. Consolidating the duplicated parsers and adapters is future work. Keep provider interpretation out of the scene renderer so future themes can reuse the evidence model.
+
+## Run and check the kitchen
+
+```sh
+cd packages/kitchen
+npm ci
+npm run build
+npm start -- --example
+```
+
+The example is scripted and labeled. Live provider validation should use your own disposable project. Do not install hooks into unrelated repos or submit real transcripts as test fixtures.
+
+```sh
+npm run check
+npm test
+npm pack
+node scripts/check-package.mjs ./agenttrail-kitchen-0.1.0-alpha.1.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.
+
+## Preserve the meaning of activity
+
+- Sessions are actual executors; chefs are responsibilities. Never infer parallel execution from the number of visible chefs.
+- Native todos remain the source of dish identity and completion. Never replace missing task progress with an invented checklist.
+- A turn ending, tool finishing or file changing does not prove an outcome shipped.
+- Explicit receipt metadata is required for confirmed artifact transfers. Clearly distinguish inferred associations.
+- Keep pending human actions in the provider's own tool. This project observes; it does not approve or run those actions.
+
+## Report a problem
+
+Use the [issue tracker](https://github.com/sodiumsun/agenttrail/issues). Include the package version, OS, Node version, provider and a short reproduction. Describe whether the problem affects live data, example mode or both. Redact project paths, task titles and private data from screenshots. Useful labels are `kitchen`, `provider-adapter` and `first-run`.
+
+In a pull request, explain the trigger, resulting behavior and relevant checks. Include a screenshot or short silent clip for visible scene changes. Preserve the project's visual direction. New dependencies should have a concrete purpose and their license notices must accompany bundled assets.
+
+## License
+
+Project code and original assets are MIT. Preserve the root license and third-party notices. Do not add game assets, soundtrack recordings, personal logs, secrets or local connection state. Contributions must be yours to contribute under the relevant license.

PLAN.md

@@ -164,9 +164,37 @@ files: [bin/**, public/**]
   by: claude
   tech: overview+detail per the research — status-colored nodes, click to jump
 
+## Show agents cooking together {#kitchen}
+tech: optional kitchen package, local observers, workflow model and Three.js renderer
+files: [packages/kitchen/**]
+links: [plan-reader, runs, map]
+- [x] Bring the runnable kitchen into this repository {#kitchen-import}
+  by: codex
+  from: agent
+- [x] Make the preview install without a graphics build {#kitchen-package}
+  by: codex
+  from: agent
+- [x] Verify the packaged kitchen in a clean folder {#kitchen-package-check}
+  by: codex
+  from: agent
+
 ## Ship to GitHub and npm {#ship}
 needs: [map, explorer]
-files: [README.md, docs/**, package.json]
+files: [README.md, docs/**, package.json, CONTRIBUTING.md, examples/**, .github/**]
+- [x] Explain how to try and contribute to the kitchen {#ship-kitchen-guide}
+  by: codex
+  from: agent
+- [~] Publish a runnable experimental kitchen preview {#ship-kitchen-preview}
+  by: codex
+  from: agent
+- [x] Propose how to release the kitchen inside Agenttrail {#ship-kitchen-structure}
+  by: codex
+  from: agent
+  tech: package boundaries, shared event model, public preview and announcement in docs/KITCHEN-RELEASE-PLAN.md
+- [x] Plan the companion virtual agent office {#ship-office-plan}
+  by: codex
+  from: agent
+  tech: Research and visual alternatives in ../agent-office; planning only, no runtime changes
 - [x] Public repo and readme {#ship-repo}
   tech: github.com/sodiumsun/agenttrail + README.md
 - [x] Fresh demo gif of the current look {#ship-gif}
@@ -204,6 +232,9 @@ files: [README.md, docs/**, package.json]
   tech: README definition, sentence-case headings, npm metadata, GitHub description and topics
 
 ## decisions
+- 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.
+- 2026-09-08: Explore a visually distinct virtual office in sibling ../agent-office. This session produces research, proposed architecture, must-build scope, and comparable visual concepts only. Keep proposed future components in the companion brief until implementation makes them real; do not add speculative components to the existing map.
 - 2026-08-30: cycles + kind: knowledge + card-setup graduated into the plan after the board flagged PLAN BEHIND — the observed layer caught an undeclared build burst
 - 2026-08-21: spine is the codebase (fs watcher + PLAN.md), not agent hooks; hooks become an optional fidelity adapter
 - 2026-08-21: serve index.html fresh per request (no startup cache) so UI edits land without daemon restart

README.md

@@ -33,6 +33,22 @@ The browser opens on the live board. On a repo with no plan it offers the full s
 
 That's it. No account, no global install, no telemetry. agenttrail opens on localhost and starts watching the repo.
 
+## Watch your agents cook
+
+**[Agenttrail Kitchen](docs/kitchen/README.md)** is an experimental 3D view in this same project. Responsibilities become chefs, native todos become dishes, and completed tasks travel down a conveyor. Real Codex and Claude sessions have been exercised together; Cursor hooks have automated coverage, with native live validation pending.
+
+![Real coding-agent responsibilities working on a shared dish in Agenttrail Kitchen](docs/kitchen/preview.png)
+
+Kitchen is an optional package. The existing map command stays lightweight and independent. [Try the prebuilt preview](https://github.com/sodiumsun/agenttrail/releases/tag/kitchen-v0.1.0-alpha.1), or run from this repository:
+
+```bash
+npm ci --prefix packages/kitchen
+npm run build --prefix packages/kitchen
+npm start --prefix packages/kitchen -- --project /absolute/path/to/your/repo
+```
+
+No running agent yet? Add `--example` to the last command for a labeled demonstration. Chefs represent responsibilities, so several chefs can belong to one actual session. Artifact transfers require explicit receipts; missing progress stays unknown. [Connection details](docs/kitchen/CONNECTING.md) · [Contribute](CONTRIBUTING.md)
+
 ## How the live agent map works
 
 A plan says what the agent intends to do. The filesystem says what it actually touched. agenttrail shows both.
@@ -80,7 +96,7 @@ The agent studies the code first, git history next, and planning prose last. It
 
 ## Local by construction
 
-The daemon is one dependency-free Node file, about 470 lines. The interface is one static HTML file. There is no database, build step, cloud service, account, or telemetry.
+The map's daemon is one dependency-free Node file. Its interface is one static HTML file. The map needs no database or build step. The optional kitchen has a separate graphics build, included in its release archive. Neither view needs a cloud service, account, or telemetry.
 
 It binds to **127.0.0.1 only**. Claude Code hooks live in the repo-local `.claude/settings.local.json` and relay events to the local daemon. While it runs, agenttrail only observes. It never sends a prompt or edits your code.
 

docs/KITCHEN-RELEASE-PLAN.md

@@ -0,0 +1,73 @@
+# Release Agenttrail Kitchen
+
+Status: approved and implemented for the first experimental preview. See [release details](kitchen/RELEASE.md) for verification and distribution status.
+
+## One project, two views
+
+Use **Agenttrail** as the project name and **Agenttrail Kitchen** as its optional 3D view. The map explains project structure and activity; the kitchen makes the same work visible as a collaborative cooking scene. Use one GitHub repository, issue tracker, documentation entry point, and contribution process.
+
+The map remains a small dependency-free Node package. The kitchen has been imported under `packages/kitchen`, with MIT licensing, a package file allowlist and its own Node service and Three.js build. It reads Agenttrail board data and also parses plans and provider activity itself. The views belong to one project but do not yet share one runtime.
+
+## Repository and installation
+
+For the first public preview, keep the existing map package in place and import the kitchen as an independently runnable package:
+
+```text
+agenttrail/
+  bin/                       existing Agenttrail command
+  public/                    existing map
+  packages/
+    kitchen/
+      bin/                   kitchen launcher and local relays
+      src/                   observers, event state and local service
+      public/                scene, characters and interface
+      scripts/               bundle the renderer
+      test/
+      package.json
+  docs/
+    kitchen/                 quick start, connection limits, event model
+  examples/
+    kitchen-workflow/        portable roles and a labeled example
+  LICENSE
+  CONTRIBUTING.md
+```
+
+The package is `agenttrail-kitchen@0.1.0-alpha.1`. The preview is distributed as a prebuilt GitHub release archive because npm registry authentication is currently unavailable. The short `npx agenttrail-kitchen` command must not be advertised as available until registry publication succeeds. The archive includes built graphics and local fonts, has an explicit file allowlist and has no runtime npm dependencies. The existing `npx agenttrail` package and command remain unchanged.
+
+After the optional package works, offer a convenient `agenttrail kitchen` launcher and Map/Kitchen navigation that preserve the selected repo. That launcher is a later interface change, not an existing command.
+
+## Shared meaning before more themes
+
+Consolidate the duplicated plan and provider handling incrementally after the import. Both views should eventually subscribe to one local event stream and model. Keep kitchen geometry, characters and animation separate from provider adapters and task state. A future space-station or fire-station view can reuse those events and change its scene and presentation.
+
+The shared model must distinguish:
+
+| Product fact | Kitchen presentation |
+| --- | --- |
+| Actual provider session/executor | Source of observed work; provider badge and session count |
+| Project responsibility/role | Persistent chef; several roles may belong to one session |
+| Ephemeral native todo | Dish and evolving order ticket |
+| Durable component or outcome | Project map context or destination table; not fabricated todo progress |
+| Observed contribution to a todo | Chef works on that dish |
+| Explicit artifact revision and receipt | Plate transfer with provenance |
+
+Inferred roles remain labeled inferred. One session moving between roles does not establish parallel execution. Handoffs inferred from timing remain distinct from acknowledged artifact receipts. Missing native tasks or progress remain unknown. Switching views must not create new activity or start agents.
+
+## Make the preview useful to contributors
+
+1. Import only the runtime, tests, useful documentation and original project assets. Preserve the existing map behavior and package contents.
+2. Apply the existing MIT license to code the owner is entitled to license; retain Three.js MIT and Nunito OFL notices. Keep the soundtrack compilation and game-reference screenshots outside the open-source distribution.
+3. Provide one copyable quick start and an explicit example mode for people without agents running. Clearly label examples and replays. Test a packed package in a clean folder, not just the development checkout.
+4. Publish a short compatibility table: Codex and Claude local integration were exercised in the demo; native Cursor validation is pending. Explicit handoff metadata is required for reliable artifact receipts. Remote sessions without local logs are not automatically visible.
+5. Move only a sanitized version of the Maze Shift role/example configuration. Do not include `.runs`, personal paths, native transcripts, saved local connection state or the full raw recordings.
+6. Run the existing kitchen checks plus install/launch verification, then publish an experimental release with a runnable source link. Make issue labels for kitchen visuals, provider adapters and first-run problems.
+
+## Announce it with the kitchen clip
+
+Use the 22-second kitchen-only video as the main post. Introduce the experience, identify the demo as real Codex and Claude work, and link the runnable preview and setup instructions. Invite people to try their own repos and report integration gaps. Use “Overcooked-inspired” as the inspiration, while retaining Agenttrail Kitchen as the product name.
+
+The music edit uses the owner's supplied MP3 from 10:25.000 to 10:46.833. Public promotional use needs to be covered by the owner's applicable music licence; an MIT software release does not grant rights to the soundtrack. Audio Network offers [social and promotional licensing](https://us.audionetwork.com/licensing) and sets out its [usage terms](https://www.audionetwork.com/terms-and-conditions). Use the silent cut or another suitably licensed track if that coverage is unavailable.
+
+Promotion videos are separate from the software distribution. Only the original kitchen screenshot is included in these docs; native logs, raw recordings and soundtrack files are excluded.
+
+Do not describe the kitchen as published until its code is in the public repository. A post made before then should call it a work-in-progress preview.