@wipcomputer/wip-ldm-os 0.4.73-alpha.2 → 0.4.73-alpha.20

package/bin/ldm.js

@@ -544,20 +544,14 @@ function deployDocs() {
     return count;
   }
 
-  // Deploy to settings/docs/ (agent reference)
-  const docsDest = join(workspacePath, 'settings', 'docs');
-  const docsCount = renderTemplates(docsDest);
-  if (docsCount > 0) {
-    console.log(`  + ${docsCount} personalized doc(s) deployed to ${docsDest.replace(HOME, '~')}/`);
-  }
-
-  // Deploy to library/documentation/ (human-readable library copy)
+  // Deploy to library/documentation/ (the canonical doc path since Mar 28 rename).
+  // Previously also deployed to settings/docs/ which Parker renamed to library/documentation/.
+  // That created a ghost folder on every install. Removed 2026-04-05 per INST-1.
   const libraryDest = join(workspacePath, 'library', 'documentation');
-  if (existsSync(join(workspacePath, 'library'))) {
-    const libCount = renderTemplates(libraryDest);
-    if (libCount > 0) {
-      console.log(`  + ${libCount} doc(s) deployed to ${libraryDest.replace(HOME, '~')}/`);
-    }
+  mkdirSync(libraryDest, { recursive: true });
+  const docsCount = renderTemplates(libraryDest);
+  if (docsCount > 0) {
+    console.log(`  + ${docsCount} personalized doc(s) deployed to ${libraryDest.replace(HOME, '~')}/`);
   }
 
   return docsCount;
@@ -820,10 +814,16 @@ async function cmdInit() {
     // Scaffold workspace output dirs if workspace is configured
     const workspace = config.workspace;
     if (workspace && existsSync(workspace)) {
-      // Per-agent workspace dirs
-      const agentNameMap = { 'cc-mini': 'cc-mini', 'cc-air': 'cc-air', 'oc-lesa-mini': 'Lēsa' };
+      // Per-agent workspace dirs.
+      // Resolve the team folder name from config.json agents[id].teamFolder
+      // so agents with unicode names or custom folder names don't get ghost
+      // folders created from their agent ID. Falls back to agent ID if no
+      // override is configured. Fixed 2026-04-05 per INST-1: previously
+      // hardcoded a map that only knew three agents and created ghost folders
+      // for any others.
       for (const agentId of agentList) {
-        const teamName = agentNameMap[agentId] || agentId;
+        const agentObj = typeof agentsObj[agentId] === 'object' ? agentsObj[agentId] : {};
+        const teamName = agentObj.teamFolder || agentObj.name || agentId;
         for (const sub of ['journals', 'automated/memory/summaries/daily', 'automated/memory/summaries/weekly', 'automated/memory/summaries/monthly', 'automated/memory/summaries/quarterly']) {
           dirs.push(join(workspace, 'team', teamName, sub));
         }
@@ -1321,23 +1321,31 @@ async function cmdInstall() {
 
   // Check if target looks like an npm package (starts with @ or is a plain name without /)
   if (resolvedTarget.startsWith('@') || (!resolvedTarget.includes('/') && !existsSync(resolve(resolvedTarget)))) {
-    // Try npm install to temp dir
+    // Try npm pack + tar extract to temp dir
+    // npm install --prefix silently fails for scoped packages in temp directories...
+    // it creates the lock file but doesn't extract files. npm pack is reliable.
     const npmName = resolvedTarget;
     const tempDir = join(LDM_TMP, `npm-${Date.now()}`);
     console.log('');
     console.log(`  Installing ${npmName} from npm...`);
     try {
       mkdirSync(tempDir, { recursive: true });
-      execSync(`npm install ${npmName} --prefix "${tempDir}"`, { stdio: 'pipe' });
-      // Find the installed package in node_modules
-      const pkgName = npmName.startsWith('@') ? npmName : npmName;
-      const installed = join(tempDir, 'node_modules', pkgName);
-      if (existsSync(installed)) {
-        console.log(`  + Installed from npm`);
-        repoPath = installed;
+      // Use npm pack + tar instead of npm install --prefix
+      const tarball = execSync(`npm pack ${npmName} --pack-destination "${tempDir}" 2>/dev/null`, {
+        encoding: 'utf8', timeout: 60000, cwd: tempDir,
+      }).trim();
+      const tarPath = join(tempDir, tarball);
+      if (existsSync(tarPath)) {
+        execSync(`tar xzf "${tarPath}" -C "${tempDir}"`, { stdio: 'pipe' });
+        const extracted = join(tempDir, 'package');
+        if (existsSync(extracted)) {
+          console.log(`  + Installed from npm`);
+          repoPath = extracted;
+        } else {
+          console.error(`  x npm pack succeeded but extraction failed`);
+        }
       } else {
-        console.error(`  x Package installed but not found at expected path`);
-        process.exit(1);
+        console.error(`  x npm pack failed: tarball not found`);
       }
     } catch (e) {
       // npm failed, fall through to git clone or path resolution
@@ -2206,13 +2214,56 @@ async function cmdInstallCatalog() {
       continue;
     }
 
-    if (!entry.catalogRepo) {
+    if (!entry.catalogRepo && !entry.catalogNpm) {
       console.log(`  Skipping ${entry.name}: no catalog repo (install manually with ldm install <org/repo>)`);
       continue;
     }
-    console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from ${entry.catalogRepo})...`);
+
+    // Source resolution chain (#264):
+    // 1. npm (when --alpha/--beta or npm package available) - works online, any machine
+    // 2. Local private repo (offline, developer machine) - works without internet
+    // 3. GitHub clone (fallback) - works online, any machine
+    let installSource = null;
+    const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : null;
+
+    // Try npm first when using alpha/beta tracks or when npm is available
+    if (entry.catalogNpm && (npmTag || !entry.catalogRepo)) {
+      const ver = npmTag ? `${entry.catalogNpm}@${npmTag}` : `${entry.catalogNpm}@${entry.latestVersion}`;
+      installSource = ver;
+      console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from npm ${npmTag || 'latest'})...`);
+    }
+
+    // Try local private repo (for offline/developer installs)
+    if (!installSource && entry.catalogRepo) {
+      const repoName = basename(entry.catalogRepo);
+      const privateRepoName = repoName + '-private';
+      const WORKSPACE = join(HOME, 'wipcomputerinc');
+      // Search known repo locations
+      const searchDirs = ['repos/ldm-os/devops', 'repos/ldm-os/components', 'repos/ldm-os/utilities', 'repos/ldm-os/apps', 'repos/ldm-os/apis', 'repos/ldm-os/identity'];
+      for (const dir of searchDirs) {
+        const localPrivate = join(WORKSPACE, dir, privateRepoName);
+        const localPublic = join(WORKSPACE, dir, repoName);
+        if (existsSync(localPrivate)) {
+          installSource = localPrivate;
+          console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from local ${privateRepoName})...`);
+          break;
+        }
+        if (existsSync(localPublic)) {
+          installSource = localPublic;
+          console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from local ${repoName})...`);
+          break;
+        }
+      }
+    }
+
+    // Fallback: GitHub clone
+    if (!installSource) {
+      installSource = entry.catalogRepo;
+      console.log(`  Updating ${entry.name} v${entry.currentVersion} -> v${entry.latestVersion} (from ${entry.catalogRepo})...`);
+    }
+
     try {
-      execSync(`ldm install ${entry.catalogRepo}`, { stdio: 'inherit' });
+      execSync(`ldm install ${installSource}`, { stdio: 'inherit' });
       updated++;
 
       // For parent packages, update registry version for all sub-tools (#139, #262)

package/dist/bridge/{chunk-LF7EMFBY.js → chunk-24DJYS7Z.js}

@@ -6,6 +6,27 @@ import { homedir } from "os";
 import { promisify } from "util";
 import { randomUUID } from "crypto";
 var execAsync = promisify(exec);
+var GATEWAY_HOST = "127.0.0.1";
+var DEFAULT_GATEWAY_PORT = 18789;
+var DEFAULT_INBOX_PORT = 18790;
+var GATEWAY_TIMEOUT_MS = 12e4;
+var OP_CLI_TIMEOUT_MS = 1e4;
+var EMBEDDING_API_URL = "https://api.openai.com/v1/embeddings";
+var DEFAULT_EMBEDDING_MODEL = "text-embedding-3-small";
+var DEFAULT_EMBEDDING_DIMS = 1536;
+var VECTOR_SEARCH_ROW_LIMIT = 1e3;
+var RECENCY_DECAY_RATE = 0.01;
+var RECENCY_FLOOR = 0.5;
+var FRESHNESS_FRESH_DAYS = 3;
+var FRESHNESS_RECENT_DAYS = 7;
+var FRESHNESS_AGING_DAYS = 14;
+var DEFAULT_SEARCH_LIMIT = 5;
+var WORKSPACE_MAX_DEPTH = 4;
+var WORKSPACE_MAX_EXCERPTS = 5;
+var WORKSPACE_MAX_RESULTS = 10;
+var SKILL_EXEC_TIMEOUT_MS = 12e4;
+var SKILL_EXEC_MAX_BUFFER = 10 * 1024 * 1024;
+var MS_PER_DAY = 1e3 * 60 * 60 * 24;
 var HOME = process.env.HOME || homedir();
 var LDM_ROOT = process.env.LDM_ROOT || join(HOME, ".ldm");
 function resolveConfig(overrides) {
@@ -14,9 +35,9 @@ function resolveConfig(overrides) {
     openclawDir,
     workspaceDir: overrides?.workspaceDir || join(openclawDir, "workspace"),
     dbPath: overrides?.dbPath || join(openclawDir, "memory", "context-embeddings.sqlite"),
-    inboxPort: overrides?.inboxPort || parseInt(process.env.LESA_BRIDGE_INBOX_PORT || "18790", 10),
-    embeddingModel: overrides?.embeddingModel || "text-embedding-3-small",
-    embeddingDimensions: overrides?.embeddingDimensions || 1536
+    inboxPort: overrides?.inboxPort || parseInt(process.env.LESA_BRIDGE_INBOX_PORT || String(DEFAULT_INBOX_PORT), 10),
+    embeddingModel: overrides?.embeddingModel || DEFAULT_EMBEDDING_MODEL,
+    embeddingDimensions: overrides?.embeddingDimensions || DEFAULT_EMBEDDING_DIMS
   };
 }
 function resolveConfigMulti(overrides) {
@@ -29,9 +50,9 @@ function resolveConfigMulti(overrides) {
         openclawDir,
         workspaceDir: raw.workspaceDir || overrides?.workspaceDir || join(openclawDir, "workspace"),
         dbPath: raw.dbPath || overrides?.dbPath || join(openclawDir, "memory", "context-embeddings.sqlite"),
-        inboxPort: raw.inboxPort || overrides?.inboxPort || parseInt(process.env.LESA_BRIDGE_INBOX_PORT || "18790", 10),
-        embeddingModel: raw.embeddingModel || overrides?.embeddingModel || "text-embedding-3-small",
-        embeddingDimensions: raw.embeddingDimensions || overrides?.embeddingDimensions || 1536
+        inboxPort: raw.inboxPort || overrides?.inboxPort || parseInt(process.env.LESA_BRIDGE_INBOX_PORT || String(DEFAULT_INBOX_PORT), 10),
+        embeddingModel: raw.embeddingModel || overrides?.embeddingModel || DEFAULT_EMBEDDING_MODEL,
+        embeddingDimensions: raw.embeddingDimensions || overrides?.embeddingDimensions || DEFAULT_EMBEDDING_DIMS
       };
     } catch {
     }
@@ -53,7 +74,7 @@ function resolveApiKey(openclawDir) {
         `op read "op://Agent Secrets/OpenAI API/api key" 2>/dev/null`,
         {
           env: { ...process.env, OP_SERVICE_ACCOUNT_TOKEN: saToken },
-          timeout: 1e4,
+          timeout: OP_CLI_TIMEOUT_MS,
           encoding: "utf-8"
         }
       ).trim();
@@ -76,7 +97,7 @@ function resolveGatewayConfig(openclawDir) {
   }
   const config = JSON.parse(readFileSync(configPath, "utf-8"));
   const token = config?.gateway?.auth?.token;
-  const port = config?.gateway?.port || 18789;
+  const port = config?.gateway?.port || DEFAULT_GATEWAY_PORT;
   if (!token) {
     throw new Error("No gateway.auth.token found in openclaw.json");
   }
@@ -262,37 +283,64 @@ async function sendMessage(openclawDir, message, options) {
   const { token, port } = resolveGatewayConfig(openclawDir);
   const agentId = options?.agentId || "main";
   const senderLabel = options?.senderLabel || "Claude Code";
-  const response = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${token}`,
-      "Content-Type": "application/json",
-      "x-openclaw-scopes": "operator.read,operator.write",
-      "x-openclaw-session-key": `agent:${agentId}:main`
-    },
-    body: JSON.stringify({
-      model: `openclaw/${agentId}`,
-      messages: [
-        {
-          role: "user",
-          content: `[${senderLabel}]: ${message}`
-        }
-      ]
-    })
+  const fireAndForget = options?.fireAndForget ?? false;
+  const requestBody = JSON.stringify({
+    model: `openclaw/${agentId}`,
+    messages: [
+      {
+        role: "user",
+        content: `[${senderLabel}]: ${message}`
+      }
+    ]
   });
-  if (!response.ok) {
-    const body = await response.text();
-    throw new Error(`Gateway returned ${response.status}: ${body}`);
+  const requestHeaders = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+    "x-openclaw-scopes": "operator.read,operator.write",
+    "x-openclaw-session-key": `agent:${agentId}:main`
+  };
+  const url = `http://${GATEWAY_HOST}:${port}/v1/chat/completions`;
+  if (fireAndForget) {
+    fetch(url, {
+      method: "POST",
+      headers: requestHeaders,
+      body: requestBody
+    }).catch(() => {
+    });
+    return "Message sent (queued). Response will arrive in the TUI.";
   }
-  const data = await response.json();
-  const reply = data.choices?.[0]?.message?.content;
-  if (!reply) {
-    throw new Error("No response content from gateway");
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), GATEWAY_TIMEOUT_MS);
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: requestHeaders,
+      body: requestBody,
+      signal: controller.signal
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Gateway returned ${response.status}: ${body}`);
+    }
+    const data = await response.json();
+    const reply = data.choices?.[0]?.message?.content;
+    if (!reply) {
+      throw new Error("No response content from gateway");
+    }
+    return reply;
+  } catch (err) {
+    clearTimeout(timeoutId);
+    if (err.name === "AbortError") {
+      throw new Error(
+        "Gateway timeout: Lesa may be busy or the gateway is processing another request. Try again in a moment."
+      );
+    }
+    throw err;
   }
-  return reply;
 }
-async function getQueryEmbedding(text, apiKey, model = "text-embedding-3-small", dimensions = 1536) {
-  const response = await fetch("https://api.openai.com/v1/embeddings", {
+async function getQueryEmbedding(text, apiKey, model = DEFAULT_EMBEDDING_MODEL, dimensions = DEFAULT_EMBEDDING_DIMS) {
+  const response = await fetch(EMBEDDING_API_URL, {
     method: "POST",
     headers: {
       Authorization: `Bearer ${apiKey}`,
@@ -331,15 +379,15 @@ function cosineSimilarity(a, b) {
   return denom === 0 ? 0 : dot / denom;
 }
 function recencyWeight(ageDays) {
-  return Math.max(0.5, 1 - ageDays * 0.01);
+  return Math.max(RECENCY_FLOOR, 1 - ageDays * RECENCY_DECAY_RATE);
 }
 function freshnessLabel(ageDays) {
-  if (ageDays < 3) return "fresh";
-  if (ageDays < 7) return "recent";
-  if (ageDays < 14) return "aging";
+  if (ageDays < FRESHNESS_FRESH_DAYS) return "fresh";
+  if (ageDays < FRESHNESS_RECENT_DAYS) return "recent";
+  if (ageDays < FRESHNESS_AGING_DAYS) return "aging";
   return "stale";
 }
-async function searchConversations(config, query, limit = 5) {
+async function searchConversations(config, query, limit = DEFAULT_SEARCH_LIMIT) {
   const Database = (await import("better-sqlite3")).default;
   if (!existsSync(config.dbPath)) {
     throw new Error(`Database not found: ${config.dbPath}`);
@@ -360,12 +408,12 @@ async function searchConversations(config, query, limit = 5) {
            FROM conversation_chunks
            WHERE embedding IS NOT NULL
            ORDER BY timestamp DESC
-           LIMIT 1000`
+           LIMIT ${VECTOR_SEARCH_ROW_LIMIT}`
       ).all();
       const now = Date.now();
       return rows.map((row) => {
         const cosine = cosineSimilarity(queryEmbedding, blobToEmbedding(row.embedding));
-        const ageDays = (now - row.timestamp) / (1e3 * 60 * 60 * 24);
+        const ageDays = (now - row.timestamp) / MS_PER_DAY;
         const weight = recencyWeight(ageDays);
         return {
           text: row.chunk_text,
@@ -396,7 +444,7 @@ async function searchConversations(config, query, limit = 5) {
     db.close();
   }
 }
-function findMarkdownFiles(dir, maxDepth = 4, depth = 0) {
+function findMarkdownFiles(dir, maxDepth = WORKSPACE_MAX_DEPTH, depth = 0) {
   if (depth > maxDepth || !existsSync(dir)) return [];
   const files = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -426,7 +474,7 @@ function searchWorkspace(workspaceDir, query) {
       if (score === 0) continue;
       const lines = content.split("\n");
       const excerpts = [];
-      for (let i = 0; i < lines.length && excerpts.length < 5; i++) {
+      for (let i = 0; i < lines.length && excerpts.length < WORKSPACE_MAX_EXCERPTS; i++) {
         const lineLower = lines[i].toLowerCase();
         if (words.some((w) => lineLower.includes(w))) {
           const start = Math.max(0, i - 1);
@@ -438,7 +486,7 @@ function searchWorkspace(workspaceDir, query) {
     } catch {
     }
   }
-  return results.sort((a, b) => b.score - a.score).slice(0, 10);
+  return results.sort((a, b) => b.score - a.score).slice(0, WORKSPACE_MAX_RESULTS);
 }
 function parseSkillFrontmatter(content) {
   const match = content.match(/^---\n([\s\S]*?)\n---/);
@@ -532,9 +580,8 @@ async function executeSkillScript(skillDir, scripts, scriptName, args) {
       `${interpreter} "${scriptPath}" ${args}`,
       {
         env: { ...process.env },
-        timeout: 12e4,
-        maxBuffer: 10 * 1024 * 1024
-        // 10MB
+        timeout: SKILL_EXEC_TIMEOUT_MS,
+        maxBuffer: SKILL_EXEC_MAX_BUFFER
       }
     );
     return stdout || stderr || "(no output)";

package/dist/bridge/cli.js

@@ -8,7 +8,7 @@ import {
   searchConversations,
   searchWorkspace,
   sendMessage
-} from "./chunk-LF7EMFBY.js";
+} from "./chunk-24DJYS7Z.js";
 
 // cli.ts
 import { existsSync, statSync } from "fs";

package/dist/bridge/core.d.ts

@@ -107,6 +107,7 @@ declare function sendMessage(openclawDir: string, message: string, options?: {
     agentId?: string;
     user?: string;
     senderLabel?: string;
+    fireAndForget?: boolean;
 }): Promise<string>;
 declare function getQueryEmbedding(text: string, apiKey: string, model?: string, dimensions?: number): Promise<number[]>;
 declare function blobToEmbedding(blob: Buffer): number[];

package/dist/bridge/core.js

@@ -23,7 +23,7 @@ import {
   sendLdmMessage,
   sendMessage,
   setSessionIdentity
-} from "./chunk-LF7EMFBY.js";
+} from "./chunk-24DJYS7Z.js";
 export {
   LDM_ROOT,
   blobToEmbedding,

package/dist/bridge/mcp-server.js

@@ -15,7 +15,7 @@ import {
   sendLdmMessage,
   sendMessage,
   setSessionIdentity
-} from "./chunk-LF7EMFBY.js";
+} from "./chunk-24DJYS7Z.js";
 
 // mcp-server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -191,15 +191,29 @@ ${result.content}` }] };
 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.",
+    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.\n\nThis is async: returns immediately after sending. The agent's reply will arrive in your inbox (check via lesa_check_inbox or it appears automatically on your next turn).",
     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 }] };
