@wipcomputer/wip-ldm-os 0.4.83 → 0.4.85-alpha.1

package/SKILL.md

@@ -9,7 +9,7 @@ license: MIT
 compatibility: Requires git, npm, node. Node.js 18+.
 metadata:
   display-name: "LDM OS"
-  version: "0.4.83"
+  version: "0.4.84"
   homepage: "https://github.com/wipcomputer/wip-ldm-os"
   author: "Parker Todd Brooks"
   category: infrastructure

package/bin/ldm.js

@@ -1537,13 +1537,21 @@ async function cmdInstall() {
     // npm install --prefix silently fails for scoped packages in temp directories...
     // it creates the lock file but doesn't extract files. npm pack is reliable.
     const npmName = resolvedTarget;
+    // --alpha and --beta select the corresponding npm dist-tag instead of @latest.
+    // Without this, `ldm install --alpha <pkg>` was pulling the @latest version
+    // from npm pack and an existing global install would never advance to the
+    // current alpha. Now the tag flows through pack + the downstream
+    // installSingleTool's `npm install -g <pkg>@<version>` step uses the
+    // version baked into the alpha tarball.
+    const npmTag = ALPHA_FLAG ? 'alpha' : (BETA_FLAG ? 'beta' : '');
+    const packTarget = npmTag ? `${npmName}@${npmTag}` : npmName;
     const tempDir = join(LDM_TMP, `npm-${Date.now()}`);
     console.log('');
-    console.log(`  Installing ${npmName} from npm...`);
+    console.log(`  Installing ${packTarget} from npm...`);
     try {
       mkdirSync(tempDir, { recursive: true });
       // Use npm pack + tar instead of npm install --prefix
-      const tarball = execSync(`npm pack ${npmName} --pack-destination "${tempDir}" 2>/dev/null`, {
+      const tarball = execSync(`npm pack ${packTarget} --pack-destination "${tempDir}" 2>/dev/null`, {
         encoding: 'utf8', timeout: 60000, cwd: tempDir,
       }).trim();
       const tarPath = join(tempDir, tarball);
@@ -4289,6 +4297,164 @@ async function main() {
     console.log('');
   }
 
+  // ── ldm uninstall <pkg> ──
+  //
+  // Removes a single LDM-installed package. Used to reset a single
+  // extension between dogfood cycles without taking down the rest of
+  // LDM OS. Pairs with the per-package cleanup hook each package may
+  // ship (e.g. `codex-daemon uninstall --purge` for Codex Remote
+  // Control), which the user runs first to clean up product-specific
+  // state. This command then removes the LDM-side install record + the
+  // global npm package + the LDM extension dir.
+  //
+  // Safety:
+  //   - Never touches ~/.codex/ or other unrelated user state.
+  //   - Never removes ~/.ldm/memory/ or ~/.ldm/agents/.
+  //   - Never removes other extensions.
+  //   - Idempotent: running twice exits cleanly.
+  //   - Refuses to uninstall LDM OS itself (use `ldm uninstall` for that).
+
+  async function cmdUninstallPackage(pkgName) {
+    const isDryRun = args.includes('--dry-run');
+
+    if (pkgName === 'wip-ldm-os' || pkgName === '@wipcomputer/wip-ldm-os') {
+      console.error('  Refusing to uninstall LDM OS itself with `ldm uninstall <pkg>`.');
+      console.error('  To remove all of LDM OS: ldm uninstall');
+      process.exit(1);
+    }
+
+    console.log('');
+    console.log(`  ldm uninstall ${pkgName}`);
+    console.log('  ────────────────────────────────────');
+
+    // 1. Look up the package in the registry.
+    const registryPath = join(LDM_EXTENSIONS, 'registry.json');
+    let registry = { _format: 'v1', extensions: {} };
+    try {
+      if (existsSync(registryPath)) {
+        registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+      }
+    } catch (e) {
+      console.error(`  ! could not read registry at ${registryPath}: ${e.message}`);
+    }
+    const entry = registry.extensions?.[pkgName] || null;
+
+    // 2. Resolve npm package name.
+    //    Registry entries from npm installs put the npm name in `source.npm`
+    //    or in the top-level `name` field. Fall back to the user-supplied
+    //    pkgName (works for unscoped packages).
+    const npmPkg = entry?.source?.npm || entry?.name || pkgName;
+
+    // 3. Resolve LDM extension dir(s).
+    const ldmExtPath = entry?.paths?.ldm
+      || entry?.ldmPath
+      || join(LDM_EXTENSIONS, pkgName);
+    const ocExtPath = entry?.paths?.openclaw
+      || entry?.ocPath
+      || null;
+
+    // 4. Build the action plan.
+    const actions = [];
+    let pkgInstalledGlobally = false;
+    try {
+      const npmList = execSync(`npm list -g --depth=0 --json 2>/dev/null`, { encoding: 'utf8' });
+      const deps = JSON.parse(npmList).dependencies || {};
+      pkgInstalledGlobally = !!deps[npmPkg];
+    } catch {}
+
+    if (pkgInstalledGlobally) {
+      actions.push({ kind: 'npm-uninstall', npmPkg });
+    } else {
+      actions.push({ kind: 'skip', label: `npm: ${npmPkg} not installed globally` });
+    }
+    if (existsSync(ldmExtPath)) {
+      actions.push({ kind: 'rm-dir', label: 'LDM extension dir', path: ldmExtPath });
+    } else {
+      actions.push({ kind: 'skip', label: `LDM extension dir: ${ldmExtPath} already gone` });
+    }
+    if (ocExtPath && existsSync(ocExtPath)) {
+      actions.push({ kind: 'rm-dir', label: 'OpenClaw extension dir', path: ocExtPath });
+    }
+    if (entry) {
+      actions.push({ kind: 'registry-remove', name: pkgName });
+    } else {
+      actions.push({ kind: 'skip', label: `registry: no entry for ${pkgName}` });
+    }
+
+    const realActions = actions.filter(a => a.kind !== 'skip');
+    const skips = actions.filter(a => a.kind === 'skip');
+
+    console.log('');
+    if (realActions.length === 0) {
+      for (const s of skips) console.log(`  - ${s.label}`);
+      console.log('');
+      console.log('  Nothing to do.');
+      console.log('');
+      console.log('  Will NOT touch ~/.codex/ or ~/.ldm/memory/ or other extensions.');
+      return;
+    }
+    console.log('  Will:');
+    for (const a of realActions) {
+      switch (a.kind) {
+        case 'npm-uninstall':
+          console.log(`    - npm uninstall -g ${a.npmPkg}`);
+          break;
+        case 'rm-dir':
+          console.log(`    - remove ${a.label}: ${a.path}`);
+          break;
+        case 'registry-remove':
+          console.log(`    - remove registry entry for ${a.name}`);
+          break;
+      }
+    }
+    for (const s of skips) console.log(`    - skipped: ${s.label}`);
+    console.log('');
+    console.log('  Will NOT touch ~/.codex/ or ~/.ldm/memory/ or other extensions.');
+
+    if (isDryRun) {
+      console.log('');
+      console.log('  Dry run. Nothing removed.');
+      console.log('');
+      console.log('  Re-run without --dry-run to apply.');
+      return;
+    }
+
+    console.log('');
+    for (const a of realActions) {
+      switch (a.kind) {
+        case 'npm-uninstall':
+          try {
+            execSync(`npm uninstall -g ${a.npmPkg}`, { stdio: 'pipe', timeout: 60000 });
+            console.log(`  + npm uninstall -g ${a.npmPkg}`);
+          } catch (e) {
+            console.error(`  ! npm uninstall -g ${a.npmPkg} failed: ${e.message}`);
+          }
+          break;
+        case 'rm-dir':
+          try {
+            execSync(`rm -rf "${a.path}"`, { stdio: 'pipe' });
+            console.log(`  + removed ${a.label}: ${a.path}`);
+          } catch (e) {
+            console.error(`  ! could not remove ${a.path}: ${e.message}`);
+          }
+          break;
+        case 'registry-remove':
+          try {
+            delete registry.extensions[a.name];
+            writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
+            console.log(`  + removed registry entry for ${a.name}`);
+          } catch (e) {
+            console.error(`  ! could not update registry: ${e.message}`);
+          }
+          break;
+      }
+    }
+
+    console.log('');
+    console.log('  Uninstalled.');
+    console.log('');
+  }
+
   // ── ldm worktree ──
 
   async function cmdWorktree() {
@@ -4619,9 +4785,17 @@ async function main() {
     case 'disable':
       await cmdDisable();
       break;
-    case 'uninstall':
-      await cmdUninstall();
+    case 'uninstall': {
+      // ldm uninstall <pkg> [--dry-run]   removes one package
+      // ldm uninstall                     removes the whole LDM OS install
+      const target = args.slice(1).find(a => !a.startsWith('--'));
+      if (target) {
+        await cmdUninstallPackage(target);
+      } else {
+        await cmdUninstall();
+      }
       break;
+    }
     case 'worktree':
       await cmdWorktree();
       break;

package/docs/universal-installer/README.md

@@ -68,7 +68,7 @@ If I say yes, run: ldm install --dry-run
 Show me exactly what will change. Don't install anything until I say "install".
 ```
 
-See [TECHNICAL.md](TECHNICAL.md) for sensors/actuators, the interface table, and real examples.
+See [SPEC.md](SPEC.md) for the architecture layers, the **eight interfaces** (CLI, Module, MCP local stdio, Remote MCP, OpenClaw Plugin, Skill, Claude Code Hook, Claude Code Plugin), the install spec URL convention, track flags (alpha/beta), and the `agent.txt` distinction. See [TECHNICAL.md](TECHNICAL.md) for sensors/actuators, the interface table, and real examples.
 
 ---
 

package/docs/universal-installer/SPEC.md

@@ -4,7 +4,29 @@ Every tool is a sensor, an actuator, or both. Every tool should be accessible th
 
 This is the spec.
 
-## The Six Interfaces
+## Architecture Layers
+
+Five layers. Each one does one job. Together they let any AI safely consume any product.
+
+| Layer | What it is | Where it lives |
+|-------|-----------|----------------|
+| **Interface** | What a product exposes (CLI, MCP, Skill, etc.). Eight kinds, listed below in canonical order. | The product repo. |
+| **Installer** | Detects a product's interfaces and installs them all. `ldm install`. Stable, alpha, and beta tracks via flags. | `wip-ldm-os` (`bin/ldm.js`). |
+| **Catalog** | Slug→source resolver (npm package, repo, registry/CLI matches, status) **plus** the trust surface: provenance, version pinning, permission scopes, audits, install/update/revocation. Stays human-readable and browseable as a fallback discovery surface; not the primary steering wheel. | `catalog.json` at the LDM OS root. |
+| **Install Spec** | Agent-readable install runbook published at `wip.computer/install/<slug>.txt`. Track-neutral. Teaches an AI to safely check, explain, dry-run, install, update, and pair the product. | `https://wip.computer/install/<slug>.txt`. See [Install Spec](#install-spec). |
+| **Stacks** | Multi-product bundles. One install brings up several products and their MCP servers. | `catalog.json.stacks`. |
+
+Use the install spec URL to learn the safe install flow; use catalog to resolve the slug; use `ldm install` with stable/alpha/beta track flags; installer detects and installs the product's declared interfaces; stacks install bundles.
+
+### Primary flow
+
+The user's path is **outcome → agent resolves services → install specs / catalog / auth → bespoke artifact**. Not "browse a plugin store and pick one." The catalog stays browseable for the times a user wants to look around, but it is no longer the steering wheel. The steering wheel is the user's stated outcome and the agent's composition.
+
+**Personal context** (goals, preferences, prior experiments, constraints) does not come from this spec. It comes from **Memory Crystal**, a sibling LDM OS component. The universal-installer spec describes how *services* expose themselves; Memory Crystal describes how the *agent* knows you. Both feed the bespoke composition.
+
+## The Eight Interfaces
+
+The canonical order is fixed: CLI (1), Module (2), MCP Server local stdio (3), Remote MCP (4), OpenClaw Plugin (5), Skill (6), Claude Code Hook (7), Claude Code Plugin (8). Local and Remote MCP sit next to each other because they are sibling transports of the same protocol. Claude Code Plugin sits last because it bundles the others.
 
 ### 1. CLI
 
@@ -45,15 +67,15 @@ An importable ES module. The programmatic interface. Other tools compose with it
 }
 ```
 
-### 3. MCP Server
+### 3. MCP Server (local stdio)
 
-A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible agent can use it.
+A JSON-RPC server implementing the Model Context Protocol over stdio. Spawned as a child process by the agent (Claude Code, Cursor, OpenClaw). For the HTTP/SSE sibling, see [#4 Remote MCP](#4-remote-mcp).
 
 **Convention:** `mcp-server.mjs` (or `.js`, `.ts`) at the repo root. Uses `@modelcontextprotocol/sdk`.
 
 **Detection:** One of `mcp-server.mjs`, `mcp-server.js`, `mcp-server.ts`, `dist/mcp-server.js` exists.
 
-**Install:** Add to `.mcp.json`:
+**Install:** Add to `.mcp.json` with `command` + `args`:
 
 ```json
 {
@@ -64,7 +86,51 @@ A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible ag
 }
 ```
 
-### 4. OpenClaw Plugin
+### 4. Remote MCP
+
+The HTTP/SSE (or streamable HTTP) sibling of #3. Hosted at an HTTPS endpoint, not spawned locally. The transport that lights up Claude Desktop connectors, web, and mobile clients.
+
+**Contract:** Remote MCP endpoint is **declared by package/catalog metadata** and **registered by `ldm install`**. No filesystem-sniffing fallback.
+
+**Convention:** `mcp.remote` field in `package.json`:
+
+```json
+{
+  "mcp": {
+    "remote": {
+      "url": "https://example.com/mcp",
+      "transport": "streamable-http",
+      "auth": "oauth"
+    }
+  }
+}
+```
+
+`url` may be a placeholder (`"https://__DEPLOYED_URL__"`) when the repo ships the server code and the URL is supplied by the catalog at install time.
+
+**Detection:** `package.json.mcp.remote.url` is a string.
+
+**Install:** Add to `.mcp.json` as a remote entry (`url` + `transport` instead of `command` + `args`). Print a one-line Claude Desktop hint so the user can also add it under Connectors. Implementation tracked in [bugs/installer/](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-install.md).
+
+```json
+{
+  "tool-name": {
+    "url": "https://example.com/mcp",
+    "transport": "streamable-http"
+  }
+}
+```
+
+**How it differs from #3:** sibling transport, not a flag on #3.
+
+| | #3 Local stdio | #4 Remote |
+|---|---|---|
+| Transport | stdio (child process) | HTTPS + SSE or streamable HTTP |
+| Process model | Per-session spawn | Long-running, multi-tenant |
+| Auth | Trust the local process | OAuth or shared secret |
+| Surfaces | Claude Code, Cursor, OpenClaw | Claude Desktop, web, mobile |
+
+### 5. OpenClaw Plugin
 
 A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
@@ -74,12 +140,14 @@ A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
 **Install:** Copy to `~/.openclaw/extensions/<name>/`, run `npm install --omit=dev`.
 
-### 5. Skill (SKILL.md)
+### 6. Skill (SKILL.md)
 
 A markdown file that teaches agents when and how to use the tool. The instruction interface. Follows the [Agent Skills Spec](https://agentskills.io/specification).
 
 **Convention:** `SKILL.md` at the repo root. YAML frontmatter with name, description. Optional `references/` directory for context files.
 
+**Platform variants:** Codex CLI reads `AGENTS.md` instead of `SKILL.md`, with the same role and the same content shape. Treat `AGENTS.md` as the Codex-flavored filename for this same interface, not a separate interface. A repo may ship both (or symlink one to the other) so it works in Codex and SKILL.md-aware agents.
+
 **Detection:** `SKILL.md` exists.
 
 **Install:** `SKILL.md` deployed to `~/.openclaw/skills/<name>/`. If `references/` exists, deployed alongside SKILL.md and to `settings/docs/skills/<name>/` in the workspace.
@@ -113,7 +181,7 @@ metadata:
 ---
 ```
 
-### 6. Claude Code Hook
+### 7. Claude Code Hook
 
 A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
 
@@ -138,6 +206,58 @@ A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
 }
 ```
 
+### 8. Claude Code Plugin
+
+A distributable plugin for Claude Code. Bundles skills, agents, hooks, MCP servers, and LSP servers into one installable package. Shareable via marketplaces.
+
+**Convention:** `.claude-plugin/plugin.json` at the repo root.
+
+**Detection:** `.claude-plugin/plugin.json` exists.
+
+**Install:** Registered with Claude Code via `/plugin install` or marketplace.
+
+```
+your-plugin/
+├── .claude-plugin/
+│   └── plugin.json   # manifest (name, version, description)
+├── skills/           # SKILL.md files
+├── agents/           # subagent definitions
+├── hooks/
+│   └── hooks.json    # event handlers
+├── .mcp.json         # MCP server configs
+└── .lsp.json         # LSP server configs
+```
+
+```json
+{
+  "name": "your-plugin",
+  "version": "1.0.0",
+  "description": "What it does",
+  "author": { "name": "Your Name" }
+}
+```
+
+### Out of scope by design
+
+**Disposable, agent-generated artifacts** (custom dashboards, ephemeral scripts, one-off automations, the 300-line cardio tracker someone vibe-codes in an hour) are out of scope for this spec. They are products of an agent, not Universal Interface products. The eight interfaces describe what the agent has to *compose with*. The composition output is not itself a numbered interface and never will be.
+
+### Worked example (compact sketch)
+
+User says: *"Help me track my resting heart rate over the next 8 weeks. Goal: 50 → 45 bpm. Zone 2 cardio + 1 HIIT/week."*
+
+The agent:
+
+1. Reads personal context from Memory Crystal (RHR baseline, prior experiments, units preference).
+2. Resolves the treadmill via catalog → install spec URL → declared Remote MCP (#4) for workout data.
+3. Pulls calendar/time semantics for the 8-week window.
+4. Composes a disposable dashboard (~300 lines).
+
+The dashboard is **not** a Universal Interface product. It is the agent's output, assembled from agent-native sensors and actuators. Full version of this example is tracked separately ... see [bugs/installer/2026-04-28--cc-mini--installer-cardio-tracker-worked-example.md](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-cardio-tracker-worked-example.md).
+
+### Future considerations
+
+*LSP as a standalone interface (#9).* LSP servers are currently surfaced via Claude Code Plugin bundles (#8) ... `.lsp.json` is part of the plugin shape. If a product ships a standalone LSP server outside a CC Plugin, we will add it as a numbered interface. Not added today because no WIP product ships one yet, and the spec should describe interfaces we install and use, not interfaces software could theoretically have.
+
 ## Architecture
 
 Every repo that follows this spec has the same basic structure:
@@ -153,9 +273,9 @@ your-tool/
   ai/                  development process (plans, todos, notes)
 ```
 
-Not every tool needs all six interfaces. Build the ones that make sense.
+Not every tool needs all eight interfaces. Build the ones that make sense.
 
-The minimum viable agent-native tool has two interfaces: **Module** (importable) and **Skill** (agent instructions). Add CLI for humans. Add MCP for agents that speak MCP. Add OpenClaw/CC Hook for specific platforms.
+The minimum viable agent-native tool has two interfaces: **Module** (importable) and **Skill** (agent instructions). Add CLI for humans. Add local MCP (#3) for agents that speak MCP over stdio. Add Remote MCP (#4) when you want Claude Desktop / web / mobile to reach the same server. Add OpenClaw Plugin / CC Hook / CC Plugin for specific platforms.
 
 ## The `ai/` Folder
 
@@ -175,20 +295,73 @@ The `ai/` folder is the development process. It is not part of the published pro
 
 **Public/private split:** If a repo is public, the `ai/` folder should not ship. The recommended pattern is to maintain a private working repo (with `ai/`) and a public repo (everything except `ai/`). The public repo has everything an LLM or human needs to understand and use the tool. The `ai/` folder is operational context for the team building it.
 
-## The Reference Installer
+## The Installer
 
-`ldm install` is the primary installer (part of LDM OS). `wip-install` is the standalone fallback. Both scan a repo, detect which interfaces exist, and install them all. One command.
+`ldm install` is the primary installer (part of LDM OS). `wip-install` is the standalone fallback. Both scan a repo or slug, detect which interfaces exist, and install them all. One command.
 
 ```bash
-ldm install /path/to/repo           # local (via LDM OS)
-ldm install org/repo                # from GitHub
-ldm install org/repo --dry-run      # detect only
-wip-install /path/to/repo           # standalone fallback (bootstraps LDM OS if needed)
-wip-install --json /path/to/repo    # JSON output
+ldm install /path/to/repo               # local (via LDM OS)
+ldm install org/repo                    # from GitHub
+ldm install <slug>                      # from catalog (stable, default)
+ldm install --alpha <slug>              # alpha (validation track)
+ldm install --beta <slug>               # beta (validation track)
+ldm install <slug> --dry-run            # detect only, no changes
+wip-install /path/to/repo               # standalone fallback (bootstraps LDM OS if needed)
+wip-install --json /path/to/repo        # JSON output
 ```
 
+Tracks select the npm dist-tag (or git ref) the installer pulls from. The same install spec URL covers all three; the AI follows the spec, the user (or releasing agent) picks the track via flag.
+
 For toolbox repos (with a `tools/` directory containing sub-tools), the installer enters toolbox mode and installs each sub-tool.
 
+## Install Spec
+
+An **install spec** is an agent-readable install runbook published at a stable URL:
+
+```
+https://wip.computer/install/<slug>.txt
+```
+
+The contract is the URL and the behavior, not the file origin. An install spec can be generated from `SKILL.md`, mirrored from it, or live alongside it. What matters is that any AI can fetch it, read it, and walk a user through a safe install.
+
+### Behavior contract
+
+The spec teaches an AI to:
+
+1. **Check** whether the product is already installed and at what version.
+2. **Explain** what the product is, what it installs, and what changes for this AI and the user's other AIs.
+3. **Dry-run** so the user sees what will change before anything is touched.
+4. **Install** only after explicit user consent.
+5. **Update** an existing install (skip steps the user already did).
+6. **Pair** any post-install steps (passkey, device pairing, gateway start, etc.) with explicit consent at each step.
+
+### Tracks
+
+One install spec covers all release tracks. The user picks via flag:
+
+| Track | Flag | Audience |
+|-------|------|----------|
+| Stable | (default) `ldm install <slug>` | End users. Owner-dogfooded. |
+| Beta | `ldm install --beta <slug>` | Validation; agents may install. |
+| Alpha | `ldm install --alpha <slug>` | Validation; agents may install. |
+
+The spec text itself is track-neutral. Tracks are an installer concern, not a copy concern.
+
+### Install spec vs `agent.txt`
+
+These are related, not the same. Both are agent-readable. They sit at different scopes:
+
+- **`agent.txt`** ... site- or product-level entrypoint for agents. "What can agents do here? What routes exist? What policies apply?" Lives at the root of a site or product (e.g. `wip.computer/agent.txt`).
+- **`install/<slug>.txt`** ... per-product install runbook. "How should an agent safely check, explain, dry-run, install, update, and pair this product?" Lives under `wip.computer/install/`.
+
+`agent.txt` can point agents at install specs. An install spec does not replace `agent.txt`.
+
+### Worked example: Codex Remote Control
+
+Install spec: [`https://wip.computer/install/wip-codex-remote-control.txt`](https://wip.computer/install/wip-codex-remote-control.txt).
+
+The user pastes one prompt into Codex (or any AI). The AI fetches the install spec, checks installed state, explains the product, runs `ldm install --dry-run wip-codex-remote-control`, and only installs (and starts the daemon, and pairs the phone) after the user says yes at each step. Tracks are selected by flag against the same URL.
+
 ## Examples
 
 ### AI DevOps Toolbox (this repo)

package/docs/universal-installer/TECHNICAL.md

@@ -18,23 +18,24 @@ Every tool is a sensor, an actuator, or both. Every tool should be accessible th
 - Guard a file from edits (wip-file-guard)
 - Generate a video (wip-grok generate_video)
 
-## The Seven Interfaces
+## The Eight Interfaces
 
-Agents don't all speak the same language. Some run shell commands. Some import modules. Some talk MCP. Some read markdown instructions.
+Agents don't all speak the same language. Some run shell commands. Some import modules. Some talk MCP over stdio. Some talk MCP over HTTPS. Some read markdown instructions.
 
 So every tool should expose multiple interfaces into the same core logic:
 
-| Interface | What | Who uses it |
-|-----------|------|-------------|
-| **CLI** | Shell command | Humans, any agent with bash |
-| **Module** | ES import | Other tools, scripts |
-| **MCP Server** | JSON-RPC over stdio | Claude Code, Cursor, any MCP client |
-| **OpenClaw Plugin** | Lifecycle hooks + tools | OpenClaw agents |
-| **Skill** | Markdown instructions (SKILL.md) | Any agent that reads files |
-| **Claude Code Hook** | PreToolUse/Stop events | Claude Code |
-| **Claude Code Plugin** | Distributable package (skills, agents, hooks, MCP, LSP) | Claude Code marketplace |
+| # | Interface | What | Who uses it |
+|---|-----------|------|-------------|
+| 1 | **CLI** | Shell command | Humans, any agent with bash |
+| 2 | **Module** | ES import | Other tools, scripts |
+| 3 | **MCP Server (local stdio)** | JSON-RPC over stdio | Claude Code, Cursor, OpenClaw |
+| 4 | **Remote MCP** | JSON-RPC over HTTPS (SSE / streamable HTTP) | Claude Desktop, web, mobile |
+| 5 | **OpenClaw Plugin** | Lifecycle hooks + tools | OpenClaw agents |
+| 6 | **Skill** | Markdown instructions (SKILL.md) | Any agent that reads files |
+| 7 | **Claude Code Hook** | PreToolUse/Stop events | Claude Code |
+| 8 | **Claude Code Plugin** | Distributable package (skills, agents, hooks, MCP, LSP) | Claude Code marketplace |
 
-Not every tool needs all seven. Build what makes sense. But the more interfaces you expose, the more agents can use your tool.
+Not every tool needs all eight. Build what makes sense. But the more interfaces you expose, the more agents can use your tool. Local and Remote MCP are sibling transports of the same protocol; they sit next to each other so the relationship is obvious.
 
 ### 1. CLI
 
@@ -75,15 +76,15 @@ An importable ES module. The programmatic interface. Other tools compose with it
 }
 ```
 
-### 3. MCP Server
+### 3. MCP Server (local stdio)
 
-A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible agent can use it.
+A JSON-RPC server implementing the Model Context Protocol over stdio. Spawned as a child process by the agent. For the HTTP/SSE sibling, see [#4 Remote MCP](#4-remote-mcp).
 
 **Convention:** `mcp-server.mjs` (or `.js`, `.ts`) at the repo root. Uses `@modelcontextprotocol/sdk`.
 
 **Detection:** One of `mcp-server.mjs`, `mcp-server.js`, `mcp-server.ts`, `dist/mcp-server.js` exists.
 
-**Install:** Add to `.mcp.json`:
+**Install:** Add to `.mcp.json` with `command` + `args`:
 
 ```json
 {
@@ -94,7 +95,46 @@ A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible ag
 }
 ```
 
-### 4. OpenClaw Plugin
+### 4. Remote MCP
+
+The HTTP/SSE (or streamable HTTP) sibling of #3. Hosted at an HTTPS endpoint, not spawned locally. The transport that lights up Claude Desktop connectors, web, and mobile clients.
+
+**Contract:** Remote MCP endpoint is **declared by package/catalog metadata** and **registered by `ldm install`**. No filesystem-sniffing fallback.
+
+**Convention:** `mcp.remote` field in `package.json`:
+
+```json
+{
+  "mcp": {
+    "remote": {
+      "url": "https://example.com/mcp",
+      "transport": "streamable-http",
+      "auth": "oauth"
+    }
+  }
+}
+```
+
+`url` may be a placeholder (`"https://__DEPLOYED_URL__"`) when the repo ships the server code and the catalog supplies the URL at install time.
+
+**Detection:** `package.json.mcp.remote.url` is a string.
+
+**Install:** Add to `.mcp.json` as a remote entry, plus print a one-line Claude Desktop hint:
+
+```json
+{
+  "tool-name": {
+    "url": "https://example.com/mcp",
+    "transport": "streamable-http"
+  }
+}
+```
+
+**Auth:** `none` writes the URL as-is. `shared-secret` prompts the user once and stores out-of-band. `oauth` is gated behind a follow-up ticket; first cut prints a TODO.
+
+**Implementation status:** detection + install action are tracked in `ai/product/bugs/installer/` (see [Remote MCP detection](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-detection.md) and [Remote MCP install](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-install.md)). The spec is canonical now; the detector and installer catch up next.
+
+### 5. OpenClaw Plugin
 
 A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
@@ -104,12 +144,14 @@ A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
 
 **Install:** Copy to `~/.openclaw/extensions/<name>/`, run `npm install --omit=dev`.
 
-### 5. Skill (SKILL.md)
+### 6. Skill (SKILL.md)
 
 A markdown file that teaches agents when and how to use the tool. The instruction interface. Follows the [Agent Skills Spec](https://agentskills.io/specification).
 
 **Convention:** `SKILL.md` at the repo root. Optional `references/` directory for context files.
 
+**Platform variants:** Codex CLI reads `AGENTS.md` with the same role and content shape. Treat as the Codex-flavored filename for this same interface, not a separate one.
+
 **Detection:** `SKILL.md` exists.
 
 **Install:** `ldm install` deploys `SKILL.md` to `~/.openclaw/skills/<name>/`. If `references/` exists, it is deployed alongside and also to `settings/docs/skills/<name>/` in the workspace (so all agents can read them).
@@ -132,7 +174,7 @@ metadata:
 ---
 ```
 
-### 6. Claude Code Hook
+### 7. Claude Code Hook
 
 A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
 
@@ -157,7 +199,7 @@ A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
 }
 ```
 
-### 7. Claude Code Plugin
+### 8. Claude Code Plugin
 
 A distributable plugin for Claude Code. Bundles skills, agents, hooks, MCP servers, and LSP servers into one installable package. Shareable via marketplaces.
 
@@ -188,6 +230,14 @@ your-plugin/
 }
 ```
 
+### Out of scope by design
+
+Disposable, agent-generated artifacts (custom dashboards, ephemeral scripts, one-off automations) are out of scope for this spec. They are products of an agent, not Universal Interface products. The eight interfaces describe what the agent has to *compose with*. Worked example: [SPEC.md ... Worked example (compact sketch)](SPEC.md#worked-example-compact-sketch).
+
+### Future considerations
+
+*LSP as a standalone interface (#9).* LSP servers are currently surfaced via Claude Code Plugin bundles (#8) ... `.lsp.json` is part of the plugin shape. If a product ships a standalone LSP server outside a CC Plugin, we will add it as a numbered interface. Not added today.
+
 ## How to Build It
 
 The architecture is simple. Four files:
@@ -206,30 +256,33 @@ This means one codebase, one set of tests, multiple interfaces.
 
 ## Install Prompt Template
 
-Every product gets an install prompt. Paste it into any AI. The AI reads the spec, explains it, checks what's installed, and walks you through a dry run.
+Every product gets an install prompt. Paste it into any AI. The AI reads the install spec, explains the product, checks what's installed, and walks you through a dry run before touching anything.
+
+The install spec URL convention, behavior contract, track flags, and `agent.txt` distinction are defined in [SPEC.md ... Install Spec](SPEC.md#install-spec). This is the canonical paste-into-an-AI form:
 
 ```
-Read wip.computer/install/{URL}
+Read https://wip.computer/install/<slug>.txt
 
-Then explain:
-1. What is {name of product}?
+Check if <product name> is already installed. If it is, run
+`ldm install --dry-run <slug>` and show me what I have and what's new.
+
+If not, walk me through setup and explain:
+1. What is <product name>?
 2. What does it install on my system?
 3. What changes for us? (this AI)
 4. What changes across all my AIs?
 
-Check if {name of product} is already installed.
-
-If it is, show me what I have and what's new.
-
 Then ask:
 - Do you have questions?
 - Want to see a dry run?
 
-If I say yes, run: {product-init} init --dry-run
+If I say yes, run: ldm install --dry-run <slug>
 
 Show me exactly what will change. Don't install anything until I say "install".
 ```
 
+Tracks: append `--alpha` or `--beta` to install a prerelease (e.g. `ldm install --beta <slug>`). The same install spec URL covers all tracks.
+
 ## The `ai/` Folder
 
 Every repo should have an `ai/` folder. This is where agents and humans collaborate on the project ... plans, todos, dev updates, research notes, conversations.
@@ -308,7 +361,8 @@ ldm install                            # update all
 |---------|-----------|---------------|
 | `package.json` with `bin` | CLI | `npm install -g` |
 | `main` or `exports` in `package.json` | Module | Reports import path |
-| `mcp-server.mjs` | MCP | Prints `.mcp.json` config |
+| `mcp-server.mjs` | MCP (local stdio) | Adds `command` + `args` entry to `.mcp.json` |
+| `mcp.remote.url` in `package.json` | Remote MCP | Adds `url` + `transport` entry to `.mcp.json`; prints Claude Desktop hint. **Implementation in flight ([ticket](../../ai/product/bugs/installer/2026-04-28--cc-mini--installer-remote-mcp-detection.md)).** |
 | `openclaw.plugin.json` | OpenClaw | Copies to `~/.openclaw/extensions/` |
 | `SKILL.md` | Skill | Reports path |
 | `guard.mjs` or `claudeCode.hook` | CC Hook | Adds to `~/.claude/settings.json` |
@@ -323,6 +377,7 @@ ldm install                            # update all
 | [wip-file-guard](https://github.com/wipcomputer/wip-ai-devops-toolbox/tree/main/tools/wip-file-guard) | Actuator | CLI + OpenClaw + CC Hook | Protect files from AI edits |
 | [wip-healthcheck](https://github.com/wipcomputer/wip-healthcheck) | Sensor | CLI + Module | System health monitoring |
 | [wip-markdown-viewer](https://github.com/wipcomputer/wip-markdown-viewer) | Actuator | CLI + Module | Live markdown viewer |
+| [wip-codex-remote-control](https://wip.computer/install/wip-codex-remote-control.txt) | Sensor + Actuator | CLI + Module + MCP + Skill + Install Spec | Pair phone with Codex; AI-led install via published install spec. Worked example of the install-spec URL pattern. |
 
 ## Supported Tools
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.83",
+  "version": "0.4.85-alpha.1",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "engines": {

package/src/hosted-mcp/nginx/codex-relay.conf

@@ -0,0 +1,109 @@
+# Codex Remote Control relay
+#
+# Routes /api/codex-relay/* to the wip-mcp Node app at 127.0.0.1:18800.
+# Without these blocks nginx falls back to /index.html and the phone-side
+# bootstrap + ws-ticket calls receive HTML, which breaks the E2EE handshake
+# and the relay attach flow.
+#
+# Owners: this snippet pairs with src/hosted-mcp/server.mjs codex-relay
+# routes and the kaleidoscope-private phone surface. See
+# wip-ldm-os-private/ai/product/plans-prds/codex-remote-control/
+# for the full architecture.
+#
+# Include from inside the wip.computer server block.
+
+# ── HTTP routes ──────────────────────────────────────────────────────
+# bootstrap (GET) ... phone reads daemon E2EE pubkey + presence
+location /api/codex-relay/bootstrap/ {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
+# ws-ticket (POST) ... single-use, route-bound, 60s TTL
+location /api/codex-relay/ws-ticket {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
+# state (GET) ... daemon presence diagnostic
+location /api/codex-relay/state {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
+# pair-init (POST) ... codex-daemon link starts here
+location /api/codex-relay/pair-init {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
+# pair-status (GET) ... daemon polls during pair flow
+location /api/codex-relay/pair-status/ {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
+# pair-complete (POST) ... phone -> server after passkey + code
+location /api/codex-relay/pair-complete {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+
+# ── WebSocket routes ────────────────────────────────────────────────
+# Standard nginx WebSocket pattern: Upgrade + Connection "upgrade", long
+# read/send timeout for daemon's persistent socket, buffering off so
+# streamed Codex events don't pool.
+
+# Phone side ... attached with ?ticket=<single-use>
+location /api/codex-relay/web/ {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 86400;
+    proxy_send_timeout 86400;
+    proxy_buffering off;
+}
+
+# Daemon side ... long-lived presence socket from the user's Mac
+location /api/codex-relay/daemon {
+    proxy_pass http://127.0.0.1:18800;
+    proxy_http_version 1.1;
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_read_timeout 86400;
+    proxy_send_timeout 86400;
+    proxy_buffering off;
+}

package/src/hosted-mcp/nginx/wip.computer.conf

@@ -7,6 +7,68 @@ server {
     access_log /var/log/nginx/wip.computer.access.log;
     error_log /var/log/nginx/wip.computer.error.log;
 
+    # Docs redirect to docs.wip.computer
+    location = /doc {
+        return 301 https://docs.wip.computer;
+    }
+    location = /docs {
+        return 301 https://docs.wip.computer;
+    }
+    location /docs/ {
+        return 301 https://docs.wip.computer;
+    }
+
+    # MCP server
+    # OAuth 2.0 for Claude iOS connector
+    include snippets/mcp-oauth.conf;
+    include snippets/mcp-server.conf;
+
+    # Codex Remote Control relay (HTTP + WSS proxy_pass to wip-mcp Node app
+    # at 127.0.0.1:18800; covers /api/codex-relay/bootstrap, ws-ticket, state,
+    # pair-init/status/complete, web/<tid>, daemon).
+    include snippets/codex-relay.conf;
+
+    # Codex Remote Control phone surface
+    # The Next.js app at kaleidoscope.wip.computer (port 3001) renders
+    # /codex-remote-control/[threadId]. The MCP tool's auth URL uses
+    # wip.computer as the origin, so wip.computer/codex-remote-control/<tid>
+    # must reach the same Next.js app. WebSocket Upgrade headers included
+    # so live-reload / RSC streams work cleanly.
+    location /codex-remote-control/ {
+        proxy_pass http://127.0.0.1:3001;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
+    # Health check
+    location /health {
+        proxy_pass http://127.0.0.1:18800/health;
+        proxy_http_version 1.1;
+    }
+
+
+    # Demo pages (static files)
+    location /demo {
+        alias /var/www/wip.computer/app/mcp-server/demo;
+        index index.html;
+        try_files $uri $uri/ $uri/index.html =404;
+    }
+
+    # Demo API (proxied to MCP server)
+    location /demo/api/ {
+        proxy_pass http://127.0.0.1:18800/demo/api/;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+
     location / {
         autoindex off;
         try_files $uri $uri/ /index.html;

package/src/hosted-mcp/app/codex-remote-control/index.html

@@ -1,254 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
-<title>Codex remote control</title>
-<style>
-  *, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
-  :root {
-    --bg: #FFFDF5;
-    --bg-event: #F5F3ED;
-    --bg-tool: #F0EDE6;
-    --text: #1a1a1a;
-    --text-muted: #8a8580;
-    --accent: #0033FF;
-    --danger: #b00020;
-    --border: #E0DDD6;
-    --user-bubble: #E8F0FE;
-    --font: -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
-    --mono: ui-monospace, "SF Mono", Menlo, monospace;
-  }
-  html, body { height: 100%; font-family: var(--font); background: var(--bg); color: var(--text); }
-  body { display: flex; flex-direction: column; }
-  header { padding: 12px 16px; padding-top: calc(12px + env(safe-area-inset-top, 0px)); border-bottom: 1px solid var(--border); display: flex; align-items: center; gap: 10px; }
-  header .id { flex: 1; font-size: 13px; color: var(--text-muted); font-family: var(--mono); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-  header .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--text-muted); }
-  header .dot.online { background: #2ea44f; }
-  header .dot.offline { background: var(--danger); }
-  main { flex: 1; overflow-y: auto; padding: 16px; padding-bottom: 0; -webkit-overflow-scrolling: touch; }
-  .event { margin-bottom: 12px; padding: 12px 14px; border-radius: 10px; background: var(--bg-event); font-size: 14px; line-height: 1.45; }
-  .event .meta { font-size: 11px; color: var(--text-muted); font-family: var(--mono); margin-bottom: 4px; text-transform: uppercase; letter-spacing: 0.05em; }
-  .event.user { background: var(--user-bubble); }
-  .event.agent_message { background: var(--bg); border: 1px solid var(--border); }
-  .event.command_execution { background: var(--bg-tool); font-family: var(--mono); white-space: pre-wrap; word-break: break-all; }
-  .event.command_execution.failed { border-left: 3px solid var(--danger); }
-  .event.error { background: #fff0f0; border: 1px solid #f0c0c0; color: var(--danger); }
-  .event.system { background: transparent; color: var(--text-muted); font-size: 12px; padding: 6px 0; text-align: center; }
-  .event pre { font-family: var(--mono); white-space: pre-wrap; word-break: break-word; font-size: 13px; }
-  footer { padding: 12px; padding-bottom: calc(12px + env(safe-area-inset-bottom, 0px)); border-top: 1px solid var(--border); background: var(--bg); }
-  .composer { display: flex; gap: 8px; align-items: flex-end; }
-  textarea {
-    flex: 1; min-height: 44px; max-height: 120px; padding: 12px;
-    border: 1px solid var(--border); border-radius: 10px;
-    background: var(--bg); color: var(--text); font-family: var(--font); font-size: 16px;
-    resize: none;
-  }
-  textarea:focus { outline: 2px solid var(--accent); outline-offset: -1px; }
-  button { padding: 12px 16px; border: none; border-radius: 10px; font-family: var(--font); font-size: 14px; font-weight: 600; cursor: pointer; -webkit-tap-highlight-color: transparent; }
-  button:active { transform: scale(0.97); }
-  button:disabled { opacity: 0.4; cursor: not-allowed; }
-  .btn-send { background: var(--accent); color: white; }
-  .btn-stop { background: var(--danger); color: white; }
-</style>
-</head>
-<body>
-<header>
-  <div class="dot" id="presence" title="connecting"></div>
-  <div class="id" id="threadId">...</div>
-  <button id="stopBtn" class="btn-stop" type="button" disabled>Stop</button>
-</header>
-<main id="log"></main>
-<footer>
-  <form class="composer" id="composer">
-    <textarea id="prompt" rows="1" placeholder="Tell Codex what to do..." autocomplete="off"></textarea>
-    <button type="submit" class="btn-send" id="sendBtn">Send</button>
-  </form>
-</footer>
-<script>
-function getApiKey() { return sessionStorage.getItem("wip_api_key"); }
-function getHandle() { return sessionStorage.getItem("wip_handle") || ""; }
-
-function ensureSignedIn() {
-  if (!getApiKey()) {
-    location.href = "/app/login.html?next=" + encodeURIComponent(location.pathname);
-    return false;
-  }
-  return true;
-}
-
-function parsePath() {
-  // /:handle/codex-remote-control/:threadId
-  const m = location.pathname.match(/^\/([^/]+)\/codex-remote-control\/([^/]+)\/?$/);
-  if (!m) return null;
-  return { handle: decodeURIComponent(m[1]), threadId: decodeURIComponent(m[2]) };
-}
-
-function setPresence(state) {
-  const dot = document.getElementById("presence");
-  dot.classList.remove("online", "offline");
-  if (state === "online") dot.classList.add("online");
-  if (state === "offline") dot.classList.add("offline");
-  dot.title = state;
-}
-
-function appendEvent(html, kind) {
-  const log = document.getElementById("log");
-  const div = document.createElement("div");
-  div.className = "event " + (kind || "");
-  div.innerHTML = html;
-  log.appendChild(div);
-  log.scrollTop = log.scrollHeight;
-  return div;
-}
-
-function escapeHtml(s) {
-  return String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&#39;" }[c]));
-}
-
-function renderItem(item) {
-  if (item.type === "agent_message") {
-    return appendEvent('<div class="meta">codex</div>' + escapeHtml(item.text || "").replace(/\n/g, "<br>"), "agent_message");
-  }
-  if (item.type === "command_execution") {
-    const status = (item.status || "").toString();
-    const out = item.aggregated_output ? '\n\n' + item.aggregated_output : "";
-    return appendEvent(
-      '<div class="meta">$ ' + escapeHtml(status) + (item.exit_code != null ? " (exit " + item.exit_code + ")" : "") + '</div>' +
-      '<pre>' + escapeHtml(item.command || "") + escapeHtml(out) + '</pre>',
-      "command_execution" + (status === "failed" ? " failed" : ""),
-    );
-  }
-  if (item.type === "reasoning") {
-    return appendEvent('<div class="meta">reasoning</div>' + escapeHtml(item.text || ""), "reasoning");
-  }
-  return appendEvent('<div class="meta">' + escapeHtml(item.type || "item") + '</div><pre>' + escapeHtml(JSON.stringify(item, null, 2)) + '</pre>', "item");
-}
-
-let ws = null;
-let pendingId = 1;
-
-function send(req) {
-  if (!ws || ws.readyState !== WebSocket.OPEN) return;
-  ws.send(JSON.stringify(req));
-}
-
-function connect(threadId) {
-  const apiKey = getApiKey();
-  const proto = location.protocol === "https:" ? "wss:" : "ws:";
-  const url = proto + "//" + location.host + "/api/codex-relay/web/" + encodeURIComponent(threadId) + "?token=" + encodeURIComponent(apiKey);
-  ws = new WebSocket(url);
-
-  ws.addEventListener("open", () => {
-    setPresence("online");
-    appendEvent("connected. open this thread in Codex on your Mac if it's not already.", "system");
-  });
-
-  ws.addEventListener("close", (ev) => {
-    setPresence("offline");
-    appendEvent("disconnected (code " + ev.code + ")", "system");
-  });
-
-  ws.addEventListener("error", () => {
-    setPresence("offline");
-  });
-
-  ws.addEventListener("message", (ev) => {
-    let msg;
-    try { msg = JSON.parse(ev.data); } catch { return; }
-    if (msg.type === "session.started") {
-      // Daemon assigned a temp id; the real thread id will arrive in thread.started.
-      return;
-    }
-    if (msg.type === "session.event") {
-      const evt = msg.event || {};
-      if (evt.type === "thread.started") {
-        // ok
-        return;
-      }
-      if (evt.type === "turn.started") {
-        document.getElementById("stopBtn").disabled = false;
-        return;
-      }
-      if (evt.type === "item.completed" && evt.item) {
-        renderItem(evt.item);
-        return;
-      }
-      if (evt.type === "item.started") {
-        return; // skip; we render on completed for now
-      }
-      if (evt.type === "turn.completed") {
-        document.getElementById("stopBtn").disabled = true;
-        const u = evt.usage;
-        if (u) appendEvent("turn complete (" + (u.input_tokens || 0) + " in / " + (u.output_tokens || 0) + " out)", "system");
-        else appendEvent("turn complete", "system");
-        return;
-      }
-      if (evt.type === "turn.failed") {
-        document.getElementById("stopBtn").disabled = true;
-        appendEvent("turn failed: " + (evt.error && evt.error.message ? evt.error.message : "unknown"), "error");
-        return;
-      }
-      return;
-    }
-    if (msg.type === "ack") return;
-    if (msg.type === "error") {
-      appendEvent("error: " + (msg.message || ""), "error");
-      return;
-    }
-  });
-}
-
-function init() {
-  if (!ensureSignedIn()) return;
-  const parsed = parsePath();
-  if (!parsed) {
-    appendEvent("Invalid URL. Expected /<handle>/codex-remote-control/<thread-id>.", "error");
-    return;
-  }
-  document.getElementById("threadId").textContent = parsed.threadId;
-  connect(parsed.threadId);
-
-  // Open or attach to the session on the daemon. session.start returns a temp
-  // sessionId; the actual thread.id arrives via thread.started in the stream.
-  setTimeout(() => {
-    send({ type: "session.start", id: "open-" + (pendingId += 1) });
-  }, 250);
-
-  document.getElementById("composer").addEventListener("submit", (ev) => {
-    ev.preventDefault();
-    const input = document.getElementById("prompt");
-    const text = input.value.trim();
-    if (!text) return;
-    input.value = "";
-    appendEvent('<div class="meta">you</div>' + escapeHtml(text), "user");
-    send({
-      type: "session.send",
-      id: "send-" + (pendingId += 1),
-      sessionId: parsed.threadId,
-      prompt: text,
-    });
-  });
-
-  document.getElementById("stopBtn").addEventListener("click", () => {
-    send({ type: "session.interrupt", id: "stop-" + (pendingId += 1), sessionId: parsed.threadId });
-  });
-
-  // Submit on Cmd+Enter / Ctrl+Enter; auto-resize.
-  const ta = document.getElementById("prompt");
-  ta.addEventListener("input", () => {
-    ta.style.height = "auto";
-    ta.style.height = Math.min(120, ta.scrollHeight) + "px";
-  });
-  ta.addEventListener("keydown", (ev) => {
-    if ((ev.metaKey || ev.ctrlKey) && ev.key === "Enter") {
-      ev.preventDefault();
-      document.getElementById("composer").requestSubmit();
-    }
-  });
-}
-
-init();
-</script>
-</body>
-</html>