@popmelt.com/core 0.21.1 → 0.22.0

package/README.md

@@ -4,7 +4,7 @@
 
 # Popmelt
 
-Popmelt is a tiny, powerful design layer for humans and AI. Turn any React repo into a design sandbox with the AI tools you already love.
+Popmelt is a tiny, powerful design layer for humans and AI. Turn your local web app into a design sandbox with the AI tools you already love.
 
 Run your app locally and Popmelt appears as a toolbar in the browser. Point to any part of your UI, describe what you have in mind, or steer the design directly. Work through the result with Codex or Claude Code in a thread right on the page. Stack as many threads as you want so different ideas can move forward without losing their context.
 
@@ -14,9 +14,9 @@ Runs locally, learns naturally. Your annotations, screenshots, threads, and Impr
 
 ## What you need
 
-- A local React project
-- Node.js 18 or newer
-- React 18 or newer
+- A local web project: React is the established integration; vanilla HTML/JS with Vite, Vue, Nuxt, Svelte/SvelteKit, and Astro have experimental DOM integrations
+- Node.js 18 or newer, or a newer version required by your framework
+- React 18 or newer for a React host; non-React integrations still require the renderer peers listed in their setup instructions
 - The Codex CLI or Claude Code CLI installed, available in your terminal, and signed in
 
 The Codex and Claude Code desktop apps work too. Open your local app in their built-in browser and use Popmelt there just as you would in any other browser. The corresponding CLI still needs to be installed and signed in because it runs the threads.
@@ -27,7 +27,11 @@ From inside your project, give your coding agent this prompt:
 
 > Let's install `@popmelt.com/core` in this project
 
