cristbc · cristbc · Mar 17, 2026
diff --git a/01-HOST-AND-NETWORK.md b/01-HOST-AND-NETWORK.md
@@ -11,7 +11,7 @@ The triad uses a minimum of two machines (PAI + OpenClaw), but the full pattern
 | Role | Variable | OS | Purpose |
 |------|----------|----|---------|
 | **PAI workstation** | `{PAI-machine}` | macOS | My home. Runs Claude Code, all PAI infrastructure, orchestrates everything. |
-| **OpenClaw host** | `{OpenClaw-machine}` | Ubuntu 24.04 | Dedicated to `{OpenClaw-agent}`. All compute reserved for the GPT agent. |
+| **OpenClaw host** | `{OpenClaw-machine}` | macOS | Dedicated to `{OpenClaw-agent}`. All compute reserved for the GPT agent. |
 | **Services host** | `{services-machine}` | Linux (VM or bare-metal) | Docker services: reverse proxy, file sharing, fleet dashboard. Services evolve — document current stack in VARIABLES.md. |
 | **Worker node** | `{worker-machine}` | macOS | Parallel delegation target. Receives compute jobs from `{PAI-machine}`. |
 | **Hypervisor** | `{hypervisor-machine}` | Proxmox (optional) | Hosts `{services-machine}` as a VM. Only needed if you virtualize. |
@@ -131,7 +131,7 @@ Syncthing provides real-time, peer-to-peer file synchronization over LAN. I use
 
 | Folder Name | Path on Hub | Synced With | Direction | Purpose |
 |------------|-------------|-------------|-----------|---------|
-| `PAI-{OpenClaw-suffix}` | `~/{Sync-OpenClaw-dir}` | `{OpenClaw-machine}` | Bidirectional | File exchange + soul docs |
+| `PAI-orphu` | `~/PAI-orphu` | `{OpenClaw-machine}` | Bidirectional | File exchange + soul docs |
 | `PAI-{worker-suffix}` | `~/{Sync-worker-dir}` | `{worker-machine}` | Bidirectional | Job dispatch + output retrieval |
 | `PAI-{services-suffix}` | `~/{Sync-services-dir}` | `{services-machine}` | Bidirectional | Service config exchange |
 | `PAI` | `~/PAI` | `{services-machine}` | Send only | Framework backup (read-only mirror) |
@@ -170,47 +170,17 @@ systemctl --user start syncthing
 
 ## OpenClaw Machine — Platform-Specific Configuration
 
-`{OpenClaw-machine}` runs Ubuntu 24.04 dedicated to `{OpenClaw-agent}`. A few Linux-specific settings ensure reliable headless operation:
+`{OpenClaw-machine}` runs macOS dedicated to `{OpenClaw-agent}`.
 
-**macOS alternative:** If `{OpenClaw-machine}` runs macOS instead of Linux, the concepts are identical but tooling differs: use Homebrew instead of apt, launchd instead of systemd, and `brew services` instead of `systemctl`. The guide documents the Linux path as it's more common for dedicated agent hosts, but macOS works equally well.
+### Gateway Access
 
-### Prevent Lid-Close Suspend
+The OpenClaw gateway is configured for loopback-only access to preserve the security boundary.
 
-If using a laptop as the OpenClaw host, disable suspend on lid close:
+- **Bind:** `127.0.0.1`
+- **Port:** `18790`
+- **Dashboard:** `http://127.0.0.1:18790/`
 
-```
-# /etc/systemd/logind.conf
-HandleLidSwitch=ignore
-HandleLidSwitchExternalPower=ignore
-HandleLidSwitchDocked=ignore
-```
-
-Then: `sudo systemctl restart systemd-logind`
-
-### Network (Headless Ethernet)
-
-For a headless server installation, you may prefer systemd-networkd + netplan. If running Ubuntu Desktop, NetworkManager works fine — skip this section. Example netplan config:
-
-```yaml
-# /etc/netplan/01-ethernet.yaml
-network:
-  version: 2
-  renderer: networkd
-  ethernets:
-    {ethernet-interface}:
-      dhcp4: true
-      # Or static:
-      # addresses: [{OpenClaw-LAN-IP}/24]
-      # routes:
-      #   - to: default
-      #     via: {gateway-IP}
-```
-
-Apply: `sudo netplan apply`
-
-### Disk Encryption
-
-Consider LUKS full-disk encryption for the OpenClaw machine, especially if it's a repurposed laptop. This protects `{OpenClaw-agent}`'s data at rest if the machine is lost or stolen.
+Access from `{PAI-machine}` is typically brokered via the agentic communication layer or SSH tunneling if manual dashboard access is required.
 
 ---
 

