---
name: cortex-update
description: Update this cortex-ops workspace to the latest published release in place, preserving the user's real agents, .env and MCP auth. Use when the user wants to update/upgrade cortex-ops, when a "newer version available" notice appears, or to check whether a newer release exists.
---

# cortex-update — pull the latest release, in place, without losing local state

Updates the local cortex-ops workspace (skills, knowledge, templates, docs, the operating manual,
and the reference agents) to the latest published release. It is **overlay-only**: it never touches
your real client agents under `agents/<name>/`, your `.env`, your `.mcp-auth/` (so you stay logged
in), or `.claude/settings.local.json`.

Only useful in **Claude Code** (terminal or web/cloud), which can run the update script. App /
custom-connector users update by re-downloading the project zip and re-attaching it — see the
"Connecting" wiki.

## How it works

The release pipeline publishes a versioned `cortex-ops.zip` plus `releases/latest.json`
(`{version, zip, published}`). Each download carries a `VERSION` file. This skill compares the local
`VERSION` to the published one and, if newer, fetches and overlays the managed files.

## Run it

1. Run the overlay script from the project root:

   ```bash
   bash .claude/skills/cortex-update/apply-update.sh
   ```

   - If the local version is current it prints "nothing to do" and exits.
   - If the published version is newer it downloads the zip and overlays the managed paths only.
   - If the local version is *ahead* (dev build) it refuses to downgrade.
   - For a custom domain or local testing, set `CORTEX_OPS_SITE` (e.g.
     `CORTEX_OPS_SITE=https://<your-site> bash .claude/skills/cortex-update/apply-update.sh`).

2. Relay the script's output to the user verbatim (the from→to versions and what was preserved).

3. Tell the user to **restart Claude Code** (or re-run `/mcp`) so the refreshed skills and hooks
   load. New MCP *tools* from the gateway also refresh on a new session — that is independent of this
   skill, which only updates the local playbook files.

## Guardrails

- **Never** hand-edit files to "update" instead of running the script — the script is the
  correct-by-construction overlay (it preserves local state by construction).
- If the script reports an error (unreachable site, bad manifest), report the exact error and the
  site URL it tried; do not partially copy files yourself.
- The reserved `agents/sample-*` names are refreshed by the update; do not name a real client agent
  `sample-*`.
