@wipcomputer/wip-ldm-os 0.4.71 → 0.4.73-alpha.1

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.71"
+  version: "0.4.72"
   homepage: "https://github.com/wipcomputer/wip-ldm-os"
   author: "Parker Todd Brooks"
   category: infrastructure

package/bin/ldm.js

@@ -20,7 +20,7 @@
  *   ldm --version         Show version
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync, unlinkSync, readlinkSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync, unlinkSync, readlinkSync, renameSync, statSync } from 'node:fs';
 import { join, basename, resolve, dirname } from 'node:path';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -148,6 +148,8 @@ const NONE_FLAG = args.includes('--none');
 const FIX_FLAG = args.includes('--fix');
 const CLEANUP_FLAG = args.includes('--cleanup');
 const CHECK_FLAG = args.includes('--check');
+const ALPHA_FLAG = args.includes('--alpha');
+const BETA_FLAG = args.includes('--beta');
 
 function readJSON(path) {
   try {
@@ -411,6 +413,174 @@ async function installCatalogComponent(c) {
 }
 
 // ── Bridge deploy (#245) ──
+// Deploy all scripts from scripts/ to ~/.ldm/bin/
+// Called from both cmdInit() and cmdInstallCatalog() so script fixes land on every update.
+function deployScripts() {
+  const scriptsSrc = join(__dirname, '..', 'scripts');
+  if (!existsSync(scriptsSrc)) return 0;
+  mkdirSync(join(LDM_ROOT, 'bin'), { recursive: true });
+  let count = 0;
+  for (const file of readdirSync(scriptsSrc)) {
+    if (!file.endsWith('.sh')) continue;
+    const src = join(scriptsSrc, file);
+    const dest = join(LDM_ROOT, 'bin', file);
+    cpSync(src, dest);
+    chmodSync(dest, 0o755);
+    count++;
+  }
+  if (count > 0) {
+    console.log(`  + ${count} script(s) deployed to ~/.ldm/bin/`);
+  }
+  return count;
+}
+
+// Deploy personalized docs to both settings/docs/ and library/documentation/
+// Called from both cmdInit() and cmdInstallCatalog() so doc fixes land on every update.
+function deployDocs() {
+  const docsSrc = join(__dirname, '..', 'shared', 'docs');
+  if (!existsSync(docsSrc)) return 0;
+
+  let workspacePath = '';
+  try {
+    const ldmConfig = JSON.parse(readFileSync(join(LDM_ROOT, 'config.json'), 'utf8'));
+    workspacePath = (ldmConfig.workspace || '').replace('~', HOME);
+  } catch { return 0; }
+  if (!workspacePath || !existsSync(workspacePath)) return 0;
+
+  // Read config for template vars
+  let ldmConfig;
+  try {
+    ldmConfig = JSON.parse(readFileSync(join(LDM_ROOT, 'config.json'), 'utf8'));
+  } catch { return 0; }
+
+  const sc = ldmConfig;
+
+  // Agents from 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 config
+  const harnessConfig = sc.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,
+  };
+
+  function renderTemplates(destDir) {
+    mkdirSync(destDir, { recursive: true });
+    let count = 0;
+    for (const file of readdirSync(docsSrc)) {
+      if (!file.endsWith('.tmpl')) continue;
+      let content = readFileSync(join(docsSrc, file), 'utf8');
+      content = content.replace(/\{\{([^}]+)\}\}/g, (match, key) => {
+        return templateVars[key.trim()] || match;
+      });
+      const outName = file.replace('.tmpl', '');
+      writeFileSync(join(destDir, outName), content);
+      count++;
+    }
+    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)
+  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, '~')}/`);
+    }
+  }
+
+  return docsCount;
+}
+
+// Check backup health: is a trigger configured, did it run recently, is iCloud set up?
+// Called from cmdInstallCatalog() on every install.
+function checkBackupHealth() {
+  const config = readJSON(join(LDM_ROOT, 'config.json'));
+  if (!config) return;
+
+  const backup = config.backup || {};
+  const issues = [];
+
+  // Check iCloud offsite
+  const icloudPath = config.paths?.icloudBackup || backup.icloudPath;
+  if (!icloudPath) {
+    issues.push('iCloud offsite not configured. Add paths.icloudBackup to ~/.ldm/config.json');
+  } else {
+    const expandedPath = icloudPath.replace(/^~/, HOME);
+    if (!existsSync(expandedPath)) {
+      try { mkdirSync(expandedPath, { recursive: true }); } catch {}
+      if (!existsSync(expandedPath)) {
+        issues.push(`iCloud path does not exist: ${icloudPath}`);
+      }
+    }
+  }
+
+  // Check LaunchAgent
+  try {
+    const label = backup.triggerLabel || 'ai.openclaw.ldm-backup';
+    const result = execSync(`launchctl list ${label} 2>/dev/null`, { encoding: 'utf8', timeout: 3000 });
+    if (!result) issues.push(`LaunchAgent ${label} not loaded`);
+  } catch {
+    issues.push('Backup LaunchAgent not loaded. Backups may not run automatically.');
+  }
+
+  // Check last backup age
+  const backupRoot = join(LDM_ROOT, 'backups');
+  if (existsSync(backupRoot)) {
+    const dirs = readdirSync(backupRoot)
+      .filter(d => d.match(/^20\d{2}-\d{2}-\d{2}--/) && statSync(join(backupRoot, d)).isDirectory())
+      .sort()
+      .reverse();
+    if (dirs.length > 0) {
+      const latest = dirs[0];
+      const latestDate = latest.replace(/--.*/, '').replace(/-/g, '/');
+      const age = Date.now() - new Date(latestDate).getTime();
+      const hours = Math.round(age / (1000 * 60 * 60));
+      if (hours > 36) {
+        issues.push(`Last backup is ${hours} hours old (${latest}). Expected within 24 hours.`);
+      }
+    } else {
+      issues.push('No backups found. Run: ldm backup');
+    }
+  }
+
+  // Check backup script exists
+  const scriptPath = join(LDM_ROOT, 'bin', 'ldm-backup.sh');
+  if (!existsSync(scriptPath)) {
+    issues.push('Backup script missing at ~/.ldm/bin/ldm-backup.sh. Run: ldm init');
+  }
+
+  if (issues.length > 0) {
+    for (const issue of issues) {
+      console.log(`  ! Backup: ${issue}`);
+    }
+  }
+}
+
 // The bridge (src/bridge/) builds to dist/bridge/ and ships in the npm package.
 // After `npm install -g`, the updated files live at the npm package location but
 // never get copied to ~/.ldm/extensions/lesa-bridge/dist/. This function fixes that.
@@ -724,29 +894,8 @@ async function cmdInit() {
     }
   }
 
-  // Deploy backup + restore scripts (#119)
-  const backupSrc = join(__dirname, '..', 'scripts', 'ldm-backup.sh');
-  const backupDest = join(LDM_ROOT, 'bin', 'ldm-backup.sh');
-  if (existsSync(backupSrc)) {
-    mkdirSync(join(LDM_ROOT, 'bin'), { recursive: true });
-    cpSync(backupSrc, backupDest);
-    chmodSync(backupDest, 0o755);
-    console.log(`  + ldm-backup.sh deployed to ~/.ldm/bin/`);
-  }
-  const restoreSrc = join(__dirname, '..', 'scripts', 'ldm-restore.sh');
-  const restoreDest = join(LDM_ROOT, 'bin', 'ldm-restore.sh');
-  if (existsSync(restoreSrc)) {
-    cpSync(restoreSrc, restoreDest);
-    chmodSync(restoreDest, 0o755);
-    console.log(`  + ldm-restore.sh deployed to ~/.ldm/bin/`);
-  }
-  const summarySrc = join(__dirname, '..', 'scripts', 'ldm-summary.sh');
-  const summaryDest = join(LDM_ROOT, 'bin', 'ldm-summary.sh');
-  if (existsSync(summarySrc)) {
-    cpSync(summarySrc, summaryDest);
-    chmodSync(summaryDest, 0o755);
-    console.log(`  + ldm-summary.sh deployed to ~/.ldm/bin/`);
-  }
+  // Deploy all scripts from scripts/ to ~/.ldm/bin/ (#119)
+  deployScripts();
 
   // Deploy shared rules to ~/.ldm/shared/rules/ and to harnesses
   const rulesSrc = join(__dirname, '..', 'shared', 'rules');
@@ -859,67 +1008,8 @@ 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 ~/.ldm/config.json (unified config)
-        // Legacy: settings/config.json was a separate file, now merged into config.json
-        const sc = ldmConfig;
-        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 {}
-  }
+  // Deploy personalized docs to settings/docs/ and library/documentation/
+  deployDocs();
 
   // Deploy LaunchAgents to ~/Library/LaunchAgents/
   // Templates use {{HOME}} and {{OPENCLAW_GATEWAY_TOKEN}} placeholders, replaced at deploy time.
@@ -1103,6 +1193,8 @@ async function cmdInstall() {
     --json       JSON output
     --yes        Auto-accept catalog prompts
     --none       Skip catalog prompts
+    --alpha      Check @alpha npm tag for updates (prerelease track)
+    --beta       Check @beta npm tag for updates (prerelease track)
 `);
     process.exit(0);
   }
