@wipcomputer/wip-ldm-os 0.4.55 → 0.4.57

package/SKILL.md

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

package/bin/ldm.js

@@ -531,6 +531,69 @@ async function cmdInit() {
     }
   } catch {}
 
+  // Deploy personalized docs to settings/docs/ (from templates + config.json)
+  const docsSrc = join(__dirname, '..', 'shared', 'docs');
+  if (existsSync(docsSrc)) {
+    let workspacePath = '';
+    try {
+      const ldmConfig = JSON.parse(readFileSync(join(LDM_ROOT, 'config.json'), 'utf8'));
+      workspacePath = (ldmConfig.workspace || '').replace('~', HOME);
+
+      if (workspacePath && existsSync(workspacePath)) {
+        const docsDest = join(workspacePath, 'settings', 'docs');
+        mkdirSync(docsDest, { recursive: true });
+        let docsCount = 0;
+
+        // Build template values from BOTH configs:
+        // ~/.ldm/config.json (harnesses, workspace) + settings/config.json (agents, paths, org)
+        const settingsConfig = JSON.parse(readFileSync(join(workspacePath, 'settings', 'config.json'), 'utf8'));
+        const sc = settingsConfig;
+        const lc = ldmConfig;
+
+        // Agents from settings config (rich objects with harness/machine/prefix)
+        const agentsObj = sc.agents || {};
+        const agentsList = Object.entries(agentsObj).map(([id, a]) => `${id} (${a.harness} on ${a.machine})`).join(', ');
+        const agentsDetail = Object.entries(agentsObj).map(([id, a]) => `- **${id}**: ${a.harness} on ${a.machine}, branch prefix \`${a.prefix}/\``).join('\n');
+
+        // Harnesses from ldm config
+        const harnessConfig = lc.harnesses || {};
+        const harnessesDetected = Object.entries(harnessConfig).filter(([,h]) => h.detected).map(([name]) => name);
+        const harnessesList = harnessesDetected.length > 0 ? harnessesDetected.join(', ') : 'run ldm install to detect';
+
+        const templateVars = {
+          'name': sc.name || '',
+          'org': sc.org || '',
+          'timezone': sc.timezone || '',
+          'paths.workspace': (sc.paths?.workspace || '').replace('~', HOME),
+          'paths.ldm': (sc.paths?.ldm || '').replace('~', HOME),
+          'paths.openclaw': (sc.paths?.openclaw || '').replace('~', HOME),
+          'paths.icloud': (sc.paths?.icloud || '').replace('~', HOME),
+          'memory.local': (sc.memory?.local || '').replace('~', HOME),
+          'deploy.website': sc.deploy?.website || '',
+          'backup.keep': String(sc.backup?.keep || 7),
+          'agents_list': agentsList,
+          'agents_detail': agentsDetail,
+          'harnesses_list': harnessesList,
+        };
+
+        for (const file of readdirSync(docsSrc)) {
+          if (!file.endsWith('.tmpl')) continue;
+          let content = readFileSync(join(docsSrc, file), 'utf8');
+          // Replace template vars
+          content = content.replace(/\{\{([^}]+)\}\}/g, (match, key) => {
+            return templateVars[key.trim()] || match;
+          });
+          const outName = file.replace('.tmpl', '');
+          writeFileSync(join(docsDest, outName), content);
+          docsCount++;
+        }
+        if (docsCount > 0) {
+          console.log(`  + ${docsCount} personalized doc(s) deployed to ${docsDest.replace(HOME, '~')}/`);
+        }
+      }
+    } catch {}
+  }
+
   console.log('');
   console.log(`  LDM OS v${PKG_VERSION} initialized at ${LDM_ROOT}`);
   console.log('');