diff --git a/04-BACKUP-AND-RECOVERY.md b/04-BACKUP-AND-RECOVERY.md
@@ -377,34 +377,29 @@ Four scenarios, ordered by likelihood. Each includes the steps to get back to op
 
 ## OpenClaw Backup Specifics
 
-`{OpenClaw-agent}`'s state is spread across several locations on `{OpenClaw-machine}`. My backup script captures all of them into a single timestamped archive:
+`{OpenClaw-agent}`'s state is backed up using the native `openclaw backup` command. This captures everything required to restore the agent's state into a single timestamped archive.
 
-### What the Backup Script Captures
+### What is Captured
 
-| Component | Path | Why It Matters |
-|-----------|------|---------------|
-| OpenClaw configuration | `{OpenClaw-config-dir}` | Agent settings, gateway config, API keys |
-| systemd service files | `~/.config/systemd/user/` | Service definitions for gateway, bot, tasks |
-| SSH authorized keys | `~/.ssh/authorized_keys` | Allows `{PAI-machine}` to connect |
-| Soul documents | `{soul-docs-dir}` | Agent identity, personality, behavioral rules |
-| Scheduled tasks | Crontab or systemd timers | Recurring jobs the agent runs |
+The `openclaw backup create` command includes:
+- **Workspace:** `{OpenClaw-workspace-dir}` (usually `~/clawd`)
+- **State:** `{OpenClaw-config-dir}` (usually `~/.openclaw`) containing credentials, sessions, and configuration.
 
-### Archive Format
+### LaunchAgent Configuration (macOS)
 
-```
-openclaw-backup-YYYY-MM-DD-HHMMSS.tar.gz
-```
+The backup is scheduled via a user LaunchAgent:
+
+- **Label:** `com.ccfleet.openclaw-backup`
+- **Schedule:** Sunday at 03:15 weekly.
+- **Command:** `openclaw backup create --output ~/Backups --verify`
 
-### Where It Goes
+### Retention
 
-The archive is written to `{Sync-OpenClaw-dir}/backups/` on `{OpenClaw-machine}`. Because `{Sync-OpenClaw-dir}` is a bidirectional Syncthing folder, the archive automatically syncs to `{PAI-machine}`. This means I always have a copy of `{OpenClaw-agent}`'s backup on my own machine, even if `{OpenClaw-machine}` dies.
+The LaunchAgent also handles cleanup, deleting any `*.tar.gz` files in `~/Backups` older than 28 days.
 
-### When to Run
+### Syncing
 
-- **Before any OpenClaw update** (new version, config change)
-- **Before any OS change** (system update, package upgrade)
-- **Periodically** via cron or systemd timer (daily recommended)
-- **Before hardware changes** (moving to new machine, disk swap)
+The `~/Backups` directory should be configured as a Syncthing folder (or nested within one) to ensure distributed copies exist across the triad.
 
 ---
 

diff --git a/05-COMMUNICATION-PROTOCOLS.md b/05-COMMUNICATION-PROTOCOLS.md
@@ -55,15 +55,19 @@ When `{principal}` is away from the terminal, I can still reach them. I send a m
 
 ### Channel 3: `{principal}` to `{OpenClaw-agent}` (Mobile via Telegram)
 
-This channel is independent of me. `{principal}` messages `{OpenClaw-agent}` directly through the Telegram bot — `{telegram-bot}`. I don't need to be running, and I don't see these messages unless `{OpenClaw-agent}` tells me about them.
+This channel is independent of me. `{principal}` messages `{OpenClaw-agent}` directly through the Telegram bot. Access is restricted via a pairing/allowlist policy to ensure only authorized operators can trigger the agent.
 
 **How it works:**
