@wipcomputer/wip-ldm-os 0.4.56 → 0.4.58

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}}