Project Configuration Files

This page describes the canonical project-owned configuration under .embraion/.

A useful rule is: store project facts and preferences here; keep reusable engineering mechanisms in EmbrAIon Core. Generated host files should project this contract rather than become a second place to maintain it.

Most files below are created by embraion init. Projects that opt into provider-neutral execution or pricing may add the optional runtime configuration described near the end of this page.

.embraion/project.yaml

This is the stable project identity and framework-pin file.

framework:
  repository: GORYNED/EmbrAIon
  version: <pinned-version>

project:
  name: MyProject

capabilities: {}

framework

framework.repository identifies the upstream EmbrAIon framework. framework.version pins the project to an exact EmbrAIon release. Ordinary CLI commands resolve that version and may use an isolated cached runtime when the globally installed launcher is newer.

project

project.name is the project identity used by the project overlay.

capabilities

capabilities is intentionally open project metadata. It can describe project traits such as an engine, language family, or integration surface.

capabilities:
  engine:
    family: ExampleEngine
    language: ExampleLanguage

At the current contract level, EmbrAIon does not use arbitrary capabilities values to select models or bypass policy. Treat it as an extension point and project metadata, not as a security or routing mechanism.

This metadata is separate from the optional, schema-checked external capability inventory. A declaration there records requirements and lifecycle evidence; it does not install an integration or prove that a host loaded it.

housekeeping

housekeeping is optional. It controls automatic cleanup of the branches and worktrees that agents created. Every switch defaults to the previous behavior:

housekeeping:
  on-task-start: false
  local-branches: true
  remote-branches: false
  worktrees: true
  preserve-branches: []

• on-task-start (default false) runs cleanup before an independent writable task. Nothing is removed unless it is true.
• local-branches, remote-branches, and worktrees choose what cleanup may remove. Remote deletion is off by default.
• preserve-branches lists branch names or patterns that are never removed, such as main or release/*.

Only resources that EmbrAIon recorded as agent-created, and that pass the completion and integration checks, are removed. Unknown branches and worktrees are reported and kept. The switches must be booleans and preserve-branches a list of names; anything else is an error. See the worktree tool guide.

worktree

worktree.lfs is optional. The default is none: new worktrees are created exactly as before. Set it to hydrate for a repository that uses Git LFS:

worktree:
  lfs: hydrate

A new checkout of such a repository holds pointer text files until the content is fetched. With hydrate, embraion worktree create (and worktree register for a worktree your host created) fetches the LFS content of the exact worktree HEAD from the repository's own LFS remote, checks it out, and verifies every LFS file by size and SHA-256. A failed check makes the command exit non-zero, but the worktree is kept. Any other value, or an unknown key under worktree, is an error. See the worktree tool guide.

.embraion/knowledge.yaml

This file points EmbrAIon at project-owned knowledge.

New projects include canonical Project Contract Slots:

slots:
  constitution:
  architecture:
  source-authority:
  compatibility:
  persistence:
  engineering-workflow:
  specification:
  deferred-tasks:

A project binds only the slots it actually owns:

slots:
  architecture: docs/architecture.md
  source-authority: docs/references/project-sources.md
  persistence:
    path: docs/persistence.md
    data-class: PRIVATE

These slot names are framework-owned semantic extension points. EmbrAIon knows the reusable responsibility of each slot; the consuming repository owns the referenced content. Unbound slots remain null and are not selected.

In v0.10.0 the top-level slots key becomes framework-reserved. This is an intentional pre-1.0 contract cleanup rather than a compatibility shim for hypothetical earlier custom entries named slots.

Ordinary custom knowledge remains supported alongside slots:

product: knowledge/project.md
domain-video: knowledge/video.md

The structured form adds context-selection metadata:

architecture:
  path: knowledge/architecture.md
  data-class: PRIVATE
  trust: project
  roles:
    - architect
    - lead
  triggers:
    - architecture

Supported structured fields are:

• path — required path inside the consuming repository;
• data-class — PUBLIC, PRIVATE, or CONFIDENTIAL;
• trust — project, external, or generated;
• roles — optional roles eligible to receive that knowledge;
• triggers — optional task terms used for context selection.

Knowledge files remain ordinary repository files. knowledge.yaml stores references and selection metadata, not duplicated knowledge content.

.embraion/policy.yaml

This file owns project safety and source classification policy.

Path patterns preserve existing shell-style matching, including * across separators. A whole **/ segment also matches zero directories, so private/**/*.cs protects both private/file.cs and nested files. Matching rejects patterns longer than 4,096 characters or with more than eight optional **/ segments rather than silently missing a protected path.

