@wipcomputer/wip-ldm-os 0.4.0 → 0.4.2

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,15 +99,11 @@ 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
 
-- [Architecture, principles, and technical details](TECHNICAL.md)
+- [Architecture, principles, and technical details](docs/universal-installer/TECHNICAL.md)
 
 ## License
 

package/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 interface: [cli, skill]
 metadata:
   display-name: "LDM OS"
-  version: "0.4.0"
+  version: "0.4.2"
   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('');
@@ -644,6 +688,11 @@ async function cmdInstallCatalog() {
     updated++;
   }
 
+  // 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).`);
 
@@ -1345,7 +1394,7 @@ async function main() {
       await cmdUpdateAll();
       break;
     case 'doctor':
-      cmdDoctor();
+      await cmdDoctor();
       break;
     case 'status':
       cmdStatus();

package/bin/wip-install.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// wip-install: thin bootstrap + delegate to ldm install.
+// If ldm is on PATH, delegates immediately.
+// If not, installs LDM OS from npm, then delegates.
+// Replaces the standalone 700-line install.js from wip-ai-devops-toolbox.
+
+import { run } from '../lib/bootstrap.mjs';
+run(process.argv.slice(2));

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](./TECHNICAL.md)

package/docs/skills/TECHNICAL.md

@@ -0,0 +1,67 @@
+# Skills ... Technical Reference
+
+## 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.
+
+## Interface Detection
+
+`ldm install` auto-detects which interfaces a repo supports:
+
+| Pattern | Interface | Install Action |
+|---------|-----------|---------------|
+| `package.json` with `bin` | CLI | `npm install -g` from registry |
+| `main` or `exports` | Module | Reports import path |
+| `mcp-server.mjs` | MCP | `claude mcp add --scope user` |
+| `openclaw.plugin.json` | OpenClaw Plugin | Deploy to `~/.ldm/extensions/` + `~/.openclaw/extensions/` |
+| `SKILL.md` | Skill | Deploy to `~/.openclaw/skills/` |
+| `guard.mjs` or `claudeCode.hook` | CC Hook | Add to `~/.claude/settings.json` |
+| `.claude-plugin/plugin.json` | CC Plugin | Register with marketplace |
+
+## Key Files
+
+| File | What |
+|------|------|
+| `catalog.json` | Component + stack definitions |
+| `lib/detect.mjs` | Interface detection engine |
+| `lib/deploy.mjs` | Deployment engine |
+| `bin/ldm.js` | `ldm stack` and `ldm install` commands |

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/SPEC.md

