# 0.2.0 Update Compatibility Audit

This audit compares pre-merge `main` (`1173b8a`, core 0.1.9) with the initially
published merge (`c917615`, incorrectly numbered 1.2.0). The merge changed 191
files: 75 core/runtime files, 85 plugin files, 20 generated knowledge files, and
11 other project files.

## Confirmed Upgrade Failures

1. **Core imported an independently preserved plugin.** `src/web/server.js`
   loaded `plugins/okf/backend/file_knowledge` during startup. Core-only updates
   deliberately preserve the whole `plugins/` directory, so a 0.1.9 install did
   not receive the new OKF plugin file and crashed before the web server started.
2. **A newly added package was required before dependencies were updated.** The
   OBS connector loaded `obs-websocket-js` at module initialization. Core updates
   preserve `node_modules/` and the old updater did not reconcile it with the new
   lockfile, producing another startup crash.
3. **Core and plugin delivery were not coordinated.** The merged repository had
   patch-bumped plugins, but a core update copied none of them by design. There
   was no historical release catalog or exact-version plugin installer to let an
   administrator bring an old installation to a known release set.
4. **The release number was wrong.** 1.2.0 was a mistaken major-version jump from
   0.1.9. Normal semantic-version ordering would reject the corrected 0.2.0 as a
   downgrade for an already affected install.

No unresolved static relative imports remain in the repaired tree. Plugin data
remains isolated under each plugin's `data/` directory, and current plugin
manifests match the 0.2.0 release catalog.

## Repairs

- Core now uses the OKF capability registered at
  `global.lumiFrameworks.okf.saveCorrection`; if OKF is absent, only that action
  shows an install/enable message.
- OBS WebSocket is an optional dependency and is loaded behind a guarded
  connector boundary. Its absence cannot stop the overlay or web server.
- `run.js` reconciles required direct dependencies with `package-lock.json`
  before each application start. Optional integration failure is degraded, not
  fatal.
- `release-index.json` maps core, plugin, and Lumi AI tool versions to immutable
  release tags. Admins can install or reinstall an exact core/plugin version.
- `update-manifest.json` declares 0.2.0 as the supported replacement for 1.2.0,
  allowing affected installations to repair themselves despite semver ordering.
- Repository checkout and post-copy verification both confirm the requested
  version. Plugin updates preserve plugin data and now restart before reporting
  the selected code as active.

## Data Safety

The repair does not replace `data/`, `plugins/`, `node_modules/`, configuration,
storage, uploads, logs, databases, secrets, environment files,
`knowledge/community/`, or `knowledge/corrections/`. It creates a compressed
rollback snapshot first. The repair ZIP contains only managed core files, a
preservation manifest, and SHA-256 hashes; it contains no user or plugin data.

The snapshot database copy is a safety backup, not a migration or replacement.
The repair introduces no destructive database migration.