# 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 |