@popmelt.com/core 0.8.17 → 0.10.0

package/README.md

@@ -1,30 +1,86 @@
 <p align="center">
-  <img src="src/assets/bar - popmelt.png" alt="Popmelt" width="360" />
+  <img src="https://raw.githubusercontent.com/popmelt/core/main/src/assets/popmelt-logo.svg" alt="Popmelt" width="72" />
 </p>
 
 # Popmelt
 
-Popmelt is a design collaboration layer for AI coding agents. It gives you a visual toolbar inside your running React app so you can annotate UI, adjust it directly, and hand the result to Claude Code, Codex, or GitHub Copilot without translating every design decision into a written prompt.
+Popmelt is a design collaboration layer that lives inside your local app projects. When your app is running locally, Popmelt appears as a toolbar in the browser.
 
-Popmelt is local-first. Your project, annotations, screenshots, conversations, decisions, and models remain in your development environment.
+Point to any part of your UI, describe what you have in mind, and work through it with Codex or Claude Code in a thread right on the page. You can stack as many threads as you want, so different ideas can move forward without losing their context.
 
-## Install
+As you collaborate, Popmelt builds an **Imprint**: a living project memory of your intent, preferences, and design decisions. Later threads can use that shared understanding instead of starting from scratch.
 
-Install Popmelt and its icon peer dependency:
+Popmelt is local-first. Its annotations, screenshots, threads, and Imprint live with your project under `.popmelt/`.
+
+## What you need
+
+- A local React project
+- Node.js 18 or newer
+- React 18 or newer
+- 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.
+
+## Install with your coding agent
+
+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.
+
+## Use Popmelt
+
+1. Run your project locally and open it in a browser
+2. Double-tap Command on macOS or Control on Windows and Linux to open the Popmelt toolbar
+3. Select part of the UI and leave a note about what should change
+4. Press Command+Enter on macOS or Control+Enter on Windows and Linux to send the thread to your coding agent. Review the result and keep iterating from the same thread
+5. To edit text directly, double-tap a text element. Popmelt marks the change so you can send it like any other annotation
+
+Each annotation owns its thread. Status stays attached to the relevant part of the page while work is queued or running, and you can reopen any thread from its badge. Tool and Imprint receipts show what helped the agent reach its result.
+
+## 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:
 
 ```bash
-npm install @popmelt.com/core lucide-react
+npx @popmelt.com/core codex install
 ```
 
-Popmelt requires React 18+ and Node.js 18+. At least one supported AI CLI must be installed and authenticated:
+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.
+
+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.
+
+Useful diagnostics:
+
+```bash
+npx @popmelt.com/core codex status
+npx @popmelt.com/core codex doctor
+```
+
+## Imprint
+
+As you work, Popmelt recognizes choices that may be useful beyond the current thread and proposes an Imprint update:
 
-- Claude Code
-- Codex CLI
-- GitHub Copilot CLI
+- **Yes** adds the learning to the project's shared understanding
+- **This time** keeps it local to the current situation
+- **No** leaves the Imprint unchanged and gives you room to explain what Popmelt misunderstood
+
+Confirmed Imprint knowledge is available to future threads when it is relevant. Popmelt can also search the project's collaboration history when a question depends on earlier discussions, feedback, or the evolution of a part of the UI.
+
+Open the Imprint panel with `I` to inspect the project's current understanding, supporting evidence, relationships, and exceptions.
+
+## Manual setup
+
+Install Popmelt and its icon peer dependency:
+
+```bash
+npm install @popmelt.com/core lucide-react
+```
 
 ### Add the provider
 
-Wrap your application with `PopmeltProvider`. The component that calls `useRouter()` must be a client component in Next.js.
+Wrap your app with `PopmeltProvider`. In Next.js, the component that calls `useRouter()` must be a client component.
 
 ```tsx
 'use client';
@@ -40,13 +96,13 @@ export function Providers({ children }: { children: React.ReactNode }) {
 }
 ```
 
