From 6c84d6ae722418ee384ea0091ac040791231f70c Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Wed, 8 Apr 2026 21:36:48 -0400
Subject: [PATCH] docs: update README and CLAUDE.md for install script and
 backup
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: add Setup/Install section (install.py), Development Workflow
  (dev-restart.sh), and Backup (restic/backup.sh) sections; fix
  .env.example reference → .env.default
- CLAUDE.md: replace stale Docker start command with install.py

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md |  4 ++--
 README.md | 44 +++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8b3991e..3f5191d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,8 +98,8 @@ Cortex_and_Inara_dev/
 ## Run Commands
 
 ```bash
-# Start (Docker)
-docker compose up -d
+# First-time setup or update on any machine
+python3 install.py
 
 # Restart service (after any Python change)
 systemctl --user restart cortex
diff --git a/README.md b/README.md
index 365cf7d..1749b32 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,20 @@ with a letter or underscore; max 32 characters. Example: `scott`, `holly`, `my_a
 
 ---
 
+## Setup / Install
+
+Run `install.py` on any machine to set up or update Cortex. It is idempotent — safe to re-run.
+
+```bash
+python3 install.py           # install / update everything
+python3 install.py --check   # status check only, no changes
+```
+
+What it does: creates the Python venv, installs dependencies, writes the systemd user service,
+enables linger, starts/restarts the service, checks LLM CLI auth, and sets up the daily backup timer.
+
+Config: copy `cortex/.env.default` to `cortex/.env` and fill in secrets before first run.
+
 ## Running Cortex
 
 Cortex runs as a **systemd user service** (no sudo required).
@@ -67,7 +81,35 @@ http://localhost:8000   (or cortex.dgrzone.com on WireGuard)
 The service starts automatically at boot via `loginctl enable-linger`.
 Service file: `~/.config/systemd/user/cortex.service`
 
-Config lives in `cortex/config.py` and `cortex/.env` (not tracked — see `cortex/.env.example`).
+Config lives in `cortex/config.py` and `cortex/.env` (not tracked — see `cortex/.env.default`).
+
+## Development Workflow
+
+The codebase lives in `agents_sync/` and syncs to all fleet machines via Syncthing.
+Edit code on any machine; use `dev-restart.sh` to apply changes on the host running the service.
+
+```bash
+./dev-restart.sh          # restart service, show last 30 log lines
+./dev-restart.sh logs     # tail live logs (ctrl-c to stop)
+./dev-restart.sh status   # show service status only
+```
+
+## Backup
+
+Persona data (`home/`) is excluded from git and backed up with restic.
+`install.py` sets up a systemd timer that runs `backup.sh` daily at 03:00.
+
+```bash
+./backup.sh    # run a backup manually
+
+# Inspect snapshots (set env vars or export them)
+RESTIC_REPOSITORY=~/backups/cortex-home-restic \
+RESTIC_PASSWORD_FILE=~/.config/cortex/restic-password \
+restic snapshots
+```
+
+The restic password is generated at `~/.config/cortex/restic-password` on first install.
+Back it up separately — it is required to restore from any snapshot.
 
 ---