LifeOS Upgrade Process: How to Update and Maintain Configuration Across Versions

Run the bun Tools/Update.ts --apply command to perform an idempotent, non-destructive upgrade that preserves all user-created files.

LifeOS upgrades are designed to be additive and non-destructive, ensuring your personal configuration remains intact while system files are updated. This guide covers the complete upgrade workflow based on the [LifeOS/Workflows/Update.md](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md) specification and the TypeScript toolchain in LifeOS/Tools/.

Understanding the Core Upgrade Philosophy

The LifeOS upgrade process follows one immutable rule: "Update is additive and non-destructive" [1]. This means:

• No user-created files are removed
• No custom settings are overwritten
• Only system-owned components are updated or added

The 7-Step Update Workflow

Each upgrade executes the following sequence, enforced by [LifeOS/Tools/Update.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/Update.ts):

1. Environment Detection

bun Tools/DetectEnv.ts

[DetectEnv.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DetectEnv.ts) identifies your OS, shell harness, and <configRoot> path. All subsequent operations use these detected paths—nothing is hard-coded.

2. Version Comparison

The system reads <configRoot>/LIFEOS/VERSION and queries https://api.github.com/repos/<LIFEOS_REPO>/releases/latest. If behind, it re-runs install.sh. The VERSION file serves as the install marker, preventing false "already current" states.

3. System Overlay (Copy-Missing)

bun Tools/DeployCore.ts --apply

[DeployCore.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployCore.ts) copies new system templates (e.g., CLAUDE/, settings.system.json) using copy-missing semantics: only files that don't exist are added.

4. Hook Re-Merge

bun Tools/InstallHooks.ts --apply

[InstallHooks.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/InstallHooks.ts) merges new hook entries into settings.json, with automatic backup. Hook merging is deduplicated—your custom hooks survive intact.

5. User Template Scaffolding

bun Tools/ScaffoldUser.ts --apply

[ScaffoldUser.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ScaffoldUser.ts) adds new USER template files (e.g., Goals.md, Identity.md) without touching your existing personal templates.

6. Import Activation

bun Tools/ActivateImports.ts --apply

[ActivateImports.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ActivateImports.ts) inserts new import lines into the system prompt, preserving existing ones.

7. Verification

Evidence classes confirm hooks fire and imports resolve before the upgrade completes.

How Configuration Persistence Works

Three mechanisms protect your setup:

Mechanism	Location	Protection Method
User-owned tree	<configRoot>/LIFEOS/USER_TEMPLATES/	Copy-missing strategy in ScaffoldUser.ts
Version marker	<configRoot>/LIFEOS/VERSION	Overwritten only by new payload, never stale copies
Settings merge	settings.json	Deduplicated hook merging with backup

Running the Complete Upgrade

Quick Method (Recommended)

# Dry-run first to preview changes

bun Tools/Update.ts

# Apply the upgrade

bun Tools/Update.ts --apply

Manual Step-by-Step

# 1. Detect environment

bun Tools/DetectEnv.ts

# 2. Overlay system files

bun Tools/DeployCore.ts --apply

# 3. Merge new hooks

bun Tools/InstallHooks.ts --apply

# 4. Scaffold new user templates

bun Tools/ScaffoldUser.ts --apply

# 5. Activate new imports

bun Tools/ActivateImports.ts --apply

All tools default to dry-run mode. The --apply flag is required for actual changes.

Handling Legacy Migrations

Pre-7.x aliases (like the old pai command) are automatically redirected. The Update workflow adjusts your shell rc file to point legacy aliases to the new launcher, preserving muscle memory [2].

Key Upgrade Files Reference

File	Purpose
[LifeOS/Workflows/Update.md](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Workflows/Update.md)	Canonical upgrade documentation
[LifeOS/Tools/Update.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/Update.ts)	Main orchestration script
[LifeOS/Tools/DetectEnv.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DetectEnv.ts)	Environment detection
[LifeOS/Tools/DeployCore.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/DeployCore.ts)	System file deployment
[LifeOS/Tools/InstallHooks.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/InstallHooks.ts)	Hook merging
[LifeOS/Tools/ScaffoldUser.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ScaffoldUser.ts)	User template scaffolding
[LifeOS/Tools/ActivateImports.ts](https://github.com/danielmiessler/LifeOS/blob/main/LifeOS/Tools/ActivateImports.ts)	Import activation

Summary

• LifeOS upgrades are idempotent—run bun Tools/Update.ts --apply safely again and again.
• Your configuration is never overwritten—copy-missing semantics protect all user files in USER_TEMPLATES/.
• Always dry-run first—preview changes with commands before using --apply.
• Hooks and imports merge intelligently—deduplication prevents duplicates while preserving custom entries.
• Legacy aliases migrate automatically—no manual intervention needed for pre-7.x setups.

Frequently Asked Questions

Will upgrading LifeOS delete my custom templates?

No. The upgrade process uses copy-missing logic in ScaffoldUser.ts, which only adds files that don't exist. Your existing templates in <configRoot>/LIFEOS/USER_TEMPLATES/ remain untouched.

How do I know if an upgrade is available?

The Update.ts tool automatically compares your <configRoot>/LIFEOS/VERSION file against the latest GitHub release. Run bun Tools/Update.ts (without --apply) to check status without making changes.

Can I preview what an upgrade will change before applying it?

Yes. All LifeOS tools default to dry-run mode. Simply omit the --apply flag to see a JSON plan of proposed changes. This applies to Update.ts, DeployCore.ts, InstallHooks.ts, and all other upgrade tools.

What happens to my custom hooks in settings.json during an upgrade?

They are preserved. InstallHooks.ts performs deduplicated merging—new hooks from the release are added, existing hooks (including your custom ones) remain unchanged, and a backup of settings.json is created before any modification.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}