Upgrade Philosophy

How kit updates work and why your data is always safe.

The Promise

When you upgrade a kit:

• Your data is preserved — Config, content, environment variables
• You get new features — Commands, knowledge, improvements
• Your customizations are respected — We don't overwrite your work

---

File Categories

Every file in a kit belongs to a category that determines upgrade behavior:

Always Replace

What: Kit code that we control

Examples:

• .claude/commands/* — Command procedures
• .claude/knowledge/* — Domain knowledge
• CLAUDE.md — Project context
• recipes/* — Implementation guides

Why: These files contain our latest improvements. You get new features, bug fixes, and better prompts.

Never Touch

What: Your data and configuration

Examples:

• .env* — Environment variables
• config/* — Your settings
• content/* — Content you created
• Kit data folders (.marketing-os/, .pmf-os/, etc.)

Why: This is YOUR data. We never modify it, ever.

Merge

What: Files that contain both kit defaults and your customizations

Examples:

• package.json — Dependencies (we add ours, keep yours)
• .claude/settings.json — Settings (deep merge, your values win)

Why: Both parties have legitimate changes. Merge preserves both.

Add Only

What: Files that should only be added, never updated

Examples:

• supabase/migrations/* — Database migrations

Why: Migrations are immutable. We add new ones, never modify existing.

---

Visual Example

Before upgrade (v1.0.0):
├── .claude/
│   ├── commands/
│   │   └── setup.md           # v1.0.0
│   └── settings.json          # Your custom settings
├── config/
│   └── my-config.json         # Your data
├── content/
│   └── my-content.md          # Your content
├── .env.local                  # Your secrets
└── CLAUDE.md                   # v1.0.0

After upgrade (v1.1.0):
├── .claude/
│   ├── commands/
│   │   └── setup.md           # v1.1.0 ← REPLACED
│   └── settings.json          # MERGED (yours preserved)
├── config/
│   └── my-config.json         # UNCHANGED
├── content/
│   └── my-content.md          # UNCHANGED
├── .env.local                  # UNCHANGED
└── CLAUDE.md                   # v1.1.0 ← REPLACED

---

Why This Approach

We Control What We Know

Files in "Always Replace" are things we maintain:

• We fix bugs
• We add features
• We improve prompts
• You benefit automatically

You Control What You Know

Files in "Never Touch" are things you own:

• Your API keys
• Your business data
• Your content
• Your customizations

The Merge Zone

Some files need both:

• package.json — Your dependencies + ours
• Settings — Your preferences + our defaults

We merge intelligently: your values always win conflicts.

---

Template vs Companion

Template Upgrades

For templates (SaaS Dev Team, Landing Page), we're more conservative:

Why? You've likely customized the code. We won't break it.

New features? We give you the recipe, not the code:

SaaS Dev Team v2.0.0 includes multi-tenant support.

This isn't automatically added to your project.
To add it, run: /recipes → "Add Multi-Tenancy"

Companion Upgrades

For companion tools (Marketing OS, PMF OS), upgrades are simpler:

Companion tools don't change your code — only their own files.

---

New Requirements

Sometimes upgrades add new requirements:

New Environment Variables

Upgrade complete!

⚠️  New environment variables required:
   TWITTER_API_KEY - For /viral command

Add to your .env file and restart.

We tell you what's needed. Your .env isn't modified.

New Dependencies

For templates with package.json:

New dependencies added:
+ @sentry/nextjs ^8.0.0

Run: pnpm install

Dependencies are merged, you run the install.

---

Rollback

If something goes wrong:

Automatic Backup

Before upgrading, we backup files that will change:

.claude/
├── commands/
│   └── setup.md.bak          # Previous version
└── settings.json.bak         # Previous settings

Manual Rollback

# Revert to previous version
npx @aiorg/cli rollback marketing-os

# Or install specific version
npx @aiorg/cli install marketing-os@1.4.0

Git Rollback

If your project is in git:

git checkout -- .claude/
git checkout -- CLAUDE.md

---

Version Pinning

Don't want automatic updates? Pin your version:

// .aiorg
{
  "project": "my-startup",
  "pinnedVersions": {
    "marketing-os": "1.5.0"
  }
}

You'll get a notification about new versions but won't auto-upgrade.

---

Checking Changes

Before upgrading, see what will change:

npx @aiorg/cli changelog marketing-os

v1.5.0 (2025-01-10)
━━━━━━━━━━━━━━━━━━━

Added:
- /viral command for viral content campaigns
- Twitter thread generator

Changed:
- Improved SEO keyword research accuracy
- Better content calendar suggestions

Fixed:
- Twitter auth flow edge case

New environment variables:
- TWITTER_API_KEY (optional, for /viral)

No breaking changes.

---

Breaking Changes

Rarely, we make breaking changes:

⚠️  BREAKING CHANGES in v2.0.0:

- /diagnose renamed to /analyze
  Your muscle memory needs updating

- Config format changed
  Auto-migrated, no action needed

- Removed /old-command
  It's been deprecated since v1.3.0

Our policy:

1. Deprecate first (warning for 2+ versions)
2. Auto-migrate when possible
3. Clear instructions when manual action needed

---

Best Practices

1. Use Version Control

git add -A
git commit -m "Before kit upgrade"
npx @aiorg/cli upgrade
git diff  # See what changed

2. Read Changelogs

npx @aiorg/cli changelog [kit]

Know what you're getting before you upgrade.

3. Upgrade Regularly

Small, frequent upgrades are easier than big jumps.

4. Test After Upgrade

Run a few commands to verify everything works:

> /help
> /status