sources:
  canonical:
    - src/**
  protected:
    - vendor/**
  generated:
    - build/**
  external:
    - external/**

review:
  substantial-required: true

privacy:
  default-class: PRIVATE

enforcement:
  enabled: false
  validation-profile: affected
  require-review: false

sources

The four path classes are:

• canonical — project-owned source-of-truth paths;
• protected — paths that should not be mutated through ordinary writable work;
• generated — generated artifacts rather than canonical authored source;
• external — externally sourced material.

review

substantial-required: true requires review evidence for substantial work where the execution contract calls for it.

privacy

default-class defines the project default when a more specific data classification is not supplied. Valid values are PUBLIC, PRIVATE, and CONFIDENTIAL.

Model selection never widens these policy boundaries.

enforcement

Enforcement is disabled by default. The policy records whether an explicitly installed gate is active, which validation profile it must run, and whether independent review is required:

enforcement:
  enabled: false
  validation-profile: affected
  require-review: false

Enable a CI surface only by an explicit command:

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

This creates .github/workflows/embraion-enforcement.yml, enables the policy gate, runs protected-path and validation checks on pull requests, and optionally requires at least one current approved GitHub review. Existing different workflow content is refused unless --force is deliberately supplied.

EmbrAIon does not silently install host-native hooks. harness audit continues to report native hook capability, while enforcement installation remains an explicit project action.

.embraion/deployments.yaml

This file defines reusable project-owned execution deployments without creating a framework-owned model catalog.

providers: {}
deployments: {}

A deployment names a concrete host/model choice and may declare provider identity, supported/default effort, billing metadata, eligibility capabilities, host options, and non-secret metadata. Routes and roles can reference the deployment id from .embraion/routing.yaml.

See Project deployments for the full contract.

.embraion/routing.yaml

This file contains optional model-selection overrides for specific AI hosts.

The default is:

overrides: {}

That means EmbrAIon resolves the route as host-default, and the active AI client chooses its own default/automatic model.

A project can override a route:

overrides:
  codex:
    routes:
      complex:
        model: "<selector reported by the host>"
        effort: "<host-supported effort>"

Or a role:

overrides:
  codex:
    roles:
      reviewer:
        model: "<selector reported by the host>"

Role overrides are more specific and merge over route overrides.

EmbrAIon deliberately does not maintain a model catalog. model, effort, and options are opaque host-owned values. Only use selectors and settings confirmed by the active host.

.embraion/validation.yaml

This file declares project validation profiles.

profiles:
  fast:
    - python -m unittest discover -s tests
  affected:
    - python -m unittest discover -s tests
  full:
    - python -m unittest discover -s tests
    - python -m compileall src

fast, affected, and full are the default profile names, but the schema permits additional named profiles.

The effective policy exposes these profiles through:

embraion policy show
embraion policy show --json

Profiles are executable first-class project configuration:

embraion validation list
embraion validation run fast
embraion validation run affected --json
embraion validation run full --run-id task-001

Commands run sequentially from the project root. Each invocation writes redacted structured evidence under .embraion/state/validation/. A failed command makes the profile fail; by default remaining commands still run so the result captures complete evidence. Use --fail-fast when later commands would be meaningless after the first failure.

An empty profile is reported as skipped, never as a false pass. --timeout can apply a per-command timeout. When --run-id names an active EmbrAIon execution run, the validation result is attached to that run by evidence ID.

Keep commands deterministic and repository-local where possible. Project validation commands are executable project code and run only when embraion validation run is explicitly invoked.

.embraion/agents.yaml

This file defines project-specific agents that are projected into Codex, GitHub Copilot, and Claude Code together with the reusable Core roles.

A project agent can extend one existing non-Lead Core role:

agents:
  - id: domain-specialist
    title: Domain Specialist
    extends: reviewer
    purpose: Review project-specific domain behavior.
    access: read-only
    responsibilities:
      - focus review on project-specific domain contracts
    restrictions:
      - do not modify project files
    triggers:
      - domain-focused review
    outputs:
      - domain review findings

Required fields:

• id — unique kebab-case project agent ID; it must not shadow a Core agent ID;
• purpose — concise project-specific responsibility;
• access — explicit read-only or workspace-write boundary;
• responsibilities — one or more project-specific responsibilities.

Optional fields:

• title — display title; defaults to the title-cased ID;
• extends — an existing non-Lead Core agent ID;
• restrictions, triggers, and outputs — additional project-specific contract items.

When extends is present, EmbrAIon inherits the Core role's responsibilities, restrictions, triggers, and outputs, then appends the project-specific items. The project agent must preserve the Core role's access level. It cannot extend lead, widen a read-only role into a writable role, or replace a canonical Core agent.

Without extends, the definition is a standalone project agent with its explicitly declared access and responsibilities. Standalone project agents are still non-Lead roles: EmbrAIon automatically adds the canonical do not recursively delegate restriction during projection. Projects may add stricter restrictions but cannot remove that delegation boundary.

During embraion install or embraion projection diff, these definitions are resolved from the consuming project's .embraion/agents.yaml and emitted as host-native files:

Codex          .codex/agents/<id>.toml
GitHub Copilot .github/agents/<id>.agent.md
Claude Code    .claude/agents/<id>.md

Each project agent profile lists its merged triggers and outputs. When at least one project agent is declared, the projected orchestration skill also gets a compact Project specialists section with each specialist's ID, inherited Core role, purpose, and the triggers and outputs the project declares, so Lead knows when to delegate. Core role profiles are unchanged, and no section is written without project agents.

Framework-only embraion sync remains deterministic and generates Core agents only; project agents belong to a consuming repository and are resolved during project projection.

Optional .embraion/execution.yaml

Projects that use embraion execute can declare reviewed executable bindings in .embraion/execution.yaml.

These bindings connect project-owned deployments to an execution adapter and may constrain:

• the exact upstream selector/provider expected by the project;
• credential references such as environment-variable names, never credential values;
• allowed source IDs and trust levels;
• task-class or data-class aliases;
• timeout and option ceilings;
• observed model/provider evidence.

The project owns those concrete bindings because they describe project-approved external execution. EmbrAIon Core owns the generic execution, fallback, failure, health, and evidence mechanics.

If a project does not use executable provider bindings, it does not need this file.

A dataClassAliases entry is a compatibility mapping at the execution boundary. For example:

dataClassAliases:
  CONFIDENTIAL: PROJECT_SECRET

does not create a new Core data class. EmbrAIon requests still use the canonical PUBLIC, PRIVATE, or CONFIDENTIAL vocabulary; the alias only maps that canonical class to an intentional project-specific capability label.

See Execution & providers for the full contract.

Optional .embraion/pricing.yaml

Projects that want deterministic provider cost calculation can declare approved official pricing sources and SKU mappings in .embraion/pricing.yaml.

Pricing refresh is explicit:

embraion pricing refresh

Runtime calculation uses the validated local snapshot rather than fetching prices during execution. Concrete rates, provider URLs, SKU mappings, freshness policy, and applicability dates remain project-owned facts.

Use:

embraion pricing status

to inspect the current validated snapshot.

See Pricing & cost for refresh, snapshot, staleness, usage-semantics, and cost-evidence behavior.

Optional .embraion/external-capabilities.yaml

This strict, versioned inventory declares independently installed host-managed capabilities. The file is absent by default. Include only version/digest, source, license, host requirements, access, data class, and environment-variable names. A declaration is not an installation, authorization, or proof of host loading. embraion capabilities --path . --host codex --json reports what local evidence can establish; later host stages remain unverified without trusted live observation. See External capabilities.

Schema v1 can read legacy builtin:unity declarations for diagnostics, but the bundle is no longer shipped. Remove such an entry explicitly before installing for its selected host or updating; install the desired replacement independently through the host first. See External capabilities.

Optional .embraion/integrations.yaml

This strict, versioned file declares the MCP servers the project's host configuration should contain: id, host, command, args, transport, access, environment-variable names, and optional portable, cwd, and required (cwd and required for Codex entries only). The file is absent by default; then no integration comparison runs. When it exists, embraion security scan reports missing, unexpected, mismatched, and non-portable servers as high-severity integration-drift findings. See Declared integrations.

Optional .embraion/knowledge-maintenance.yaml

Declare which project document depends on which source files, then explicitly run embraion knowledge snapshot --path . after reviewing the relationships. embraion knowledge audit --path . compares local hashes and reports changed or missing sources for review. It does not rewrite documentation or infer external version drift without observed metadata. See Knowledge maintenance.

Optional .embraion/organization.yaml

Project-owned code organization limits can supplement the Core procedure. embraion organization check --path . --base-ref main --head-ref HEAD --include-worktree --json checks changed files incrementally. Existing debt does not waive a new violation. See Code organization.

Optional .embraion/sources.yaml

This strict, versioned file lists the stable source IDs with a role, a write policy (read-only, workspace-write, or forbidden), and optional description, doc, and a raised data-class. It never holds machine paths. The file is absent by default; then nothing changes. When it exists, embraion validate checks it, embraion sources reports it, and a workspace-write execution request may name only sources that allow writing. See Source registry.

Optional .embraion/skills/

Project-owned skills use the Core skill layout: one directory per skill with SKILL.md as the entry point.

.embraion/skills/<name>/SKILL.md
.embraion/skills/<name>/references/...   # optional supporting files

The skills component projects each skill next to the Core skills for Codex (.agents/skills/), GitHub Copilot (.github/skills/), and Claude Code (.claude/skills/). Projected files are recorded in the projection ownership ledger, so projection diff and projection verify report edited copies as conflicts and removed skills as obsolete; install --prune removes unchanged obsolete copies. Portable bundles remain Core-only.

Projection fails before writing when an entry is not a skill directory, the name is not lowercase kebab-case (at most 64 characters), the name matches a Core skill, SKILL.md is missing, its front matter lacks a matching name or a non-empty description, or the skill contains a symbolic link.

Project settings should not reimplement Core

Do not copy generic EmbrAIon mechanisms into project configuration just to customize a repository.

For example:

• the project may choose which deployment should handle complex work, but Core owns the routing contract;
• the project may declare which paths are protected, but Core owns generic policy/enforcement mechanics;
• the project may define which validation commands prove correctness, but Core owns validation execution/evidence behavior;
• the project may add a domain specialist, but generic Architect/Reviewer/Validator roles remain Core concerns.

This boundary is what makes a project overlay portable instead of becoming another framework.

.embraion/.gitignore

The project-local ignore file protects runtime-only state:

state/
cache/

During normal operation EmbrAIon may create:

.embraion/state/
.embraion/cache/

These are not canonical project configuration and should normally remain untracked.

Local checkpoint references and knowledge audit baselines also live under state/; they are not project policy or a substitute for source control and review evidence.

Host projection ownership ledgers also live under .embraion/state/projections/. Because that state is intentionally gitignored, a fresh worktree may not have the ledger created by an earlier install. During an intentional framework update, EmbrAIon can create temporary recovery evidence by comparing tracked host files byte-for-byte with the exact projection of the project's previous pin. Only exact matches are eligible; modified or otherwise unproven files remain conflicts. A successful install replaces that recovery evidence with the normal local ownership ledger.

Canonical configuration vs generated host projection

The .embraion/ files above are project-owned configuration. Host files generated by embraion install are projections.

Examples:

.codex/...       # Codex
.github/...      # GitHub Copilot
.claude/...      # Claude Code

When you want to change project policy, knowledge, validation, or routing, prefer the canonical .embraion/ file rather than editing a generated host projection to represent the same intent.

Projected host guidance links to Core files that do not exist in a consuming project, such as the worktree workflow, through the EmbrAIon release tag of the projected framework version.

See AI host examples for concrete workflows.

Projection ownership is scoped by host and canonical destination: .embraion/state/projections/<host>/<destination-id>.json, with matching <destination-id>.recovery.json evidence. The root projection uses root; alternate destinations use a SHA-256 identity of the canonical project-relative path, or absolute path for external destinations. Filenames contain no absolute paths. Installs, inventories, config-mode evidence, and pruning are independent per destination. Matching legacy host-only ledgers are read without mutation and migrate automatically after a successful install; mismatched or ambiguous evidence is never assigned to another destination. A relocated project does not automatically inherit ownership from a recorded absolute destination.

.embraion/claude-native.yaml

Optional bindings from routing roles to Claude native agents, with explicit role, route-class, data-class and access assignment tuples to install. This file contains no model or effort choices: definitions derive from routing and deployments. The scoped-agents component and guard/observer hooks are explicit opt-ins; see Claude Code.