migrate-workspace

Migrate a legacy per-harness workspace into the shared .apothem layout.

Synopsis

apothem migrate-workspace [--project PATH] [--dry-run]
                          [--quiet|-q] [--verbose|-v]
                          [--format plain|json] [--json] [--no-color]

migrate-workspace collapses a legacy per-harness data home (.apothem/<harness>/...) and a legacy .plans/ tree into the single shared .apothem/{plans,memory,learning,contexts} working directory. The base is the resolved --project root when supplied, otherwise the current working directory (the project-local default).

Per-harness memory, contexts, and learning stores union-merge into the shared store by id; learning signals concatenate-dedup; a conflicting record (same id, different body) is skipped, never overwritten. A legacy .plans/ tree moves under .apothem/plans/. Every consumed source is backed up first. The migration is idempotent — re-running on an already-migrated tree is a no-op.

Options

Option	Description
`--project PATH`	Project root for project-scope adapters that materialize into a project tree rather than a user-scope configuration directory.
`--dry-run`	Detect the legacy layout and report what would migrate without writing.
`--quiet`, `-q`	Suppress informational output; only errors are emitted.
`--verbose`, `-v`	Emit additional diagnostic output.
`--format plain\|json`	Output format (default: `plain`).
`--json`	Shorthand for `--format json`.
`--no-color`	Disable ANSI color codes in output.
`-h`, `--help`	Show help and exit.

JSON output

The --json envelope carries the migration outcome. On a completed migration status is success and the payload reports the merged record counts, whether a .plans/ tree was relocated, the backup root, and any skipped conflicts. A --dry-run invocation instead reports legacy_layout_detected.

{
  "command": "migrate-workspace",
  "status": "success",
  "base": "/home/example/project",
  "migrated": true,
  "backup_root": "/home/example/project/.apothem/.backups/01J9Z…",
  "memory_merged": 12,
  "contexts_merged": 4,
  "learning_merged": 7,
  "conflicts": [],
  "plans_moved": true,
  "notes": []
}

When no legacy layout is present, migrated is false and nothing is written. The --dry-run envelope omits the outcome counts and reports detection only:

{
  "command": "migrate-workspace",
  "base": "/home/example/project",
  "dry_run": true,
  "legacy_layout_detected": false
}

Examples

apothem migrate-workspace
apothem migrate-workspace --project .
apothem migrate-workspace --dry-run --json

Exit codes

Code	Meaning
0	Migration completed, or no legacy layout was found (nothing to migrate)
1	Expected error — a validation or project-root error, or a migration failure