-`navigate` is optional for single-page use. Pass your router's navigation function to support annotations and screenshots across routes.
+`navigate` is optional for single-page use. Pass your router's navigation function when Popmelt needs to restore annotations across routes.
 
 ### Next.js
 
-For Next.js, both steps below are required.
+Next.js needs both the command wrapper and the config wrapper.
 
-1. Run the dev server through the Popmelt wrapper. Update the existing `dev` script while preserving any flags your project already uses:
+Update the existing development script while preserving any flags already in use:
 
 ```json
 {
@@ -56,13 +112,7 @@ For Next.js, both steps below are required.
 }
 ```
 
-For example, a Turbopack project can use:
-
-```json
-"dev": "popmelt wrap -- next dev --turbopack"
-```
-
-2. Wrap the Next config:
+Then wrap the Next config:
 
 ```ts
 // next.config.ts
@@ -73,11 +123,11 @@ const nextConfig = {};
 export default withPopmelt(nextConfig);
 ```
 
-The command wrapper starts the bridge for this project. The Next config wrapper connects the browser UI to that bridge. Using only one of these two pieces is not a complete setup.
+The command wrapper starts the project bridge. The config wrapper connects the browser toolbar to it. Using only one is not a complete setup.
 
 ### Vite
 
-Add the Vite plugin. It starts and connects the bridge with the Vite dev server.
+Add the Vite plugin:
 
 ```ts
 // vite.config.ts
@@ -92,7 +142,7 @@ export default defineConfig({
 
 ### Astro
 
-Add the Astro integration. It starts and connects the bridge with the Astro dev server.
+Add the Astro integration:
 
 ```js
 // astro.config.mjs
