Upgrading Kits

Keep your kits up to date with the latest features and fixes.

Why Upgrade?

Each kit release includes:

New features and commands
Bug fixes
Improved prompts and knowledge
Better integrations

Your data is preserved — only kit files are updated.

Quick Upgrade

cd ~/my-project
npx @aiorg/cli upgrade

The CLI:

Checks for new versions
Downloads updates
Merges files according to categories
Preserves your data

What Gets Updated

File Categories

Category	Example Files	Behavior
Always Replace	`.claude/commands/`, `.claude/knowledge/`, `CLAUDE.md`	Overwritten with latest
Never Touch	`.env`, `config/`, `content/*`	Never modified
Merge	`package.json`, `.claude/settings.json`	Deep merge (your values win)
Add Only	`supabase/migrations/*`	Added if file doesn't exist

Visual Example

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

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

Upgrade Workflow

Step 1: Check for Updates

npx @aiorg/cli status

Marketing OS v1.4.0 (installed) → v1.5.0 (available)

Changelog for v1.5.0:
- Added /viral command
- Improved SEO keyword research
- Fixed Twitter thread formatting

Step 2: Review Changes

Before upgrading, see what changed:

npx @aiorg/cli changelog marketing-os

Shows:

New features
Breaking changes (if any)
New environment variables (if any)
Upgrade notes

Step 3: Upgrade

npx @aiorg/cli upgrade

Or upgrade a specific kit:

npx @aiorg/cli upgrade marketing-os

Step 4: Handle New Requirements

If the upgrade adds new environment variables:

Upgrade complete!

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

Add to your .env file and restart.

What's New Greeting

After upgrading, the kit greets you with what changed:

Welcome back to Marketing OS!

🆕 What's New in v1.5.0:
├── /viral - Create viral content campaigns
├── Improved SEO keyword research
└── Better Twitter thread formatting

Run /help to see all commands.

Safe Upgrades

Data Protection

Your data is NEVER touched:

config/ — Your settings
content/ — Your created content
.env* — Your environment variables
Kit-specific data folders (.marketing-os/, etc.)

Rollback

If something breaks:

npx @aiorg/cli rollback marketing-os

Reverts to previous version.

Manual Rollback

# See installed versions
ls ~/.aiorg/cache/marketing-os/

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

Template Upgrades

For templates (SaaS Dev Team, Landing Page), upgrades are more careful:

What Updates

Updated	Not Updated
`.claude/commands/*`	`src/` (your code)
`.claude/knowledge/*`	`components/` (your UI)
`CLAUDE.md`	`supabase/migrations/*`
`recipes/*`	Custom pages

New Features

When templates add new features, you get the recipe, not the code:

SaaS Dev Team v2.0.0 includes:
├── New: Multi-tenant support

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

This prevents breaking your customizations.

Checking Versions

Current Version

npx @aiorg/cli version
# or
cat .claude/version.json

All Installed Kits

npx @aiorg/cli list

Installed kits:
├── marketing-os v1.5.0 (up to date)
├── pmf-os v1.1.0 (update available: v1.2.0)
└── success-os v2.2.0 (up to date)

Troubleshooting

"Merge Conflict" Error

If settings can't be merged:

npx @aiorg/cli upgrade --force

This uses the new version's settings. Your old settings are backed up to .claude/settings.json.bak.

"Command Not Found" After Upgrade

Restart Claude Code to reload commands:

# In Claude Code
/clear
# Or close and reopen terminal

Breaking Changes

Check the changelog before upgrading:

npx @aiorg/cli changelog pmf-os

⚠️  BREAKING CHANGES in v2.0.0:
- /diagnose renamed to /analyze
- Config format changed (auto-migrated)

The CLI handles most breaking changes automatically.

Best Practices

1. Upgrade Regularly

Check for updates weekly:

npx @aiorg/cli status

2. Read Changelogs

Before upgrading, know what changed:

npx @aiorg/cli changelog [kit]

3. Test After Upgrade

Run a few commands to verify everything works:

> /help
> /status

4. Keep Environment Variables

If upgrade mentions new env vars, add them before using new features.

5. Use Version Control

If your project is in git, commit before upgrading:

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

Kit Collaboration

How kits share context

Getting Started

Install your first kit