@@ -1410,13 +1502,19 @@ async function cmdInstallCatalog() {
   // Self-update: check if CLI itself is outdated. Update first, then re-exec.
   // This breaks the chicken-and-egg: new features in ldm install are always
   // available because the installer upgrades itself before doing anything else.
+  // --alpha and --beta flags check the corresponding npm dist-tag instead of @latest.
   if (!DRY_RUN && !process.env.LDM_SELF_UPDATED) {
     try {
-      const latest = execSync('npm view @wipcomputer/wip-ldm-os version 2>/dev/null', {
+      const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
+      const trackLabel = npmTag === 'latest' ? '' : ` (${npmTag} track)`;
+      const npmViewCmd = npmTag === 'latest'
+        ? 'npm view @wipcomputer/wip-ldm-os version 2>/dev/null'
+        : `npm view @wipcomputer/wip-ldm-os dist-tags.${npmTag} 2>/dev/null`;
+      const latest = execSync(npmViewCmd, {
         encoding: 'utf8', timeout: 15000,
       }).trim();
       if (latest && latest !== PKG_VERSION) {
-        console.log(`  LDM OS CLI v${PKG_VERSION} -> v${latest}. Updating first...`);
+        console.log(`  LDM OS CLI v${PKG_VERSION} -> v${latest}${trackLabel}. Updating first...`);
         try {
           execSync(`npm install -g @wipcomputer/wip-ldm-os@${latest}`, { stdio: 'inherit', timeout: 60000 });
           console.log(`  CLI updated to v${latest}. Re-running with new code...`);
@@ -1451,6 +1549,13 @@ async function cmdInstallCatalog() {
   // in the extension directories. This copies them to both LDM and OpenClaw targets.
   deployBridge();
 
+  // Deploy scripts and docs on every install so fixes land without re-init
+  deployScripts();
+  deployDocs();
+
+  // Check backup configuration
+  checkBackupHealth();
+
   const { detectSystemState, reconcileState, formatReconciliation } = await import('../lib/state.mjs');
   const state = detectSystemState();
   const reconciled = reconcileState(state);
@@ -1724,9 +1829,14 @@ async function cmdInstallCatalog() {
     }
 
     // Check npm for updates (fast, one HTTP call)
+    // --alpha and --beta flags check the corresponding npm dist-tag
     if (npmPkg) {
       try {
-        const latestVersion = execSync(`npm view ${npmPkg} version 2>/dev/null`, {
+        const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
+        const npmViewCmd = npmTag === 'latest'
+          ? `npm view ${npmPkg} version 2>/dev/null`
+          : `npm view ${npmPkg} dist-tags.${npmTag} 2>/dev/null`;
+        const latestVersion = execSync(npmViewCmd, {
           encoding: 'utf8', timeout: 10000,
         }).trim();
 
@@ -1790,7 +1900,11 @@ async function cmdInstallCatalog() {
     if (!currentVersion) continue;
 
     try {
-      const latestVersion = execSync(`npm view ${catalogComp.npm} version 2>/dev/null`, {
+      const npmTag = ALPHA_FLAG ? 'alpha' : BETA_FLAG ? 'beta' : 'latest';
+      const npmViewCmd = npmTag === 'latest'
+        ? `npm view ${catalogComp.npm} version 2>/dev/null`
+        : `npm view ${catalogComp.npm} dist-tags.${npmTag} 2>/dev/null`;
+      const latestVersion = execSync(npmViewCmd, {
         encoding: 'utf8', timeout: 10000,
       }).trim();
       if (latestVersion && latestVersion !== currentVersion) {

package/docs/backup/README.md

@@ -0,0 +1,108 @@
+# Backup
+
+## One Script, One Place
+
+`~/.ldm/bin/ldm-backup.sh` runs daily at 3:00 AM via LaunchAgent `ai.openclaw.ldm-backup`. 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 |
+| Workspace directory | 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
+  <workspace>.tar
+```
+
+## iCloud Offsite
+
+After local backup, the entire dated folder is compressed and copied to iCloud. The destination path is read from `~/.ldm/config.json` at `paths.icloudBackup`.
+
+One file per backup. iCloud syncs it across devices. Rotation matches the local retention setting.
+
+## 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/
+```
+
+You can also run via the CLI:
+
+```bash
+ldm backup                                   # run backup now
+ldm backup --dry-run                         # preview with sizes
+ldm backup --pin "before upgrade"            # pin latest backup so rotation skips it
+```
+
+## 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 | 3:00 AM | LaunchAgent `ai.openclaw.ldm-backup` |
+
+One LaunchAgent. One script. No Full Disk Access currently (target: midnight via LDMDevTools.app once PID error is fixed). Verify is built into the script (exit code + log).
+
+## Config
+
+All backup settings live in `~/.ldm/config.json`:
+- `paths.workspace` ... workspace path
+- `paths.icloudBackup` ... iCloud offsite destination
+- `backup.keep` ... retention days (default: 7)
+- `backup.includeSecrets` ... whether to include `~/.ldm/secrets/`
+- `org` ... used for tar filename prefix
+
+## Logs
+
+`~/.ldm/logs/backup.log` (LaunchAgent stdout/stderr)
+
+## Technical Details
+
+See [TECHNICAL.md](./TECHNICAL.md) for config schema, LaunchAgent plist, rotation logic, and script internals.

package/docs/backup/TECHNICAL.md

@@ -0,0 +1,112 @@
+# Backup: Technical Details
+
+## Config Schema
+
+All backup settings are in `~/.ldm/config.json`. The backup script reads these at runtime.
+
+```json
+{
+  "org": "wipcomputerinc",
+  "paths": {
+    "workspace": "~/wipcomputerinc",
+    "ldm": "~/.ldm",
+    "claude": "~/.claude",
+    "openclaw": "~/.openclaw",
+    "icloudBackup": "~/Library/Mobile Documents/com~apple~CloudDocs/wipcomputerinc-icloud/backups"
+  },
+  "backup": {
+    "keep": 7,
+    "includeSecrets": false
+  }
+}
+```
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `paths.workspace` | string | required | Root workspace directory to back up |
+| `paths.icloudBackup` | string | optional | iCloud destination for offsite copies |
+| `backup.keep` | number | 7 | Days of backups to keep before rotation |
+| `backup.includeSecrets` | boolean | false | Whether to include `~/.ldm/secrets/` |
+| `org` | string | required | Used as prefix in iCloud tar filenames |
+
+## Script Location
+
+- **Source:** `scripts/ldm-backup.sh` in the wip-ldm-os-private repo
+- **Deployed to:** `~/.ldm/bin/ldm-backup.sh`
+- **Deployed by:** `deployScripts()` in `bin/ldm.js`, called during both `ldm init` and `ldm install`
+- **Restore script:** `scripts/ldm-restore.sh` deployed to `~/.ldm/bin/ldm-restore.sh`
+
+All `.sh` files in the repo's `scripts/` directory are deployed to `~/.ldm/bin/` on every `ldm install`. This means script fixes land automatically on the next update without requiring a full `ldm init`.
+
+## LaunchAgent
+
+**Label:** `ai.openclaw.ldm-backup`
+**Plist source:** `shared/launchagents/ai.openclaw.ldm-backup.plist`
+**Deployed to:** `~/Library/LaunchAgents/ai.openclaw.ldm-backup.plist`
+
+```xml
+<key>StartCalendarInterval</key>
+<dict>
+  <key>Hour</key>
+  <integer>3</integer>
+  <key>Minute</key>
+  <integer>0</integer>
+</dict>
+```
+
+The plist uses `{{HOME}}` placeholders that are replaced at deploy time by `ldm init`.
+
+**Logs:** stdout and stderr both go to `~/.ldm/logs/backup.log`.
+
+**No Full Disk Access (FDA):** The LaunchAgent runs at 3:00 AM without FDA. Some paths (like `~/Library/Messages/`) are inaccessible without FDA. The target is to move the trigger to midnight via LDMDevTools.app (which has FDA) once the PID error is resolved.
+
+### Dead Triggers (Cleaned Automatically)
+
+The `cleanDeadBackupTriggers()` function in `ldm.js` removes old competing triggers on every `ldm init`:
+- Old cron entries referencing `LDMDevTools.app`
+- `com.wipcomputer.daily-backup` LaunchAgent
+- OpenClaw `backup-verify` cron entries
+
+Only `ai.openclaw.ldm-backup` should exist.
+
+## Rotation Logic
+
+The backup script handles rotation after a successful backup:
+
+1. List all dated directories in `~/.ldm/backups/` (format: `YYYY-MM-DD--HH-MM-SS`)
+2. Sort by name (which sorts chronologically)
+3. Skip any directory containing a `.pinned` marker file
+4. Delete directories beyond the `keep` count (oldest first)
+5. Same rotation logic applies to iCloud tars at `paths.icloudBackup`
+
+**Pinning:** `ldm backup --pin "reason"` creates a `.pinned` file in the latest backup directory. Pinned backups are never rotated.
+
+## iCloud Offsite Details
+
+After the local backup completes:
+
+1. Tar + gzip the entire dated backup directory
+2. Filename format: `<org>-<machine>-<timestamp>.tar.gz`
+3. Copy to `paths.icloudBackup` (from config.json)
+4. Apply the same rotation (keep N, skip pinned)
+5. iCloud syncs the file to all devices automatically
+
+The iCloud path must exist. The script does not create it. `ldm init` does not create it either. Create it manually if it does not exist.
+
+## SQLite Safety
+
+SQLite files are backed up using `sqlite3 .backup`, not `cp`. This ensures a consistent snapshot even if the database is being written to. The script checks for the `sqlite3` binary and skips database backup with a warning if it is not found.
+
+Files backed up this way:
+- `~/.ldm/memory/crystal.db`
+- `~/.openclaw/memory/main.sqlite`
+- `~/.openclaw/memory/context-embeddings.sqlite`
+
+## Excludes
+
+The workspace tar excludes:
+- `node_modules/` ... reconstructable via npm install
+- `.git/objects/` ... reconstructable via git fetch
+- `backups/` ... avoids recursive backup
+- `_trash/` ... already deleted content
+- `*.tar.gz` ... avoids backing up old backup archives

package/package.json

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

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

@@ -2,7 +2,7 @@
 
 ## 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.
+`~/.ldm/bin/ldm-backup.sh` runs daily at 3:00 AM via LaunchAgent `ai.openclaw.ldm-backup`. It backs up everything to `~/.ldm/backups/`, then tars it to iCloud for offsite.
 
 ## What Gets Backed Up
 
@@ -48,14 +48,14 @@
 
 ## iCloud Offsite
 
-After local backup, the entire dated folder is compressed and copied to iCloud:
+After local backup, the entire dated folder is compressed and copied to iCloud. The iCloud path is read from `~/.ldm/config.json` at `paths.icloudBackup`.
 
 ```
 ~/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.
+One file per backup. iCloud syncs it across devices. Rotates to {{backup.keep}} days.
 
 ## How to Run
 
@@ -83,19 +83,22 @@ After restore: `openclaw gateway restart` then `crystal status` to verify.
 
 | What | When | How |
 |------|------|-----|
-| Backup | Midnight | cron -> LDM Dev Tools.app -> ~/.ldm/bin/ldm-backup.sh |
+| Backup | 3:00 AM | LaunchAgent `ai.openclaw.ldm-backup` runs `~/.ldm/bin/ldm-backup.sh` |
 
-One cron entry. One script. One app. Verify is built into the script (exit code + log).
+One LaunchAgent. One script. No Full Disk Access currently (target: midnight via LDMDevTools.app once PID error is fixed). 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
+All backup settings live in `~/.ldm/config.json`:
+- `paths.workspace` ... workspace path
+- `paths.icloudBackup` ... iCloud offsite destination
+- `backup.keep` ... retention days (default: 7)
+- `backup.includeSecrets` ... whether to include `~/.ldm/secrets/`
+- `org` ... used for tar filename prefix
 
 ## Logs
 
-`~/.ldm/logs/cron.log` (via LDM Dev Tools.app stdout)
+`~/.ldm/logs/backup.log` (LaunchAgent stdout/stderr)
 
 ---
 
@@ -103,6 +106,6 @@ Backup reads from two config files:
 
 **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
+**Schedule:** 3:00 AM via LaunchAgent `ai.openclaw.ldm-backup`
+**Retention:** {{backup.keep}} days local, {{backup.keep}} days iCloud
 **Script:** `~/.ldm/bin/ldm-backup.sh` (deployed by `ldm install`)