Migration guide

Maintainer HQ 0.1.0 reads Repo Fleet document versions 1 through 9 and normalizes them to workspace document version 10 in memory. The first confirmed Maintainer HQ write persists canonical version 10 data. Existing recovery values remain private and repository records retain their capability semantics.

Move an existing document

Keep a private recoverable backup, then point Maintainer HQ at the existing file:

export MAINTAINER_HQ_DOCUMENT=/private/location/workspace.json
maintctl validate
maintctl doctor

The file must be regular, non-symlinked, and mode 0600. Outside Git, those private filesystem permissions are the default boundary. Inside a Git worktree, Maintainer HQ automatically requires a git-crypt filter and disabled plaintext diffs for the document. Pass --require-git-crypt to init or validate when that stronger boundary must be mandatory regardless of location.

Versions before 10 receive deterministic workspace metadata during normalization. Rename the imported workspace and persist the current schema through the ordinary reviewed write path:

maintctl workspace rename --name "My projects"
maintctl workspace rename --name "My projects" --apply
maintctl validate

Review the first command's exact plan before applying it. The operation preserves workspace identity, repository records, capability state, and recovery material while advancing the revision.

Import separate legacy projections

If the source installation has a GitHub policy module and private Hookrelay manifest instead of one workspace document, use the one-time importer:

maintctl migrate --policy ./policy.mjs --manifest /private/location/hookrelay-manifest.json
maintctl validate

The policy module is executable code and must be trusted. The manifest must pass the same private-file checks as workspace state. Repository membership must match across both sources. migrate refuses an existing destination unless --force is supplied.

MCP migration is intentionally narrower. A trusted process launcher must configure both legacy source paths when starting the server. Tool callers can then plan and confirm the import but cannot choose a module to execute or receive projection content.

Compatibility period

The repo-fleet executable is an alias for maintctl during the pre-1.0 period. Document fields using the stable fleet classification remain valid; the dashboard presents that class as Maintained. New automation should use maintctl, MAINTAINER_HQ_* environment variables, and workspace-named MCP tools.

Activity sidecar

The project activity ledger is separate from workspace document migration. A missing sidecar is a valid empty feed, and the first confirmed project or activity write creates one bound to the normalized workspace ID. Use MAINTAINER_HQ_ACTIVITY or --activity to carry an existing sidecar to another installation. Do not attach a sidecar to a different workspace or merge ledger JSON manually.

Rollback

Stop writers before restoring a backup. Replace the workspace document only with a regular mode-0600 file, preserve any required Git encryption attributes, then run maintctl validate. Restore its matching private activity sidecar when project history must move with it. Do not combine records from two revisions manually because recovery identities and revision-bound plans may no longer agree.