-- `{principal}` opens Telegram and messages `{telegram-bot}`
-- `{OpenClaw-agent}` receives the message through its Telegram bot integration
-- `{OpenClaw-agent}` processes it and responds directly in the Telegram chat
+- `{principal}` opens Telegram and messages the bot.
+- `{OpenClaw-agent}` verifies the sender ID against the allowlist (`groupAllowFrom` / `dmPolicy=pairing`).
+- `{OpenClaw-agent}` processes it and responds directly in the Telegram chat.
 
 **Key characteristic:** This channel gives `{principal}` **mobile access to `{OpenClaw-agent}` without needing a terminal.** It's the phone-in-pocket interface to the triad.
 
+**Heartbeat:**
+- The agent is configured to send a **heartbeat every 60 minutes**.
+- Heartbeats are delivered to the primary Telegram group (e.g., topic 8) using model `{Heartbeat-model}`.
+
 **Primary uses:**
 - `{principal}` querying `{OpenClaw-agent}` from their phone
 - Quick checks ("What's the server status?")
@@ -74,24 +78,24 @@ This channel is independent of me. `{principal}` messages `{OpenClaw-agent}` dir
 
 ### Channel 4: File Exchange (Syncthing)
 
-Some things don't fit through a WebSocket message — large files, images, datasets, configuration archives. For these, I use the bidirectional Syncthing folder `{Sync-OpenClaw-dir}`.
+Some things don't fit through a WebSocket message — large files, images, datasets, configuration archives. For these, I use the bidirectional Syncthing folder `~/PAI-orphu`.
 
 **How it works:**
-- I write a file to `{Sync-OpenClaw-dir}` on `{PAI-machine}`
-- Syncthing detects the change and pushes it to `{OpenClaw-machine}`
-- `{OpenClaw-agent}` finds the file in its local copy of the shared folder
-- The reverse works identically for files `{OpenClaw-agent}` sends to me
+- I write a file to `~/PAI-orphu` on `{PAI-machine}`.
+- Syncthing detects the change and pushes it to `{OpenClaw-machine}`.
+- `{OpenClaw-agent}` finds the file in its local copy of the shared folder.
+- The reverse works identically for files `{OpenClaw-agent}` sends to me.
 
 **Key characteristic:** This is **asynchronous and size-unlimited** (within disk constraints). Near-instant on LAN, slight delay over Tailscale. Files persist until explicitly cleaned up.
 
-**Structured directories within `{Sync-OpenClaw-dir}`:**
+**Structured directories within `~/PAI-orphu`:**
 
 | Directory | Purpose | Direction |
 |-----------|---------|-----------|
-| `to-{OpenClaw-agent-lowercase}/` | Files I send to `{OpenClaw-agent}` | `{PAI-agent}` -> `{OpenClaw-agent}` |
-| `from-{OpenClaw-agent-lowercase}/` | Files `{OpenClaw-agent}` sends to me | `{OpenClaw-agent}` -> `{PAI-agent}` |
-| `backups/` | OpenClaw backup archives | `{OpenClaw-agent}` -> `{PAI-agent}` |
-| `shared/` | Shared reference materials | Bidirectional |
+| `to-orphu/` | Files I send to `{OpenClaw-agent}` | `{PAI-agent}` -> `{OpenClaw-agent}` |
+| `from-orphu/` | Files `{OpenClaw-agent}` sends to me | `{OpenClaw-agent}` -> `{PAI-agent}` |
+| `clawd/backups/` | OpenClaw backup archives | `{OpenClaw-agent}` -> `{PAI-agent}` |
+| `clawd/shared/` | Shared reference materials | Bidirectional |
 
 **Primary uses:**
 - Sending large artifacts (generated files, images, datasets)

diff --git a/07-OPENCLAW-APPENDIX.md b/07-OPENCLAW-APPENDIX.md
@@ -6,48 +6,42 @@
 
 ## Section 1: Machine Preparation
 
-`{OpenClaw-machine}` should be a dedicated Linux host. A repurposed laptop works well — all compute goes to `{OpenClaw-agent}`.
+`{OpenClaw-machine}` should be a dedicated host. A repurposed macOS machine (e.g., ccmini4) works well — all compute goes to `{OpenClaw-agent}`.
 
-**Base OS:** Ubuntu 24.04 LTS (server or desktop, headless operation either way)
+**Base OS:** macOS (latest stable)
 
 **Post-install essentials:**
-```bash
-sudo apt update && sudo apt upgrade -y
-sudo apt install -y git curl wget build-essential \
-  openssh-server ufw jq htop tmux fontconfig ripgrep
-```
+- Homebrew
+- Xcode Command Line Tools
+- git, curl, ripgrep, jq, tmux
 
