Migrate configuration

Version 0.3.0 keeps policy under the host that executes the hook. OpenCode and Pi can use different global and project policy without reading each other’s destination. Version 0.2.0 reads the shared legacy paths below.

Legacy and destination paths

Scope	Legacy source	OpenCode destination	Pi destination
Global	`$XDG_CONFIG_HOME/auto-mode-gate/config.json`, `%APPDATA%\auto-mode-gate\config.json` on Windows, or `~/.config/auto-mode-gate/config.json`	`$OPENCODE_CONFIG_DIR/auto-mode-gate.json` or `~/.config/opencode/auto-mode-gate.json`	`$PI_CODING_AGENT_DIR/auto-mode-gate.json` or `~/.pi/agent/auto-mode-gate.json`
Project	`<project>/.auto-mode-gate.json`	`<project>/.opencode/auto-mode-gate.json`	`<project>/.pi/auto-mode-gate.json`

Automatic migration

When a host-owned destination is absent, the adapter:

reads the matching legacy source only if it is a regular non-symlink file;
applies the same 64 KiB limit and strict parser used for normal configuration;
writes the exact validated bytes to a unique temporary file beside the destination;
flushes and closes the temporary file;
publishes it without replacing a destination created by another process;
leaves the legacy source unchanged.

An existing destination is authoritative. The adapter ignores legacy even when legacy has newer or different content. Invalid destinations fail closed instead of falling back. Automatic publication requires same-filesystem hard-link support. If the filesystem rejects it, the host fails closed and you must migrate manually.

Migrate manually

Stop or reload the target host so it is not reading configuration during the copy.
Confirm the destination does not exist. Do not overwrite it.
Create the host-owned parent directory if needed.
Copy the legacy file with a create-only or no-clobber option that fails when the destination exists. Do not use a command that overwrites by default.
Start the host and verify behavior.
Repeat for the other host if you use both.

Use your operating system’s ordinary copy command. Do not paste active configuration, paths, model names, credentials, or raw errors into public issues.

Verify and clean up

Start OpenCode and confirm it reacts only to its global and .opencode project files.
Start Pi and confirm it reacts only to its global and .pi project files.
Change a harmless test setting in one destination and confirm the other host remains unchanged.
Keep a private backup before deleting legacy.
Remove legacy only after every host you use has a valid destination and rollback is no longer required.

Roll back to 0.2.0

Version 0.2.0 reads only the legacy shared paths. Leave or restore the legacy file before loading that version. Host-owned files are ignored by 0.2.0.

To retry migration in a newer build, stop the host, remove only that host’s destination, keep legacy in place, and start the host again. The adapter attempts a fresh exclusive copy.

Troubleshooting

Relative host root: use an absolute OPENCODE_CONFIG_DIR or PI_CODING_AGENT_DIR.
Missing or non-directory host root: create a regular directory or unset the variable to use the fallback.
Symlink or non-regular entry: replace it with a regular directory or file you control.
Invalid destination: repair or remove it deliberately; the adapter will not downgrade to legacy.
Unsupported publication or permissions: migrate manually without overwriting the destination.
Temporary file after interruption: do not rename it into place. Remove it only after confirming no migration process is active.
Changed configuration not loaded: reload or restart the host.