@@ -0,0 +1,206 @@
+# The Universal Interface Specification
+
+Every tool is a sensor, an actuator, or both. Every tool should be accessible through multiple interfaces. We call this the Universal Interface.
+
+This is the spec.
+
+## The Six Interfaces
+
+### 1. CLI
+
+A shell command. The most universal interface. If it has a terminal, it works.
+
+**Convention:** `package.json` with a `bin` field.
+
+**Detection:** `pkg.bin` exists.
+
+**Install:** `npm install -g .` or `npm link`.
+
+```json
+{
+  "bin": {
+    "wip-grok": "./cli.mjs"
+  }
+}
+```
+
+### 2. Module
+
+An importable ES module. The programmatic interface. Other tools compose with it.
+
+**Convention:** `package.json` with `main` or `exports` field. File is `core.mjs` by convention.
+
+**Detection:** `pkg.main` or `pkg.exports` exists.
+
+**Install:** `npm install <package>` or import directly from path.
+
+```json
+{
+  "type": "module",
+  "main": "core.mjs",
+  "exports": {
+    ".": "./core.mjs",
+    "./cli": "./cli.mjs"
+  }
+}
+```
+
+### 3. MCP Server
+
+A JSON-RPC server implementing the Model Context Protocol. Any MCP-compatible agent can use it.
+
+**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`:
+
+```json
+{
+  "tool-name": {
+    "command": "node",
+    "args": ["/path/to/mcp-server.mjs"]
+  }
+}
+```
+
+### 4. OpenClaw Plugin
+
+A plugin for OpenClaw agents. Lifecycle hooks, tool registration, settings.
+
+**Convention:** `openclaw.plugin.json` at the repo root.
+
+**Detection:** `openclaw.plugin.json` exists.
+
+**Install:** Copy to `~/.openclaw/extensions/<name>/`, run `npm install --omit=dev`.
+
+### 5. Skill (SKILL.md)
+
+A markdown file that teaches agents when and how to use the tool. The instruction interface.
+
+**Convention:** `SKILL.md` at the repo root. YAML frontmatter with name, version, description, metadata.
+
+**Detection:** `SKILL.md` exists.
+
+**Install:** Referenced by path. Agents read it when they need the tool.
+
+```yaml
+---
+name: wip-grok
+version: 1.0.0
+description: xAI Grok API. Search the web, search X, generate images.
+metadata:
+  category: search,media
+  capabilities:
+    - web-search
+    - image-generation
+---
+```
+
+### 6. Claude Code Hook
+
+A hook that runs during Claude Code's tool lifecycle (PreToolUse, Stop, etc.).
+
+**Convention:** `guard.mjs` at repo root, or `claudeCode.hook` in `package.json`.
+
+**Detection:** `guard.mjs` exists, or `pkg.claudeCode.hook` is defined.
+
+**Install:** Added to `~/.claude/settings.json` under `hooks`.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Edit|Write",
+      "hooks": [{
+        "type": "command",
+        "command": "node /path/to/guard.mjs",
+        "timeout": 5
+      }]
+    }]
+  }
+}
+```
+
+## Architecture
+
+Every repo that follows this spec has the same basic structure:
+
+```
+your-tool/
+  core.mjs            pure logic, zero or minimal deps
+  cli.mjs             thin CLI wrapper around core
+  mcp-server.mjs      MCP server wrapping core functions as tools
+  SKILL.md            agent instructions with YAML frontmatter
+  package.json         name, bin, main, exports, type: module
+  README.md            human documentation
+  ai/                  development process (plans, todos, notes)
+```
+
+Not every tool needs all six 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 `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.
+
+```
+ai/
+  plan/              architecture plans, roadmaps
+  dev-updates/       what was built, session logs
+  todos/
+    PUNCHLIST.md     blockers to ship
+    inboxes/         per-agent action items
+  notes/             research, references, raw conversation logs
+```
+
+The `ai/` folder is the development process. It is not part of the published product.
+
+**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
+
+`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.
+
+```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
+```
+
+For toolbox repos (with a `tools/` directory containing sub-tools), the installer enters toolbox mode and installs each sub-tool.
+
+## Examples
+
+### AI DevOps Toolbox (this repo)
+
+| # | Tool | Interfaces |
+|---|------|------------|
+| | **Repo Management** | |
+| 1 | [Repo Visibility Guard](tools/wip-repo-permissions-hook/) | CLI + Module + MCP + OpenClaw + Skill + CC Hook |
+| 2 | [Repo Manifest Reconciler](tools/wip-repos/) | CLI + Module + MCP + Skill |
+| 3 | [Repo Init](tools/wip-repo-init/) | CLI + Skill |
+| 4 | [README Formatter](tools/wip-readme-format/) | CLI + Skill |
+| 5 | [Branch Guard](tools/wip-branch-guard/) | CLI + Module + CC Hook |
+| | **License, Compliance, and Protection** | |
+| 6 | [Identity File Protection](tools/wip-file-guard/) | CLI + Module + OpenClaw + Skill + CC Hook |
+| 7 | [License Guard](tools/wip-license-guard/) | CLI + Skill |
+| 8 | [License Rug-Pull Detection](tools/wip-license-hook/) | CLI + Module + MCP + Skill |
+| | **Release & Deploy** | |
+| 9 | [Release Pipeline](tools/wip-release/) | CLI + Module + MCP + Skill |
+| 10 | [Private-to-Public Sync](tools/deploy-public/) | CLI + Skill |
+| 11 | [Post-Merge Branch Naming](tools/post-merge-rename/) | CLI + Skill |
+| 12 | [Universal Installer](tools/wip-universal-installer/) | CLI + Module + Skill |
+
+### Other WIP Computer Tools
+
+| Repo | Interfaces |
+|------|------------|
+| [Memory Crystal](https://github.com/wipcomputer/memory-crystal) | CLI + Module + MCP + OpenClaw + Skill |
+| [LDM OS](https://github.com/wipcomputer/wip-ldm-os) | CLI + Module + Skill + CC Hook |
+| [wip-grok](https://github.com/wipcomputer/wip-grok) | CLI + Module + MCP + Skill |
+| [wip-x](https://github.com/wipcomputer/wip-x) | CLI + Module + MCP + Skill |
+| [Markdown Viewer](https://github.com/wipcomputer/wip-markdown-viewer) | CLI + Module |

package/lib/bootstrap.mjs

@@ -0,0 +1,92 @@
+/**
+ * lib/bootstrap.mjs
+ * Thin bootstrap for wip-install.
+ * If ldm is on PATH, delegates to ldm install.
+ * If not, installs LDM OS from npm, then delegates.
+ * This replaces the 700-line standalone install.js from the toolbox.
+ * Zero external dependencies.
+ */
+
+import { execSync } from 'node:child_process';
+
+/**
+ * Check if ldm CLI is available on PATH.
+ * @returns {boolean}
+ */
+export function isLdmAvailable() {
+  try {
+    execSync('ldm --version', { stdio: 'pipe', timeout: 5000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Install LDM OS from npm registry.
+ * @returns {boolean} true if install succeeded
+ */
+export function bootstrapLdmOs() {
+  try {
+    execSync('npm install -g @wipcomputer/wip-ldm-os', { stdio: 'pipe', timeout: 120000 });
+    execSync('ldm init --yes --none', { stdio: 'pipe', timeout: 30000 });
+    return isLdmAvailable();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Delegate to ldm install with the given arguments.
+ * @param {string} target - what to install (org/repo, path, or empty for update-all)
+ * @param {string[]} flags - CLI flags (--dry-run, --json, etc.)
+ */
+export function delegateToLdm(target, flags = []) {
+  const cmd = target
+    ? `ldm install ${target} ${flags.join(' ')}`
+    : `ldm install ${flags.join(' ')}`;
+  execSync(cmd.trim(), { stdio: 'inherit' });
+}
+
+/**
+ * Full bootstrap + delegate flow.
+ * Called by wip-install as the entry point.
+ * @param {string[]} argv - process.argv.slice(2)
+ */
+export function run(argv) {
+  const target = argv.find(a => !a.startsWith('--'));
+  const flags = argv.filter(a => a.startsWith('--'));
+  const jsonOutput = flags.includes('--json');
+
+  if (isLdmAvailable()) {
+    if (!jsonOutput) {
+      console.log('');
+      console.log('  LDM OS detected. Delegating to ldm install...');
+      console.log('');
+    }
+    delegateToLdm(target, flags);
+    return;
+  }
+
+  // LDM not on PATH, try bootstrap
+  if (!jsonOutput) {
+    console.log('');
+    console.log('  LDM OS not found. Installing...');
+    console.log('');
+  }
+
+  if (bootstrapLdmOs()) {
+    if (!jsonOutput) {
+      console.log('  LDM OS installed. Delegating to ldm install...');
+      console.log('');
+    }
+    delegateToLdm(target, flags);
+  } else {
+    if (!jsonOutput) {
+      console.log('  LDM OS could not be installed automatically.');
+      console.log('  Install manually: npm install -g @wipcomputer/wip-ldm-os');
+      console.log('');
+    }
+    process.exit(1);
+  }
+}

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,12 +1,13 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "main": "src/boot/boot-hook.mjs",
   "bin": {
     "ldm": "bin/ldm.js",
     "wip-ldm-os": "bin/ldm.js",
+    "wip-install": "bin/wip-install.js",
     "ldm-scaffold": "bin/scaffold.sh",
     "ldm-boot-install": "src/boot/install-cli.js",
     "lesa": "dist/bridge/cli.js"

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