@wipcomputer/wip-ldm-os 0.2.13 → 0.3.1

package/dist/bridge/core.d.ts

@@ -0,0 +1,74 @@
+declare const LDM_ROOT: string;
+interface BridgeConfig {
+    openclawDir: string;
+    workspaceDir: string;
+    dbPath: string;
+    inboxPort: number;
+    embeddingModel: string;
+    embeddingDimensions: number;
+}
+interface GatewayConfig {
+    token: string;
+    port: number;
+}
+interface InboxMessage {
+    from: string;
+    message: string;
+    timestamp: string;
+}
+interface ConversationResult {
+    text: string;
+    role: string;
+    sessionKey: string;
+    date: string;
+    similarity?: number;
+    recencyScore?: number;
+    freshness?: "fresh" | "recent" | "aging" | "stale";
+}
+interface WorkspaceSearchResult {
+    path: string;
+    excerpts: string[];
+    score: number;
+}
+declare function resolveConfig(overrides?: Partial<BridgeConfig>): BridgeConfig;
+/**
+ * Multi-config resolver. Checks ~/.ldm/config.json first, falls back to OPENCLAW_DIR.
+ * This is the LDM OS native path. resolveConfig() is the legacy OpenClaw path.
+ * Both return the same BridgeConfig shape.
+ */
+declare function resolveConfigMulti(overrides?: Partial<BridgeConfig>): BridgeConfig;
+declare function resolveApiKey(openclawDir: string): string | null;
+declare function resolveGatewayConfig(openclawDir: string): GatewayConfig;
+declare function pushInbox(msg: InboxMessage): number;
+declare function drainInbox(): InboxMessage[];
+declare function inboxCount(): number;
+declare function sendMessage(openclawDir: string, message: string, options?: {
+    agentId?: string;
+    user?: string;
+    senderLabel?: string;
+}): Promise<string>;
+declare function getQueryEmbedding(text: string, apiKey: string, model?: string, dimensions?: number): Promise<number[]>;
+declare function blobToEmbedding(blob: Buffer): number[];
+declare function cosineSimilarity(a: number[], b: number[]): number;
+declare function searchConversations(config: BridgeConfig, query: string, limit?: number): Promise<ConversationResult[]>;
+declare function findMarkdownFiles(dir: string, maxDepth?: number, depth?: number): string[];
+declare function searchWorkspace(workspaceDir: string, query: string): WorkspaceSearchResult[];
+interface WorkspaceFileResult {
+    content: string;
+    relativePath: string;
+}
+interface SkillInfo {
+    name: string;
+    description: string;
+    skillDir: string;
+    hasScripts: boolean;
+    scripts: string[];
+    source: "builtin" | "custom";
+    emoji?: string;
+    requires?: Record<string, string[]>;
+}
+declare function discoverSkills(openclawDir: string): SkillInfo[];
+declare function executeSkillScript(skillDir: string, scripts: string[], scriptName: string | undefined, args: string): Promise<string>;
+declare function readWorkspaceFile(workspaceDir: string, filePath: string): WorkspaceFileResult;
+
+export { type BridgeConfig, type ConversationResult, type GatewayConfig, type InboxMessage, LDM_ROOT, type SkillInfo, type WorkspaceFileResult, type WorkspaceSearchResult, blobToEmbedding, cosineSimilarity, discoverSkills, drainInbox, executeSkillScript, findMarkdownFiles, getQueryEmbedding, inboxCount, pushInbox, readWorkspaceFile, resolveApiKey, resolveConfig, resolveConfigMulti, resolveGatewayConfig, searchConversations, searchWorkspace, sendMessage };

package/dist/bridge/core.js

@@ -0,0 +1,40 @@
+import {
+  LDM_ROOT,
+  blobToEmbedding,
+  cosineSimilarity,
+  discoverSkills,
+  drainInbox,
+  executeSkillScript,
+  findMarkdownFiles,
+  getQueryEmbedding,
+  inboxCount,
+  pushInbox,
+  readWorkspaceFile,
+  resolveApiKey,
+  resolveConfig,
+  resolveConfigMulti,
+  resolveGatewayConfig,
+  searchConversations,
+  searchWorkspace,
+  sendMessage
+} from "./chunk-KWGJCDGS.js";
+export {
+  LDM_ROOT,
+  blobToEmbedding,
+  cosineSimilarity,
+  discoverSkills,
+  drainInbox,
+  executeSkillScript,
+  findMarkdownFiles,
+  getQueryEmbedding,
+  inboxCount,
+  pushInbox,
+  readWorkspaceFile,
+  resolveApiKey,
+  resolveConfig,
+  resolveConfigMulti,
+  resolveGatewayConfig,
+  searchConversations,
+  searchWorkspace,
+  sendMessage
+};

package/dist/bridge/mcp-server.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/bridge/mcp-server.js