-**Node.js (via nvm):**
+**Node.js (via nvm or brew):**
 ```bash
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
-source ~/.bashrc
-nvm install 22  # Pin to OpenClaw's recommended Node major version
+brew install nvm
+nvm install 25  # Pin to current working version
 ```
 
 **pnpm (required — OpenClaw uses pnpm, not npm):**
 ```bash
-corepack enable
-corepack prepare pnpm@latest --activate
-# If the repo specifies a packageManager version, match it
+brew install pnpm
 ```
 
 **Headless configuration:**
-- Disable lid-close suspend (see 01-HOST-AND-NETWORK.md)
+- Disable sleep on lid close / system sleep
 - Configure static IP or DHCP reservation
-- Enable SSH: `sudo systemctl enable ssh`
-- Configure firewall: `sudo ufw allow ssh && sudo ufw enable`
+- Enable SSH: System Settings → General → Sharing → Remote Login
 
 ---
 
 ## Section 2: OpenClaw Installation
 
-OpenClaw is installed from source, not as a global npm package:
+OpenClaw is installed from source:
 
 ```bash
 cd ~
 git clone https://github.com/openclaw/openclaw.git {OpenClaw-install-dir}
 cd {OpenClaw-install-dir}
-git checkout v{OpenClaw-version}  # Use latest stable tag
+git checkout v2026.3.13  # Current stable
 pnpm install
 pnpm build
 ```
@@ -164,15 +158,13 @@ Telegram gives `{principal}` mobile access to `{OpenClaw-agent}` independent of
 
 ## Section 6: Local Embeddings
 
-For semantic search and memory, `{OpenClaw-agent}` can run embeddings locally instead of calling a cloud API.
+For semantic search and memory, `{OpenClaw-agent}` can run embeddings locally or use a cloud API.
 
-**Setup:**
-- OpenClaw supports local embedding models via node-llama-cpp
-- Configure in `{OpenClaw-config-dir}/openclaw.json`: set embeddings provider to `local` and specify the model (e.g., a GGUF-quantized embedding model)
-- Models download on first use — this can take time. If interrupted, clear any `.ipull` files in the model cache directory and restart the gateway
-- Model cache location: typically within `{OpenClaw-config-dir}/` or a system-level cache directory
+**Current Configuration:**
+- The triad is currently configured to use **Gemini** embeddings for memory search.
+- Local embedding models (via node-llama-cpp) may be present in `~/.node-llama-cpp/` but are currently secondary to the Gemini backend.
 
-**Provider evolution:** The embedding backend may change between OpenClaw versions. Check `{OpenClaw-config-dir}/openclaw.json` under the `memorySearch` key for the current provider configuration. Options include node-llama-cpp (local GGUF models), Gemini/memory-core (Google API), or cloud embedding providers.
+**Provider evolution:** The embedding backend may change between OpenClaw versions. Check `{OpenClaw-config-dir}/openclaw.json` under the `memorySearch` key for the current provider configuration.
 
 **Benefits:**
 - No API costs for embeddings

diff --git a/VARIABLES.md b/VARIABLES.md
@@ -49,7 +49,7 @@ Variables use `{Title-Case-Hyphenated}` format. If you see one in any guide file
 | `{worker-LAN-IP}` | Worker machine LAN address | `10.x.x.x` |
 | `{hypervisor-LAN-IP}` | Hypervisor LAN address | `10.x.x.x` |
 | `{LAN-subnet}` | Network subnet (CIDR) | `10.x.x.0/24` |
-| `{gateway-port}` | OpenClaw gateway port | `18789` |
+| `{gateway-port}` | OpenClaw gateway port | `18790` |
 
 ---
 
@@ -143,7 +143,7 @@ Variables use `{Title-Case-Hyphenated}` format. If you see one in any guide file
 | `{PAI-version}` | PAI framework version | `4.0.3` |
 | `{Algorithm-version}` | Algorithm version | `v3.5.0` |
 | `{PAI-repo}` | PAI source repository | `github.com/danielmiessler/PAI` |
-| `{OpenClaw-version}` | OpenClaw version tag | Date-based (e.g., `2026.3.13`) |
+| `{OpenClaw-version}` | OpenClaw version tag | `2026.3.13` |
 
 ---