Adopt an Existing Repository

EmbrAIon can be added to a mature repository without taking ownership of files your project or AI client already manages.

The safest approach is incremental adoption.

1. Initialize project configuration

From the repository root:

embraion init
embraion doctor

This creates .embraion/ configuration and local state/cache ignore rules. It does not install executable hooks or enforcement.

2. Prepare to install Bootstrap

Inspect existing .embraion/** and host-file ownership first. If the project is already initialized, preserve its configuration. The next step installs canonical skills without blindly replacing host settings. After installation, ask “Configure EmbrAIon for this project.” Bootstrap inspects existing documents, policy, and CI, preserves intentional settings, and binds actual sources/validation commands. See Project Bootstrap.

3. Preview host adoption

If your repository already has Codex/Copilot/Claude configuration, do not immediately overwrite it.

Preview the desired projection:

embraion projection diff --host codex --destination .

For selective adoption, start with reusable skills:

embraion projection diff \
  --host codex \
  --destination . \
  --component skills

Then install only that component:

embraion install \
  --host codex \
  --destination . \
  --component skills

Repeat --component when you intentionally want EmbrAIon to own more components.

If a mature Codex repository already owns .codex/config.toml, use partial config ownership instead of replacing the file:

embraion projection diff \
  --host codex \
  --component config \
  --config-mode merge

embraion install \
  --host codex \
  --component config \
  --config-mode merge

This preserves project-owned Codex settings while EmbrAIon manages only its required [agents] keys.

4. Resolve conflicts deliberately

EmbrAIon distinguishes generated files that can be safely updated from files that are user-owned or locally modified.

Projection ownership state under .embraion/state/ is intentionally local and gitignored. When a framework update runs in a fresh worktree with no local projection ledger, EmbrAIon attempts a conservative ownership recovery from the exact previous project pin. A file is recovered only when its current bytes exactly match the projection generated by that previous published EmbrAIon version. The recovered evidence is temporary and is promoted into ordinary local projection state after a successful install.

If the previous runtime cannot be resolved, the destination differs, or a file has been edited, EmbrAIon does not infer ownership and keeps reporting a conflict. Recovery never behaves like --force.

If projection diff reports a conflict:

1. inspect the conflicting file;
2. decide which system should own it;
3. prefer selective installation when only some components are needed;
4. use --force only when replacing the file is explicitly intended.

5. Validate the project contract

Run:

embraion doctor
embraion status
embraion context slots
embraion policy show
embraion validation list

If validation profiles contain real commands, execute the profile appropriate for the repository. Structured profiles can declare runtime parameters when values such as a base ref, head ref, filter, or justification are task-specific:

embraion validation run affected --param base-ref=origin/main

After installing host projections, add a strict parity gate:

embraion projection verify --host codex --component agents --component skills
embraion projection verify --host copilot

A clean verification exits zero. Any create/update/conflict/obsolete drift exits non-zero, making the command suitable for CI.

6. Add enforcement last

Do not start adoption by installing merge enforcement. First make project policy and validation trustworthy.

When they are ready, enforcement can be explicitly installed:

embraion enforcement install \
  --surface github-actions \
  --validation-profile affected

See Enforcement before making that status check required in repository rules.

Recommended adoption order

Next

Configure the project or run your first AI task.