+      await sendMessage(config.openclawDir, message, { fireAndForget: true });
+      const { agentId, sessionName } = getSessionIdentity();
+      sendLdmMessage({
+        from: `${agentId}:${sessionName}`,
+        to: "lesa",
+        body: message,
+        type: "chat"
+      });
+      return {
+        content: [{
+          type: "text",
+          text: `Sent to L\u0113sa: "${message}"
+
+Message delivered to the gateway (fire-and-forget). L\u0113sa will process it through her full pipeline. Her reply will arrive in your inbox. Use lesa_check_inbox to check, or it will appear automatically on your next turn.`
+        }]
+      };
     } catch (err) {
       return { content: [{ type: "text", text: `Error sending message: ${err.message}` }], isError: true };
     }

package/dist/bridge/openclaw.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    register(api: any): void;
+};
+
+export { _default as default };

package/dist/bridge/openclaw.js

@@ -0,0 +1,9 @@
+// openclaw.ts
+var openclaw_default = {
+  register(api) {
+    api.logger.info("lesa-bridge plugin registered (skill-only; MCP server runs out of process)");
+  }
+};
+export {
+  openclaw_default as default
+};

package/docs/doc-pipeline/README.md

@@ -0,0 +1,74 @@
+# Documentation Pipeline
+
+Documentation lives in three places. They stay in sync through the installer. This is not optional.
+
+## The Three Levels
+
+### 1. Repo Docs (source of truth)
+
+Every repo has documentation at its root and in `docs/` for features:
+
+```
+repo/
+├── README.md              What this repo is
+├── TECHNICAL.md           How it works
+├── SKILL.md               Agent instructions
+├── CLAUDE.md              Agent context for Claude Code
+├── docs/
+│   └── <feature>/
+│       ├── README.md      What this feature is
+│       └── TECHNICAL.md   How this feature works
+```
+
+When a feature gets absorbed into a repo, its README and TECHNICAL move into `docs/<feature>/`.
+
+Repo docs are the source of truth. Everything else is derived from them.
+
+### 2. Home Docs (human readable, personalized)
+
+Location: `~/wipcomputerinc/library/documentation/`
+
+These are personalized for YOUR system. "Here's how releases work on YOUR machine." Generated by the installer from repo doc templates + your `~/.ldm/config.json`.
+
+The human reads these. They describe how the system is set up on this specific machine, with this specific configuration.
+
+### 3. Agent Docs (OS reference)
+
+Location: `~/.ldm/shared/`
+
+```
+~/.ldm/shared/
+├── rules/               Thin rules deployed to ~/.claude/rules/
+├── dev-guide-*.md       Org-specific dev conventions
+├── boot/                Boot sequence config
+└── prompts/             Cron prompts
+```
+
+These are what agents reference. Rules, dev guide, boot config. The installer deploys them so agents always have current instructions.
+
+### 4. ai/ (development process)
+
+Location: `<repo>/ai/`
+
+Plans, bugs, research, dev updates. Private repo only. Never ships to public. Updated by the dev team (humans + AI agents) during development.
+
+## The Update Flow
+
+### On merge to private main
+
+1. **Repo docs** updated. README, TECHNICAL, docs/<feature>/, SKILL.md, CLAUDE.md. Part of the PR. Code and docs ship together.
+2. **ai/** updated. Plan archived, bugs closed, dev update written. Notes the version is on alpha.
+
+### On `ldm install`
+
+3. **Home docs** regenerated. Installer reads repo doc templates + config.json, generates personalized `library/documentation/` files.
+4. **Agent docs** deployed. Installer copies rules, dev guide, boot config from the installed package to `~/.ldm/shared/` and `~/.claude/rules/`.
+
+### On deploy to public
+
+5. **Public repo** updated. `deploy-public.sh` syncs everything except `ai/`.
+6. **ai/** dev update notes the version moved from alpha to release.
+
+## The Rule
+
+Three places, one update, never out of sync. The installer is the bridge between "code landed" and "docs are current everywhere." Developers write repo docs. The installer propagates them. Nobody manually updates home docs or agent docs.

package/docs/doc-pipeline/TECHNICAL.md

@@ -0,0 +1,79 @@
+# Documentation Pipeline: Technical Details
+
+## File Paths
+
+### Repo doc templates (in the LDM OS repo)
+
+```
+shared/docs/*.md.tmpl           Templates for home docs
+shared/rules/*.md               Source for agent rules
+shared/boot/                    Boot sequence config
+```
+
+Templates use placeholders from `~/.ldm/config.json` (workspace path, agent names, org name, etc.).
+
+### Installed locations
+
+```
+~/.ldm/config.json                       Org config (agents, paths, co-authors)
+~/.ldm/shared/rules/*.md                 Agent rules (source for ~/.claude/rules/)
+~/.ldm/shared/dev-guide-*.md             Org dev guide
+~/.ldm/shared/boot/                      Boot sequence config
+~/.ldm/shared/prompts/                   Cron prompts
+~/.ldm/templates/                        CLAUDE.md templates, install prompt, etc.
+~/wipcomputerinc/library/documentation/  Personalized human docs (from templates)
+~/.claude/rules/                         Deployed rules (copied from ~/.ldm/shared/rules/)
+~/.claude/CLAUDE.md                      Level 1 global (generated from template + config)
+```
+
+### What ldm install deploys
+
+| Source | Destination | When |
+|--------|------------|------|
+| `shared/rules/*.md` | `~/.ldm/shared/rules/` then `~/.claude/rules/` | Every install |
+| `shared/docs/*.md.tmpl` | `~/wipcomputerinc/library/documentation/` | Every install |
+| `shared/boot/` | `~/.ldm/shared/boot/` | Every install |
+| `shared/prompts/` | `~/.ldm/shared/prompts/` | Every install |
+| `shared/templates/` | `~/.ldm/templates/` | Every install |
+
+**Known bug (April 2026):** The installer currently deploys shared rules on `ldm init` (first install) but not on every `ldm install`. This means rule updates in new versions don't propagate until the user re-initializes. This needs to be fixed so rules deploy on every install.
+
+**Known bug (April 2026):** The installer previously deployed home docs to `settings/docs/`. This path was renamed to `library/documentation/` on March 28, 2026. The installer must deploy to the correct path.
+
+## How templates work
+
+Home doc templates at `shared/docs/*.md.tmpl` contain placeholders:
+
+```
+Workspace: {{workspace}}
+Agents: {{agents}}
+```
+
+The installer reads `~/.ldm/config.json`, substitutes the placeholders, and writes the personalized docs to `~/wipcomputerinc/library/documentation/`.
+
+## CLAUDE.md cascade
+
+Three levels. Claude Code reads all of them, walking up from CWD:
+
+```
+Level 1: ~/.claude/CLAUDE.md              Global. ~30 lines. Universal rules.
+Level 2: ~/wipcomputerinc/CLAUDE.md       Workspace. ~150 lines. Org context.
+Level 3: <repo>/CLAUDE.md                 Per-repo. ~50-86 lines. Repo-specific.
+```
+
+After context compaction, CWD may shift to a repo. Without Level 3, all context is lost. Every repo must have a CLAUDE.md.
+
+## Config paths (correct as of April 2026)
+
+References in CLAUDE.md and rules must use absolute paths:
+
+| Reference | Correct path |
+|-----------|-------------|
+| Org config | `~/.ldm/config.json` |
+| Dev guide | `~/.ldm/shared/dev-guide-wipcomputerinc.md` |
+| Human docs | `~/wipcomputerinc/library/documentation/` |
+| Agent rules | `~/.ldm/shared/rules/` (source) or `~/.claude/rules/` (deployed) |
+| Workspace CLAUDE.md | `~/wipcomputerinc/CLAUDE.md` |
+| Global CLAUDE.md | `~/.claude/CLAUDE.md` |
+
+NOT `settings/config.json`. NOT `settings/docs/`. Those paths are from before the March 28 rename.