Upgrade Guide

Captain Who includes a signed stable-channel update client, but the public update channel is not currently enabled and there is no automatic rollback service. Once the formal channel is enabled, the client will accept only a pointer, Release Manifest, and artifact for the current architecture that pass verification against the built-in Ed25519 trust root. It will verify the artifact's size and SHA-256 again after download. The only built-in database upgrade path currently available is from exact storage v20 to v21. It does not change the table structure or user records; it only advances the global schema version. No other cross-version compatibility can be inferred from this path. While the public channel remains disabled, replace a build manually only when a trusted distributor supplies both the new build and instructions that apply to it.

Before upgrading

1. Read the changes, compatibility information, and known issues supplied with the new build. Without this information, do not treat replacement as a risk-free upgrade.
2. Wait for running Agents, commands, MCP calls, and Automation Runs to finish or stop safely.
3. Quit Captain Who completely so that you do not copy data while the database or attachments are still being written.
4. Back up important project files. Captain Who does not back up the project directory.
5. To preserve application history, back up the complete Captain Who application data directory rather than copying only storage.sqlite. Electron determines the directory's location from the operating system and installation identity. The current interface does not provide a “one-click data export” function.

When the application recognizes an exact v20 database, it automatically creates storage-backups/pre-upgrade-v20-to-v21-*.sqlite before starting any data cleanup or Agent recovery. The system first validates the source database read-only, then constructs and verifies a v21 working copy from that backup, and finally publishes it atomically. This snapshot is a database-level recovery point. It does not include attachments, images, Skills, or system credentials from the application data directory, so it cannot replace the complete-directory backup described above.

Model Tokens, the Tavily Key, and image-generation credentials may be stored in the operating system's credential store or in a build-specific private credential directory and may not be included in a database or ordinary file-based data-directory backup. A legacy v20 database and its pre-upgrade snapshot may still contain credentials stored in plaintext before migration; protect every backup as sensitive data. After restoring configuration, re-enter any missing credentials as indicated by the interface. Do not treat opaque references as portable keys.

Install the new version

1. Obtain the new installer for the correct operating system and architecture from the same trusted source that supplied the existing installer.
2. Verify the publisher, version, signature, notarization status, or file checksum actually supplied by the distributor. Do not infer verification information that is absent from the documentation.
3. Keep the application closed and replace or overwrite the previous version using the platform's standard installation method.
4. After launch, confirm that projects, conversations, and settings load correctly.
5. Use a low-risk conversation to verify the model connection, then inspect the Skill, MCP, browser, and Scheduled pages.

Do not overwrite a formal installation with a development build, unsigned directory package, or files from another operating system.

If the upgrade fails

• Preserve the first error message. Do not repeatedly launch tasks that may have side effects.
• Do not edit the SQLite schema manually or delete the database to bypass the error.
• If the v20→v21 upgrade fails, preserve the original storage.sqlite and the generated pre-upgrade-v20-to-v21 snapshot. A failure before publication does not rewrite the source database.
• If reinstalling the previous version cannot open data written by the new version, do not force a downgrade. Cross-version database rollback is not currently guaranteed.
• Retain the complete application-data backup from before the upgrade and use Diagnostics and Logs to prepare a redacted reproduction report.

Current limitations

• There is currently no enabled public automatic-update channel or automatic rollback service. The existing client accepts only a signed pointer, Manifest, and full ZIP that pass verification against the built-in production trust root, then checks the downloaded artifact's size and SHA-256. The default trust configuration is disabled; the existence of the code does not make it publicly available.
• Current update packages are full ZIP files; differential updates are not provided.
• There is no formal data export/import or cross-version recovery wizard.
• The built-in migration accepts only a v20 database whose catalog fingerprint matches exactly. Versions v3–v19, unknown versions, schema drift, or foreign-key damage fail closed rather than being migrated speculatively.
• When the database version changes, do not assume that an older application can read newer data. Only compatibility evidence supplied for a specific version can broaden that conclusion.