@wipcomputer/wip-ldm-os 0.4.1 → 0.4.3

package/README.md

@@ -1,6 +1,6 @@
 ###### WIP Computer
 
-# LDM OS
+# LDM OS: Learning Dreaming Machines
 
 ## All your AIs. One system.
 
@@ -47,23 +47,27 @@ That's it. Your AI reads the spec, explains what it does, and walks you through
 
 Ships with LDM OS.
 
+**Bridge**
+- Cross-platform agent bridge. Enables Claude Code CLI to talk to OpenClaw CLI without a human in the middle.
+- [Read more about Bridge](docs/bridge/README.md)
+
 **Universal Installer**
 - Point any skill, application, or plugin at any AI running LDM OS, and it will convert those skills to work with all of your AIs.
 - Build applications that work with any AI, even ones that don't have LDM OS.
-- [Read more about Universal Installer](docs/universal-installer.md)
+- [Read more about Universal Installer](docs/universal-installer/README.md)
 
 **Shared Workspace**
 - One directory for all your AIs. Memories, tools, identity files, boot config. Every AI you use reads from and writes to the same place.
 - Lives in one folder on your computer. Easy to back up, easy to move, easy to own.
-- [Read more about Shared Workspace](docs/shared-workspace.md)
+- [Read more about Shared Workspace](docs/shared-workspace/README.md)
 
 **System Pulse**
 - Is everything working? What's installed? What needs fixing? A complete picture of your AI setup in seconds.
-- [Read more about System Pulse](docs/system-pulse.md)
+- [Read more about System Pulse](docs/system-pulse/README.md)
 
 **Recall**
 - Every session, your AI starts with full context. Identity, memory, tools, what happened yesterday. No blank slates. No repeating yourself.
-- [Read more about Recall](docs/recall.md)
+- [Read more about Recall](docs/recall/README.md)
 
 **LUME**
 - Language for Unified Memory and Emergence. A memory language for AI agents to document their own learning and maintain continuity across sessions. Not a programming language. A way for your AI to write memories to itself, retrieve past learnings, track unfinished thoughts, and pass context between sessions.
