Cortex-Inara/documentation/SELF_UPDATE.md

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

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

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

./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

./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:

   python3 -m py_compile cortex/<file>.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:

   ssh scott@scott-lt-i7-rtx "~/agents_sync/projects/Cortex_and_Inara_dev/cortex/.venv/bin/pip install <package>"
   

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