@@ -0,0 +1,284 @@
+import {
+  discoverSkills,
+  drainInbox,
+  executeSkillScript,
+  inboxCount,
+  pushInbox,
+  readWorkspaceFile,
+  resolveConfig,
+  searchConversations,
+  searchWorkspace,
+  sendMessage
+} from "./chunk-KWGJCDGS.js";
+
+// mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "http";
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { z } from "zod";
+var config = resolveConfig();
+var METRICS_DIR = join(process.env.HOME || "/Users/lesa", ".openclaw", "memory");
+var METRICS_PATH = join(METRICS_DIR, "search-metrics.jsonl");
+function logSearchMetric(tool, query, resultCount) {
+  try {
+    mkdirSync(METRICS_DIR, { recursive: true });
+    const entry = JSON.stringify({
+      ts: (/* @__PURE__ */ new Date()).toISOString(),
+      tool,
+      query,
+      results: resultCount
+    });
+    appendFileSync(METRICS_PATH, entry + "\n");
+  } catch {
+  }
+}
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+    req.on("error", reject);
+  });
+}
+function startInboxServer(cfg) {
+  const httpServer = createServer(async (req, res) => {
+    const remoteAddr = req.socket.remoteAddress;
+    if (remoteAddr !== "127.0.0.1" && remoteAddr !== "::1" && remoteAddr !== "::ffff:127.0.0.1") {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "localhost only" }));
+      return;
+    }
+    if (req.method === "POST" && req.url === "/message") {
+      try {
+        const body = JSON.parse(await readBody(req));
+        const msg = {
+          from: body.from || "agent",
+          message: body.message,
+          timestamp: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        const queued = pushInbox(msg);
+        console.error(`lesa-bridge inbox: message from ${msg.from}`);
+        try {
+          server.sendLoggingMessage({
+            level: "info",
+            logger: "lesa-bridge",
+            data: `[OpenClaw \u2192 Claude Code] ${msg.from}: ${msg.message}`
+          });
+        } catch {
+        }
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true, queued }));
+      } catch (err) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: err.message }));
+      }
+      return;
+    }
+    if (req.method === "GET" && req.url === "/status") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ ok: true, pending: inboxCount() }));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "not found" }));
+  });
+  httpServer.listen(cfg.inboxPort, "127.0.0.1", () => {
+    console.error(`lesa-bridge inbox listening on 127.0.0.1:${cfg.inboxPort}`);
+  });
+  httpServer.on("error", (err) => {
+    console.error(`lesa-bridge inbox server error: ${err.message}`);
+  });
+}
+var server = new McpServer({
+  name: "lesa-bridge",
+  version: "0.3.0"
+});
+server.registerTool(
+  "lesa_conversation_search",
+  {
+    description: "Search embedded conversation history. Returns semantically similar excerpts from past conversations. Use this to find what was discussed about a topic, decisions made, or technical details from earlier sessions.",
+    inputSchema: {
+      query: z.string().describe("What to search for in past conversations"),
+      limit: z.number().optional().default(5).describe("Max results to return (default: 5)")
+    }
+  },
+  async ({ query, limit }) => {
+    try {
+      const results = await searchConversations(config, query, limit);
+      logSearchMetric("lesa_conversation_search", query, results.length);
+      if (results.length === 0) {
+        return { content: [{ type: "text", text: "No conversation history found." }] };
+      }
+      const hasEmbeddings = results[0].similarity !== void 0;
+      const freshnessIcon = { fresh: "\u{1F7E2}", recent: "\u{1F7E1}", aging: "\u{1F7E0}", stale: "\u{1F534}" };
+      const text = results.map((r, i) => {
+        const sim = r.similarity !== void 0 ? `score: ${r.similarity.toFixed(3)}, ` : "";
+        const fresh = r.freshness ? `${freshnessIcon[r.freshness]} ${r.freshness}, ` : "";
+        return `[${i + 1}] (${fresh}${sim}session: ${r.sessionKey}, date: ${r.date})
+${r.text}`;
+      }).join("\n\n---\n\n");
+      const prefix = hasEmbeddings ? "(Recency-weighted. \u{1F7E2} fresh <3d, \u{1F7E1} recent <7d, \u{1F7E0} aging <14d, \u{1F534} stale 14d+)\n\n" : "(Text search; no API key for semantic search)\n\n";
+      return { content: [{ type: "text", text: `${prefix}${text}` }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+server.registerTool(
+  "lesa_memory_search",
+  {
+    description: "Search workspace memory files (MEMORY.md, daily logs, notes, identity docs). Returns matching excerpts from .md files. Use this to find written memory, observations, todos, and notes.",
+    inputSchema: {
+      query: z.string().describe("Keywords to search for in workspace files")
+    }
+  },
+  async ({ query }) => {
+    try {
+      const results = searchWorkspace(config.workspaceDir, query);
+      logSearchMetric("lesa_memory_search", query, results.length);
+      if (results.length === 0) {
+        return { content: [{ type: "text", text: `No workspace files matched "${query}".` }] };
+      }
+      const text = results.map((r) => {
+        const excerpts = r.excerpts.map((e) => `  ${e.replace(/\n/g, "\n  ")}`).join("\n  ...\n");
+        return `### ${r.path}
+${excerpts}`;
+      }).join("\n\n---\n\n");
+      return { content: [{ type: "text", text }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+    }
+  }
+);
+server.registerTool(
+  "lesa_read_workspace",
+  {
+    description: "Read a specific file from the agent workspace. Paths are relative to the workspace directory. Common files: MEMORY.md, IDENTITY.md, SOUL.md, USER.md, AGENTS.md, TOOLS.md, memory/YYYY-MM-DD.md (daily logs), memory/todos.md, memory/observations.md, notes/*.",
+    inputSchema: {
+      path: z.string().describe("File path relative to workspace/ (e.g. 'MEMORY.md', 'memory/2026-02-07.md')")
+    }
+  },
+  async ({ path: filePath }) => {
+    try {
+      const result = readWorkspaceFile(config.workspaceDir, filePath);
+      return { content: [{ type: "text", text: `# ${result.relativePath}
+
+${result.content}` }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: err.message }], isError: !err.message.includes("Available files") };
+    }
+  }
+);
+server.registerTool(
+  "lesa_send_message",
+  {
+    description: "Send a message to the OpenClaw agent through the gateway. Routes through the agent's full pipeline: memory, tools, personality, workspace. Use this for direct communication: asking questions, sharing findings, coordinating work, or having a discussion. Messages are prefixed with [Claude Code] so the agent knows the source.",
+    inputSchema: {
+      message: z.string().describe("Message to send to the OpenClaw agent")
+    }
+  },
+  async ({ message }) => {
+    try {
+      const reply = await sendMessage(config.openclawDir, message);
+      return { content: [{ type: "text", text: reply }] };
+    } catch (err) {
+      return { content: [{ type: "text", text: `Error sending message: ${err.message}` }], isError: true };
+    }
+  }
+);
+server.registerTool(
+  "lesa_check_inbox",
+  {
+    description: "Check for pending messages from the OpenClaw agent. The agent can push messages via the inbox HTTP endpoint (POST localhost:18790/message). Call this to see if the agent has sent anything. Returns all pending messages and clears the queue.",
+    inputSchema: {}
+  },
+  async () => {
+    const messages = drainInbox();
+    if (messages.length === 0) {
+      return { content: [{ type: "text", text: "No pending messages." }] };
+    }
+    const text = messages.map((m) => `**${m.from}** (${m.timestamp}):
+${m.message}`).join("\n\n---\n\n");
+    return { content: [{ type: "text", text: `${messages.length} message(s):
+
+${text}` }] };
+  }
+);
+function registerSkillTools(skills) {
+  const executableSkills = skills.filter((s) => s.hasScripts);
+  const toolNameMap = /* @__PURE__ */ new Map();
+  for (const skill of executableSkills) {
+    const toolName = `oc_skill_${skill.name.replace(/-/g, "_")}`;
+    toolNameMap.set(toolName, skill);
+    const scriptList = skill.scripts.length > 1 ? ` Available scripts: ${skill.scripts.join(", ")}.` : "";
+    server.registerTool(
+      toolName,
+      {
+        description: `[OpenClaw skill] ${skill.description}${scriptList}`,
+        inputSchema: {
+          args: z.string().describe("Arguments to pass to the skill script (e.g. file paths, flags)"),
+          script: z.string().optional().describe(
+            skill.scripts.length > 1 ? `Which script to run: ${skill.scripts.join(", ")}. Defaults to first .sh script.` : "Script to run (optional, defaults to the only available script)"
+          )
+        }
+      },
+      async ({ args, script }) => {
+        try {
+          const result = await executeSkillScript(skill.skillDir, skill.scripts, script, args);
+          return { content: [{ type: "text", text: result }] };
+        } catch (err) {
+          return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
+        }
+      }
+    );
+  }
+  server.registerTool(
+    "oc_skills_list",
+    {
+      description: "List all available OpenClaw skills and their descriptions. Skills with scripts can be called directly as oc_skill_{name} tools. Instruction-only skills describe how to use external CLIs.",
+      inputSchema: {
+        filter: z.string().optional().describe("Filter skills by name or description keyword")
+      }
+    },
+    async ({ filter }) => {
+      let filtered = skills;
+      if (filter) {
+        const f = filter.toLowerCase();
+        filtered = skills.filter(
+          (s) => s.name.toLowerCase().includes(f) || s.description.toLowerCase().includes(f)
+        );
+      }
+      if (filtered.length === 0) {
+        return { content: [{ type: "text", text: "No skills matched the filter." }] };
+      }
+      const lines = filtered.map((s) => {
+        const prefix = s.hasScripts ? `oc_skill_${s.name.replace(/-/g, "_")}` : "(instruction-only)";
+        const emoji = s.emoji ? `${s.emoji} ` : "";
+        return `- ${emoji}**${s.name}** [${prefix}]: ${s.description}`;
+      });
+      const header = `${filtered.length} skill(s)` + (filter ? ` matching "${filter}"` : "") + ` (${executableSkills.length} executable, ${skills.length - executableSkills.length} instruction-only)`;
+      return { content: [{ type: "text", text: `${header}
+
+${lines.join("\n")}` }] };
+    }
+  );
+  console.error(`lesa-bridge: registered ${executableSkills.length} skill tools + oc_skills_list (${skills.length} total skills)`);
+}
+async function main() {
+  startInboxServer(config);
+  try {
+    const skills = discoverSkills(config.openclawDir);
+    registerSkillTools(skills);
+  } catch (err) {
+    console.error(`lesa-bridge: skill discovery failed: ${err.message}`);
+  }
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`lesa-bridge MCP server running (openclaw: ${config.openclawDir})`);
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/docs/TECHNICAL.md

@@ -0,0 +1,290 @@
+###### WIP Computer
+# Universal Interface ... Technical Reference
+
+Every tool is a sensor, an actuator, or both. Every tool should be accessible through multiple interfaces. We call this the Universal Interface.
+
+## Sensors and Actuators
+
+**Sensors** convert state into data:
+- Search the web (wip-grok search_web)
+- Search X/Twitter (wip-grok search_x, wip-x search_recent)
+- Fetch a post (wip-x fetch_post)
+- Read bookmarks (wip-x get_bookmarks)
+- Check system health (wip-healthcheck)
+
+**Actuators** convert intent into action:
+- Generate an image (wip-grok generate_image)
+- Post a tweet (wip-x post_tweet)
+- Guard a file from edits (wip-file-guard)
+- Generate a video (wip-grok generate_video)
+
+## The Seven Interfaces
+
+Agents don't all speak the same language. Some run shell commands. Some import modules. Some talk MCP. 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 |
+
+Not every tool needs all seven. Build what makes sense. But the more interfaces you expose, the more agents can use your tool.
+
+### 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
+      }]
+    }]
+  }
+}
+```
+
+### 7. 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" }
+}
+```
+
+## How to Build It
+
+The architecture is simple. Four files:
+
+```
+your-tool/
+  core.mjs            <- pure logic, zero deps if possible
+  cli.mjs             <- thin CLI wrapper
+  mcp-server.mjs      <- MCP server wrapping core as tools
+  SKILL.md            <- when/how to use it, for agents
+```
+
+`core.mjs` does the work. Everything else is a thin wrapper. CLI parses argv and calls core. MCP server maps tools to core functions. SKILL.md teaches agents when to call what.
+
+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.
+
+```
+Read wip.computer/install/{URL}
+
+Then explain:
+1. What is {name of product}?
+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
+
+Show me exactly what will change. Don't install anything until I say "install".
+```
+
+## 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 Installer
+
+`ldm install` scans any repo, detects which interfaces exist, and installs them all. One command.
+
+```bash
+ldm install wipcomputer/wip-grok      # from GitHub
+ldm install /path/to/repo             # from a local path
+ldm install --dry-run                  # detect only
+ldm install                            # update all
+```
+
+### What It Detects
+
+| Pattern | Interface | Install action |
+|---------|-----------|---------------|
+| `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 |
+| `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` |
+| `.claude-plugin/plugin.json` | CC Plugin | Registers with Claude Code marketplace |
+
+## Examples
+
+| Tool | Type | Interfaces | What it does |
+|------|------|------------|-------------|
+| [wip-grok](https://github.com/wipcomputer/wip-grok) | Sensor + Actuator | CLI + Module + MCP + Skill | xAI Grok API: search web/X, generate images/video |
+| [wip-x](https://github.com/wipcomputer/wip-x) | Sensor + Actuator | CLI + Module + MCP + Skill | X Platform API: read/write tweets, bookmarks |
+| [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 |
+
+## Supported Tools
+
+Works with any AI agent or coding tool that can run shell commands:
+
+| Tool | How |
+|------|-----|
+| Claude Code | CLI via bash, hooks via settings.json, MCP via .mcp.json, plugins via marketplace |
+| OpenAI Codex CLI | CLI via bash, skills via AGENTS.md |
+| Cursor | CLI via terminal, MCP via config |
+| Windsurf | CLI via terminal, MCP via config |
+| OpenClaw | Plugins, skills, MCP |
+| Any agent | CLI works everywhere. If it has a shell, it works. |