Update TRACE-OS

An update takes a new release into a project and keeps your own instructions, records and research files. The latest completed update can be rolled back.

Steps

1. Download the release archive and its .sha256 digest file, then ask for a plan.

   Say to your agent

   Plan the update of this project to the release in my Downloads folder, and show me any conflicts.

   The plan changes nothing; an unsupported pair of releases stops here.

2. Apply it.

   Say to your agent

   Apply the update.

   Your agent verifies the digest, runs the release’s tests, and runs the project’s checks; a failing check restores the previous files.

3. Or update every project on this machine at once.

   Say to your agent

   Find every TRACE-OS project under my Developer folder, show me the plan, and update them all.

   Projects with uncommitted changes are skipped, and nothing is committed or pushed for you.

Things to know

• More than one release behind? The update walks each release in turn, from a folder holding the earlier archives. The releases page carries 0.1.0-rc24 and later only, so the earlier archives come from your own folder.
• An edited instruction section waits for you. It needs a compatibility declaration in ai/project.json, or the whole update stays pending.
• You can roll back the latest completed update, unless a file it wrote has changed since, for example by a skills operation.

What the agent runs

python scripts/bootstrap.py --target /path/to/project --profile academic --agent claude --plan
python scripts/bootstrap.py --target /path/to/project --profile academic --agent claude \
  --release-archive /path/to/trace-os-0.1.0-rcN.zip \
  --expected-sha256 <digest-from-the-release-sidecar> --update
python scripts/bootstrap.py --target /path/to/project --profile academic --agent claude \
  --release-archive /path/to/trace-os-0.1.0-rcN.zip \
  --expected-sha256 <digest-from-the-release-sidecar> \
  --release-store /path/to/earlier-release-archives --update-chain    # more than one release behind
python scripts/kit_projects.py list --root ~/Developer
python scripts/kit_projects.py plan --root ~/Developer \
  --release-archive /path/to/trace-os-0.1.0-rcN.zip --sha256-file /path/to/trace-os-0.1.0-rcN.zip.sha256
python scripts/kit_projects.py update --root ~/Developer --all \
  --release-archive /path/to/trace-os-0.1.0-rcN.zip --sha256-file /path/to/trace-os-0.1.0-rcN.zip.sha256
python scripts/bootstrap.py --target . --rollback                     # undo the latest completed update
python scripts/bootstrap.py --recover                                  # finish or undo an interrupted operation

Each command runs from the unpacked new release, except rollback and recover, which run from the project.