Migration ​

Moving from Agent Harness to Tenetora: what changes, how an upgrade proceeds, and what never happens automatically.

Audience ​

Users of Agent Harness planning the move to Tenetora.

Task path ​

1. Read the change table below to see which entry points are replaced.
2. Re-run the installer without a scope on the machine; it refreshes existing registered surfaces only.
3. Update each governed project with tenetora-update.
4. Verify with tenetora version and tenetora doctor, then restart the native plugin hosts.

What changes ​

Upgrading a machine ​

Re-running the installer without a scope performs an existing-only upgrade: every registered global surface, project surface, and governance-only project is refreshed; nothing new is created. Legacy machine state migrates only when at least two independent ownership signals match — managed CLI shim, stable runtime, versioned releases or skills, installation registry, plugin source, or managed source checkout. The sequence is transactional: converge the native plugin, bootstrap the canonical CLI, back up and atomically rewrite the managed legacy Git hooks, and only then migrate the proven legacy home. If the new and old homes both exist, the old one is archived into the migration backup and only missing releases, plugin sources, logs, and project registrations are merged.

Preview bounded discovery before upgrading, and register explicit roots for projects outside the automatic ones:

tenetora installations discover --auto --dry-run
tenetora installations discover --root ~/projects

On native Windows, activation uses a junction created by mklink /J: localized command output is decoded tolerantly so a system code page cannot break the upgrade, a failure keeps its first diagnostic line, and a zero-exit invocation that never created the junction is reported as an error (see the per-version notes on Releases). POSIX symlink activation is unchanged.

Legacy skills and directories in projects ​

Do not rename .harness, CLAUDE.md, or AGENTS.md by hand. Classify first:

tenetora migrate --check --path <project>
tenetora migrate --plan --path <project>

High-confidence self-owned directories migrate with tenetora migrate --apply; third-party directories stay untouched; mixed or ambiguous layouts block by default and require explicit review. Every successful migration produces a manifest, an off-project recovery backup, and a machine-level migration log.

Rollback boundaries ​

Versioned releases are kept under the machine home, and current switches only after package verification. A project directory migration copies the old directory into backups, builds and validates in staging, then publishes .tenetora atomically. Entry adapter rewrites use atomic writes with a shared rollback log; a later failure restores every file already modified. Do not delete migration backups or plugin registries by hand before acceptance passes.

What never happens automatically ​

• Installing the skill package never creates .tenetora/.
• A product rename alone never rewrites existing project rules.
• Third-party or ambiguous plugins, hooks, and legacy directories are never renamed, deleted, or merged.
• User files and tool-private configuration are never migrated into shared .tenetora content.
• Legacy environment variables never select the active home, interpreter, plugin root, language, or runtime behavior.

Limitations ​

• This page covers user-facing migration boundaries; internal development history is not published here.
• While the public sources are unverified, no recommended migration entry is offered — verify the evidence on Releases first.

Next steps ​

• Read Concepts for the governance model you are migrating into.
• Follow Quickstart once the sources are verified.