Upgrade an existing KOS vault

Goal and prerequisites

Update a supported vault without losing existing content or installer authority. Keep a verified complete backup outside the vault and test with a separate copy. Retain the old package, new package and applicable run records.

Identify the current installation

Read the installed version/installation records and the package’s release notes. Distinguish Starter Kit version, edition version and Core contract. Do not infer the edition from a folder name.

Community via Starter Kit 1.2.0

From the extracted package, run the planner against a test copy first:

./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation upgrade -DryRun
./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation upgrade -Approve
./install.ps1 -Target 'PATH-TO-TEST-COPY' -Operation validate

Review preserved files, proposals and link checks. The Community installer refuses Pro vaults. For a conflict, use the decisions-file procedure with -Operation upgrade; include the same -Decisions file in both the preview and approved invocation.

Pro 1.0.0 to Pro 1.1.0

Use the guided Pro installer from the exact 1.1.0 package. It supports qualifying Pro 1.0.0 sources and same-version verify/repair. Its inspection determines whether the vault is supported; the package version alone does not prove compatibility.

Pro 1.0.0 users on macOS or Linux should retain their current installation and matching maintenance package. These docs provide no qualified in-place 1.1.0 upgrade path on those systems; do not infer support from PowerShell availability. Any Windows transition still requires inspection of a separate copy.

Starter 1.1.0 → 1.2.0 → Pro 1.1.0

For a completed historical Starter 1.1.0 vault, first use the released Starter Kit 1.2.0 upgrade and validate it on a separate copy. Then run the approved October 19 Pro package through its guided flow. Review the distinct adoption and edition-transition decisions. The installer must recognize both the current Community identity and completed historical record.

Pro preserves the legacy record in its receipt history and retires the Starter writer. Use Pro verification, repair and transactional recovery after transition. Retain the original Starter packages and full backup for recovery; never resume the retired legacy installer. Incomplete history and direct older Starter sources remain blocked. The full starting-point matrix applies.

Older or customized vaults

An unsupported private or legacy vault needs a deliberate manual review. This is a conservative maintainer process, not a universal automated migration contract:

1. Identify the source edition/version and record existing role folders, adapters and installer authority.
2. Back up the complete vault and prove the backup is readable.
3. Create a separate test copy and inspect the new package’s changes.
4. Review differences file by file. Preserve notes, custom instructions, decisions and existing state.
5. Resolve conflicts explicitly, using the supplied compatibility and recovery documentation. Do not copy the payload wholesale or remove receipts to make a blocker disappear.
6. Validate the copied vault, open representative content, and test a fresh AI session.
7. Plan the original-vault update only after those results and the exact remaining risks are understood.

The precise merge instructions depend on the old vault’s version and customizations. There is no safe generic list of files to overwrite.

Verify and recover

Check edition/version identity, validator output, note links, role paths and context loading. Keep the original unchanged until the copy passes. If apply is interrupted, use the exact package and run/transaction ID; follow recovery guidance.