-Your agent can detect the framework, add the provider and integration, and preserve your existing development command. Restart the development server when it is finished.
+Your agent can detect the framework, add the matching integration, and preserve your existing development command. Restart the development server when it is finished.
+
+For the installing agent: finish with the [installation checks](#verify-the-installation), including the applicable ambient integration below. Report what is verified and any remaining step; adding dependencies alone is not a ready-to-use installation.
+
+For manual instructions, see [Manual setup](#manual-setup). Experimental non-React integrations support DOM annotations and style edits, but do not provide React-specific component hierarchy or library previews.
 
 To add local object recognition to an existing Popmelt project, use:
 
@@ -36,168 +40,16 @@ To add local object recognition to an existing Popmelt project, use:
 The integration installs See and adds it to the existing Core provider's
 `extensions` array without replacing Core.
 
-### Experimental standalone browser entry
-
-The first framework-independent integration is available at `@popmelt.com/core/browser`.
-It mounts Popmelt beside the host application, without JSX or a React provider in
-your application code. React still renders Popmelt internally; the package's
-existing React, React DOM, and Lucide React peer dependencies are still required.
-This is an experimental DOM integration, not a claim of Vue/Svelte/Angular feature
-parity. React-specific component hierarchy and library previews are not supplied
-for other frameworks yet.
+## Try your first change
 
-For a Vite host, keep the existing `@popmelt.com/core/vite` bridge plugin, then use
-this in your browser entry:
+Pick one thing in your own app that you already want to improve:
 
-```js
-if (import.meta.env.DEV) {
-  const { mountPopmelt } = await import('@popmelt.com/core/browser');
-  const popmelt = await mountPopmelt({ enabled: true });
-  import.meta.hot?.dispose(() => popmelt.unmount());
-}
-```
-
-Enablement is explicit: omitted/false `enabled` or a server-side call is a no-op
-and does not load the renderer. `unmount()` removes the UI and releases its
-subscriptions without deleting saved annotations or cancelling bridge jobs.
-Call it before mounting again; simultaneous integrations on one page are rejected.
-Use either this entry or `PopmeltProvider`, not both. Pass `bridgeUrl`, `projectId`,
-or a host-router `navigate` callback when these are not supplied by your integration.
-Explicit bridge/project options take effect before startup and restore prior
-host bindings when unmounted; no manual browser-global assignment is needed.
-
-For Vue, mount your app normally and mount Popmelt alongside it, not inside the
-Vue component tree. Keep your Vue Vite plugin and add `popmelt()` to that same
-plugin list. Connect the returned `unmount()` to your app's teardown (for example,
-`app.onUnmount(() => popmelt.unmount())` in Vue 3.5+). With Vue Router, pass
-`navigate: (url) => router.push(url)`; no router dependency is required by Core.
+1. Open your local app and double-tap Command on macOS or Control on Windows/Linux to open Popmelt.
+2. Choose Chat (`C`), click the element, and describe a concrete change—for example, “Give this card more breathing room without changing the text size.”
+3. Press Command/Control+Enter to send it, then review the result on the page.
+4. Refine it in the same thread: “A little less padding, and keep the button aligned with the text.”
 
-The plain HTML/JS fixture at `e2e/fixtures/browser` and Vue fixture at
-`e2e/fixtures/vue` share a browser workflow: author and recover an annotation
-draft through target replacement and page reload, submit it, receive streamed
-and final replies, and continue the same thread after another target replacement.
-Both verify durable thread history, stage a Steer edit, select Chat through the
-toolbar, and recover the exact edited style and completed thread after reload.
-Vanilla replacement creates a fresh DOM node without copying Popmelt attributes
-or inline styles; Vue uses keyed rerenders. Both verify teardown/remount releases
-Popmelt's UI and connection while preserving the host DOM and input state.
-
-Vue additionally exercises real Vite SFC template/script hot updates and Vue
-Router navigation/back. Hot updates must retain the same Popmelt renderer and
-bridge connection, without a full-page reload. The tests edit temporary fixture
-copies, not repository files.
-Only the external provider process is controlled; HTTP, SSE, queue dispatch, and
-durable thread storage use the real bridge. It does not run your installed agent.
-Run both fixtures after building:
-
-```sh
-pnpm run build
-pnpm exec vitest run --config vitest.browser.config.ts e2e/browser-mount.browser.ts
-```
-
-For a fresh tarball installation with the real Vite bridge plugin, run
-`pnpm run vue:smoke`. This opt-in check needs npm registry access and Chrome
-(`CHROME_PATH` can override its location). It installs into a temporary Vue app,
-verifies bridge startup/shutdown and the toolbar, and checks that the
-development-only import is absent from production output. It does not publish
-or replace the separate package-size release gate.
-
-The plain HTML/JS fixture still uses Vite and installed npm peers; this does not
-validate a bundler-free script tag or arbitrary static-server integration.
-The journeys use stable target IDs and Chrome, not a cross-browser or arbitrary
-DOM-identity matrix. They validate the client-side DOM boundary, not Vue component
-metadata. Router guards, nested routes, and hash-history mode are
-not yet covered. Vue and its test tooling are development dependencies only;
-they do not add a second Popmelt UI implementation or become runtime dependencies.
-
-### Experimental Nuxt integration
-
-For Nuxt 4.5.2, install Popmelt and its internal renderer peers as development
-dependencies, then add the module:
-
-```sh
-npm install -D @popmelt.com/core react react-dom lucide-react
-```
-
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: ['@popmelt.com/core/nuxt'],
-});
-```
-
-No separate Vite plugin, React provider, or manual browser mount is needed.
-The module starts the local bridge in development and mounts Popmelt after Nuxt
-has mounted the client app. It uses Nuxt's router for navigation and releases
-its bridge lease on graceful shutdown. When Nuxt's CLI exits immediately, the
-existing lease-expiry cleanup stops an idle bridge within about a minute.
-Production builds do not register the client
-plugin or start the bridge. Optional `popmelt` settings are `port`, `projectRoot`,
-and `bridge` (set `bridge: false` to disable automatic bridge startup).
-
-Run `pnpm run nuxt:smoke` with a Nuxt-compatible Node version (22.19+, 24.11+,
-or 26+) to check a fresh tarball installation. It requires npm registry access
-and Chrome, like the Vue smoke check. The isolated fixture checks SSR/hydration,
-thread recovery through navigation/back and template/script HMR, and production
-exclusion. It also exercises annotation submission, streaming replies, same-thread
-follow-ups, and staged style recovery through routing and reload. Provider responses
-are controlled in that journey; it never launches your coding agent.
-Nuxt 3, component metadata, and advanced router configurations are not yet tested.
-
-### Experimental Svelte and SvelteKit
-
-Tested with Svelte 5.57.0, SvelteKit 2.70.3, and Vite 8.2.2. Install the same
-development dependencies used by the standalone entry:
-
-```sh
-npm install -D @popmelt.com/core react react-dom lucide-react
-```
-
-Keep your existing Vite configuration and add `popmelt()` alongside `sveltekit()`
-(or `svelte()` for a plain Svelte app):
-
-```js
-import { sveltekit } from '@sveltejs/kit/vite';
-import { popmelt } from '@popmelt.com/core/vite';
-
-export default { plugins: [sveltekit(), popmelt()] };
-```
-
-Mount once in your root `+layout.svelte`, without replacing its existing content:
-
-```svelte
-<script>
-  import { onMount } from 'svelte';
-  import { goto } from '$app/navigation';
-  import { bridgeUrl, projectId } from 'virtual:popmelt/bridge';
-
-  onMount(() => {
-    if (!import.meta.env.DEV || !bridgeUrl || !projectId) return;
-    let disposed = false;
-    const pending = import('@popmelt.com/core/browser').then(({ mountPopmelt }) => {
-      if (!disposed) return mountPopmelt({ enabled: true, bridgeUrl, projectId, navigate: goto });
-    });
-    void pending.catch(console.error);
-    return () => {
-      disposed = true;
-      void pending.then((handle) => handle?.unmount()).catch(() => {});
-    };
-  });
-</script>
-```
-
-For plain Svelte, place this in `App.svelte` and omit the `goto` import and
-`navigate` option, or supply your own router callback. TypeScript projects can
-add `/// <reference types="@popmelt.com/core/vite/client" />` to their app's
-ambient declarations for the virtual module types.
-
-This setup is development-only, including during SSR. It does not provide
-Svelte component metadata or framework-specific library previews. Advanced
-Kit routing, form actions, and deployment adapters beyond Node are not yet tested.
-Run `pnpm run svelte:smoke` with Node 24.11+, npm registry access, and Chrome
-to check fresh Svelte and SvelteKit installs; it does not launch your coding agent.
-The SvelteKit check also runs the shared annotation/reply/style-edit journey,
-including same-thread continuation and recovery after navigation and reload.
+Questions, ideas, or issues? [Email](mailto:reb@popmelt.com) or [DM on X](https://x.com/bekhovsgun).
 
 ## Use Popmelt
 
@@ -273,16 +125,70 @@ Archiving hides a thread from the active canvas without deleting its stored conv
 
 ## Ambient Popmelt in Codex
 
-Popmelt can also pair ordinary project-bound Codex conversations with the same local project memory. Install the bundled Codex plugin once:
+Popmelt can also pair ordinary project-bound Codex conversations with the same local project memory. On supported Codex desktop or CLI surfaces, include this in setup unless the user wants toolbar-only use or has disabled the integration.
+
+The bundled `popmelt-core` plugin installs the skill, MCP tools, and lifecycle hooks together; do not install separate copies of the skill or hooks. This is a personal installation, not just a project dependency. Explain that the hooks supply project context and record project-bound turns, and obtain any required permission before changing personal configuration. Preserve unrelated plugins, settings, and explicit opt-outs. See [OpenAI's plugin guidance](https://learn.chatgpt.com/docs/plugins) for supported surfaces and hook trust.
+
+From the project, inspect the existing installation first:
+
+```bash
+npx @popmelt.com/core codex status
+```
+
+If missing or needing an update, install the bundled plugin:
 
 ```bash
 npx @popmelt.com/core codex install
 ```
 
-Restart Codex completely, then begin a new conversation in the project. Popmelt will orient the conversation automatically when one store applies. If multiple stores apply, Codex will ask you to choose one writable primary store and any read-only mounted stores; it never infers write authority from directory nesting, recency, or store size.
+Follow the install command's restart instructions after ongoing work finishes, then begin a new Codex conversation in the project. Do not close active sessions automatically. A result of `files_installed` means plugin registration is incomplete; `installed` or `update_ready` still requires the reported restart and new conversation. Popmelt will orient the conversation automatically when one store applies. If multiple stores apply, Codex will ask you to choose one writable primary store and any read-only mounted stores; it never infers write authority from directory nesting, recency, or store size.
+
+After restart, check that the plugin is registered and enabled and that the new session exposes the Popmelt skill, tools, and ambient context. Registration alone does not prove the hooks have loaded. If you cannot inspect the new session, report ambient activation as unverified rather than reinstalling repeatedly.
+
+This installer is Codex-specific. Claude Code toolbar threads do not need it. For ordinary local Claude conversations, see the experimental native plugin below; do not copy Codex hooks into Claude settings.
 
 Ambient capture stays out of toolbar-owned runs, so opening a thread from the in-page toolbar still produces exactly one toolbar job. Popmelt tools remain available for intentional context expansion, decision review, and Imprint grounding.
 
+### Ambient Popmelt in Claude Code (local preview)
+
+The package also includes an experimental native Claude plugin with the Popmelt skill, local MCP tools, and prompt/tool/completion hooks. For local Claude Code, inspect first:
+
+```bash
+npx @popmelt.com/core claude status
+```
+
+With the user's permission for a personal plugin installation, install or update the bundle:
+
+```bash
+npx @popmelt.com/core claude install
+```
+
+The installer registers `popmelt-core@popmelt-local` through Claude's native plugin commands, using a local marketplace under `CLAUDE_CONFIG_DIR` (or `~/.claude`). It preserves disabled plugins, refuses conflicting sources/scopes, and never writes execution permission settings. Partial registration is reported separately from success. After ongoing work finishes, reload plugins or start a new Claude Code session; don't interrupt active work automatically.
+
+Then check the setup without launching an agent request or restarting a bridge:
+
+```bash
+npx @popmelt.com/core claude doctor
+```
+
+`infrastructureReady` covers registration, locally reported sign-in, and the identity/version of an already-running project bridge. `sessionVerified` requires recent prompt-hook, MCP-tool, and completion-hook observations from one session of that installed plugin version. `ok` requires both. Observations expire after 24 hours and do not prove the session is still live or that Claude read the skill. Missing observations are **unverified**, not a reason to reinstall repeatedly. Bridge probes cover the standard 1111–1120 range; verify a custom port separately.
+
+In a multi-store workspace, diagnostics honor the same saved human-selected primary and read-only mounts as ambient sessions. If that choice is missing, invalid, or no longer matches the available stores, orientation remains required; diagnostics never pick a replacement or rewrite the saved choice.
+
+For a one-session trial without changing personal settings, you can instead load the packaged plugin directly:
+
+```bash
+claude --plugin-dir ./node_modules/@popmelt.com/core/claude-plugin
+```
+
+This uses Claude's native [plugin](https://code.claude.com/docs/en/plugins-reference) and [hook](https://code.claude.com/docs/en/hooks) formats. Respect Claude's workspace trust, plugin/MCP consent, and existing permission settings. The plugin adds no permission policy or execution grants.
+
+Check that the session exposes the Popmelt skill and tools and that the next ordinary prompt receives ambient context. Use the exact tool-session ID it supplies. Store orientation, mounted read stores, focus inspection, and Imprint use the same bridge as Codex. Toolbar-owned Claude runs skip ambient capture.
+
+The adapter keeps a private, bounded current-turn journal locally, correlates Claude's hooks, and retries against the same durable turn after bridge recovery. Missing/failed hooks remain unverified; API-error and session-end events are not recorded as successful completions. Concurrent processes using the same native Claude session are not supported in this preview. No transcript copy is read or retained.
+
+Local sessions in Desktop’s Code tab are expected to work through shared configuration. Chat, Cowork, and cloud sessions are outside this preview’s scope. Native plugin validation and isolated lifecycle checks do not prove activation in the user's session. Let the user choose the next real task; do not submit an automatic test annotation or paid request to manufacture readiness. The toolbar works independently.
+
 ### Point and discuss
 
 With your app running and the Popmelt canvas active, point at an element and ask Codex, “What am I pointing at?” You can also ask it to inspect a comment or explain what was discussed in an existing thread, without pointing at that item first.
@@ -300,6 +206,8 @@ npx @popmelt.com/core codex status
 npx @popmelt.com/core codex doctor
 ```
 
+`status` reports plugin registration and project discovery. `doctor` can start the local project bridge and check its health, so run it only for the intended project when starting that service is appropriate. Inspect the plugin fields and any project-selection warning as well as bridge health: a healthy bridge does not prove plugin activation, browser connectivity, or provider authentication.
+
 ## Imprint
 
 As you work, Popmelt recognizes choices that may be useful beyond the current thread and proposes an Imprint update:
@@ -314,7 +222,13 @@ Enter Imprint mode with `I` to inspect the project's current understanding, supp
 
 ## Manual setup
 
-Install Popmelt and its icon peer dependency:
+For React, add the provider below and follow the [Next.js](#nextjs),
+[Vite](#vite), or [other development server](#other-development-servers) instructions.
+For experimental non-React hosts, use the [standalone entry for vanilla HTML/JS or Vue](#experimental-standalone-browser-entry),
+[Nuxt module](#experimental-nuxt-integration), [Svelte/SvelteKit setup](#experimental-svelte-and-sveltekit),
+or [Astro integration](#experimental-astro-integration) instead of adding a React provider.
+
+For a React app, install Popmelt and its icon peer dependency:
 
 ```bash
 npm install @popmelt.com/core lucide-react
@@ -416,6 +330,125 @@ export default defineConfig({
 });
 ```
 
+### Experimental standalone browser entry
+
+The first framework-independent integration is available at `@popmelt.com/core/browser`.
+It mounts Popmelt beside the host application, without JSX or a React provider in
+your application code. React still renders Popmelt internally; the package's
+existing React, React DOM, and Lucide React peer dependencies are still required.
+This is an experimental DOM integration, not a claim of Vue/Svelte/Angular feature
+parity. React-specific component hierarchy and library previews are not supplied
+for other frameworks yet.
+
+For a Vite host, keep the existing `@popmelt.com/core/vite` bridge plugin, then use
+this in your browser entry:
+
+```js
+if (import.meta.env.DEV) {
+  const { mountPopmelt } = await import('@popmelt.com/core/browser');
+  const popmelt = await mountPopmelt({ enabled: true });
+  import.meta.hot?.dispose(() => popmelt.unmount());
+}
+```
+
+Enablement is explicit: omitted/false `enabled` or a server-side call is a no-op
+and does not load the renderer. `unmount()` removes the UI and releases its
+subscriptions without deleting saved annotations or cancelling bridge jobs.
+Call it before mounting again; simultaneous integrations on one page are rejected.
+Use either this entry or `PopmeltProvider`, not both. Pass `bridgeUrl`, `projectId`,
+or a host-router `navigate` callback when these are not supplied by your integration.
+Explicit bridge/project options take effect before startup and restore prior
+host bindings when unmounted; no manual browser-global assignment is needed.
+
+For Vue, mount your app normally and mount Popmelt alongside it, not inside the
+Vue component tree. Keep your Vue Vite plugin and add `popmelt()` to that same
+plugin list. Connect the returned `unmount()` to your app's teardown (for example,
+`app.onUnmount(() => popmelt.unmount())` in Vue 3.5+). With Vue Router, pass
+`navigate: (url) => router.push(url)`; no router dependency is required by Core.
+
+The vanilla HTML/JS integration requires Vite and installed npm peers; a
+bundler-free script tag or arbitrary static-server setup is not covered.
+Vue Router guards, nested routes, and hash-history mode are not yet tested.
+
+### Experimental Nuxt integration
+
+For Nuxt 4.5.2, install Popmelt and its internal renderer peers as development
+dependencies, then add the module:
+
+```sh
+npm install -D @popmelt.com/core react react-dom lucide-react
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@popmelt.com/core/nuxt'],
+});
+```
+
+No separate Vite plugin, React provider, or manual browser mount is needed.
+The module starts the local bridge in development and mounts Popmelt after Nuxt
+has mounted the client app. It uses Nuxt's router for navigation and releases
+its bridge lease on graceful shutdown. When Nuxt's CLI exits immediately, the
+existing lease-expiry cleanup stops an idle bridge within about a minute.
+Production builds do not register the client
+plugin or start the bridge. Optional `popmelt` settings are `port`, `projectRoot`,
+and `bridge` (set `bridge: false` to disable automatic bridge startup).
+
+Use a Nuxt-compatible Node version (22.19+, 24.11+, or 26+).
+Nuxt 3, component metadata, and advanced router configurations are not yet tested.
+
+### Experimental Svelte and SvelteKit
+
+Tested with Svelte 5.57.0, SvelteKit 2.70.3, and Vite 8.2.2. Install the same
+development dependencies used by the standalone entry:
+
+```sh
+npm install -D @popmelt.com/core react react-dom lucide-react
+```
+
+Keep your existing Vite configuration and add `popmelt()` alongside `sveltekit()`
+(or `svelte()` for a plain Svelte app):
+
+```js
+import { sveltekit } from '@sveltejs/kit/vite';
+import { popmelt } from '@popmelt.com/core/vite';
+
+export default { plugins: [sveltekit(), popmelt()] };
+```
+
+Mount once in your root `+layout.svelte`, without replacing its existing content:
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import { goto } from '$app/navigation';
+  import { bridgeUrl, projectId } from 'virtual:popmelt/bridge';
+
+  onMount(() => {
+    if (!import.meta.env.DEV || !bridgeUrl || !projectId) return;
+    let disposed = false;
+    const pending = import('@popmelt.com/core/browser').then(({ mountPopmelt }) => {
+      if (!disposed) return mountPopmelt({ enabled: true, bridgeUrl, projectId, navigate: goto });
+    });
+    void pending.catch(console.error);
+    return () => {
+      disposed = true;
+      void pending.then((handle) => handle?.unmount()).catch(() => {});
+    };
+  });
+</script>
+```
+
+For plain Svelte, place this in `App.svelte` and omit the `goto` import and
+`navigate` option, or supply your own router callback. TypeScript projects can
+add `/// <reference types="@popmelt.com/core/vite/client" />` to their app's
+ambient declarations for the virtual module types.
+
+This setup is development-only, including during SSR. It does not provide
+Svelte component metadata or framework-specific library previews. Advanced
+Kit routing, form actions, and deployment adapters beyond Node are not yet tested.
+
 ### Experimental Astro integration
 
 For Astro 7.3.1, install Popmelt and its internal renderer peers as development
