grilling-workbench 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Grilling Workbench contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# Grilling Workbench
+
+Local question forms for project interviews in an embedded browser. The agent
+writes questions, the user submits the entire form, and a waiting socket delivers
+the saved answers back to the agent. Reasoning and clarification stay in the
+existing chat. No model API, external assets, or production dependencies.
+
+Once installed, the skill applies whenever the agent interviews the user. Calling
+an interview skill such as `grill-me` is enough; the user does not need to request
+a browser form or enable a separate project preference.
+
+**Run with `npx`; no project dependency is required.** Node.js 22 or later is required.
+The supported deployment is a browser and agent on the same computer; no public
+server or idle-chat wakeup service is included.
+
+## Install in a project
+
+From the project where you want to use the workbench:
+
+```sh
+npx --yes grilling-workbench@0.2.0 install-skill
+```
+
+The installer creates `.agents/skills/grilling-workbench` and refuses to overwrite
+an existing skill. Codex detects new skills automatically; restart it if the skill
+does not appear. Explicit `$grilling-workbench` invocation can verify installation;
+normal interview use should select it automatically. npm caches the application;
+the skill and interview sessions remain in your project. Use the same pinned
+version for setup and every command in a round.
+
+Source: [PavingLayer/grilling-workbench](https://github.com/PavingLayer/grilling-workbench).
+Package: [grilling-workbench on npm](https://www.npmjs.com/package/grilling-workbench).
+License: [MIT](LICENSE).
+
+The [deployment guide](docs/deployment.md) covers non-Node projects, session
+storage, updates, shutdown, backups, and recovery. The [integration guide](docs/integration.md)
+explains skill discovery and project configuration alongside Matt Pocock's skills.
+
+## Agent workflow
+
+```sh
+npx --yes grilling-workbench@0.2.0 init --session .workbench/topic-r01 --questions /absolute/path/round.json
+npx --yes grilling-workbench@0.2.0 serve --session .workbench/topic-r01
+```
+
+Keep the server process running. In a second persistent process, **before showing
+the URL returned by serve**:
+
+```sh
+npx --yes grilling-workbench@0.2.0 wait --session .workbench/topic-r01
+```
+
+Keep the agent turn waiting on that process. The listener blocks on TCP and exits
+with the complete immutable submission. Read it in the current chat, then run
+`ack SUBMISSION_ID --session .workbench/topic-r01` and continue the conversation.
+No extra user click or paste is needed. The socket alone cannot start a turn in an
+idle host chat; an active tool wait is required.
+
+Read the complete [agent protocol](skills/grilling-workbench/references/agent-protocol.md)
+and [question format](skills/grilling-workbench/references/questions.md) before
+using the tool. One directory belongs to one chat round. New rounds use new
+directories; reconnects use the original exact directory.
+
+## Answering a form
+
+Navigate between questions using the sidebar, or the question picker on narrow
+screens. The footer keeps navigation and submission actions visible. Each question
+shows its full wording, options, benefits, and trade-offs. Recommendations are
+labels; every question starts unanswered.
+
+Choices and notes save as drafts while you work. Drafts survive navigation,
+reloads, and question updates. If a question's meaning changes, the app retains
+your earlier answer and asks you to revisit the new wording. Save failures offer
+retry and recovery options.
+
+**Submit form** sends the entire round in one click, including edits still being
+saved. Questions left blank are reported as `not_answered`. Each submission keeps
+the exact question versions and answers; retries reuse its identity to prevent
+duplicates. Drafts become submitted outcomes only when you click Submit.
+
+After saving, the server delivers the submission to the waiting agent over a
+socket. Unacknowledged forms replay after a reconnect, and the page shows when the
+agent records receipt. The interview skill interprets answers and maintains the
+project's decision records.
+
+Use chat or native browser annotations to discuss questions and options. The
+agent can explain or revise them while your draft remains in the form.
+
+## Development and evidence
+
+`npm run dev` starts the reading-room demo at
+[localhost:4310](http://127.0.0.1:4310/), using `data/questions.json` and
+`.workbench/session.json`. Use separate CLI sessions for your interviews.
+
+To develop from a source checkout:
+
+```sh
+npm ci
+npm run check
+npm test
+npm run test:package
+```
+
+The pure state model has generated action-history tests plus HTTP, persistence,
+socket, and runtime integration tests. The package smoke test installs the actual
+archive offline and through `npx` in unrelated directories and exercises the executable,
+skill installation, concurrent isolated sessions, full submission, receipt,
+definition updates, and restart. CI runs those commands for Node 22 and 24.
+
+The [validation note](docs/validation.md) records the automated and browser
+checks, the delivery guarantees they establish, and the remaining validation gaps.

package/bin/grilling-workbench.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+try { await main(); }
+catch (error) { console.error(error.message); process.exitCode = 1; }

package/data/questions.json

@@ -0,0 +1,44 @@
+{
+  "id": "reading-room-demo",
+  "title": "A neighborhood reading room",
+  "description": "A sample interview about a shared space for books, conversation, and quiet time. These are demonstration answers, not project decisions.",
+  "navigationLabels": {
+    "atmosphere": "Atmosphere",
+    "activities": "Activities",
+    "success": "Success"
+  },
+  "questions": [
+    {
+      "id": "atmosphere",
+      "revision": 1,
+      "title": "What should the room feel like on an ordinary afternoon?",
+      "context": "Imagine someone walking in with an hour to spare. Choose the experience we should design around first.",
+      "type": "single",
+      "options": [
+        { "id": "quiet", "label": "A quiet place to settle in", "description": "Comfortable seats, individual reading spots, and a shared expectation of quiet. People can be together without needing to join in.", "benefit": "A dependable retreat for reading and focused work.", "tradeoff": "Spontaneous conversations need a separate space or time.", "recommended": true },
+        { "id": "social", "label": "A place to meet over books", "description": "A large shared table and an easygoing atmosphere where conversations are welcome. Reading becomes a way to get to know neighbors.", "benefit": "Makes it easier for newcomers to connect with people.", "tradeoff": "Noise and interruptions can make longer reading sessions difficult." },
+        { "id": "mixed", "label": "A little of both, in separate zones", "description": "A quiet reading area alongside a smaller conversation area, with furniture and signs making the difference clear.", "benefit": "Accommodates different moods and reasons for visiting.", "tradeoff": "Needs more space and careful attention to sound carrying between zones." }
+      ]
+    },
+    {
+      "id": "activities",
+      "revision": 1,
+      "title": "Which activities belong in the first month?",
+      "context": "Select any activities worth trying. We can start with a small program and learn from who turns up.",
+      "type": "multiple",
+      "options": [
+        { "id": "open-reading", "label": "Open reading afternoons", "description": "Regular drop-in hours with no program or booking. Visitors bring a book or browse the shelves.", "benefit": "Easy to run and welcoming to people with different schedules.", "tradeoff": "People may need another reason to make their first visit.", "recommended": true },
+        { "id": "book-circle", "label": "A monthly book circle", "description": "One book, a small group, and a hosted discussion. Announce the book early so people have time to read.", "benefit": "Gives returning visitors a shared interest and a familiar rhythm.", "tradeoff": "Reading the book in advance asks for a bigger commitment." },
+        { "id": "skill-swap", "label": "Neighbor-led skill sharing", "description": "Short informal sessions such as mending, drawing, or writing, led by people from the neighborhood.", "benefit": "Brings in people who might not join a reading group.", "tradeoff": "Requires finding hosts, preparing materials, and rearranging the room." }
+      ]
+    },
+    {
+      "id": "success",
+      "revision": 1,
+      "title": "After three months, what would make this feel worthwhile?",
+      "context": "Describe one or two things you would hope to notice. A small, specific sign is more useful than a perfect target.",
+      "type": "text",
+      "options": []
+    }
+  ]
+}

package/docs/agent-monitor.md

@@ -0,0 +1,48 @@
+# Agent submission delivery
+
+The canonical operating instructions ship with the installable skill:
+[agent protocol](../skills/grilling-workbench/references/agent-protocol.md).
+Read that protocol before presenting a form. It covers preparation, the active
+socket wait, receipt, continuation, definition updates, and recovery.
+
+## Transport contract
+
+CLI servers expose HTTP and TCP only on loopback. `serve --session DIR` writes a
+private `runtime.json` descriptor with protocol version 1, actual ports, process
+identity, and a random per-run token. `wait --session DIR` reads that descriptor
+and connects to the matching socket. Applications should use the CLI rather than
+reimplement the transport.
+
+For transport implementers, messages are UTF-8 newline-delimited JSON. The client
+first sends `{ "type": "subscribe", "protocolVersion": 1, "token": "..." }`.
+Authentication must complete within five seconds and 4096 characters. The server
+attaches a live listener before replaying saved unacknowledged submissions, with
+per-connection ID deduplication, then sends `{ "type": "ready" }`. A replayed or
+live submission may precede ready. Errors use `{ "type": "error", "error": "..." }`
+and close the connection.
+
+After a whole-form snapshot has been written, the server sends
+`{ "type": "submission", "submission": {...} }`. Draft edits never emit that
+event. The snapshot contains `scope: "form"`, its ID/time, questionnaire identity,
+title/description, and every exact question version, answer, and outcome. The CLI
+returns the first event and closes its socket; it never records receipt itself.
+
+`ack ID --session DIR` records receipt after the agent reads the snapshot.
+Acknowledgment is durable and idempotent; concurrent writers are excluded by a
+lock. Reconnect replays unacknowledged submissions. There is no server polling,
+heartbeat automation, or clipboard handoff.
+
+## What delivery proves
+
+A socket event proves the server saved the whole form. A receipt proves the agent
+read that snapshot into its context. Neither proves that later reasoning finished,
+a decision ticket closed, or a chat reply was rendered. Delivery is at least once
+until receipt; downstream work must account for its submission ID.
+
+The receiving agent must keep an active tool call waiting on the listener process.
+No verified idle-chat event bridge is included. The browser correctly shows
+waiting until receipt, including if the agent was interrupted. Installing the
+skill does not create a host capability that is absent.
+
+The [validation note](validation.md) records the checks for active delivery,
+replay, receipts, and restart, along with the limits of that evidence.

package/docs/deployment.md

@@ -0,0 +1,186 @@
+# Local deployment
+
+Version 0.2.0 ships on public npm with a CLI, static browser files,
+a demo questionnaire, operational docs, and the integration skill. It needs Node
+22+ and no production dependencies or build service. Linux with Node 22.22.2 was
+verified locally. CI is configured for Node 22 and 24 on Linux; other operating
+systems have not been release-tested.
+
+## Distribution and installation
+
+Run this from any project, including a non-Node project:
+
+```sh
+npx --yes grilling-workbench@0.2.0 install-skill
+npx --yes grilling-workbench@0.2.0 --version
+```
+
+npm fetches the application into its execution cache. Only the installed skill
+and the sessions you create live in the consuming project; no project dependency
+or global installation is required. Keep `@0.2.0` on every command so the skill,
+server, and listener use the same release. npm needs registry access on first use;
+use an explicit archive installation when reliable offline availability matters.
+
+Source and releases are maintained at
+[PavingLayer/grilling-workbench](https://github.com/PavingLayer/grilling-workbench).
+The public npm package is
+[grilling-workbench](https://www.npmjs.com/package/grilling-workbench).
+
+If you prefer a project dependency:
+
+```sh
+npm install --save-dev --save-exact grilling-workbench@0.2.0
+npx --no grilling-workbench install-skill
+```
+
+Or explicitly install the executable globally:
+
+```sh
+npm install --global grilling-workbench@0.2.0
+grilling-workbench --version
+```
+
+Run the setup command from each project that should discover it.
+The default target is `.agents/skills/grilling-workbench`. `--target DIR` supports
+another host's skill directory. This command copies the bundled skill; it does
+not edit AGENTS.md, install upstream skills, or overwrite existing skills.
+
+### Offline archives and maintainer releases
+
+From a clean source checkout:
+
+```sh
+npm ci
+npm run check
+npm test
+npm run test:package
+mkdir -p dist
+npm pack --pack-destination dist
+```
+
+The result is `dist/grilling-workbench-0.2.0.tgz`. The explicit package allowlist
+excludes sessions, receipts, development dependencies, and tests. The package
+tests exercise both an offline project installation and `npx` execution from an
+isolated cache, including full form delivery, updates, shutdown, and restart.
+Building the archive does not publish it.
+
+Offline consumers can install the archive as a project dependency or globally:
+
+```sh
+npm install --offline --save-dev /absolute/path/grilling-workbench-0.2.0.tgz
+npx --no grilling-workbench install-skill
+```
+
+Configure the agent to use that installed executable at the matching version;
+the bundled skill defaults to the version-pinned `npx` registry command.
+
+Maintainers publish the checked archive to npm and attach the same file to its
+GitHub release. After the source commit is pushed and GitHub checks pass:
+
+```sh
+npm publish ./dist/grilling-workbench-0.2.0.tgz --access public
+```
+
+Publication requires an authenticated npm account with publishing access. For
+later releases, increment the package version and update the pinned commands in
+the docs and bundled skill before running these checks. Never overwrite a
+published version or run mixed versions within a round.
+
+## Session lifecycle
+
+Every CLI operation except validation and skill installation requires an explicit
+`--session DIR`. Relative paths resolve from the current working directory. Use
+an absolute path when resuming from another directory. `init` refuses any existing
+directory, so it cannot reset a previous form accidentally.
+
+```sh
+npx --yes grilling-workbench@0.2.0 init --session .workbench/topic-r01 --questions /absolute/path/round.json
+npx --yes grilling-workbench@0.2.0 serve --session .workbench/topic-r01
+```
+
+Both servers bind exclusively to `127.0.0.1`. By default the OS assigns free HTTP
+and TCP ports; use the URL returned by `serve`, not guessed port numbers. Explicit
+`--port 4310 --signal-port 4311` is available when stable ports are useful. Invalid
+ports and collisions fail with a nonzero exit code. Readiness follows validation,
+initial storage, and successful binding of both listeners.
+
+`serve` remains in the foreground. The agent should retain its process handle and
+start `wait` in another persistent process. Ctrl+C or SIGTERM shuts down the
+server, waits for queued state operations, disconnects listeners, and removes
+runtime metadata and its lock. The questions, answers, and receipts remain.
+
+`status --session DIR` makes one health request and checks the runtime identity;
+`pending --session DIR` reads saved unacknowledged submissions once. Neither is a
+scheduled monitor. Follow the [agent protocol](../skills/grilling-workbench/references/agent-protocol.md)
+for socket waits, exact-ID receipts, and interrupted conversations.
+
+## Stored files and ownership
+
+| File inside the session | Purpose |
+| --- | --- |
+| `config.json` | Versioned session configuration. |
+| `questions.json` | Session-owned definitions copied by init; use update to replace atomically. |
+| `session.json` | Versioned state, drafts, request deduplication, and immutable submissions. |
+| `chat-receipts.json` | Submission IDs read by the agent and receipt times. |
+| `runtime.json` | Ephemeral process identity, ports, and random socket credential. |
+| `server.lock` | Exclusive server ownership; PID and start time for recovery. |
+| `receipt.lock` | Short-lived acknowledgment writer ownership. |
+| `.gitignore` | Keeps runtime content out of ordinary Git additions. |
+
+Files are written with mode 0600 and newly created session directories with 0700
+on systems honoring POSIX permissions. Existing parent permissions are not changed.
+Keep sessions on a local disk; network filesystems and multiple machines sharing
+one session are unsupported. One server owns a session. Concurrent acknowledgment
+writers fail instead of losing another writer's receipt; retry sequentially.
+
+The browser serves a fixed file allowlist, rejects unrelated Host/Origin headers,
+and escapes question text. The TCP subscriber supplies a per-run random token
+read from the session descriptor; a stale or wrong session is rejected. No token
+is printed in normal CLI output or sent to the browser. This is a single-user
+local tool, not a multi-tenant service: other trusted processes on the same
+computer can access its local HTTP API. Do not expose either port through a public
+proxy. There is no remote authentication or TLS deployment mode.
+
+## Update and recovery
+
+Use `update --session DIR --questions FILE` to validate and atomically replace the
+current definitions. Keep the form ID. The browser checks ordinary definition and
+receipt refreshes every 2.5 seconds while local saves are settled; **agent completion
+uses TCP events, not this refresh interval**. The [question format](../skills/grilling-workbench/references/questions.md)
+describes changed-answer handling and size limits.
+
+For package upgrades, stop the server, back up its session directory, select the
+new exact package version, compare its bundled skill with the installed copy, and
+restart `serve` at that version against the same directory. Update a local or
+global installation explicitly if you use one. To inspect a skill upgrade without overwriting
+customizations, use `install-skill --target /path/to/new-empty-directory` and merge
+changes deliberately. State schema 1 is retained in 0.2.0; unsupported state
+versions and corrupt files fail without resetting answers.
+
+Back up `config.json`, `questions.json`, `session.json`, and `chat-receipts.json`
+with the server and receipt writer stopped. Restore those files into a private
+session directory, then start serve. Do not restore `runtime.json` or lock files;
+those describe processes, not answers. Atomic replacement and file synchronization
+protect against interrupted writes; backups remain necessary for device loss or
+filesystem failure. Power-loss durability across every filesystem is not guaranteed.
+
+A forced kill can leave a lock. Read its PID/start time and verify that its owner
+has exited using the operating system's process inspection. Only then remove
+that specific stale lock (and stale runtime descriptor for a server lock) and
+restart/retry. Never remove a live owner's lock. The program deliberately does not
+steal locks based only on age or a potentially reused PID. If ownership cannot be
+established, keep the files and resolve it before restarting.
+
+A failed browser save leaves unsaved work in the open tab, with retry and recovery
+export. Closing the tab loses memory that never reached storage. A failed receipt
+keeps the submission available for replay. A crash after receipt can leave
+unfinished downstream work; the immutable submission and chat/handoff record
+support recovery, but exactly-once replies are not guaranteed.
+
+## Source checkout demo
+
+`npm run dev` serves the demo from `data/questions.json` and saves its answers in
+`.workbench/session.json`. `PORT` and `SIGNAL_PORT` override its defaults 4310 and
+4311 independently. The source-checkout helper `node src/monitor.js wait` reads
+the demo's runtime descriptor; `pending` and `ack ID` use the same demo directory.
+Use the CLI's initialized sessions for project interviews.

package/docs/integration.md

@@ -0,0 +1,145 @@
+# Use the workbench with your interview skills
+
+The workbench lets you answer interview rounds in a browser while reasoning and
+follow-up stay in the same chat. Once installed, it should be selected whenever
+the agent interviews you. You can simply say “grill me” or invoke your usual
+interview skill; you do not need to request a browser form.
+
+## Set up the project once
+
+You need Node.js 22 or later, and an agent that can open a browser and keep a local
+command running while waiting for your answers. The browser, workbench server,
+and agent must run on the same computer.
+
+From the project where you want to use it:
+
+```sh
+npx --yes grilling-workbench@0.2.0 install-skill
+```
+
+This fetches the application into npm's cache and installs the instructions that
+teach the agent when and how to use it. It creates `.agents/skills/grilling-workbench`
+and preserves any existing skill at that path. No `package.json`, project
+dependency, or global installation is required, including in non-Node projects.
+The skill uses the same pinned package version for subsequent commands.
+
+For offline installation, source development, or upgrades, use the
+[deployment guide](deployment.md). Keep your existing interview skills installed;
+Matt Pocock's repository has its own [installation instructions](https://github.com/mattpocock/skills).
+
+## Start your usual interview
+
+For example, invoke `grill-me` or say:
+
+> Grill me about the checkout design.
+
+The expected flow is:
+
+1. The interview skill chooses the next round of questions.
+2. The agent starts a workbench session, connects its submission listener, and
+   opens the form in the browser.
+3. You answer, revisit questions as needed, and click **Submit form** once.
+4. The agent receives the complete submitted round and continues the same chat.
+
+There is no separate review step or manual copy/paste. You may leave a question
+blank: submission reports that as `not_answered`, so the agent knows you chose
+not to answer it. That does not settle the underlying decision.
+
+For explanations or changes to a question, use chat or the browser's native
+Annotate/Quick Annotate features. The agent can revise the form while preserving
+your draft. The app itself only handles answering and submitting questions.
+
+The agent must remain actively waiting on the listener to continue immediately.
+This package does not start new turns in an idle chat. Agents should read the
+[operating protocol](../skills/grilling-workbench/references/agent-protocol.md)
+before presenting questions; it covers the listener, receipts, and interruptions.
+The [question format](../skills/grilling-workbench/references/questions.md) is the
+reference for authoring or updating a round.
+
+## How it fits the existing workflow
+
+The workbench handles question presentation and answer delivery. Your chosen skill
+still decides what to ask, interprets the answers, updates project records, and
+determines when the interview is complete.
+
+| Workflow | How to combine it with the workbench |
+| --- | --- |
+| [`grilling`](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/productivity/grilling/SKILL.md) / `grill-me` | Use one form for the current round of independent questions. Questions that depend on unresolved answers belong in a later round. |
+| [`grill-with-docs`](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/grill-with-docs/SKILL.md) | Use the same form interface while the existing interview and domain-modeling skills maintain the project documents. |
+| [`wayfinder`](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/wayfinder/SKILL.md) | Use forms during interviews about the current decision ticket. Keep the map, ticket ownership, dependencies, and resolution records in Wayfinder. |
+| [`setup-matt-pocock-skills`](https://github.com/mattpocock/skills/blob/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/setup-matt-pocock-skills/SKILL.md) | Keep the tracker and domain-document configuration it establishes. Installing the workbench does not replace that configuration or invoke setup. |
+
+A submitted form supplies answers; it does not automatically close tickets or
+approve further work. Keep canonical decisions in the configured documents or
+tracker, using submission and question IDs for attribution. Raw session files
+remain private by default.
+
+These integration recommendations were reviewed against upstream revision
+`3cca18b368ae95cdbdebbff572ccafa662551015` on September 5, 2026. Check the actual
+installed skills when upgrading; there is no need to patch their bodies to use
+the workbench.
+
+## If the agent does not use the workbench
+
+First check whether `grilling-workbench` appears in the agent's available skills.
+In Codex, that list combines applicable project skills, user skills, administrator
+and system skills, and enabled plugin skills. It does not automatically include
+local skills from unrelated projects. Our installer adds the workbench at the
+current project's `.agents/skills/grilling-workbench` path.
+
+Codex normally detects new skills automatically. If it is missing, restart Codex
+and check the installed path. If it appears more than once, inspect the source
+paths for duplicate user/project installations. [Codex skill discovery](https://learn.chatgpt.com/docs/build-skills#where-codex-loads-local-skills)
+
+If the skill is listed but not selected during an interview, explicitly invoke
+`$grilling-workbench` once to check that it can run. This is a troubleshooting step,
+not the expected everyday workflow. Automatic selection depends on the agent
+matching the interview to the skill description; it is not an application hook.
+[How Codex selects skills](https://learn.chatgpt.com/docs/build-skills#how-chatgpt-and-codex-use-skills)
+
+A short project instruction can reinforce the trigger. Merge this into the
+project's existing AGENTS.md or equivalent instruction file, preserving its other
+rules. It is optional; the skill already defines the interview trigger.
+
+```markdown
+Whenever interviewing the user, use the grilling-workbench skill at
+`.agents/skills/grilling-workbench/SKILL.md`. Apply it alongside the current
+interview workflow, including grill-me, without requiring a request for a browser
+form. The command is `npx --yes grilling-workbench@0.2.0`.
+
+Read the skill's operating protocol before presenting questions. Keep reasoning,
+clarification, and decision records in the existing workflow. Respect an explicit
+user request for another interface.
+```
+
+The installer does not edit project instructions automatically. Adjust the command
+in the snippet if you explicitly configure a local or global installation.
+
+## Check answer delivery in your agent
+
+Try a throwaway two-question round. Answer one question, leave the other blank,
+and submit. The agent should receive both outcomes and continue without another
+chat message. Its listener should already be waiting before the form opens.
+
+If the page stays on “Waiting for the agent,” inspect the listener process and
+follow the [reconnection and receipt instructions](../skills/grilling-workbench/references/agent-protocol.md#definitions-and-interruptions).
+Do not replace the listener with repeated status checks or ask the user to paste
+answers. If the agent application cannot maintain an active tool wait, that
+integration needs support before immediate continuation can work.
+
+The package tests verify installation, socket delivery, receipts, and recovery.
+Automatic skill selection in a fresh agent installation still needs this real
+workflow check. Test ordinary interview requests without mentioning the browser;
+explanations about an existing option should continue in chat.
+
+## Share it with another project
+
+Share [PavingLayer/grilling-workbench](https://github.com/PavingLayer/grilling-workbench)
+and repeat the one-command setup above. npm includes the matching application and
+skill; browser and command-execution tools must be supplied by the agent host.
+
+The repository also exposes `skills/grilling-workbench/SKILL.md` in a layout
+recognized by the [Skills CLI](https://github.com/vercel-labs/skills#skill-discovery).
+The npm `install-skill` command is the primary setup path because it bundles the
+skill with the same exact application release. Offline users can instead share
+the release archive; see [distribution and installation](deployment.md#distribution-and-installation).

package/docs/validation.md

@@ -0,0 +1,85 @@
+# Validation and known limits
+
+This records what has been checked for the implemented workbench. For normal use,
+start with the [integration guide](integration.md); for installation and recovery,
+use the [deployment guide](deployment.md).
+
+## Automated checks
+
+The 0.2.0 release checks passed locally on Linux with Node.js 22.22.2 on September
+6, 2026 (UTC): syntax validation, 18 automated tests, and both installed-package
+and `npx` smoke tests. CI runs the same checks on Node 22 and 24; see
+[GitHub Actions](https://github.com/PavingLayer/grilling-workbench/actions/workflows/verify.yml)
+for the hosted results associated with a release commit.
+
+The automated tests cover:
+
+- Unanswered defaults, recommendation labels, and 1,000 generated action histories
+  checked against an independent model. The default seed is `20260905`;
+  `FC_SEED` and `FC_PATH` reproduce other generated cases.
+- Complete immutable submission snapshots, including submitted blanks; rejection
+  of partial forms and stale snapshots; and idempotent retries.
+- Draft preservation through definition changes, conflicts, failed writes, and
+  restart. Corrupt saved data is retained rather than reset.
+- Socket completion only after persistence. Tests deliberately hold the storage
+  write open, then check delivery, reconnect replay, and receipt failure recovery.
+- Session ownership, listener credentials, startup failure cleanup, port reuse,
+  and rejection of unrelated web origins and private-file requests.
+
+The package smoke test packs the actual release and exercises it twice: installed
+offline in an unrelated project, and through `npx` from an isolated cache in a
+project without package files or dependencies. Both modes verify skill
+installation without overwriting an existing copy, two isolated sessions, served
+browser assets, whole-form delivery, acknowledgments, definition updates, restart,
+and the source-checkout demo entrypoint. The `npx` test uses the local archive,
+so registry publication and a fresh registry download are separate release checks.
+
+## Embedded-browser checks
+
+The implemented interface has been checked in the embedded browser for:
+
+- A 20-question form at 808×1139, with independently scrolling navigation and
+  question content, a visible footer, and no horizontal overflow.
+- Narrow layouts at 390×844 and 320×740, with the question picker, footer actions,
+  draft persistence after reload, and submission history available.
+- Direct submission while draft saves are deliberately delayed. Submit remains
+  enabled while typing and sends the latest text without a review step.
+- Submission containing one answer and two blanks, received over TCP with both
+  `not_answered` outcomes. Recording receipt updates the page's delivery status.
+- Definition refresh, preserved draft text, recoverable save failures, and restart.
+
+Native browser annotations were received in chat during UI iteration. After the
+0.2.0 runtime upgrade, the existing preview still displayed the user's submitted
+answers; its saved state and receipt files matched their pre-upgrade backups.
+
+## Limits of this evidence
+
+An actively waiting listener receives submissions immediately. The package does
+not provide an idle-chat wakeup bridge. One user submission was captured over TCP
+while the agent was idle, then read only after another chat message; that is not
+evidence of automatic continuation in an idle chat.
+
+The skill now directs agents to use the workbench for all interviews. Metadata
+validation checks its structure; it does not prove that every model will select
+it correctly. Automatic discovery and continuation in a fresh agent installation
+still need the [target-agent checks](integration.md#check-answer-delivery-in-your-agent).
+
+Screen-reader testing and a dedicated option-targeted annotation/clarification
+round trip remain outstanding. Other operating systems, network filesystems,
+device loss, and power-loss durability have not been release-tested. Exactly-once
+chat replies across crashes are not guaranteed; the agent protocol documents
+receipt and downstream-work recovery separately.
+
+## Run the checks
+
+From the source repository:
+
+```sh
+npm ci
+npm run check
+npm test
+npm run test:package
+```
+
+Integration tests require permission to bind local HTTP and TCP sockets. Browser
+and target-agent checks are separate from these automated commands.