@@ -106,7 +156,7 @@ export default defineConfig({
 
 ### Other development servers
 
-The wrapper works with any dev command:
+The wrapper can start Popmelt alongside another development command:
 
 ```json
 {
@@ -116,137 +166,46 @@ The wrapper works with any dev command:
 }
 ```
 
-You can also start the bridge from custom server startup code:
-
-```ts
-import { startPopmelt } from '@popmelt.com/core/server';
-
-await startPopmelt();
-```
-
 ## Verify the installation
 
-Start the app using its normal development command:
+Start the app normally:
 
 ```bash
 npm run dev
 ```
 
-You should see both the bridge URL and the application URL in the terminal. Open the app and double-tap Cmd on macOS or Ctrl on Windows/Linux. The Popmelt toolbar should appear.
+Open the local app in a browser and double-tap Command or Control. The Popmelt toolbar should appear.
 
 If the toolbar opens but cannot reach an AI, check that:
 
-- The dev script includes `popmelt wrap` when using Next.js.
-- The framework plugin or config wrapper is installed.
-- A supported AI CLI is available and authenticated.
-- Another project is not using an old Popmelt bridge. Restart the dev command to reconnect the correct project.
-
-## Installing with an AI
-
-You can hand the following checklist to an AI coding agent:
-
-> Install `@popmelt.com/core` and `lucide-react`. Add `PopmeltProvider` at the application root. Preserve the existing dev command, but for Next.js prefix it with `popmelt wrap --` and wrap `next.config` with `withPopmelt`. For Vite or Astro, add the corresponding Popmelt plugin. Start the app and verify that the toolbar opens after double-tapping Cmd/Ctrl and that the bridge belongs to this project.
+- 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
 
-The important Next.js detail is that `withPopmelt()` does not start the bridge by itself. The `dev` script must also use the Popmelt wrapper.
+## Data and privacy
 
-## Use Popmelt
-
-Double-tap Cmd/Ctrl to open or collapse the toolbar. Hover any toolbar control to see its guidance panel.
-
-| Tool      | Shortcut | Use it to                                                                             |
-| --------- | -------- | ------------------------------------------------------------------------------------- |
-| Comment   | `C`      | Pin feedback to a specific element and start a conversation with your AI.             |
-| Handle    | `H`      | Adjust layout, spacing, typography, color, borders, and effects directly on the page. |
-| Rectangle | `R`      | Mark a rectangular region.                                                            |
-| Oval      | `O`      | Mark an oval region.                                                                  |
-| Line      | `L`      | Point at or connect parts of the UI.                                                  |
-| Pen       | `P`      | Draw a freehand annotation.                                                           |
-| Text      | `T`      | Add a label or edit existing page text inline.                                        |
-| Model     | `M`      | Review project patterns, components, and design-model suggestions.                    |
-
-### Hand off work
-
-Create one or more annotations, then press Cmd/Ctrl+Enter. Popmelt sends the visual state, element context, requested edits, and relevant project history to the selected AI.
-
-The conversation opens in a thread beside the page. You can continue working while jobs run, reopen threads from their status badges, answer questions, and send follow-up guidance. Messages sent while an active thread is working are staged and delivered together on its next run.
-
-### Comment on elements
-
-Select Comment and click an element. Type what should change, then hand it off with Cmd/Ctrl+Enter. The annotation remains attached to that element as the page scrolls and across supported route changes.
-
-If the AI needs clarification, the annotation shows a Question badge. Open the thread, answer it, and send the reply.
-
-### Adjust UI directly
-
-Select Handle and hover an element. Depending on the element, you can adjust:
-
-- Width, height, padding, and gap
-- Flex and grid alignment
-- Font family, weight, size, line height, letter spacing, and alignment
-- Text and background colors
-- Opacity, radius, borders, and effects
-- Raw CSS for properties not represented by a dedicated control
-
-Right-click the focused element to open the full Handle panel. Values inherited from the page appear as placeholders until you explicitly change them. Hover and scrub numeric field icons to tune values; use modifier keys shown in the panel guidance for snapping and finer control.
-
-Handle changes are previews. They are recorded with the annotation so the AI can implement the corresponding source-code changes.
-
-You can also drag supported elements to propose a new position, and use Cmd/Ctrl+C and Cmd/Ctrl+V in Handle mode to duplicate supported page structures as visual guidance.
-
-### Edit text inline
-
-Select Text and hover page copy. Recognized text elements receive a bounding box. Click to edit the actual visible text in place, then finish the edit to retain it as a pending change.
-
-Clicking outside editable page copy still creates a free-positioned text annotation.
-
-### Draw visual guidance
-
-Rectangle, Oval, Line, and Pen annotations are useful when the desired result is easier to show than describe. Add labels where useful, then submit them with the rest of the page context.
-
-### Work across routes
-
-Pass `navigate` to `PopmeltProvider` to enable route-aware annotations and multi-page capture. Annotation and status badges appear only on their relevant routes. When a handoff includes multiple routes, Popmelt captures each route and sends them together.
+Popmelt stores its annotations, screenshots, threads, UI preferences, and Imprint locally under `.popmelt/`. Unsent annotation drafts and preview state also use browser storage.
 
-## AI providers and models
+When you send a thread, the context needed to complete that work is passed to your selected AI provider and is subject to that provider's privacy policy.
 
-Popmelt detects supported AI CLIs available in the project environment. Click the provider icon to switch providers. Click the model name, or hover the provider controls, to choose among detected models.
-
-When supported by the selected model, the model guidance panel also exposes:
-
-- Thinking or reasoning effort
-- Standard or faster service tiers
-
-These settings persist per provider and model and apply to annotations, replies, and model work.
-
-## Threads and job status
-
-Each handoff creates or continues a conversation thread. Status badges stay available while work is queued or running and return you to the associated element and conversation.
-
-Use Cancel in the thread to stop the active job associated with that conversation. Closing a thread does not delete it. Delete its annotation to remove that thread, or use Cmd/Ctrl+Backspace to clear all local annotations and pending preview changes.
-
-## Decisions and the project model
-
-Completed annotation threads leave a decision history in the project. Popmelt uses that evidence to identify reusable design patterns rather than treating every edit as an isolated instruction.
-
-When Popmelt finds a model opportunity, it places the proposal in the relevant annotation thread. Expand the proposal to inspect the exact changes, select only the entries you agree with, and apply or dismiss them. Applied changes contribute to the local project model.
-
-Use the Model panel to inspect captured patterns and components or to synthesize model guidance from accumulated project history.
+Popmelt is designed for local development. As with any AI-assisted coding, your agent may edit files or run commands, so review its work, use version control, and run your project tests before you ship.
 
 ## Useful shortcuts
 
-| Shortcut                  | Action                                                          |
-| ------------------------- | --------------------------------------------------------------- |
-| Double-tap Cmd/Ctrl       | Open or collapse Popmelt                                        |
-| Cmd/Ctrl+Enter            | Hand off pending work                                           |
-| Cmd/Ctrl+C                | Copy an annotated screenshot, or copy an element in Handle mode |
-| Cmd/Ctrl+V                | Paste a copied element in Handle mode                           |
-| Cmd/Ctrl+Z                | Undo a pending change                                           |
-| Cmd/Ctrl+Shift+Z          | Redo a pending change                                           |
-| Backspace/Delete          | Delete the selected annotation                                  |
-| Cmd/Ctrl+Backspace/Delete | Clear all annotations and pending changes                       |
-| Escape                    | Cancel the active edit or deselect the current annotation       |
+| Shortcut                         | Action                                                    |
+| -------------------------------- | --------------------------------------------------------- |
+| Double-tap Command or Control    | Open or collapse Popmelt                                  |
+| `C`                              | Enter Comment mode                                        |
+| `I`                              | Enter Imprint mode                                        |
+| Command/Control+Enter            | Send pending work                                         |
+| Command/Control+Z                | Undo a pending change                                     |
+| Command/Control+Shift+Z          | Redo a pending change                                     |
+| Backspace/Delete                 | Delete the selected annotation                            |
+| Command/Control+Backspace/Delete | Clear all annotations and pending changes                 |
+| Escape                           | Cancel the active edit or deselect the current annotation |
 
-## Advanced setup
+## Bridge commands
 
 Run a bridge without wrapping another command:
 
@@ -254,38 +213,16 @@ Run a bridge without wrapping another command:
 npx @popmelt.com/core bridge
 ```
 
-Stop a detached bridge for the current project:
+Stop the bridge for the current project:
 
 ```bash
 npx @popmelt.com/core stop
 ```
 
-Start a configured bridge in server code:
-
-```ts
-await startPopmelt({
-  port: 1111,
-  projectRoot: '.',
-  devOrigin: 'http://localhost:3000',
-  provider: 'codex',
-  timeoutMs: undefined,
-});
-```
-
-`startPopmelt()` returns the selected port, the stable project ID, and a `close()` function.
-
-## Local project data
-
-Popmelt writes project history under `.popmelt/`. Keep this directory when you want decisions, threads, and the local model to survive across sessions. The browser also uses local storage for unsent annotations and preview edits.
-
 ## License
 
 [PolyForm Shield 1.0.0](./LICENSE)
 
 You may use and extend Popmelt for yourself and your team. You may not sell it, offer it as a managed service, or use the code to create a competing product or service. The software is provided as-is.
 
-For custom licensing, contact [reb@popmelt.com](mailto:reb@popmelt.com).
-
-<p align="center">
-  <img src="src/assets/popmelt-logo.svg" alt="Popmelt" width="64" />
-</p>
+For custom licensing, contact **reb@popmelt.com**.

package/codex-plugin/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "popmelt-core",
+  "version": "0.10.0",
+  "description": "Ambient project memory and shared understanding for Codex",
+  "author": {
+    "name": "Popmelt",
+    "email": "reb@popmelt.com",
+    "url": "https://popmelt.com"
+  },
+  "homepage": "https://popmelt.com",
+  "repository": "https://github.com/popmelt/core",
+  "license": "PolyForm-Shield-1.0.0",
+  "keywords": [
+    "codex",
+    "memory",
+    "design",
+    "collaboration",
+    "knowledge"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Popmelt Core",
+    "shortDescription": "Ambient project memory for Codex",
+    "longDescription": "Pairs Codex conversations with Popmelt threads, retrieves accepted product truth and provisional explanations, records implementation evidence, and preserves explicit human authority over decisions and grounding.",
+    "developerName": "Popmelt",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://popmelt.com",
+    "defaultPrompt": [
+      "Show the Popmelt context relevant to this task.",
+      "Inspect the current Popmelt thread.",
+      "Help me review the surfaced product decision."
+    ],
+    "brandColor": "#111111",
+    "composerIcon": "./assets/popmelt-logo.svg",
+    "logo": "./assets/popmelt-logo.svg",
+    "logoDark": "./assets/popmelt-logo.svg"
+  }
+}

package/codex-plugin/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "popmelt-core": {
+      "command": "node",
+      "args": ["./scripts/mcp.mjs"],
+      "cwd": ".",
+      "env_vars": ["POPMELT_CODEX_ORIENTATION_DIR", "POPMELT_CODEX_SESSION_DIR", "POPMELT_EXECUTION_OWNER", "POPMELT_PARENT_JOB_ID"],
+      "startup_timeout_sec": 40,
+      "tool_timeout_sec": 60
+    }
+  }
+}

package/codex-plugin/assets/popmelt-logo.svg

@@ -0,0 +1,4 @@
+<svg width="256" height="256" viewBox="0 0 40 40" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="40" height="40" fill="#F1F1F1"/>
+<path d="M11.1406 31.2559C11.2407 31.3875 11.351 31.5132 11.4697 31.6338L3.10449 40H2.39746L11.1406 31.2559ZM8.05371 40H7.34668L14.5498 32.7959C14.8554 32.7706 15.1541 32.7063 15.4414 32.6113L8.05371 40ZM18.2197 34.0762C18.3788 34.1569 18.5445 34.2272 18.7168 34.2861L13.0039 40H12.2969L18.2197 34.0762ZM17.9531 40H17.2461L26.1338 31.1113C26.438 31.0829 26.7427 31.0148 27.0439 30.9082L17.9531 40ZM40 22.9023L22.9033 40H22.1963L40 22.1953V22.9023ZM40 27.8525L27.8525 40H27.1455L40 27.1455V27.8525ZM40 32.8027L32.8027 40H32.0957L40 32.0957V32.8027ZM40 37.752L37.752 40H37.0449L40 37.0449V37.752ZM9.06543 28.3809C9.25255 28.4332 9.45183 28.4715 9.66504 28.4883L0 38.1543V37.4473L9.06543 28.3809ZM6.59375 25.9023C6.65822 26.0626 6.73171 26.2263 6.81445 26.3896L0 33.2041V32.4971L6.59375 25.9023ZM20.25 8.00293H20.249C21.5098 8.0286 22.7219 8.25094 23.8584 8.63672L23.8604 8.63574C23.8961 8.64787 23.9312 8.66145 23.9668 8.67383C24.0611 8.70686 24.1548 8.74106 24.248 8.77637C24.2915 8.79273 24.3357 8.80727 24.3789 8.82422L24.376 8.82617C27.6145 10.0955 30.1646 12.7301 31.3213 16.0234L31.3232 16.0225C31.3327 16.0493 31.3404 16.0766 31.3496 16.1035C31.7691 17.3256 32 18.6356 32 20C32 20.8726 31.9366 21.6706 31.7598 22.4902L31.7197 22.6328C31.6412 23.0066 31.5136 23.6108 31.3408 24.2217L31.3398 24.2246C31.2967 24.377 31.251 24.5299 31.2021 24.6797C30.9215 25.5403 30.5473 26.2998 30.0879 26.2998C29.7613 26.2996 29.5995 25.9674 29.4316 25.6221C29.2501 25.2487 29.0614 24.8605 28.6484 24.8604C27.8532 24.8604 27.2081 25.5046 27.208 26.2998V27.0771C27.2079 27.6079 26.9661 28.112 26.5205 28.4004C25.9146 28.7925 25.2357 28.6462 24.7959 28.2061L24.7949 28.208C24.7897 28.2028 24.7854 28.1967 24.7803 28.1914C24.7654 28.1761 24.7507 28.1606 24.7363 28.1445C24.7105 28.1156 24.6858 28.0857 24.6621 28.0547C24.6461 28.0339 24.6302 28.013 24.6152 27.9912C24.5931 27.9591 24.5726 27.9257 24.5527 27.8916C24.5392 27.8685 24.5261 27.8452 24.5137 27.8213C24.5093 27.8128 24.5043 27.8045 24.5 27.7959L24.501 27.7939C24.3932 27.5763 24.3282 27.3276 24.3281 27.0576V26.2998C24.328 25.5993 23.8278 25.0158 23.165 24.8867V24.8877C23.0752 24.8702 22.9826 24.8604 22.8877 24.8604C22.8446 24.8604 22.8019 24.8624 22.7598 24.8662C22.0247 24.9312 21.4483 25.5479 21.4482 26.2998C21.4482 26.9127 21.4608 27.5305 21.4736 28.1494L21.4951 29.3135C21.5 29.7013 21.5015 30.089 21.4971 30.4756C21.4874 31.3103 20.8426 32 20.0078 32C19.1732 31.9998 18.5292 31.3102 18.5195 30.4756C18.5159 30.1613 18.5176 29.8464 18.5205 29.5312V29.5322C18.5212 29.4593 18.5206 29.3864 18.5215 29.3135L18.5303 28.8154V28.8145C18.5343 28.5927 18.5384 28.371 18.543 28.1494C18.5558 27.5305 18.5684 28.1129 18.5684 27.5C18.5684 26.7047 17.9232 26.0596 17.1279 26.0596C16.907 26.0596 16.6978 26.1103 16.5107 26.1992C16.2161 26.3393 15.9767 26.5769 15.834 26.8701C15.8269 26.8846 15.8201 26.8993 15.8135 26.9141C15.7821 26.9845 15.7562 27.0579 15.7363 27.1338C15.7243 27.1798 15.7155 27.2267 15.708 27.2744C15.7012 27.3175 15.6953 27.361 15.6924 27.4053C15.6903 27.4366 15.6885 27.4681 15.6885 27.5V28.7383C15.6883 29.9234 14.4911 30.7248 13.4961 30.0811C13.0505 29.7926 12.8086 29.2886 12.8086 28.7578V26.2998C12.8086 25.9737 12.6984 25.674 12.5156 25.4326C12.4437 25.3381 12.3612 25.2521 12.2686 25.1777V25.1768C12.0219 24.9788 11.709 24.8604 11.3682 24.8604C10.9892 24.8604 10.8622 24.8872 10.7295 25.2295C10.5837 25.6055 10.4302 26 9.92773 26C9.33081 25.9996 8.95963 25.2403 8.71484 24.3799C8.5591 23.8325 8.45907 23.571 8.3623 23.0107C8.3501 22.9401 8.33284 22.8403 8.31738 22.7529C8.12812 21.9466 8.02043 21.1089 8.00293 20.249V20.25L8 20C8 19.8617 8.00317 19.724 8.00781 19.5869C8.00837 19.5703 8.00816 19.5537 8.00879 19.5371L8.00977 19.5352C8.0998 17.1716 8.87444 14.9844 10.1396 13.1631C10.1488 13.1499 10.1587 13.1372 10.168 13.124C12.255 10.1453 15.6582 8.15745 19.5352 8.00977L19.5371 8.00879C19.5537 8.00816 19.5703 8.00837 19.5869 8.00781C19.724 8.00317 19.8617 8 20 8L20.25 8.00293ZM5.72266 22.5303L0 28.2539V27.5469L5.62793 21.918C5.6553 22.1234 5.6868 22.3275 5.72266 22.5303ZM16.2637 26.8398L16.2617 26.8408C16.2784 26.8013 16.2954 26.7627 16.3135 26.7256C16.3203 26.7116 16.3275 26.6982 16.334 26.6855C16.3125 26.7277 16.289 26.7808 16.2637 26.8398ZM40 17.9531L33.9854 23.9668C34.051 23.6832 34.1043 23.4321 34.1445 23.2412L34.1641 23.1748L34.1865 23.0967L34.1963 23.0488L40 17.2461V17.9531ZM5.87012 16.7266C5.80321 17.0165 5.74649 17.3101 5.69727 17.6064L0 23.3047V22.5977L5.87012 16.7266ZM40 13.0039L34.4297 18.5732C34.409 18.3615 34.3832 18.1513 34.3535 17.9424L40 12.2969V13.0039ZM0 18.3555V17.6484L17.6484 0H18.3555L0 18.3555ZM40 8.05371L33.458 14.5947C33.3909 14.4277 33.3202 14.2625 33.2471 14.0986L40 7.34668V8.05371ZM0 13.4053V12.6982L12.6992 0H13.4062L0 13.4053ZM40 3.10352L31.6865 11.416C31.5868 11.2805 31.4851 11.1465 31.3809 11.0146L40 2.39648V3.10352ZM29.2881 8.86523C29.1595 8.75783 29.0288 8.65278 28.8965 8.5498L37.4473 0H38.1543L29.2881 8.86523ZM0 8.45508V7.74805L7.74805 0H8.45508L0 8.45508ZM26.2783 6.92578C26.1183 6.84878 25.9562 6.77534 25.793 6.7041L32.498 0H33.2051L26.2783 6.92578ZM17.6064 5.69727C17.3101 5.74649 17.0165 5.80321 16.7266 5.87012L22.5977 0H23.3047L17.6064 5.69727ZM22.5322 5.7207C22.3295 5.685 22.1254 5.65316 21.9199 5.62598L27.5469 0H28.2539L22.5322 5.7207ZM0 3.50586V2.79883L2.79883 0H3.50586L0 3.50586Z" fill="black"/>
+</svg>

package/codex-plugin/hooks/hooks.json

@@ -0,0 +1,41 @@
+{
+  "description": "Ambient Popmelt Core turn lifecycle",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 40,
+            "statusMessage": "Loading Popmelt context",
+            "additionalContextLimit": 12000
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/hook.mjs\"",
+            "timeout": 15,
+            "statusMessage": "Recording the Popmelt turn"
+          }
+        ]
+      }
+    ]
+  }
+}

package/codex-plugin/scripts/hook.mjs

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+import { locatePopmeltCli } from './locate-cli.mjs';
+
+const input = readFileSync(0, 'utf8');
+const cli = locatePopmeltCli();
+const result = spawnSync(cli.command, [...cli.prefix, 'codex', 'hook'], {
+  cwd: process.cwd(),
+  env: process.env,
+  input,
+  encoding: 'utf8',
+  timeout: 45_000,
+});
+if (result.status === 0 && result.stdout?.trim()) {
+  process.stdout.write(result.stdout);
+} else {
+  process.stdout.write('{}\n');
+}

package/codex-plugin/scripts/locate-cli.mjs

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export function locatePopmeltCli(start = process.cwd()) {
+  try {
+    const runtimePath = join(dirname(fileURLToPath(import.meta.url)), '..', 'runtime.json');
+    const runtime = JSON.parse(readFileSync(runtimePath, 'utf8'));
+    if (typeof runtime.cliPath === 'string' && existsSync(runtime.cliPath)) {
+      return { command: process.execPath, prefix: [runtime.cliPath] };
+    }
+  } catch {
+    // Source checkouts do not have an installed-runtime pointer yet.
+  }
+  let current = resolve(start);
+  const root = parse(current).root;
+  while (true) {
+    const candidates = [
+      join(current, 'node_modules', '@popmelt.com', 'core', 'dist', 'cli.mjs'),
+      join(current, 'packages', 'popmelt', 'dist', 'cli.mjs'),
+    ];
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return { command: process.execPath, prefix: [candidate] };
+    }
+    const packagePath = join(current, 'package.json');
+    if (existsSync(packagePath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(packagePath, 'utf8'));
+        if (pkg.name === '@popmelt.com/core') {
+          const local = join(current, 'dist', 'cli.mjs');
+          if (existsSync(local)) return { command: process.execPath, prefix: [local] };
+        }
+      } catch {
+        // Ignore malformed package metadata and continue searching upward.
+      }
+    }
+    if (current === root) break;
+    current = dirname(current);
+  }
+  return { command: 'popmelt', prefix: [] };
+}

package/codex-plugin/scripts/mcp.mjs

@@ -0,0 +1,15 @@
+import { spawn } from 'node:child_process';
+
+import { locatePopmeltCli } from './locate-cli.mjs';
+
+const cli = locatePopmeltCli();
+const child = spawn(cli.command, [...cli.prefix, 'codex', 'mcp'], {
+  cwd: process.cwd(),
+  env: process.env,
+  stdio: 'inherit',
+});
+child.on('error', () => process.exit(1));
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 1);
+});

package/codex-plugin/skills/popmelt-core/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: popmelt-core
+description: Use Popmelt Core when the user asks to inspect project memory, expand relevant product context, review a surfaced decision candidate, ground a surfaced Imprint explanation, or discuss the current Popmelt thread.
+---
+
+# Popmelt Core
+
+Popmelt pairs the current Codex conversation with a durable project thread. Ambient hooks already retrieve context and capture ordinary turns, so do not call tools merely to announce or duplicate that automatic work.
+
+Use the tools deliberately:
+
+- Pass the exact `tool session` ID supplied by the Ambient Popmelt Core context as `sessionId` on every tool call. This routes the call to the correct project even when the MCP process has a different working directory.
+
+- Use `popmelt_orient_stores` only after the human explicitly chooses the writable primary store and any mounted read stores from an ambient orientation packet. Save that choice as the workspace default unless the human explicitly requests a session-only override. Store proximity, nesting, size, or recency never implies that choice.
+- Use `popmelt_expand_context` when the automatically supplied packet is truncated or the user explicitly asks for broader history.
+- Use `popmelt_inspect_thread` when the user asks to inspect the paired thread or its evidence.
+- Use `popmelt_review_decision` only after the human explicitly resolves the exact surfaced candidate. Preserve the actions `accept`, `edit_and_accept`, `reject`, and `defer`. Never infer acceptance from implementation, praise, silence, or ambiguity.
+- Use `popmelt_ground_imprint` only after the human explicitly answers a surfaced grounding question. Preserve the actions `yes`, `this_time`, and `no`.
+- Use `popmelt_assess_turn` only when the current collaboration changed reusable shared understanding. Ordinary completion and tool evidence are captured automatically.
+
+Accepted product decisions are authoritative within scope. Imprint explanations are provisional and advisory. The human remains the authority for both decision acceptance and Imprint grounding.
+
+If Popmelt reports `already_managed_by_bridge`, stop calling Popmelt Core tools for that run; the toolbar bridge owns the turn lifecycle.