AGENTS.md

1# src/config-migration/ - Legacy Config Discovery + Transforms
2 
3## OVERVIEW
4 
5Discovers legacy config files (oh-my-opencode/oh-my-openagent JSON[C], `~/.omo/config.jsonc`) and builds migration plans that transform them into the unified `omo.json[c]` chain. The migration *engine* (lock, journal, no-clobber merge, atomic commit) lives in `packages/omo-config-core/src/migration/`; this directory owns the OpenCode-side discovery and content transforms. Consumed at plugin startup (opencode + senpi config-startup) and codex startup.
6 
7## WHERE TO LOOK
8 
9| Task | Location |
10|------|----------|
11| Which files count as legacy | `discovery.ts` + `discovery-roots.ts` + `discovery-paths.ts` (ids `OPENCODE_CONFIG_MIGRATION_ID`, `CONFIG_JSONC_MIGRATION_ID`) |
12| Plan building | `migration-plans.ts` (`createLegacyConfigMigrationPlans`) |
13| Plan execution | `migration-executor.ts` (`executeLegacyConfigMigrationPlan`) |
14| Content transforms | `transform-opencode.ts` / `transform-config-jsonc.ts` |
15| Reasoning-key unification | `reasoning-unification.ts` (`REASONING_UNIFICATION_MIGRATION_ID`, fixtures under `2026-08-reasoning-unification/`) |
16| Historical migration ids | `legacy-history.ts` |
17 
18## CONVENTIONS
19 
20- Transforms are pure: they take loaded sources and return `ConfigMigrationTransformResult`; all filesystem side effects go through the omo-config-core engine.
21- Every migration is identified by a stable id recorded in `_migrations`; never reuse or rename shipped ids (append to `legacy-history.ts` instead).
22- `deep-diff.ts` backs no-clobber semantics: existing target values always win over migrated values.
23 
24## ANTI-PATTERNS
25 
26- Never write config files directly from here; hand plans to the engine (`runMigration`).
27- Never delete legacy sources; migration copies forward and leaves timestamped backups.
28