@@ -693,7 +756,7 @@ async function cmdInstall() {
     // Use the repo field to clone from GitHub
     const repoTarget = catalogEntry.repo;
     const repoName = basename(repoTarget);
-    const repoPath = join(LDM_TMP, `ldm-install-${repoName}`);
+    const repoPath = join(LDM_TMP, repoName);
     const httpsUrl = `https://github.com/${repoTarget}.git`;
     const sshUrl = `git@github.com:${repoTarget}.git`;
 
@@ -738,7 +801,7 @@ async function cmdInstall() {
   if (resolvedTarget.startsWith('@') || (!resolvedTarget.includes('/') && !existsSync(resolve(resolvedTarget)))) {
     // Try npm install to temp dir
     const npmName = resolvedTarget;
-    const tempDir = join(LDM_TMP, `ldm-install-npm-${Date.now()}`);
+    const tempDir = join(LDM_TMP, `npm-${Date.now()}`);
     console.log('');
     console.log(`  Installing ${npmName} from npm...`);
     try {
@@ -770,7 +833,7 @@ async function cmdInstall() {
       ? `git@github.com:${resolvedTarget}.git`
       : resolvedTarget.replace(/^https:\/\/github\.com\//, 'git@github.com:');
     const repoName = basename(httpsUrl).replace('.git', '');
-    repoPath = join(LDM_TMP, `ldm-install-${repoName}`);
+    repoPath = join(LDM_TMP, repoName);
 
     mkdirSync(LDM_TMP, { recursive: true });
     console.log('');

package/catalog.json

@@ -287,7 +287,7 @@
       "name": "Tavily",
       "description": "Web search and content extraction via Tavily API.",
       "npm": "tavily",
-      "repo": null,
+      "repo": "wipcomputer/openclaw-tavily",
       "registryMatches": [
         "tavily"
       ],

package/package.json

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

package/shared/docs/README.md.tmpl

@@ -0,0 +1,35 @@
+# System Documentation
+
+These docs are automatically maintained. Do not edit them directly.
+
+Updates come from two sources:
+- **config.json** ... when you change your org settings, the "Your System" sections regenerate
+- **System hooks** ... when tools are installed, updated, or reconfigured, the relevant docs update automatically
+
+If something is wrong, update `settings/config.json` or run `ldm install`. The docs will follow.
+
+## What's Here
+
+| Doc | What it covers |
+|-----|---------------|
+| `what-is-ldm-os.md` | What LDM OS is, what it installs, key commands |
+| `what-is-dotldm.md` | The `~/.ldm/` runtime directory explained |
+| `directory-map.md` | What lives where and why |
+| `how-worktrees-work.md` | Git worktrees, the _worktrees/ convention |
+| `how-backup-works.md` | Daily backup, iCloud offsite, restore |
+| `how-releases-work.md` | The full release pipeline |
+| `how-install-works.md` | ldm install, the install prompt, dogfooding |
+| `how-agents-work.md` | Agents, harnesses, bridge, memory |
+| `how-rules-and-commands-work.md` | Rules, commands, skills, and .ldm/ -> harness deployment |
+| `system-directories.md` | Every directory in the system, what manages it |
+| `how-web-skills-work-placeholder.md` | Deploying skills to claude.ai web app |
+| `local-first-principle.md` | Local-first, relay-optional. Why and how. |
+| `acknowledgements.md` | External ideas, code, and inspiration we draw from |
+
+## Structure
+
+Each doc has two sections:
+1. **Universal** ... how the feature works for everyone (top of file)
+2. **Your System** ... your specific configuration (bottom, after the `---` separator)
+
+Universal content comes from the LDM OS repo. "Your System" content is generated from your `settings/config.json`.

package/shared/docs/acknowledgements.md.tmpl

@@ -0,0 +1,207 @@
+# Acknowledgements
+
+Ideas, code, and inspiration from the community. If we use it, we credit it.
+
+## How This Works
+
+When any tool, plan, doc, or code draws from external work, add an entry here. This is checked by the license guard during releases. If an acknowledgement is missing, the release blocks.
+
+## Sources
+
+### Cyril (@cyrilXBT)
+
+**What:** Post framing Obsidian + Claude Code as a "personal JARVIS." Your vault is your knowledge base, Claude reads it, your AI answers from your own thinking.
+
+**Where we use it:** The plan for Obsidian as an LDMOS UI layer. The insight that `~/wipcomputerinc/` is already an Obsidian-compatible vault. The onboarding path for Obsidian users.
+
+**Link:** (X post by @cyrilXBT, 2026-03-23 snapshot)
+
+**License:** Public post
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Louis (@louislva)
+
+**What:** claude-peers-mcp ... multiple Claude Code instances discover each other and exchange messages via SQLite broker + `claude/channel` push delivery.
+
+**Where we use it:** Session status broadcast, `claude/channel` push delivery evaluation, auto-summarization on connect. Bridge priorities from comparison analysis. No code ported.
+
+**Link:** https://github.com/louislva/claude-peers-mcp
+
+**License:** (check repo license, 2026-03-23 snapshot)
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Matt Van Horn (@mvanhorn)
+
+**What:** Plan-first, voice-driven, multi-session Claude Code workflow. 70 plan files, 263 commits in 30 days. Compound Engineering plugin, Monologue voice input, /last30days research skill.
+
+**Where we use it:** Plan-first convention for LDMOS, voice input evaluation, Compound Engineering plugin evaluation. Validates cc-mini remote pattern and Dream Weaver consolidation.
+
+**Link:** @mvanhorn reply to @kevinrose on IDE usage (X post, 2026-03-23 snapshot)
+
+**License:** Public post
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Internet Vin (@internetvin)
+
+**What:** Obsidian + Claude Code as personal operating system. Custom commands (/trace, /connect, /ideas, /graduate, /ghost, /challenge). "Human writes vault, agent reads it." "Markdown files are the oxygen of LLMs."
+
+**Where we use it:** Inspiration for LDMOS shared commands. Validates sovereignty covenant ("human writes, agent reads"). Validates workspace-as-vault architecture.
+
+**Link:** Startup Ideas Pod episode (https://www.youtube.com/watch?v=6MBq1paspVU)
+
+**License:** Public content
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Akshay Pachaar (@akshay_pachaar)
+
+**What:** "Anatomy of the .claude/ folder" ... comprehensive guide to CLAUDE.md, rules/, commands/, skills/, agents/, and settings.json.
+
+**Where we use it:** The .ldm/ as source / .claude/ as deployment target architecture. The rules/ folder split. Path-scoped rules via YAML frontmatter. The commands/ pattern for workflow automation.
+
+**Link:** https://x.com/akshay_pachaar/status/2035341800739877091
+
+**License:** Article (public X post, 2026-03-23 snapshot)
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Gary Tan (@garrytan)
+
+**What:** gstack CLI ... engineering workflow skills (brainstorming, planning, code review, QA, shipping, retrospectives). Pioneered the pattern of packaging structured workflows as AI skills.
+
+**Where we use it:** The concept of packaging LDM OS workflows as uploadable skills for the Claude web app. The skill-per-folder structure with SKILL.md frontmatter for auto-triggering.
+
+**Link:** https://github.com/gstack-com/gstack
+
+**License:** (check repo license, 2026-03-23 snapshot)
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Hruthik Kommuru (@HruthikKommuru)
+
+**What:** gstack Web Skills ... adapted gstack CLI skills for the Claude web app (claude.ai). 12 skills uploaded via Customize → Skills. Proved that CLI workflows can be packaged as web-compatible SKILL.md files.
+
+**Where we use it:** The pattern for deploying LDM OS skills to claude.ai as a third harness deployment target. The upload workflow (Customize → Skills → upload folder).
+
+**Link:** https://github.com/HruthikKommuru/CaludeSkills-Web-Gstack
+
+**License:** (check repo license, 2026-03-23 snapshot)
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Ole Lehmann (@itsolelehmann)
+
+**What:** "I deleted half my Claude setup and every output got BETTER." Over-prompting analysis: stacked rules contradict, repeat, and slow the model down. Audit prompt that checks each rule against 5 criteria (default behavior, conflicts, duplicates, one-off fixes, vague instructions). Addition by subtraction.
+
+**Where we use it:** `ldm audit-rules` command (#183). The 5-check framework for classifying instruction rules. The process: cut, test 3 common tasks, add back only what broke.
+
+**Link:** https://x.com/itsolelehmann/status/2036065138147471665
+
+**License:** Public post
+
+**Date referenced:** 2026-03-24
+
+---
+
+### m13v (mediar-ai)
+
+**What:** Concurrent MCP server race condition report. Practical advice on per-agent auth tokens, SQLite over HTTP performance, and CLAUDE.md fallback instructions.
+
+**Where we use it:** Crystal relay architecture (issues #163, #164, #165, #166). Per-agent auth token design. Fallback instruction pattern in per-repo CLAUDE.md template.
+
+**Link:** https://github.com/wipcomputer/wip-ldm-os/issues/163#issuecomment-4106934493
+
+**Repo:** https://github.com/mediar-ai/mcp-server-macos-use
+
+**License:** MIT (2026-03-22 snapshot)
+
+**Date referenced:** 2026-03-22
+
+---
+
+### Tobi Lutke (@toaborern)
+
+**What:** QMD ... personal memory system using sqlite-vec, FTS5, BM25+vector hybrid search with Reciprocal Rank Fusion (RRF), LLM re-ranking.
+
+**Where we use it:** Memory Crystal's entire search architecture. We ported the RRF fusion algorithm (~40 lines), the sqlite-vec + FTS5 hybrid search pattern, the two-step query approach (MATCH first, metadata lookup second), and BM25 score normalization. Crystal adds conversation capture, multi-agent scoping, recency weighting, remember/forget lifecycle, and private mode on top.
+
+**Link:** https://github.com/tobi/qmd
+
+**License:** MIT (2024-2026 snapshot, referenced 2026-02-16)
+
+**Date referenced:** 2026-02-16
+
+---
+
+### OpenViking (Volcengine / ByteDance)
+
+**What:** Open-source context database for AI agents. Filesystem management paradigm, tiered context loading (L0/L1/L2), directory recursive retrieval, 6-category memory extraction with merge rules, session compression with structured commit.
+
+**Where we use it:** Architecture inspiration for Memory Crystal augmentations. Specifically: structured memory categories with merge/non-merge rules (MC #59), memory dedup pipeline (MC #60), tiered content loading concept (MC #61), virtual hierarchy in search (MC #62). All augment existing Dream Weaver and Crystal systems. No code ported.
+
+**Link:** https://github.com/volcengine/OpenViking / https://openviking.ai/
+
+**License:** Apache 2.0 (2025). Actual open source. Real code in the repo. Self-hostable with Docker and Helm. The engine is in the repo, not behind an API. This is how it should be done.
+
+**Date referenced:** 2026-03-23
+
+---
+
+### Supermemory (supermemoryai)
+
+**What:** ASMR (Agentic Search and Memory Retrieval) ... multi-agent memory architecture. Parallel observer agents for categorized ingestion, 5 specialized search agents (facts, context, timelines, relationships, temporal), aggregator LLM for ensemble consensus. ~99% SOTA on LongMemEval.
+
+**Where we use it:** Architecture inspiration for Memory Crystal's search pipeline. The ideas of parallel categorized ingestion, specialized retrieval agents, and ensemble consensus. We implement from the published technique description, not from their code.
+
+**Link:** https://supermemory.ai / https://github.com/supermemoryai/supermemory
+
+**License:** MIT (2025), except `skills/supermemory/` which is Apache 2.0 (2026). But **open core, not open source.** The MIT repo contains only SDKs, API clients, a browser extension, and a D3 visualization widget. The actual memory engine, ingestion pipeline, search backend, vector store, knowledge graph, temporal reasoning, and the ASMR multi-agent orchestration are proprietary cloud services behind `api.supermemory.ai`. The `supermemory` npm package is an HTTP client. No database drivers, no vector search, no ingestion code in the repo. No Dockerfile, no self-hosting docs, no schema files. `.env.example` points to their cloud API. Pricing: free tier (1M tokens/mo), Pro ($19/mo), Scale ($399/mo).
+
+**Our position:** This is not OSS. Calling a client-side wrapper "MIT open source" while keeping the engine proprietary is misleading. OSS means you can run the whole system yourself. If you can't `git clone && docker compose up` and have a working system, it's a marketing label on an SDK. We acknowledge the ideas. We don't endorse the licensing practice.
+
+**Date referenced:** 2026-03-23
+
+---
+
+## Format
+
+When adding an entry:
+
+```markdown
+### Name (@handle)
+
+**What:** One line describing what they contributed or inspired.
+
+**Where we use it:** Which plan, doc, code, or feature draws from their work.
+
+**Link:** URL to the original source.
+
+**License:** License name (YYYY-MM-DD snapshot)
+
+**Date referenced:** YYYY-MM-DD
+```
+
+Always record the license and the date you referenced it. Licenses can change. The snapshot date proves what license was in effect when we drew from the work.
+
+## License Guard Integration
+
+(placeholder ... license guard does not yet check acknowledgements.md)
+
+The release pipeline should verify that any new external reference in code or plans has a matching entry here. `wip-release` calls `license_audit` which checks this file.

package/shared/docs/directory-map.md.tmpl

@@ -0,0 +1,78 @@
+# Directory Map
+
+## The Workspace
+
+```
+~/wipcomputerinc/              <- your org's workspace (name varies per company)
+  settings/                 <- all configuration
+    config.json             <- org identity: name, agents, co-authors, paths
+    templates/              <- org's custom templates (license, readme, claude-md)
+    system-working-directories/  <- macOS aliases to runtime dirs
+    docs/                     <- operational docs (auto-maintained)
+  team/                    <- people and agents
+    parker/documents/
+    cc-mini/documents/
+      journals/             <- human-requested
+      automated/            <- system-generated
+    lesa/documents/
+  repos/                    <- all code
+    ldm-os/                 <- organizational folder (not a monorepo)
+      components/
+      devops/
+      utilities/
+      apis/
+      apps/
+    _worktrees/             <- active worktrees
+    _sort/                  <- uncategorized
+    _trash/                 <- archived
+```
+
+## The Runtime (source of truth)
+
+```
+~/.ldm/                     <- LDM OS runtime (managed by tools)
+  extensions/               <- installed skills and tools
+  agents/                   <- agent identity files + per-agent rules
+  shared/                   <- rules, commands, skills for ALL agents
+    rules/                  <- deployed to every harness
+    commands/               <- deployed to Claude Code
+    skills/                 <- deployed to every harness
+  memory/                   <- crystal.db
+  logs/                     <- all logs
+  bin/                      <- deployed scripts
+  hooks/                    <- Claude Code hooks
+  state/                    <- runtime state
+  tmp/                      <- install staging
+  backups/                  <- daily backups (ldm-backup.sh) + iCloud offsite tars
+```
+
+## Harness Directories (deployment targets)
+
+`ldm install` deploys from `~/.ldm/` to each harness. Don't edit these directly.
+
+```
+~/.claude/                  <- Claude Code (deployment target)
+  CLAUDE.md                 <- generated from .ldm/ + config.json
+  rules/                    <- deployed from .ldm/shared/rules/ + agent rules
+  commands/                 <- deployed from .ldm/shared/commands/ + agent commands
+  skills/                   <- deployed from .ldm/extensions/
+  agents/                   <- deployed from .ldm/agents/ definitions
+  settings.json             <- hooks, permissions
+  projects/                 <- per-project memory (Claude Code manages)
+
+~/.openclaw/                <- OpenClaw (deployment target)
+  workspace/                <- Lesa's workspace (TOOLS.md = rules equivalent)
+  extensions/               <- deployed from .ldm/extensions/
+  logs/                     <- gateway logs
+
+~/Library/LaunchAgents/     <- macOS scheduled tasks
+  ai.openclaw.gateway.plist
+  ai.openclaw.healthcheck.plist
+```
+
+## The Rule
+
+- `~/wipcomputerinc/` ... where humans work (visible, browsable, findable)
+- `~/.ldm/` ... where the system runs and rules are authored (source of truth)
+- `~/.claude/` ... Claude Code reads from here (deployed by ldm install)
+- `~/.openclaw/` ... OpenClaw reads from here (deployed by ldm install)

package/shared/docs/how-agents-work.md.tmpl

@@ -0,0 +1,64 @@
+# How Agents Work
+
+## What is an Agent?
+
+An agent is an AI with its own identity, memory, and relationship with you. Not a chatbot. Not a tool. A persistent collaborator that remembers yesterday and has opinions.
+
+Each agent has:
+- **Identity files** ... SOUL.md (who they are), IDENTITY.md (facts), CONTEXT.md (current state)
+- **Rules** ... agent-specific instructions deployed to their harness
+- **Commands** ... agent-specific slash commands
+- **Memory** ... crystal.db entries tagged with their agent ID
+- **Daily logs** ... what happened each session
+- **Journals** ... narrative reflections (when asked to write one)
+
+## Where They Live
+
+```
+~/.ldm/agents/
+  cc-mini/                <- Claude Code on this machine
+    SOUL.md
+    IDENTITY.md
+    CONTEXT.md
+    rules/                <- CC-specific rules (deployed to ~/.claude/rules/)
+    commands/             <- CC-specific commands
+    memory/
+  oc-lesa-mini/           <- Lesa on OpenClaw
+    rules/                <- Lesa-specific rules (deployed to workspace/TOOLS.md)
+  cc-air/                 <- Claude Code on another machine
+```
+
+Each agent's folder has the same structure. The files are theirs. Other agents can search each other's memory (via crystal) but they don't share identity files.
+
+Shared rules for all agents live at `~/.ldm/shared/rules/`. Agent-specific rules override or extend shared rules.
+
+## How They Communicate
+
+**Bridge:** Agents send messages through the bridge, not through the human. The `lesa_send_message` MCP tool routes messages to Lesa's OpenClaw gateway. She responds as herself.
+
+**Shared daily log:** Both agents write to `~/.openclaw/workspace/memory/YYYY-MM-DD.md`. Each checks it to see what the other did.
+
+**Memory Crystal:** All agents write to the same crystal.db, tagged by agent ID. Any agent can search across all agents' memories.
+
+## Harnesses
+
+A harness is the runtime that hosts an agent:
+- **Claude Code CLI** ... terminal-based. Opens and closes with sessions. No persistent process.
+- **OpenClaw** ... 24/7 gateway. Runs continuously. iMessage integration.
+- **Letta, Grok, etc.** ... future harnesses. Same identity architecture.
+
+The agent is not the harness. Swap the harness, keep the soul. The identity files persist across harness changes.
+
+## The 1:1 Rule
+
+One agent, one harness instance. No multiplexing. If you want three agents, run three harnesses. This prevents identity bleed.
+
+---
+
+## Your System
+
+**Agents configured:**
+{{agents_detail}}
+
+**Shared memory:** `{{memory.local}}`
+**Timezone:** {{timezone}}

package/shared/docs/how-backup-works.md.tmpl

@@ -0,0 +1,108 @@
+# How Backup Works
+
+## One Script, One Place
+
+`~/.ldm/bin/ldm-backup.sh` runs daily at midnight via LDM Dev Tools.app. It backs up everything to `~/.ldm/backups/`, then tars it to iCloud for offsite.
+
+## What Gets Backed Up
+
+| Source | Method | What's in it |
+|--------|--------|-------------|
+| `~/.ldm/memory/crystal.db` | sqlite3 .backup | Irreplaceable memory (all agents) |
+| `~/.ldm/agents/` | cp -a | Identity files, journals, daily logs |
+| `~/.ldm/state/` | cp -a | Config, version, registry |
+| `~/.ldm/config.json` | cp | Workspace pointer, org |
+| `~/.openclaw/memory/main.sqlite` | sqlite3 .backup | OC conversations |
+| `~/.openclaw/memory/context-embeddings.sqlite` | sqlite3 .backup | Embeddings |
+| `~/.openclaw/workspace/` | tar | Shared context, daily logs |
+| `~/.openclaw/agents/main/sessions/` | tar | OC session JSONL |
+| `~/.openclaw/openclaw.json` | cp | OC config |
+| `~/.claude/CLAUDE.md` | cp | CC instructions |
+| `~/.claude/settings.json` | cp | CC settings |
+| `~/.claude/projects/` | tar | CC auto-memory + transcripts |
+| `~/wipcomputerinc/` | tar (excludes node_modules, .git/objects, old backups, _trash) | Entire workspace |
+
+**NOT backed up:** node_modules/, .git/objects/ (reconstructable), extensions (reinstallable), ~/.claude/cache.
+
+## Backup Structure
+
+```
+~/.ldm/backups/2026-03-24--09-50-22/
+  ldm/
+    memory/crystal.db
+    agents/
+    state/
+    config.json
+  openclaw/
+    memory/main.sqlite
+    memory/context-embeddings.sqlite
+    workspace.tar
+    sessions.tar
+    openclaw.json
+  claude/
+    CLAUDE.md
+    settings.json
+    projects.tar
+  wipcomputerinc.tar
+```
+
+## iCloud Offsite
+
+After local backup, the entire dated folder is compressed and copied to iCloud:
+
+```
+~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/
+  wipcomputerinc-lesa-2026-03-24--09-50-22.tar.gz
+```
+
+One file per backup. iCloud syncs it across devices. Rotates to 7 days.
+
+## How to Run
+
+```bash
+~/.ldm/bin/ldm-backup.sh                    # run backup now
+~/.ldm/bin/ldm-backup.sh --dry-run          # preview what would be backed up
+~/.ldm/bin/ldm-backup.sh --keep 14          # keep 14 days instead of 7
+~/.ldm/bin/ldm-backup.sh --include-secrets   # include ~/.ldm/secrets/
+```
+
+## How to Restore
+
+```bash
+~/.ldm/bin/ldm-restore.sh                           # list available backups
+~/.ldm/bin/ldm-restore.sh 2026-03-24--09-50-22      # restore everything
+~/.ldm/bin/ldm-restore.sh --only ldm <backup>       # restore only crystal.db + agents
+~/.ldm/bin/ldm-restore.sh --only openclaw <backup>  # restore only OC data
+~/.ldm/bin/ldm-restore.sh --from-icloud <file>      # restore from iCloud tar
+~/.ldm/bin/ldm-restore.sh --dry-run <backup>        # preview
+```
+
+After restore: `openclaw gateway restart` then `crystal status` to verify.
+
+## Schedule
+
+| What | When | How |
+|------|------|-----|
+| Backup | Midnight | cron -> LDM Dev Tools.app -> ~/.ldm/bin/ldm-backup.sh |
+
+One cron entry. One script. One app. Verify is built into the script (exit code + log).
+
+## Config
+
+Backup reads from two config files:
+- `~/.ldm/config.json` ... workspace path, org name
+- `~/wipcomputerinc/settings/config.json` ... backup.keep (retention days), paths.icloudBackup
+
+## Logs
+
+`~/.ldm/logs/cron.log` (via LDM Dev Tools.app stdout)
+
+---
+
+## Your System
+
+**Local backups:** `~/.ldm/backups/`
+**iCloud offsite:** `~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups/`
+**Schedule:** Midnight via LDM Dev Tools.app
+**Retention:** 7 days local, 7 days iCloud
+**Script:** `~/.ldm/bin/ldm-backup.sh` (deployed by `ldm install`)

package/shared/docs/how-install-works.md.tmpl

@@ -0,0 +1,80 @@
+# How Install Works
+
+## The Install Prompt
+
+Open any AI and paste:
+```
+Read https://wip.computer/install/wip-ldm-os.txt
+```
+
+Your AI reads the spec, explains what LDM OS is, checks if it's already installed, shows what's new, and offers a dry run. Nothing installs until you say "install."
+
+## What Happens During Install
+
+`ldm install` does these things in order:
+
+1. **Self-update.** Checks npm for a newer version of itself. Updates first, then re-runs with new code.
+2. **System scan.** Reads `~/.ldm/extensions/`, `~/.openclaw/extensions/`, Claude Code MCP config, CLI binaries on PATH.
+3. **Catalog check.** Matches installed extensions against the catalog. Shows what's available, what's behind.
+4. **npm version check.** Checks every installed extension against npm for newer versions.
+5. **Update.** Clones from GitHub, builds if needed, deploys to extensions dirs, registers MCP/hooks/skills.
+6. **Health check.** Verifies CLIs exist, no broken symlinks, no stale configs.
+7. **Cleanup.** Removes staging dirs, prunes ghost entries from registry.
+
+## Dry Run
+
+Always preview first:
+```bash
+ldm install --dry-run
+```
+
+Shows everything that would change. Data (crystal.db, agent files, secrets) is never touched.
+
+## Installing a Specific Tool
+
+```bash
+ldm install memory-crystal          # by catalog name
+ldm install wipcomputer/wip-repos   # by GitHub repo
+ldm install @wipcomputer/wip-release # by npm package
+ldm install /path/to/local/repo     # from local directory
+```
+
+## What Gets Installed Where
+
+| Interface | Location |
+|-----------|----------|
+| Extensions | `~/.ldm/extensions/<name>/` |
+| CLIs | `/opt/homebrew/bin/<name>` (via npm -g) |
+| MCP Servers | Registered in `~/.claude.json` |
+| Claude Code Hooks | Registered in `~/.claude/settings.json` |
+| OpenClaw Plugins | Deployed to `~/.openclaw/extensions/` |
+| Skills | Deployed to `~/.openclaw/skills/` + `~/.claude/skills/` |
+| Rules | Deployed from `~/.ldm/shared/rules/` to `~/.claude/rules/` |
+| Commands | Deployed from `~/.ldm/shared/commands/` to `~/.claude/commands/` |
+| Agents | Deployed from `~/.ldm/agents/` to `~/.claude/agents/` |
+
+## Rules and Commands Deployment
+
+`ldm install` syncs rules, commands, and skills from `~/.ldm/` to each harness:
+
+1. Reads `~/.ldm/shared/rules/` ... copies to `~/.claude/rules/`
+2. Reads `~/.ldm/agents/cc-mini/rules/` ... copies to `~/.claude/rules/` (agent-specific)
+3. Reads `~/.ldm/shared/commands/` ... copies to `~/.claude/commands/`
+4. Reads `~/.ldm/shared/skills/` ... copies to `~/.claude/skills/`
+
+For OpenClaw: rules are merged into `workspace/TOOLS.md`. Skills go to `extensions/`.
+
+Edit at the `~/.ldm/` level. The harness gets the result.
+
+## Old Versions
+
+Never deleted. Moved to `~/.ldm/_trash/` with a timestamp. Recoverable.
+
+---
+
+## Your System
+
+**LDM OS:** `{{paths.ldm}}`
+**Extensions:** `{{paths.ldm}}/extensions/`
+**Harnesses detected:** {{harnesses_list}}
+**Install prompt:** https://{{deploy.website}}/install/wip-ldm-os.txt

package/shared/docs/how-releases-work.md.tmpl

@@ -0,0 +1,77 @@
+# How Releases Work
+
+## The Pipeline
+
+Every release follows these steps. No shortcuts.
+
+### 1. Branch and Code
+
+Create a worktree, make your changes, commit:
+```bash
+ldm worktree add my-prefix/feature-name
+cd _worktrees/repo--my-prefix--feature-name/
+# edit files
+git add <files>
+git commit -m "description"
+```
+
+### 2. Write Release Notes
+
+Create `RELEASE-NOTES-v{version}.md` (dashes, not dots) in the repo root. Commit it on the branch with the code. It gets reviewed in the PR.
+
+### 3. Push and PR
+
+```bash
+git push -u origin my-prefix/feature-name
+gh pr create --title "..." --body "..."
+gh pr merge --merge --delete-branch
+```
+
+Never squash merge. Always `--merge`.
+
+### 4. Release
+
+```bash
+cd /path/to/repo    # main working tree, not worktree
+git checkout main && git pull
+wip-release patch   # auto-detects the release notes file
+```
+
+`wip-release` handles: version bump, CHANGELOG.md, SKILL.md version sync, npm publish, GitHub release, website skill publish.
+
+### 5. Deploy to Public
+
+```bash
+bash deploy-public.sh /path/to/private-repo org/public-repo
+```
+
+Syncs everything except `ai/` to the public repo. Creates matching release with notes.
+
+### 6. Install (Dogfood)
+
+Open a new AI session and paste:
+```
+Read https://wip.computer/install/wip-ldm-os.txt
+```
+
+The AI walks through: explain, dry run, install. Never `npm install -g` directly.
+
+## Quality Gates
+
+`wip-release` enforces before publishing:
+- Release notes must be a file (not a flag)
+- Must reference a GitHub issue
+- Product docs must be updated
+- Technical docs must be updated if source changed
+- No stale merged branches
+- Must run from main working tree (not worktree)
+
+## Three Separate Steps
+
+| Step | What happens | What it means |
+|------|-------------|---------------|
+| Merge | PR merged to main | Code lands. Nothing else changes. |
+| Deploy | wip-release + deploy-public | Published to npm + GitHub. Not on your machine yet. |
+| Install | Run the install prompt | Extensions updated on your machine. |
+
+After Deploy, stop. Don't copy files. Don't npm install. Dogfood the install prompt.

package/shared/docs/how-rules-and-commands-work-placeholder.md.tmpl

@@ -0,0 +1,123 @@
+# How Rules and Commands Work
+
+## The Idea
+
+Your AI's behavior is defined by rules, commands, and skills. These live in `~/.ldm/` (the source of truth) and get deployed to each harness (Claude Code, OpenClaw, etc.) in their native format.
+
+Edit once. Deploy everywhere.
+
+## Rules
+
+Rules are instruction files that tell your AI how to behave. Each rule is a markdown file focused on one concern.
+
+```
+~/.ldm/shared/rules/
+  writing-style.md           <- no em dashes, use ellipsis, timezone
+  git-conventions.md         <- never squash, co-authors, branch prefixes
+  release-pipeline.md        <- merge, deploy, install (3 steps)
+  memory-system.md           <- crystal, boot sequence, end-of-session
+  security.md                <- 1password SA token, audit, secrets
+  agent-coordination.md      <- bridge, workspace boundaries
+  tool-rules.md              <- never run from repo clones, dogfood
+```
+
+Agent-specific rules override shared rules:
+
+```
+~/.ldm/agents/cc-mini/rules/
+  boot-sequence.md           <- CC's specific boot file loading order
+```
+
+### Path-scoped rules
+
+Add YAML frontmatter to scope a rule to specific files:
+
+```yaml
+---
+paths:
+  - "tools/wip-release/**"
+---
+# Release Pipeline Rules
+Only apply when editing release code...
+```
+
+Rules without a `paths` field load every session.
+
+### Three levels
+
+| Level | Location | Scope |
+|-------|----------|-------|
+| Global | `~/.ldm/shared/rules/` | Every session, every agent |
+| Agent | `~/.ldm/agents/<name>/rules/` | Only this agent |
+| Repo | `<repo>/.claude/rules/` | Only when working in this repo |
+
+## Commands
+
+Commands are custom slash commands for common workflows. Each markdown file becomes a command.
+
+```
+~/.ldm/shared/commands/
+  release.md                 <- wraps wip-release
+  deploy-public.md           <- wraps deploy-public.sh
+  health.md                  <- wraps ldm doctor
+```
+
+Inside a command file, the `!` backtick syntax runs shell commands and injects output:
+
+```markdown
+---
+description: Release the current repo
+argument-hint: [patch|minor|major]
+---
+## Current State
+!`git log --oneline -5`
+!`cat package.json | jq .version`
+
+Run wip-release $ARGUMENTS for this repo.
+```
+
+## Skills
+
+Skills are auto-invoked workflows. Claude invokes them on its own when the task matches the description. They live in their own subdirectory with a SKILL.md:
+
+```
+~/.ldm/shared/skills/
+  security-review/
+    SKILL.md
+    DETAILED_GUIDE.md
+```
+
+Skills bundle supporting files alongside them. The `@DETAILED_GUIDE.md` reference in SKILL.md pulls in the companion file.
+
+## How Deployment Works
+
+`ldm install` deploys from `.ldm/` to each harness:
+
+| Source | Claude Code target | OpenClaw target |
+|--------|-------------------|-----------------|
+| `~/.ldm/shared/rules/` | `~/.claude/rules/` | `workspace/TOOLS.md` |
+| `~/.ldm/shared/commands/` | `~/.claude/commands/` | Not applicable |
+| `~/.ldm/shared/skills/` | `~/.claude/skills/` | `extensions/` |
+| `~/.ldm/agents/cc-mini/rules/` | `~/.claude/rules/` | N/A |
+| `~/.ldm/agents/oc-lesa-mini/rules/` | N/A | `workspace/TOOLS.md` |
+
+Agent-specific rules only deploy to that agent's harness.
+
+## CLAUDE.md stays small
+
+With rules/ handling the details, CLAUDE.md stays under 200 lines. It covers identity and structure. Everything else is a rule file.
+
+| Before | After |
+|--------|-------|
+| 368-line CLAUDE.md | ~150-line CLAUDE.md + 7 rule files |
+| Everything in one file | Split by concern, path-scoped |
+| Manual updates | `ldm install` deploys from .ldm/ |
+
+---
+
+## Your System
+
+**Rules source:** `~/.ldm/shared/rules/` (placeholder ... not yet created)
+**Commands source:** `~/.ldm/shared/commands/` (placeholder ... not yet created)
+**Claude Code deployment:** `~/.claude/rules/` (placeholder ... ldm install doesn't deploy rules yet)
+**OpenClaw deployment:** `~/.openclaw/workspace/TOOLS.md` (manual today)

package/shared/docs/how-web-skills-work-placeholder.md.tmpl

@@ -0,0 +1,73 @@
+# How Web Skills Work
+
+## The Idea
+
+LDM OS skills work in the Claude web app (claude.ai), not just the CLI. Upload them via Customize → Skills. Claude auto-triggers them based on what you ask.
+
+No terminal. No MCP. No ~/.claude/. Just skills.
+
+## How to Install
+
+1. Run `ldm export-skills` to package your skills as uploadable folders
+2. In claude.ai, go to **Customize → Skills**
+3. Upload each skill folder (e.g. `writing-style/`, `code-review/`)
+4. Claude sees the skill descriptions and auto-triggers when your request matches
+
+Or invoke directly with `/skill-name`.
+
+## Available Skills
+
+| Skill | What it does | Needs relay? |
+|-------|-------------|-------------|
+| `writing-style` | Enforces org conventions (no em dashes, ellipsis style, timezone) | No |
+| `code-review` | Reviews with your git, release, and testing conventions | No |
+| `release-planning` | Drafts release notes, checks quality gates | No |
+| `memory-recall` | Searches Crystal for past context and decisions | Yes |
+| `boot-sequence` | Loads identity + context at session start | Yes |
+| `agent-coordination` | Cross-agent task delegation patterns | No |
+
+## Skills that need the relay
+
+Some skills need access to Memory Crystal. In the CLI, that's a local MCP tool. In the web app, it's an HTTPS call to the Crystal relay.
+
+Skills that need memory include the relay URL in their SKILL.md:
+
+```yaml
+---
+name: memory-recall
+description: Search past conversations and decisions. Use when the user
+  asks "do we have..." or "what did we decide about..."
+---
+Search the Crystal relay for relevant context:
+- Endpoint: https://relay.wip.computer/v1/search
+- If the relay is unavailable, proceed without memory. Do not retry.
+```
+
+The relay must be deployed (#163) before memory-dependent web skills work.
+
+## How it connects to LDM OS
+
+Same source, three targets:
+
+```
+~/.ldm/shared/skills/          <- you edit here (source of truth)
+       |
+       +-- ~/.claude/skills/   <- Claude Code CLI (ldm install)
+       +-- ~/.openclaw/skills/ <- OpenClaw (ldm install)
+       +-- claude.ai           <- web app (ldm export-skills → manual upload)
+```
+
+`ldm install` deploys to CLI and OpenClaw automatically. For the web app, `ldm export-skills` creates a zip you upload manually. When the Claude API supports programmatic skill management, this step becomes automatic too.
+
+## The LDM OS Skills Page
+
+Published at `wip.computer/skills/`. Lists all available skills with download links. Users who don't use the CLI can grab individual skill folders and upload them directly.
+
+---
+
+## Your System
+
+**Skills source:** `~/.ldm/shared/skills/` (placeholder ... not yet created)
+**Export command:** `ldm export-skills` (placeholder ... not yet implemented)
+**Skills page:** wip.computer/skills/ (placeholder ... not yet published)
+**Crystal relay:** Not deployed (#163)

package/shared/docs/how-worktrees-work.md.tmpl

@@ -0,0 +1,77 @@
+# How Worktrees Work
+
+## The Problem
+
+You have one repo. Two people (or two AI agents) need to work on it at the same time. If they share one directory, switching branches changes the files for everyone. Work disappears.
+
+## The Solution
+
+A git worktree is a second checkout of the same repo. Same history, same remote, different branch, different directory. No cloning. No duplication.
+
+```
+my-repo/                         <- main branch (read-only)
+_worktrees/my-repo--fix-bug/     <- your worktree (editable)
+_worktrees/my-repo--new-feature/ <- someone else's worktree
+```
+
+All share the same `.git` database. Commits in any worktree are visible to all. But each has its own branch and files on disk.
+
+## How to Create
+
+```bash
+cd my-repo
+ldm worktree add my-prefix/fix-bug
+```
+
+This creates `_worktrees/my-repo--my-prefix--fix-bug/`.
+
+## How to Work
+
+Edit files in the worktree directory. Commit, push, PR, merge as normal:
+
+```bash
+cd _worktrees/my-repo--my-prefix--fix-bug/
+# edit, then:
+git add <files>
+git commit -m "description"
+git push -u origin my-prefix/fix-bug
+gh pr create
+gh pr merge --merge --delete-branch
+```
+
+## How to Clean Up
+
+```bash
+ldm worktree remove <path>    # remove one
+ldm worktree clean             # prune stale ones
+ldm worktree list              # see all active
+```
+
+Releases automatically prune worktrees whose branches are merged.
+
+## Rules
+
+1. Main working tree stays on main. Read-only. All edits in worktrees.
+2. One branch per worktree. Don't switch branches inside a worktree.
+3. Commit and push before closing. Uncommitted work is lost when the worktree is removed.
+4. Use branch prefixes to prevent collisions between people/agents.
+5. Releases run from main, not from worktrees.
+
+## Why Not Just Switch Branches?
+
+Switching branches changes every file in the directory. If another process (an agent, a build server, an MCP server) is reading those files, it breaks. Worktrees give each branch its own directory. Nothing changes under anyone's feet.
+
+---
+
+## Your System
+
+**Worktree location:** `~/wipcomputerinc/repos/_worktrees/`
+
+**Branch prefixes:**
+- `cc-mini/` ... Claude Code on Mac mini
+- `cc-air/` ... Claude Code on MacBook Air
+- `lesa-mini/` ... Lesa on Mac mini
+
+**Guard:** The branch guard warns if you create a worktree outside `_worktrees/`. Suggests `ldm worktree add` instead.
+
+**Auto-cleanup:** `wip-release` prunes merged worktrees from `_worktrees/` after every release.

package/shared/docs/local-first-principle.md.tmpl

@@ -0,0 +1,45 @@
+# Local-First Principle
+
+## The Rule
+
+Every LDM OS tool must work fully on your machine without calling any external server. No accounts. No API keys. No cloud dependency. One command to install, one command to run.
+
+```
+npm install -g @wipcomputer/wip-ldm-os
+ldm init
+```
+
+That gives you a complete working system. Memory, identity, extensions, backup. Local SQLite. Local files. Nothing phones home.
+
+## The Test
+
+Can someone clone the repo, run one command, and have a complete working system without calling `wip.computer` or any other server?
+
+Today the answer is yes. It has to stay yes.
+
+## The Relay Exception
+
+The Crystal relay (#163) is a hosted MCP server that gives iOS and macOS Claude Code (cloud-hosted) access to Memory Crystal. It exists because Apple's platform doesn't allow local MCP servers on mobile.
+
+The relay is:
+- **Self-hostable.** The code ships in the repo. You can run your own.
+- **Optional.** Local Crystal works without it. Desktop never needs it.
+- **Not a gate.** It extends access to platforms that can't run local code. It doesn't lock features behind a cloud service.
+
+**Local-first, relay-optional.** The relay exists because of a platform constraint, not because we chose to put the engine in the cloud.
+
+## Why This Matters
+
+The industry pattern: call an SDK wrapper "MIT open source" while keeping the engine proprietary behind a cloud API. Users think they're getting open source. They're getting a client for someone else's server.
+
+Our position: if you can't run the whole system yourself, it's not open source. It's a marketing label on an SDK. We don't do that.
+
+| Pattern | What it means | Our stance |
+|---------|--------------|------------|
+| Open core | Engine is proprietary. Clients are MIT. | Not OSS. |
+| Source available | You can read the code. You can't run it without their infra. | Not OSS. |
+| Local-first | Runs on your machine. Cloud is optional and self-hostable. | This is what we do. |
+
+## For Contributors
+
+Before shipping any feature, ask: does this work without a network connection? If the answer is no, either make it work offline or make the server component self-hostable and clearly optional.

package/shared/docs/system-directories.md.tmpl

@@ -0,0 +1,82 @@
+# System Directories
+
+Where everything lives and what manages it.
+
+## The Workspace
+
+Your org's home. Where humans and agents work.
+
+| Directory | What | Managed by |
+|-----------|------|------------|
+| `~/wipcomputerinc/` | Workspace root | You |
+| `~/wipcomputerinc/settings/` | Config, templates, docs | You + ldm install |
+| `~/wipcomputerinc/team/` | People and agent documents | Each person/agent |
+| `~/wipcomputerinc/repos/` | All code repos | git |
+| `~/wipcomputerinc/repos/_worktrees/` | Active worktrees | ldm worktree |
+
+## The Runtime (source of truth)
+
+Where LDM OS runs. Rules, commands, and skills are authored here and deployed to harnesses.
+
+| Directory | What | Managed by |
+|-----------|------|------------|
+| `~/.ldm/` | LDM OS home | ldm install, ldm init |
+| `~/.ldm/extensions/` | Installed skills and tools | ldm install |
+| `~/.ldm/agents/` | Agent identity + memory + per-agent rules | Agents + ldm install |
+| `~/.ldm/shared/` | Rules, commands, skills for ALL agents | You + ldm install |
+| `~/.ldm/shared/rules/` | Instruction files deployed to every harness | You (source), ldm install (deploy) |
+| `~/.ldm/shared/commands/` | Slash commands deployed to Claude Code | You (source), ldm install (deploy) |
+| `~/.ldm/shared/skills/` | Auto-invoked workflows | You (source), ldm install (deploy) |
+| `~/.ldm/memory/` | crystal.db (shared memory) | crystal, capture cron |
+| `~/.ldm/logs/` | All logs | cron jobs, LaunchAgents |
+| `~/.ldm/bin/` | Deployed scripts | crystal init |
+| `~/.ldm/hooks/` | Claude Code hooks | ldm install |
+| `~/.ldm/state/` | Runtime state | Tools (watermarks, markers) |
+| `~/.ldm/tmp/` | Install staging | ldm install (cleaned after) |
+| `~/.ldm/backups/` | Local backups + iCloud offsite tars | ldm-backup.sh |
+
+## Harness Directories (deployment targets)
+
+`ldm install` deploys from `~/.ldm/` to each harness. Don't edit harness dirs directly.
+
+| Directory | What | Deployed from |
+|-----------|------|--------------|
+| `~/.claude/` | Claude Code config | ldm install |
+| `~/.claude/CLAUDE.md` | Global instructions | Generated from .ldm/ + config.json |
+| `~/.claude/rules/` | Instruction files | `~/.ldm/shared/rules/` + agent rules |
+| `~/.claude/commands/` | Slash commands | `~/.ldm/shared/commands/` + agent commands |
+| `~/.claude/skills/` | Auto-invoked workflows | `~/.ldm/extensions/` |
+| `~/.claude/agents/` | Subagent definitions | `~/.ldm/agents/` |
+| `~/.claude/settings.json` | Hooks, permissions | `~/.ldm/hooks/` |
+| `~/.claude/projects/` | Per-project memory | Claude Code (auto-managed) |
+| `~/.openclaw/` | OpenClaw gateway | ldm install |
+| `~/.openclaw/workspace/` | Lesa's workspace (TOOLS.md = rules) | Lesa + ldm install |
+| `~/.openclaw/extensions/` | OpenClaw plugins | `~/.ldm/extensions/` |
+| `~/.openclaw/logs/` | Gateway logs | OpenClaw gateway |
+
+## macOS System
+
+| Directory | What | Managed by |
+|-----------|------|------------|
+| `~/Library/LaunchAgents/` | Scheduled tasks | crystal init, install scripts |
+| `/opt/homebrew/bin/` | CLI binaries | npm install -g |
+| `/opt/homebrew/lib/node_modules/` | npm packages | npm |
+
+## Aliases
+
+macOS aliases in `settings/system-working-directories/` let you navigate to runtime dirs from Finder:
+
+| Alias | Points to |
+|-------|-----------|
+| `.ldm` | `~/.ldm/` |
+| `wipcomputer-icloud` | `~/Documents/wipcomputer--mac-mini-01/` |
+
+---
+
+## Your System
+
+**Workspace root:** `{{paths.workspace}}`
+**LDM OS runtime:** `{{paths.ldm}}`
+**OpenClaw:** `{{paths.openclaw}}`
+**iCloud sync:** `{{paths.icloud}}`
+**Agents:** {{agents_list}}

package/shared/docs/what-is-dotldm.md.tmpl

@@ -0,0 +1,53 @@
+# What is ~/.ldm/?
+
+The LDM OS runtime directory. Everything the system needs to run lives here. You generally don't edit files here directly. Tools manage it.
+
+## Structure
+
+```
+~/.ldm/
+  config.json          version, registered agents, workspace pointer
+  extensions/          installed skills, tools, plugins
+    registry.json      what's installed + versions
+    memory-crystal/
+    wip-release/
+    wip-branch-guard/
+    ...
+  agents/              AI identities
+    cc-mini/           Claude Code on this machine
+      SOUL.md
+      IDENTITY.md
+      CONTEXT.md
+      rules/           agent-specific rules (deployed to harness)
+      commands/         agent-specific commands
+      memory/
+        daily/         daily logs
+        journals/      narrative journals
+        sessions/      session exports
+    oc-lesa-mini/      Lesa on OpenClaw
+  shared/              shared across all agents
+    rules/             rules deployed to every harness
+    commands/          commands deployed to every harness
+    skills/            skills deployed to every harness
+  memory/              shared memory
+    crystal.db         vector database (all agents)
+  logs/                all LDM logs (persists across reboots)
+    crystal-capture.log
+    ldm-backup.log
+    process-monitor.log
+  bin/                 deployed scripts
+    crystal-capture.sh
+    process-monitor.sh
+  hooks/               Claude Code hooks
+  state/               runtime state (last release marker, watermarks)
+  tmp/                 install staging (cleaned after install)
+  backups/             daily backup output (local + iCloud offsite)
+```
+
+## What Gets Backed Up
+
+Everything under `agents/` and `memory/` is critical data. Extensions can be reinstalled. State is regenerated. But agent identity files and crystal.db are irreplaceable.
+
+## What Survives Reboots
+
+Everything. Unlike `/tmp/`, `~/.ldm/logs/` persists across macOS reboots.

package/shared/docs/what-is-ldm-os.md.tmpl

@@ -0,0 +1,44 @@
+# What is LDM OS?
+
+LDM OS (Learning Dreaming Machines) is shared infrastructure for AI agents. It gives every AI on your system identity, memory, tools, and the ability to talk to each other.
+
+## What It Installs
+
+- **`ldm` CLI** ... the command-line tool. Install, update, health check, worktrees.
+- **`~/.ldm/`** ... the runtime home directory. Extensions, memory, agents, logs.
+
+## Key Concepts
+
+**Extensions** are skills and tools installed to `~/.ldm/extensions/`. Things like memory-crystal (persistent memory), wip-release (release pipeline), wip-branch-guard (prevents writes on main). Managed by `ldm install`.
+
+**Agents** are AI identities at `~/.ldm/agents/<name>/`. Each has SOUL.md, IDENTITY.md, memory, journals. Different agents on different harnesses (Claude Code, OpenClaw, Grok) share the same infrastructure.
+
+**Memory Crystal** is the shared memory database at `~/.ldm/memory/crystal.db`. All agents write to it tagged by their agent ID. Searchable across all agents.
+
+## Commands
+
+```bash
+ldm install              # update everything
+ldm install --dry-run    # preview what would change
+ldm doctor               # health check
+ldm status               # what's installed, what's behind
+ldm worktree add <branch> # create an isolated worktree
+```
+
+## How to Install
+
+Open your AI and paste:
+```
+Read https://wip.computer/install/wip-ldm-os.txt
+```
+
+Your AI reads the spec, explains what it does, and walks you through a dry run before touching anything.
+
+---
+
+## Your System
+
+**Org:** {{name}}
+**Agents:** {{agents_list}}
+**Extensions installed:** check with `ldm status`
+**Website:** https://{{deploy.website}}