@@ -444,10 +477,8 @@ If your project already mounts a Popmelt provider, use `popmelt({ client: false
 to keep that provider in charge of the UI. The existing `port`, `projectRoot`,
 `basePath`, and `bridge` options remain available.
 
-Run `pnpm run astro:smoke` with Node 24.11+, npm registry access, and Chrome for
-the fresh-install browser journey. Provider responses are controlled; it does not
-launch your coding agent. Astro component metadata, framework-specific island
-previews, and deployment adapters are not yet covered.
+Astro component metadata, framework-specific island previews, and deployment
+adapters are not yet covered.
 
 ### Other development servers
 
@@ -463,20 +494,34 @@ The wrapper can start Popmelt alongside another development command:
 
 ## Verify the installation
 
-Start the app normally:
+For the installing agent, verify the user's actual app, not a separate demo or fixture. Work from the correct application directory and preserve its existing scripts and configuration.
+
+1. **Framework and app:** confirm the installed dependencies and matching provider/mount and framework integration. Explain any relevant experimental-support limit. Start the app using its existing development command, or restart only its own development process when needed and authorized. Do not interrupt active work or other projects.
+2. **Browser:** open the exact local URL reported by the development server. Confirm the app loads and double-tap Command or Control to check that the toolbar appears. If browser access is unavailable, report the integration as configured but browser verification as pending.
+3. **Bridge:** confirm the local bridge belongs to this application and is healthy, then check the toolbar's connection when browser access is available. A service responding on some port is not enough. Use the applicable Codex or Claude diagnostics above with their stated limits; do not treat them as a general end-to-end check.
+4. **Provider:** confirm the selected CLI is available to the bridge process, not only to an unrelated terminal, and check version compatibility and sign-in status using supported, non-generating diagnostics where available. Do not print credentials, change sandbox/approval settings to make checks pass, or submit a paid test prompt. If authentication cannot be checked safely, say so. These checks establish readiness, not successful end-to-end execution; the user's first real request verifies that.
+5. **Ambient integration, when applicable:** follow the bundled Codex setup or experimental local Claude Code setup above, keeping personal installation, registration, and activation in a new session distinct. Preserve disabled integrations and get permission before personal installation. Track a required restart or unavailable surface separately from toolbar readiness; an optional ambient gap should not prevent the user from trying a working toolbar.
+
+To start the app manually, use its existing development command, for example:
 
 ```bash
 npm run dev
 ```
 
-Open the local app in a browser and double-tap Command or Control. The Popmelt toolbar should appear.
+### Finish with a useful handoff
+
+Only describe a check as verified when you observed it. Keep the completion message brief: give the exact local app URL, distinguish configured from verified, and name each remaining gap with its next step. For example, when the relevant checks pass:
+
+> Popmelt is ready at [the app's actual local URL]. Double-tap Command/Control, click something you want changed, and leave a comment.
+
+If ambient setup still needs a restart, say so separately. Let the user choose the first change; do not create a test annotation or launch an agent run merely to validate installation.
 
-If the toolbar opens but cannot reach an AI, check that:
+### If something is not ready
 
-- The selected AI CLI is installed and signed in
-- A Next.js development script includes `popmelt wrap`
-- The framework plugin or config wrapper is installed
-- The development server was restarted after installation
+- **Toolbar missing:** check the provider or browser mount, development-only enablement, framework config, and whether the running app picked up the change. In Next.js, both `withPopmelt` and `popmelt wrap` are required.
+- **Bridge disconnected:** check the intended project's bridge and the toolbar's connection settings. If a process must be restarted, identify that process and check for active work first; do not restart everything.
+- **Provider unavailable:** distinguish a missing executable, incompatible version, missing sign-in, or a bridge environment that differs from the terminal. Give the specific installation, sign-in, or targeted restart step supported by the evidence. A denied diagnostic is unverified, not proof the provider is broken.
+- **Ambient context missing:** inspect `codex status` for registration/enabled state, follow any pending restart, and check a new project-bound session. Resolve project selection with the user when needed; do not infer the project or install duplicate hooks.
 
 ## React Three Fiber
 
@@ -626,7 +671,7 @@ Popmelt is designed for local development. As with any AI-assisted coding, your
 | `I`                              | Enter Imprint mode                                                  |
 | Command/Control+Enter            | Send all pending work                                               |
 | Command/Control+C                | Capture a screenshot for pending work when no text is selected      |
-| Command/Control+Z                | Undo a pending change or thread dismissal                            |
+| Command/Control+Z                | Undo a pending change or thread dismissal                           |
 | Command/Control+Shift+Z          | Redo a pending change                                               |
 | Backspace/Delete                 | Archive the open or selected historical thread                      |
 | Command/Control+Backspace/Delete | Clear all annotations and pending changes                           |

package/claude-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "popmelt-core",
+  "version": "0.22.0",
+  "description": "Local Popmelt context, canvas tools, and ambient turn capture for Claude Code.",
+  "author": {
+    "name": "Popmelt",
+    "email": "reb@popmelt.com"
+  },
+  "homepage": "https://github.com/popmelt/core",
+  "license": "PolyForm-Shield-1.0.0"
+}

package/claude-plugin/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "popmelt-core": {
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/scripts/mcp.mjs"
+      ]
+    }
+  }
+}

package/claude-plugin/hooks/hooks.json

@@ -0,0 +1,60 @@
+{
+  "description": "Ambient Popmelt context and turn capture; no permission hooks.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 12
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 12
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 12
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 12
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 12
+          }
+        ]
+      }
+    ]
+  }
+}

package/claude-plugin/scripts/environment.mjs

@@ -0,0 +1,10 @@
+import { readFileSync } from 'node:fs';
+
+export function pluginEnvironment() {
+  try {
+    const manifest = JSON.parse(readFileSync(new URL('../.claude-plugin/plugin.json', import.meta.url), 'utf8'));
+    return { ...process.env, POPMELT_CLAUDE_PLUGIN_VERSION: manifest.version };
+  } catch {
+    return { ...process.env, POPMELT_CLAUDE_PLUGIN_VERSION: '' };
+  }
+}

package/claude-plugin/scripts/hook.mjs

@@ -0,0 +1,35 @@
+import { spawn } from 'node:child_process';
+import { locatePopmeltCli } from './locate-cli.mjs';
+import { pluginEnvironment } from './environment.mjs';
+
+const cli = locatePopmeltCli();
+const child = spawn(cli.command, [...cli.prefix, 'claude', 'hook'], {
+  cwd: process.cwd(), env: pluginEnvironment(), stdio: ['pipe', 'pipe', 'ignore'],
+});
+let output = '';
+let finished = false;
+const finish = (value = '{}') => {
+  if (finished) return;
+  finished = true;
+  clearTimeout(timer);
+  process.stdin.unpipe(child.stdin);
+  process.stdin.pause();
+  process.stdout.write(value + '\n');
+};
+const timer = setTimeout(() => {
+  child.kill('SIGKILL');
+  finish();
+}, 10_000);
+child.stdout.on('data', (chunk) => {
+  output += chunk.toString();
+  if (output.length > 256_000) { child.kill('SIGKILL'); finish(); }
+});
+child.stdin.on('error', () => {});
+child.on('error', () => finish());
+child.on('close', (code) => {
+  try {
+    const value = JSON.parse(output);
+    finish(code === 0 && value && typeof value === 'object' ? JSON.stringify(value) : '{}');
+  } catch { finish(); }
+});
+process.stdin.pipe(child.stdin);