# Upgrading LumenFlow

This guide covers upgrading LumenFlow packages in your project.

## Quick Upgrade

```bash
# Check for available updates
pnpm outdated @lumenflow/*

# Update all LumenFlow packages atomically
pnpm lumenflow:upgrade --latest
```

Package upgrades change the runtime `wu:brief` defaults immediately. `lumenflow:upgrade` automatically
syncs managed docs (LUMENFLOW.md, .lumenflow/constraints.md) from templates. Bootstrap files
(AGENTS.md, vendor overlays) are updated via merge-block markers — only the LumenFlow-managed
section between `<!-- LUMENFLOW:START -->` / `<!-- LUMENFLOW:END -->` is replaced; your content
outside markers is preserved.

If you have project-specific workflow additions, put them in `LUMENFLOW.local.md` (never overwritten).
Project-local `.lumenflow/templates/` remains optional unless you want custom overrides.

## Version Compatibility

LumenFlow follows semantic versioning:

- **Major versions** (e.g., 1.x to 2.x): Breaking changes, require migration steps
- **Minor versions** (e.g., 1.1 to 1.2): New features, backwards compatible
- **Patch versions** (e.g., 1.1.0 to 1.1.1): Bug fixes, backwards compatible

All `@lumenflow/*` packages are versioned together. Always upgrade them as a group.

## Step-by-Step Upgrade Process

### 1. Check Current Versions

```bash
pnpm list @lumenflow/*
```

### 2. Review Changelog

Before upgrading, review the changelog for breaking changes:

- [GitHub Releases](https://github.com/hellmai/lumenflow/releases)
- [lumenflow.dev/changelog](https://lumenflow.dev/changelog)

### 3. Update Packages

```bash
# Update to latest versions
pnpm lumenflow:upgrade --latest

# Or update to a specific version
pnpm lumenflow:upgrade --version 1.2.0
```

### 4. Sync Documentation

`lumenflow:upgrade` already syncs the shipped docs surfaces inside the upgrade transaction:

```bash
pnpm lumenflow:upgrade --latest
```

This updates:

- Core docs: LUMENFLOW.md, AGENTS.md, .lumenflow/constraints.md
- Scaffolded onboarding documentation
- Already-present or configured vendor bootstraps
- Reserved Claude skills when Claude assets are configured

Run `pnpm docs:sync --vendor <type>` only when you want to refresh a specific vendor/bootstrap surface outside the upgrade flow.

## Defaults vs Overrides

- New installs already get the current `wu:brief` defaults.
- Existing installs get the new runtime behavior as soon as packages are upgraded.
- Project-local `.lumenflow/templates/manifest.yaml` and `spawn-prompt/*.md` files are only needed
  when you want to override the built-in prompt composition.

### 5. Verify Installation

```bash
# Run gates to verify everything works
pnpm gates

# Check CLI version
pnpm exec lumenflow --version
```

## Troubleshooting

### Package Resolution Errors

If you encounter dependency resolution errors:

```bash
# Clear pnpm cache and reinstall
pnpm store prune
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

### CLI Not Found

If `lumenflow` command is not found after upgrade:

```bash
# Rebuild CLI
pnpm --filter @lumenflow/cli build

# Or reinstall
pnpm install
```

### Template Conflicts

If a merge-block bootstrap file needs manual review:

1. Review the diff for each conflicting file
2. Merge manually or accept incoming changes
3. Run `pnpm gates` to verify

### `wu:brief` Still Uses Older Wording

Project-local templates override the built-in defaults. Review:

- `.lumenflow/templates/manifest.yaml`
- `.lumenflow/templates/spawn-prompt/*.md`
- `.lumenflow/templates.<client>/spawn-prompt/*.md`

## Migration Guides

For major version upgrades, see version-specific migration guides:

- [Migrating to v2.0](https://lumenflow.dev/migration/v2)
- [Migrating to v1.0](https://lumenflow.dev/migration/v1)

## Getting Help

- [GitHub Issues](https://github.com/hellmai/lumenflow/issues)
- [lumenflow.dev/docs](https://lumenflow.dev/docs)