@@ -95,11 +99,7 @@ The OS connects your AIs. Add-ons are what they actually use. Each one is a full
 - Open-source agent runtime. Run AI agents 24/7 with identity, memory, and tool access. The existence proof for LDM OS.
 - [Read more about OpenClaw](https://github.com/openclaw/openclaw)
 
-**Bridge**
-- Cross-platform agent bridge. Enables Claude Code CLI to talk to OpenClaw CLI without a human in the middle.
-- [Read more about Bridge](https://github.com/wipcomputer/wip-bridge)
-
-[See all skills](docs/optional-skills.md)
+[See all skills](docs/skills/README.md)
 
 ## More Info
 

package/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 interface: [cli, skill]
 metadata:
   display-name: "LDM OS"
-  version: "0.4.1"
+  version: "0.4.3"
   homepage: "https://github.com/wipcomputer/wip-ldm-os"
   author: "Parker Todd Brooks"
   category: infrastructure

package/bin/ldm.js

@@ -17,7 +17,7 @@
  *   ldm --version         Show version
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync } from 'node:fs';
 import { join, basename, resolve, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -146,6 +146,28 @@ function cleanStaleHooks() {
   return cleaned;
 }
 
+// ── Boot hook sync (#49) ──
+
+function syncBootHook() {
+  const srcBoot = join(__dirname, '..', 'src', 'boot', 'boot-hook.mjs');
+  const destBoot = join(LDM_ROOT, 'shared', 'boot', 'boot-hook.mjs');
+
+  if (!existsSync(srcBoot)) return false;
+
+  try {
+    const srcContent = readFileSync(srcBoot, 'utf8');
+    let destContent = '';
+    try { destContent = readFileSync(destBoot, 'utf8'); } catch {}
+
+    if (srcContent !== destContent) {
+      mkdirSync(dirname(destBoot), { recursive: true });
+      writeFileSync(destBoot, srcContent);
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
 // ── Catalog helpers ──
 
 function loadCatalog() {
@@ -172,6 +194,7 @@ async function cmdInit() {
     join(LDM_ROOT, 'messages'),
     join(LDM_ROOT, 'shared', 'boot'),
     join(LDM_ROOT, 'shared', 'cron'),
+    join(LDM_ROOT, 'hooks'),
   ];
 
   const existing = existsSync(VERSION_PATH);
@@ -230,6 +253,27 @@ async function cmdInit() {
     console.log(`  + registry.json created`);
   }
 
+  // Install global git pre-commit hook (blocks commits on main)
+  const hooksDir = join(LDM_ROOT, 'hooks');
+  const preCommitDest = join(hooksDir, 'pre-commit');
+  const preCommitSrc = join(__dirname, '..', 'templates', 'hooks', 'pre-commit');
+  if (!existsSync(hooksDir)) mkdirSync(hooksDir, { recursive: true });
+  if (existsSync(preCommitSrc)) {
+    cpSync(preCommitSrc, preCommitDest);
+    chmodSync(preCommitDest, 0o755);
+    // Set global hooksPath if not already set to somewhere else
+    try {
+      const currentHooksPath = execSync('git config --global core.hooksPath', { encoding: 'utf8' }).trim();
+      if (currentHooksPath !== hooksDir) {
+        console.log(`  ! core.hooksPath already set to ${currentHooksPath}. Not overwriting.`);
+      }
+    } catch {
+      // Not set. Set it.
+      execSync(`git config --global core.hooksPath "${hooksDir}"`);
+      console.log(`  + git pre-commit hook installed (blocks commits on main)`);
+    }
+  }
+
   console.log('');
   console.log(`  LDM OS v${PKG_VERSION} initialized at ${LDM_ROOT}`);
   console.log('');
@@ -478,7 +522,7 @@ function autoDetectExtensions() {
     const dirs = readdirSync(LDM_EXTENSIONS, { withFileTypes: true });
     for (const dir of dirs) {
       if (!dir.isDirectory()) continue;
-      if (dir.name === '_trash' || dir.name.startsWith('.')) continue;
+      if (dir.name === '_trash' || dir.name.startsWith('.') || dir.name.startsWith('ldm-install-')) continue;
 
       const extPath = join(LDM_EXTENSIONS, dir.name);
       const pkgPath = join(extPath, 'package.json');
@@ -559,14 +603,61 @@ async function cmdInstallCatalog() {
     console.log('');
   }
 
-  if (DRY_RUN) {
-    // Show what an update would do
-    const updatable = Object.values(reconciled).filter(e =>
-      e.registryHasSource
-    );
+  // Build the update plan: extensions with valid source paths + catalog items with npm updates (#55)
+  const fromSource = Object.values(reconciled).filter(e => e.registryHasSource);
 
+  // For extensions without valid source: check catalog for repo, check npm for newer version
+  const fromCatalog = [];
+  for (const [name, entry] of Object.entries(reconciled)) {
+    if (entry.registryHasSource) continue; // already handled above
+    if (!entry.deployedLdm && !entry.deployedOc) continue; // not installed
+
+    // Find this extension in the catalog
+    const catalogEntry = components.find(c => {
+      const matches = c.registryMatches || [c.id];
+      return matches.includes(name) || c.id === name;
+    });
+    if (!catalogEntry?.repo) continue;
+
+    // Check npm for newer version
+    const npmPkg = catalogEntry.npm;
+    const currentVersion = entry.ldmVersion || entry.ocVersion;
+    let latestVersion = null;
+
+    if (npmPkg && currentVersion) {
+      try {
+        latestVersion = execSync(`npm view ${npmPkg} version 2>/dev/null`, {
+          encoding: 'utf8', timeout: 10000,
+        }).trim();
+      } catch {}
+    }
+
+    const hasUpdate = latestVersion && currentVersion && latestVersion !== currentVersion;
+    fromCatalog.push({
+      ...entry,
+      catalogRepo: catalogEntry.repo,
+      catalogNpm: npmPkg,
+      currentVersion,
+      latestVersion,
+      hasUpdate,
+    });
+  }
+
+  const updatable = fromSource;
+  const npmUpdates = fromCatalog.filter(e => e.hasUpdate);
+  const totalUpdates = updatable.length + npmUpdates.length;
+
+  if (DRY_RUN) {
     if (updatable.length > 0) {
       console.log(`  Would update ${updatable.length} extension(s) from source repos.`);
+    }
+    if (npmUpdates.length > 0) {
+      console.log(`  Would update ${npmUpdates.length} extension(s) from npm:`);
+      for (const e of npmUpdates) {
+        console.log(`    ${e.name}: v${e.currentVersion} -> v${e.latestVersion} (${e.catalogNpm})`);
+      }
+    }
+    if (totalUpdates > 0) {
       console.log('  No data (crystal.db, agent files) would be touched.');
       console.log('  Old versions would be moved to ~/.ldm/_trash/ (never deleted).');
     } else {
@@ -579,18 +670,15 @@ async function cmdInstallCatalog() {
     return;
   }
 
-  // Real update: only touch things with linked source repos
-  const updatable = Object.values(reconciled).filter(e =>
-    e.registryHasSource
-  );
-
-  if (updatable.length === 0) {
-    console.log('  No extensions have linked source repos to update from.');
-    console.log('  Link them with: ldm install <org/repo>');
+  if (totalUpdates === 0 && available.length === 0) {
+    console.log('  Everything is up to date.');
     console.log('');
+    return;
+  }
 
-    // Still offer catalog install if TTY
-    if (available.length > 0 && !YES_FLAG && !NONE_FLAG && process.stdin.isTTY) {
+  if (totalUpdates === 0 && available.length > 0) {
+    // Nothing to update, but catalog items available
+    if (!YES_FLAG && !NONE_FLAG && process.stdin.isTTY) {
       const { createInterface } = await import('node:readline');
       const rl = createInterface({ input: process.stdin, output: process.stdout });
       const answer = await new Promise((resolve) => {
@@ -599,7 +687,6 @@ async function cmdInstallCatalog() {
           resolve(a.trim().toLowerCase());
         });
       });
-
       if (answer && answer !== 'none' && answer !== 'n') {
         let toInstall = [];
         if (answer === 'all' || answer === 'a') {
@@ -624,13 +711,19 @@ async function cmdInstallCatalog() {
   // Write revert manifest before starting
   const { createRevertManifest } = await import('../lib/safe.mjs');
   const manifestPath = createRevertManifest(
-    `ldm install (update ${updatable.length} extensions)`,
-    updatable.map(e => ({
-      action: 'update',
+    `ldm install (update ${totalUpdates} extensions)`,
+    [...updatable.map(e => ({
+      action: 'update-from-source',
       name: e.name,
       currentVersion: e.ldmVersion || e.registryVersion,
       source: e.registrySource,
-    }))
+    })), ...npmUpdates.map(e => ({
+      action: 'update-from-catalog',
+      name: e.name,
+      currentVersion: e.currentVersion,
+      latestVersion: e.latestVersion,
+      repo: e.catalogRepo,
+    }))]
   );
   console.log(`  Revert plan saved: ${manifestPath}`);
   console.log('');
@@ -639,13 +732,31 @@ async function cmdInstallCatalog() {
   setFlags({ dryRun: DRY_RUN, jsonOutput: JSON_OUTPUT });
 
   let updated = 0;
+
+  // Update from source repos (local paths)
   for (const entry of updatable) {
     await installFromPath(entry.registrySource);
     updated++;
   }
 
+  // Update from catalog repos (clone from GitHub for extensions without valid source) (#55)
+  for (const entry of npmUpdates) {
+    console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from ${entry.catalogRepo})...`);
+    try {
+      execSync(`ldm install ${entry.catalogRepo}`, { stdio: 'inherit' });
+      updated++;
+    } catch (e) {
+      console.error(`  x Failed to update ${entry.name}: ${e.message}`);
+    }
+  }
+
+  // Sync boot hook from npm package (#49)
+  if (syncBootHook()) {
+    ok('Boot hook updated (sessions, messages, updates now active)');
+  }
+
   console.log('');
-  console.log(`  Updated ${updated}/${updatable.length} extension(s).`);
+  console.log(`  Updated ${updated}/${totalUpdates} extension(s).`);
 
   // Check if CLI itself is outdated (#29)
   checkCliVersion();
@@ -731,6 +842,30 @@ async function cmdDoctor() {
     }
   }
 
+  // --fix: clean registry entries with /tmp/ sources or ldm-install- names (#54)
+  if (FIX_FLAG) {
+    const registry = readJSON(REGISTRY_PATH);
+    if (registry?.extensions) {
+      const staleNames = [];
+      for (const [name, info] of Object.entries(registry.extensions)) {
+        const src = info?.source || '';
+        const isTmpSource = src.startsWith('/tmp/') || src.startsWith('/private/tmp/');
+        const isTmpName = name.startsWith('ldm-install-');
+        if (isTmpSource || isTmpName) {
+          staleNames.push(name);
+        }
+      }
+      for (const name of staleNames) {
+        delete registry.extensions[name];
+        console.log(`  + Removed stale registry entry: ${name} (/tmp/ clone)`);
+        issues = Math.max(0, issues - 1);
+      }
+      if (staleNames.length > 0) {
+        writeFileSync(REGISTRY_PATH, JSON.stringify(registry, null, 2) + '\n');
+      }
+    }
+  }
+
   // 4. Check sacred locations
   const sacred = [
     { path: join(LDM_ROOT, 'memory'), label: 'memory/' },
@@ -1345,7 +1480,7 @@ async function main() {
       await cmdUpdateAll();
       break;
     case 'doctor':
-      cmdDoctor();
+      await cmdDoctor();
       break;
     case 'status':
       cmdStatus();

package/docs/acp/README.md

@@ -28,3 +28,7 @@ LDM OS does not currently implement ACP-Comm. The file-based message bus and ses
 ## License Compatibility
 
 Both protocols are Apache 2.0, fully compatible with LDM OS's MIT + AGPLv3 dual license.
+
+---
+
+[Technical Reference](./TECHNICAL.md)

package/docs/acp/TECHNICAL.md

@@ -0,0 +1,42 @@
+# ACP Compatibility ... Technical Reference
+
+## Protocols
+
+| Protocol | Full Name | Origin | License | Wire Format |
+|----------|-----------|--------|---------|-------------|
+| ACP-Client | Agent Client Protocol | Zed Industries | Apache 2.0 | JSON-RPC (stdio) + HTTP/WebSocket |
+| ACP-Comm | Agent Communication Protocol | IBM / Linux Foundation | Apache 2.0 | REST/HTTP |
+| MCP | Model Context Protocol | Anthropic | MIT | JSON-RPC (stdio) |
+
+## How LDM OS Uses Each
+
+**MCP (current):** All LDM OS tools (bridge, sessions, messages, updates, crystal) are MCP servers. Claude Code, Cursor, and any MCP client can use them. This is the primary interface.
+
+**ACP-Client (available, not configured):** OpenClaw implements ACP-Client via `@agentclientprotocol/sdk`. It enables IDE-to-agent communication (Zed, VS Code). LDM OS could expose services via ACP-Client for IDE integration. The transport-agnostic core design supports adding ACP-Client as another wrapper.
+
+**ACP-Comm (not implemented):** Agent-to-agent REST protocol. LDM OS's file-based message bus and session registry serve the same purpose locally. Cloud relay (Phase 7) may evaluate ACP-Comm as a wire protocol for remote agent-to-agent communication.
+
+## Architecture
+
+```
+LDM OS Core (pure functions, zero deps)
+  |
+  |-- MCP wrapper (current, all tools)
+  |-- ACP-Client wrapper (future, IDE integration)
+  |-- ACP-Comm wrapper (future, cloud relay)
+  |-- HTTP wrapper (future, web/iOS)
+```
+
+Same core logic. Different transports. The core doesn't know or care which protocol is calling it.
+
+## License Compatibility
+
+Both ACP protocols are Apache 2.0. LDM OS is MIT + AGPLv3 dual license. Apache 2.0 is compatible with both. No license conflicts.
+
+## Key Files
+
+| File | What |
+|------|------|
+| `src/bridge/mcp-server.ts` | MCP server (current interface) |
+| `lib/sessions.mjs` | Session register (could expose via ACP-Comm) |
+| `lib/messages.mjs` | Message bus (could expose via ACP-Comm) |

package/docs/bridge/README.md

@@ -0,0 +1,55 @@
+###### WIP Computer
+
+# Bridge
+
+## Your AIs talk to each other.
+
+Cross-platform agent communication. Bridge (MCP), Agent Client Protocol (ACP-Client, Zed Industries), and Agent Communication Protocol (ACP-Comm, IBM/Linux Foundation). Three protocols, one system. Claude Code sends a message, OpenClaw responds. OpenClaw sends a task, Claude Code executes it.
+
+## Three Protocols, One System
+
+LDM OS uses three complementary protocols. Bridge is one of them.
+
+| | Bridge | ACP-Client | ACP-Comm |
+|---|---|---|---|
+| **What** | Agent-to-agent messaging + shared memory | IDE-to-agent communication | Agent-to-agent REST API |
+| **Protocol** | MCP (JSON-RPC over stdio) | JSON-RPC over stdio + WebSocket | REST/HTTP |
+| **Built by** | WIP Computer | Zed Industries | IBM / Linux Foundation |
+| **In LDM OS** | Core (v0.3.0+) | Available via OpenClaw | Planned (Cloud Relay) |
+| **What it connects** | Claude Code <-> OpenClaw agents | IDEs (Zed, VS Code) <-> agents | Cloud agents <-> each other |
+| **Memory access** | Yes (search + read across agents) | No | No |
+| **Skill sharing** | Yes (OpenClaw skills as MCP tools) | No | No |
+| **Where it runs** | Localhost only | Localhost (stdio) + remote (WebSocket) | Cloud (HTTP endpoints) |
+
+**Bridge** is how your AIs talk to each other and share memory. **ACP-Client** is how IDEs talk to agents (OpenClaw already implements this). **ACP-Comm** is how agents would talk across the network (planned for Cloud Relay, Phase 7).
+
+All three are Apache 2.0 compatible with our MIT + AGPL license. See [ACP docs](../acp/README.md).
+
+## Tools
+
+| Tool | What |
+|------|------|
+| `lesa_send_message` | Send a message to the OpenClaw agent. Gets a response. |
+| `lesa_check_inbox` | Check for messages the agent sent to you. |
+| `lesa_conversation_search` | Semantic search over conversation history. |
+| `lesa_memory_search` | Keyword search across workspace files. |
+| `lesa_read_workspace` | Read a file from the agent's workspace. |
+| `oc_skills_list` | List all OpenClaw skills. |
+| `oc_skill_*` | Run any OpenClaw skill with scripts. |
+
+## Message Flow
+
+```
+CC  --lesa_send_message-->  OpenClaw Gateway (localhost:18789)  -->  Lesa
+CC  <--lesa_check_inbox---  HTTP Inbox (localhost:18790)        <--  Lesa
+```
+
+Both directions are live. Everything is localhost. No cloud.
+
+## Part of LDM OS
+
+Bridge ships with LDM OS v0.3.0+. The standalone repo is deprecated: [wip-bridge-deprecated](https://github.com/wipcomputer/wip-bridge-deprecated).
+
+---
+
+[Technical Reference](./TECHNICAL.md)

package/docs/bridge/TECHNICAL.md

@@ -0,0 +1,153 @@
+# Bridge ... Technical Reference
+
+## Architecture
+
+```
+Claude Code CLI
+  |
+  |-- MCP stdio --> wip-bridge MCP server (single process)
+  |                   |
+  |                   |-- lesa_send_message --> HTTP POST localhost:18789 (OpenClaw gateway)
+  |                   |                          |
+  |                   |                          v
+  |                   |                        Lesa's agent pipeline
+  |                   |                          |
+  |                   |                          v
+  |                   |                        Response returned
+  |                   |
+  |                   |-- lesa_check_inbox --> HTTP GET localhost:18790 (Bridge inbox)
+  |                   |
+  |                   |-- lesa_conversation_search --> SQLite (context-embeddings.sqlite)
+  |                   |
+  |                   |-- lesa_memory_search --> filesystem (workspace/*.md)
+  |                   |
+  |                   |-- oc_skill_* --> exec scripts in ~/.openclaw/extensions/*/skills/
+```
+
+## MCP Tools
+
+| Tool | What | Transport |
+|------|------|-----------|
+| `lesa_send_message` | Send message to OpenClaw agent | HTTP POST to gateway (localhost:18789) |
+| `lesa_check_inbox` | Check for pending messages from agent | In-memory queue (drained on read) |
+| `lesa_conversation_search` | Semantic search over conversation history | SQLite + OpenAI embeddings |
+| `lesa_memory_search` | Keyword search across workspace .md files | Filesystem scan |
+| `lesa_read_workspace` | Read a specific workspace file | Filesystem |
+| `oc_skill_*` | Execute OpenClaw skill scripts | child_process exec |
+| `oc_skills_list` | List all available OpenClaw skills | Filesystem scan |
+
+## Config Resolution
+
+Bridge resolves config in two steps:
+
+1. **LDM OS path** (`~/.ldm/config.json`): checks for `openclawDir`, `workspaceDir`, `dbPath`
+2. **Legacy path** (`OPENCLAW_DIR` env or `~/.openclaw`): fallback
+
+Both return the same `BridgeConfig` shape: `openclawDir`, `workspaceDir`, `dbPath`, `inboxPort`, `embeddingModel`, `embeddingDimensions`.
+
+## Gateway Authentication
+
+Bridge reads the gateway auth token from `~/.openclaw/openclaw.json` (`gateway.auth.token`). Every HTTP request to the gateway includes `Authorization: Bearer <token>`.
+
+## Conversation Search
+
+Two modes:
+1. **Vector search** (if OpenAI API key available): embeds query, computes cosine similarity against all conversation chunks, applies recency weighting (exponential decay, half-life ~50 days)
+2. **Text search** (fallback): SQL LIKE query against chunk text
+
+The API key is resolved from: environment variable > 1Password via service account token.
+
+## Inbox Server
+
+Bridge starts a localhost-only HTTP server on port 18790:
+- `POST /message`: push a message (from OpenClaw agent)
+- `GET /status`: check pending count
+
+Messages are held in memory. `lesa_check_inbox` drains the queue.
+
+## Key Files
+
+| File | What |
+|------|------|
+| `src/bridge/core.ts` | Pure logic: config, messaging, search, skills |
+| `src/bridge/mcp-server.ts` | MCP server: tool registration, inbox HTTP server |
+| `src/bridge/cli.ts` | CLI wrapper (`lesa` command) |
+| `dist/bridge/` | Compiled output (ships with npm package) |
+
+## Node Communication (Future)
+
+Bridge currently works localhost only (Core). For Node -> Core communication:
+- Phase 7 (Cloud Relay) handles messaging via encrypted Cloudflare R2 dead drops
+- Search, workspace read, and skill execution from a Node are NOT yet covered
+- Two proposed solutions: proxy pattern (Node sends requests through relay) and sync pattern (replicate crystal.db to Node)
+
+See `ai/products/plans-prds/current/ldm-stack-spec.md` for the full platform matrix.
+
+## CLI Usage
+
+```bash
+lesa send "What are you working on?"     # Message the OpenClaw agent
+lesa search "API key resolution"          # Semantic search (recency-weighted)
+lesa memory "compaction"                  # Keyword search across workspace files
+lesa read MEMORY.md                       # Read a workspace file
+lesa read memory/2026-02-10.md            # Read a daily log
+lesa status                               # Show bridge configuration
+lesa diagnose                             # Check gateway, inbox, DB, skills health
+```
+
+## Skill Bridge
+
+On startup, Bridge scans OpenClaw's skill directories and exposes them as MCP tools. Claude Code gets the same skills the OpenClaw agent has.
+
+1. Scans `extensions/*/node_modules/openclaw/skills/` (built-in) and `extensions/*/skills/` (custom)
+2. Parses each `SKILL.md` frontmatter for name, description, requirements
+3. Skills with a `scripts/` folder get registered as executable `oc_skill_{name}` tools
+4. All skills show up in `oc_skills_list`
+
+Skills that need API keys get them from the environment. The op-secrets plugin sets these from 1Password.
+
+## Inbox Watcher (Auto-Relay)
+
+Polls the inbox endpoint and auto-injects messages into a running Claude Code tmux session.
+
+```bash
+bash scripts/watch.sh                    # Alert mode (notification only)
+bash scripts/watch.sh --auto claude:0.0  # Auto-inject into tmux pane
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `POLL_INTERVAL` | `5` | Seconds between inbox checks |
+| `COOLDOWN` | `30` | Minimum seconds between alerts |
+| `INBOX_URL` | `http://127.0.0.1:18790/status` | Inbox status endpoint |
+
+## OpenClaw Skills (Lesa -> CC)
+
+Two skills shipped with Bridge for the reverse direction:
+
+| Skill | What |
+|-------|------|
+| `claude-code` | Invoke Claude Code CLI for coding tasks (`claude -p`) |
+| `send-to-claude-code` | Push messages into CC's live inbox (POST localhost:18790) |
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `OPENCLAW_DIR` | Yes | `~/.openclaw` | Path to OpenClaw installation |
+| `OPENAI_API_KEY` | For semantic search | Resolved from 1Password | OpenAI API key for embeddings |
+| `LESA_BRIDGE_INBOX_PORT` | No | `18790` | Inbox HTTP server port |
+
+## Ports
+
+| Port | Service | Bound to |
+|------|---------|----------|
+| 18789 | OpenClaw gateway | localhost (managed by OpenClaw) |
+| 18790 | Bridge inbox | localhost (managed by Bridge) |
+
+## Requirements
+
+- OpenClaw running with gateway enabled
+- `gateway.auth.token` set in `openclaw.json`
+- `gateway.http.endpoints.chatCompletions.enabled: true`
+- OpenAI API key for semantic search (falls back to text search without it)

package/docs/recall/README.md

@@ -27,3 +27,7 @@ With Recall, your AI remembers. Not just facts, but the arc of what you're build
 ## Part of LDM OS
 
 Recall is included with LDM OS. It activates automatically after `ldm init`.
+
+---
+
+[Technical Reference](./TECHNICAL.md)

package/docs/recall/TECHNICAL.md

@@ -0,0 +1,41 @@
+# Recall ... Technical Reference
+
+## Boot Sequence
+
+Recall is implemented as a SessionStart hook. When Claude Code opens a session, the boot hook loads context files in order:
+
+```
+1. CLAUDE.md                    Identity + structure (harness config)
+2. SHARED-CONTEXT.md            Current state (under 50 lines)
+3. Most recent journal           Narrative from last session
+4. Daily logs (today + yesterday) Recency
+5. Full history (cold start)     Dream Weaver narrative
+6. CONTEXT.md                    Agent's own state
+7. SOUL.md                       Who this agent is
+8. Agent journals                Check for newer entries
+9. Agent daily logs              Check for newer entries
+```
+
+## Key Files
+
+| File | What |
+|------|------|
+| `src/boot/boot-hook.mjs` | SessionStart hook (reads + injects context) |
+| `src/boot/boot-config.json` | Which files to load, in what order |
+| `src/boot/installer.mjs` | Deploys boot hook to `~/.ldm/shared/boot/` |
+
+## How It Works
+
+The boot hook reads `boot-config.json` to determine which files to load. Each entry specifies a path pattern and priority. Files are read in priority order and concatenated into the session context.
+
+The hook runs with a 15-second timeout. If any file is missing, it's skipped silently. The boot sequence is additive. It never modifies files, only reads them.
+
+## Harness Differences
+
+**Claude Code CLI:** Full boot sequence. Identity, context, journals, daily logs all loaded via SessionStart hook.
+
+**OpenClaw:** Has its own boot sequence (workspace files). Recall provides backup context loading if the harness boot fails or is incomplete.
+
+## Session Registration
+
+On boot, Recall also registers the session in the Agent Register (`~/.ldm/sessions/`). This enables other sessions to discover this one via `ldm sessions`.

package/docs/shared-workspace/README.md

@@ -35,3 +35,7 @@ LDM OS never touches your existing data during install or update. Your memories,
 ## Part of LDM OS
 
 Shared Workspace is included with LDM OS. Run `ldm init` to create it.
+
+---
+
+[Technical Reference](./TECHNICAL.md)

package/docs/shared-workspace/TECHNICAL.md

@@ -0,0 +1,75 @@
+# Shared Workspace ... Technical Reference
+
+## Directory Structure
+
+```
+~/.ldm/
+  config.json                 Machine-level config
+  version.json                Installed version + timestamps
+  extensions/
+    registry.json             Extension metadata
+    memory-crystal/           Extension files
+    wip-release/              Extension files
+    ...
+  agents/
+    cc-mini/                  Claude Code on Mac Mini
+      IDENTITY.md
+      SOUL.md
+      CONTEXT.md
+      REFERENCE.md
+      config.json
+      memory/
+        transcripts/          Raw JSONL session files
+        sessions/             MD per-session summaries
+        daily/                Daily log breadcrumbs
+        journals/             Dream Weaver narrative output
+    oc-lesa-mini/             OpenClaw/Lesa on Mac Mini
+      memory/
+        transcripts/          Raw JSONL copies (backup)
+        workspace/            Workspace .md snapshots
+        daily/                Daily log copies
+  memory/
+    crystal.db                Shared vector DB (all agents)
+  sessions/                   Active session files (Agent Register)
+  messages/                   Inter-session messages (Message Bus)
+  shared/
+    boot/                     Boot hook files
+    cron/                     Cron job scripts
+  state/                      Capture watermarks, role state
+  secrets/                    Encryption keys, relay tokens
+  bin/                        Deployed scripts
+  backups/                    Daily backups
+```
+
+## Sacred Data
+
+These paths are never overwritten during install or update:
+
+- `memory/` (crystal.db, all vector data)
+- `agents/` (identity, soul, context, journals, transcripts)
+- `secrets/` (encryption keys, tokens)
+- `state/` (watermarks, capture state)
+- `backups/` (daily snapshots)
+
+Only `extensions/` and `shared/` are updated by `ldm install`.
+
+## Agent Identity
+
+One agent per harness per machine. The agent ID is deterministic:
+
+| Agent ID | Harness | Machine |
+|----------|---------|---------|
+| `cc-mini` | Claude Code CLI | Mac Mini |
+| `cc-air` | Claude Code CLI | MacBook Air |
+| `oc-lesa-mini` | OpenClaw | Mac Mini |
+
+All agents share one `crystal.db`. Memory is shared. Identity is per-agent.
+
+## Key Files
+
+| File | What |
+|------|------|
+| `bin/ldm.js` | CLI: `ldm init` creates the workspace |
+| `lib/deploy.mjs` | Extension deployment engine |
+| `lib/state.mjs` | System state detection |
+| `lib/safe.mjs` | Trash management (never delete, always move) |

package/docs/skills/README.md

@@ -6,6 +6,11 @@ Your AIs are only as powerful as what you give them. Here's everything available
 
 ## Core
 
+**Bridge**
+- Cross-platform agent communication. Bridge (MCP), Agent Client Protocol (ACP-Client), and Agent Communication Protocol (ACP-Comm). Three protocols, one system.
+- *Included with LDM OS*
+- [Read more about Bridge](../bridge/README.md)
+
 **Memory Crystal**
 - All your AI tools. One shared memory. Private, searchable, sovereign. Memory Crystal lets all your AIs remember you ... together. You use multiple AIs. They don't talk to each other. They can't search what the others know. Memory Crystal fixes this. All your AIs share one memory. Searchable and private. Anywhere in the world.
 - *Stable*
@@ -28,10 +33,6 @@ Your AIs are only as powerful as what you give them. Here's everything available
 - Open-source agent runtime. Run AI agents 24/7 with identity, memory, and tool access. The existence proof for LDM OS.
 - [Read more about OpenClaw](https://github.com/openclaw/openclaw)
 
-**Bridge**
-- Cross-platform agent bridge. Enables Claude Code CLI to talk to OpenClaw CLI without a human in the middle.
-- [Read more about Bridge](https://github.com/wipcomputer/wip-bridge)
-
 ## Identity
 
 **Mirror Test** *(not yet public)*
@@ -75,3 +76,7 @@ Your AIs are only as powerful as what you give them. Here's everything available
 **X Platform**
 - X Platform API. Read posts, search tweets, post, upload media.
 - [Read more about X Platform](https://github.com/wipcomputer/wip-xai-x)
+
+---
+
+[Technical Reference](../universal-installer/TECHNICAL.md)

package/docs/system-pulse/README.md

@@ -24,3 +24,7 @@ System Pulse tells you the state of your entire AI setup in seconds. What's inst
 ## Part of LDM OS
 
 System Pulse is included with LDM OS. Available after `ldm init`.
+
+---
+
+[Technical Reference](./TECHNICAL.md)

package/docs/system-pulse/TECHNICAL.md

@@ -0,0 +1,56 @@
+# System Pulse ... Technical Reference
+
+## Commands
+
+### ldm doctor
+
+Checks system health across all components:
+
+1. `~/.ldm/` exists
+2. `version.json` valid and version matches CLI
+3. Full system state scan (extensions, MCP, CLIs, skills)
+4. Reconciliation (registry vs deployed vs MCP registered)
+5. Sacred directories exist (memory/, agents/, state/, sessions/, messages/)
+6. Claude Code hooks configured (checks for stale paths)
+7. MCP servers registered
+8. CLI binaries on PATH
+
+With `--fix`:
+- Removes stale registry entries (registered but not deployed)
+- Removes stale hook paths from `~/.claude/settings.json` (missing files, `/tmp/` paths)
+
+### ldm status
+
+Quick overview: version, install date, extension count, extension list with versions.
+
+### ldm updates
+
+Shows cached update check results. Use `--check` to re-scan npm for newer versions of installed extensions.
+
+## State Detection
+
+`lib/state.mjs` scans the real system:
+
+| Source | What it finds |
+|--------|--------------|
+| `~/.claude.json` | MCP servers (user scope) |
+| `~/.ldm/extensions/` | Deployed extensions (LDM) |
+| `~/.openclaw/extensions/` | Deployed extensions (OpenClaw) |
+| `~/.ldm/extensions/registry.json` | Registry metadata |
+| PATH | CLI binaries (with 5s timeout per binary) |
+| `~/.openclaw/skills/` | Deployed skills |
+
+Reconciliation compares all sources and determines status:
+- `healthy`: registered + deployed + source available
+- `installed-unlinked`: registered + deployed, no source repo
+- `registered-missing`: in registry but not deployed
+- `deployed-unregistered`: deployed but not in registry
+- `mcp-only`: MCP server without LDM management
+
+## Key Files
+
+| File | What |
+|------|------|
+| `bin/ldm.js` | `cmdDoctor()`, `cmdStatus()`, `cmdUpdates()` |
+| `lib/state.mjs` | `detectSystemState()`, `reconcileState()`, `formatReconciliation()` |
+| `lib/updates.mjs` | npm version checking, manifest caching |

package/docs/universal-installer/TECHNICAL.md

@@ -243,6 +243,49 @@ 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.
 
+## Catalog
+
+Skills are defined in `catalog.json` at the LDM OS root. Each entry has:
+
+```json
+{
+  "id": "memory-crystal",
+  "name": "Memory Crystal",
+  "description": "Persistent memory for your AI.",
+  "npm": "@wipcomputer/memory-crystal",
+  "repo": "wipcomputer/memory-crystal",
+  "registryMatches": ["memory-crystal"],
+  "cliMatches": ["crystal"],
+  "recommended": true,
+  "status": "stable"
+}
+```
+
+## Stacks
+
+Stacks group skills for team installs. Defined in `catalog.json`:
+
+```json
+{
+  "stacks": {
+    "core": {
+      "name": "WIP Core",
+      "components": ["memory-crystal", "wip-ai-devops-toolbox", "wip-1password", "wip-markdown-viewer"],
+      "mcpServers": []
+    },
+    "web": {
+      "name": "Web Development",
+      "components": [],
+      "mcpServers": [
+        { "name": "playwright", "command": "npx", "args": ["-y", "@playwright/mcp@latest"] }
+      ]
+    }
+  }
+}
+```
+
+Stacks are composable via the `includes` field.
+
 ## The Installer
 
 `ldm install` scans any repo, detects which interfaces exist, and installs them all. One command.

package/lib/deploy.mjs

@@ -682,10 +682,18 @@ export function installSingleTool(toolPath) {
   }
 
   let installed = 0;
+  // Don't store /tmp/ clone paths as source (#54). Use the repo URL from package.json if available.
+  let source = toolPath;
+  const isTmpPath = toolPath.startsWith('/tmp/') || toolPath.startsWith('/private/tmp/');
+  if (isTmpPath && pkg?.repository?.url) {
+    source = pkg.repository.url.replace(/^git\+/, '').replace(/\.git$/, '');
+  } else if (isTmpPath) {
+    source = null; // better than a /tmp/ path
+  }
   const registryInfo = {
     name: toolName,
     version: pkg?.version || 'unknown',
-    source: toolPath,
+    source,
     interfaces: ifaceNames,
   };
 

package/lib/state.mjs

@@ -89,11 +89,11 @@ function detectCLIBinaries() {
   const binaries = {};
   for (const bin of knownBins) {
     try {
-      const path = execSync(`which ${bin} 2>/dev/null`, { encoding: 'utf8' }).trim();
+      const path = execSync(`which ${bin} 2>/dev/null`, { encoding: 'utf8', timeout: 5000 }).trim();
       if (path) {
         binaries[bin] = { path };
         try {
-          const ver = execSync(`${bin} --version 2>/dev/null`, { encoding: 'utf8' }).trim().split('\n')[0];
+          const ver = execSync(`${bin} --version 2>/dev/null`, { encoding: 'utf8', timeout: 5000 }).trim().split('\n')[0];
           binaries[bin].version = ver;
         } catch {}
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "main": "src/boot/boot-hook.mjs",

package/src/bridge/cli.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lesa-bridge/cli.ts: CLI interface.
+// wip-bridge/cli.ts: CLI interface.
 // lesa send "message", lesa inbox, lesa search "query", lesa read <file>
 
 import { existsSync, statSync } from "node:fs";
@@ -17,7 +17,7 @@ import {
 const config = resolveConfig();
 
 function usage(): void {
-  console.log(`lesa-bridge: Claude Code CLI ↔ OpenClaw TUI agent bridge
+  console.log(`wip-bridge: Claude Code CLI ↔ OpenClaw TUI agent bridge
 
 Usage:
   lesa send <message>         Send a message to the OpenClaw agent
@@ -130,7 +130,7 @@ async function main(): Promise<void> {
     }
 
     case "status": {
-      console.log(`lesa-bridge status`);
+      console.log(`wip-bridge status`);
       console.log(`  OpenClaw dir:  ${config.openclawDir}`);
       console.log(`  Workspace:     ${config.workspaceDir}`);
       console.log(`  Database:      ${config.dbPath}`);
@@ -140,7 +140,7 @@ async function main(): Promise<void> {
     }
 
     case "diagnose": {
-      console.log("lesa-bridge diagnose\n");
+      console.log("wip-bridge diagnose\n");
       let issues = 0;
 
       // 1. OpenClaw dir

package/src/bridge/core.ts

@@ -1,4 +1,4 @@
-// lesa-bridge/core.ts: Pure logic. Zero framework deps.
+// wip-bridge/core.ts: Pure logic. Zero framework deps.
 // Handles messaging, memory search, and workspace access for OpenClaw agents.
 
 import { execSync, exec } from "node:child_process";

package/src/bridge/mcp-server.ts

@@ -1,4 +1,4 @@
-// lesa-bridge/mcp-server.ts: MCP server wrapping core.
+// wip-bridge/mcp-server.ts: MCP server wrapping core.
 // Thin layer: registers tools, starts inbox HTTP server, connects transport.
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -73,12 +73,12 @@ function startInboxServer(cfg: BridgeConfig): void {
           timestamp: new Date().toISOString(),
         };
         const queued = pushInbox(msg);
-        console.error(`lesa-bridge inbox: message from ${msg.from}`);
+        console.error(`wip-bridge inbox: message from ${msg.from}`);
 
         try {
           server.sendLoggingMessage({
             level: "info",
-            logger: "lesa-bridge",
+            logger: "wip-bridge",
             data: `[OpenClaw → Claude Code] ${msg.from}: ${msg.message}`,
           });
         } catch {}
@@ -103,18 +103,18 @@ function startInboxServer(cfg: BridgeConfig): void {
   });
 
   httpServer.listen(cfg.inboxPort, "127.0.0.1", () => {
-    console.error(`lesa-bridge inbox listening on 127.0.0.1:${cfg.inboxPort}`);
+    console.error(`wip-bridge inbox listening on 127.0.0.1:${cfg.inboxPort}`);
   });
 
   httpServer.on("error", (err: Error) => {
-    console.error(`lesa-bridge inbox server error: ${err.message}`);
+    console.error(`wip-bridge inbox server error: ${err.message}`);
   });
 }
 
 // ── MCP Server ───────────────────────────────────────────────────────
 
 const server = new McpServer({
-  name: "lesa-bridge",
+  name: "wip-bridge",
   version: "0.3.0",
 });
 
@@ -344,7 +344,7 @@ function registerSkillTools(skills: SkillInfo[]): void {
     }
   );
 
-  console.error(`lesa-bridge: registered ${executableSkills.length} skill tools + oc_skills_list (${skills.length} total skills)`);
+  console.error(`wip-bridge: registered ${executableSkills.length} skill tools + oc_skills_list (${skills.length} total skills)`);
 }
 
 // ── Start ────────────────────────────────────────────────────────────
@@ -357,12 +357,12 @@ async function main() {
     const skills = discoverSkills(config.openclawDir);
     registerSkillTools(skills);
   } catch (err: any) {
-    console.error(`lesa-bridge: skill discovery failed: ${err.message}`);
+    console.error(`wip-bridge: skill discovery failed: ${err.message}`);
   }
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error(`lesa-bridge MCP server running (openclaw: ${config.openclawDir})`);
+  console.error(`wip-bridge MCP server running (openclaw: ${config.openclawDir})`);
 }
 
 main().catch((error) => {

package/templates/hooks/pre-commit

@@ -0,0 +1,19 @@
+#!/bin/bash
+# LDM OS: Global pre-commit hook
+# Blocks commits on main/master. Use a branch or worktree.
+# Installed by: ldm init
+# Location: ~/.ldm/hooks/pre-commit
+# Activated by: git config --global core.hooksPath ~/.ldm/hooks
+
+branch=$(git branch --show-current 2>/dev/null)
+
+if [ "$branch" = "main" ] || [ "$branch" = "master" ]; then
+  echo ""
+  echo "  BLOCKED: Cannot commit on $branch."
+  echo "  Create a branch first: git checkout -b cc-mini/your-feature"
+  echo "  Or use a worktree: git worktree add /tmp/wt-name -b branch-name"
+  echo ""
+  echo "  To bypass (emergencies only): git commit --no-verify"
+  echo ""
+  exit 1
+fi