Update tooling without losing local state

Repository changes and runtime deployment are separate. Keep this checkout at ~/code/dev-environment on Shipyard; active hooks continue using ~/dev-environment. Never initialize Git over the live installation or copy its private state into a checkout.

Review and update the checkout

Use git status before pulling and preserve local edits. Fetch/review changes and use git pull --ff-only only on a clean branch with the intended upstream. Run the repository checks on the pinned documentation runtime where available. Reading the Markdown and running Python diagnostics does not require Node.

Plan an explicit runtime update

On Shipyard, from this repository:

python3 scripts/runtime.py check
python3 scripts/runtime.py plan

Only deployed files in profiles/shipyard/runtime-manifest.json are eligible. Reference helpers, application code, credentials, state, logs and Orca settings are not installed. The first baseline check compares the captured installation hashes. After deployment a private receipt records the installed hashes.

If the working installation has drifted, stop and reconcile it; do not overwrite changes merely because Git has a different version. Review executable changes and their operational effects, coordinate with active users, then:

python3 scripts/runtime.py apply

The installer refuses an unexpected hostname, missing baseline files, symlinked destinations, changed files not matching the last known installed version, and unsafe manifest paths. It creates private backups and replaces only explicit allowlisted files. It does not restart processes, modify hooks, install packages or grant permissions. Multi-file application is not a transaction across a power failure; if interrupted, inspect the receipt/backup and reconcile before rerunning.

Verify and roll back

Run drift checks, syntax checks and checks for the affected workflow. Browser/sandbox upgrades need a coordinated restart and the sudo AppArmor step; changing files alone does not update a running process. API/app changes can require task-specific restart, not a global stop.

For rollback, use the installer’s printed backup directory to compare and restore only the affected files after coordinating active work. Keep the prior source revision and backup until verification passes. Do not reset private state or credentials. Baseline capture is not proof that a changed script is safe.

Record the installed state

After an installation attempt, add a sanitized record in evidence/ with the machine, date, source revision, installed scope, verification results and remaining limits. Keep private receipts and logs on the machine. If installation or verification is incomplete, say so; do not describe the whole setup as updated.

Update affected current pages and known limitations from that result, and link the evidence in the PR or a follow-up PR if the change already merged. Preserve prior observations as dated history. Documentation-only changes need no runtime installation; record “not needed” in the PR.

New machines and legacy setup

tooling/shipyard/scripts/system.sh installs Ubuntu packages and changes Docker group membership; user-tools.sh installs toolchains and changes shell/Git defaults. They are preserved for review, not run by documentation setup or the runtime installer. They do not constitute a tested full rebuild. Additional browser packages, browser/MCP install, sign-ins, app configuration, seed data and Orca settings still require the documented steps and a future rehearsal.