docs: add SELF_UPDATE.md — agent self-maintenance bootstrap
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 <noreply@anthropic.com>
This commit is contained in:
Scott Idem
@@ -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 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
144
documentation/SELF_UPDATE.md
Normal file
144
documentation/SELF_UPDATE.md
Normal file
@@ -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/<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:
|
||||
```bash
|
||||
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 |
|
||||
Reference in New Issue
Block a user