From 3a4f5183000083194c2333b08151aeadeaffc14d Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Sat, 9 May 2026 14:00:28 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20add=20SELF=5FUPDATE.md=20=E2=80=94=20ag?= =?UTF-8?q?ent=20self-maintenance=20bootstrap?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Short reference covering: git repo location, Syncthing fleet sync, ignore files (.gitignore / .stignore), helper scripts (install.py, dev-restart.sh, backup.sh), standard change workflow, doc update checklist, pip dependency process, and key paths on the service host. Linked from MASTER.md document map. Co-Authored-By: Claude Sonnet 4.6 --- documentation/MASTER.md | 1 + documentation/SELF_UPDATE.md | 144 +++++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 documentation/SELF_UPDATE.md diff --git a/documentation/MASTER.md b/documentation/MASTER.md index 0281ea1..a29e038 100644 --- a/documentation/MASTER.md +++ b/documentation/MASTER.md @@ -80,6 +80,7 @@ Cortex is a self-hosted personal AI platform. It routes messages from any input | [`CLAUDE.md`](../CLAUDE.md) | Project instructions for Claude Code — directory map, run commands, design decisions | | [`README.md`](../README.md) | Project root orientation, quick-start, user management | | [`cortex/static/HELP.md`](../cortex/static/HELP.md) | In-app help (rendered in UI for all users) | +| [`SELF_UPDATE.md`](SELF_UPDATE.md) | Bootstrap for agents doing self-maintenance — git, Syncthing, scripts, doc checklist | --- diff --git a/documentation/SELF_UPDATE.md b/documentation/SELF_UPDATE.md new file mode 100644 index 0000000..c4de2fe --- /dev/null +++ b/documentation/SELF_UPDATE.md @@ -0,0 +1,144 @@ +# Cortex — Self-Update & Maintenance Bootstrap + +> A short reference for Inara (or any agent) performing maintenance, feature additions, +> or configuration changes on the Cortex codebase. +> Last updated: 2026-05-09 + +--- + +## Where the Code Lives + +**Git repository:** `~/agents_sync/projects/Cortex_and_Inara_dev/` +This is the canonical source. All Python, HTML, config templates, and documentation live here. + +**Remote:** `ssh://git@git.dgrzone.com:2222/Scott.Idem/cortex-inara.git` + +```bash +git status # see uncommitted changes +git log --oneline -8 +git push # push to Gitea after committing +``` + +--- + +## Syncthing — How Code Gets to the Fleet + +The `~/agents_sync/` directory syncs across all fleet machines in real time via Syncthing. +Code is edited on `scott_lpt` (main laptop). Changes sync automatically to `scott-lt-i7-rtx` +(the Agents Laptop, which runs the live Cortex service). + +**You do not need to manually copy files.** Edit → Syncthing syncs → restart service. + +**Sync is not instantaneous** — allow a few seconds after saving before restarting the service. + +--- + +## Ignore Files + +Two layers of ignores apply to this project: + +| File | Scope | Purpose | +|---|---|---| +| `.gitignore` | Git | Keeps secrets, runtime data, and persona data out of the repo | +| `.stignore` | Syncthing | Keeps machine-local artifacts from syncing (overlaps `.gitignore`) | +| `~/agents_sync/.stignore` | Syncthing (root) | Fleet-wide Syncthing ignores (venvs, pyc, system files) | + +**Key ignores to be aware of:** +- `home/` — all persona data (memory, tasks, sessions, credentials). **Never in git.** Backed up via restic. +- `cortex/.env` — secrets (API keys, JWT secret, VAPID keys). Never committed; `cortex/.env.default` is the template. +- `cortex/.venv/` — Python virtualenv. Machine-local; recreated by `install.py`. +- `cortex/data/` — runtime session JSON files. Machine-local. + +--- + +## Helper Scripts + +All scripts live in the project root. Run them from `scott_lpt`; they SSH to the service host as needed. + +### `install.py` — Set up or update the service +```bash +python3 install.py # install / update (idempotent — safe to re-run) +python3 install.py --check # status check only, no changes +``` +What it does: creates `.venv`, installs `requirements.txt`, writes the systemd user service, +enables linger, starts/restarts Cortex, checks LLM CLI auth, sets up the daily backup timer. + +Run after: cloning the repo on a new machine, adding a new pip dependency, or changing the systemd service definition. + +### `dev-restart.sh` — Restart the service and view logs +```bash +./dev-restart.sh # restart on scott-lt-i7-rtx, show last 30 log lines +./dev-restart.sh logs # tail live logs (Ctrl-C to stop) +./dev-restart.sh status # show service status only +``` +This SSHes to `scott-lt-i7-rtx` — it does not restart anything locally. +Run after: any Python file change. + +### `backup.sh` — Back up persona data +```bash +./backup.sh # run a restic backup of home/ immediately +``` +Normally runs automatically via systemd timer (daily 03:00). Run manually to verify backups +or before a risky change to persona files. Backup location: `~/backups/cortex-home-restic`. + +--- + +## Making a Change — Standard Workflow + +1. **Read before writing.** Check `documentation/TODO__Agents.md` for active tasks. + Check the relevant `ARCH__*.md` for the component you're changing. +2. **Edit files** on `scott_lpt`. Syncthing handles distribution. +3. **Syntax check** before restarting: + ```bash + python3 -m py_compile cortex/.py + # or for all routers/tools at once: + for f in cortex/routers/*.py cortex/tools/*.py; do python3 -m py_compile "$f" && echo "OK: $f"; done + ``` +4. **Restart:** `./dev-restart.sh` — confirm clean startup in the log output. +5. **Update docs** — see checklist below. +6. **Commit and push.** + +--- + +## Documentation Update Checklist + +Run through this after any feature or functionality change: + +| Doc | Update when | +|---|---| +| `CLAUDE.md` | New tool, channel, router, tool count, major design change | +| `cortex/static/HELP.md` | Any user-visible feature — tools, settings, UI, endpoints | +| `documentation/TODO__Agents.md` | Mark completed items; add new planned work | +| `documentation/MASTER.md` | New capability goes live; tool count changes | +| `documentation/ROADMAP.md` | Phase items completed or added | +| `documentation/ARCH__CHANNELS.md` | New channel, notification trigger, or scheduler job | +| `documentation/ARCH__SYSTEM.md` | New module, router, or tools/ file | +| `README.md` | Architecture diagram, channels table, or setup steps change | + +The principle: **stale docs are bugs.** If a feature exists that docs don't mention, or docs +describe something that doesn't exist, fix it before moving on. + +--- + +## Adding a Python Dependency + +1. Add the package to `cortex/requirements.txt` +2. Install it on the service host: + ```bash + ssh scott@scott-lt-i7-rtx "~/agents_sync/projects/Cortex_and_Inara_dev/cortex/.venv/bin/pip install " + ``` +3. Verify it works, then commit `requirements.txt` +4. On any new machine setup, `install.py` will install it automatically from `requirements.txt` + +--- + +## Key Paths on the Service Host (`scott-lt-i7-rtx`) + +| Path | What it is | +|---|---| +| `~/agents_sync/projects/Cortex_and_Inara_dev/` | Project root (synced from `scott_lpt`) | +| `~/agents_sync/projects/Cortex_and_Inara_dev/cortex/.env` | Live secrets (not in git) | +| `~/agents_sync/projects/Cortex_and_Inara_dev/home/` | All user persona data (not in git) | +| `~/.config/systemd/user/cortex.service` | systemd service file (written by `install.py`) | +| `~/backups/cortex-home-restic/` | Restic backup repository | +| `~/.config/cortex/restic-password` | Restic encryption key — back this up separately |