---
title: Upgrades
description: Upgrade contract, compatibility guarantees, migration rules, and platform support.
sidebar_position: 6
---

This page is the canonical upgrade contract for Agent Layer.

It defines:
- upgrade event categories,
- compatibility guarantees,
- release-versioned migration rules,
- and the supported OS/shell capability matrix.

If guidance in other docs is shorter or summarized, this page is the source of truth.

## In this page

- [How to upgrade](#how-to-upgrade)
- [Upgrade event model](#upgrade-event-model)
- [Compatibility guarantees](#compatibility-guarantees)
- [Ephemeral artifacts and rollback scope](#ephemeral-artifacts-and-rollback-scope)
- [Migration rules by release](#migration-rules-by-release)
- [Documentation version retention and access](#documentation-version-retention-and-access)
- [OS and shell capability matrix](#os-and-shell-capability-matrix)
- [Commitment level and limitations](#commitment-level-and-limitations)
- [Upgrade checklist](./upgrade-checklist)

## How to upgrade

1. Update the global `al` CLI:
   - **Homebrew (macOS/Linux):** `brew upgrade conn-castle/tap/agent-layer`
   - **Script (macOS/Linux):** `curl -fsSL https://github.com/conn-castle/agent-layer/releases/latest/download/al-install.sh | bash`
2. Upgrade the repo: `al upgrade plan` then `al upgrade`.

For a full step-by-step runbook (interactive and CI), see the [upgrade checklist](./upgrade-checklist).

## Upgrade event model

Agent Layer classifies upgrade-impact changes into three categories:

| Category | Meaning | Expected user action |
| --- | --- | --- |
| `safe auto` | Low-risk change that can be applied automatically without manual migration steps. | Usually none beyond normal verification (`al doctor`, test/lint workflow). |
| `needs review` | Change is likely safe but may interact with local customizations. | Review prompts/diffs and choose whether to apply updates. |
| `breaking/manual` | Change cannot be safely auto-migrated or may require explicit user decisions. | Follow release migration notes before proceeding. |

Qualification guidance:
- `safe auto`: formatting-only docs changes, additive defaults, or internal behavior fixes that do not require user input.
- `needs review`: template updates where local edits may conflict, workflow/instruction rewrites, generated file ownership boundary changes.
- `breaking/manual`: command/flag removals, required config schema moves, or behavior changes that require an explicit user-controlled migration step.

Breaking-change policy:
- Agent Layer uses clean breaks for breaking/manual changes. Removed commands/flags fail immediately in the target release.
- We document exact migration actions in release notes and migration guidance instead of keeping compatibility shims.

Current enforcement status:
- This model is the published contract and release-labeling policy.
- Automated enforcement in CLI flows is planned for a future release.

## Compatibility guarantees

Agent Layer follows a sequential release-line guarantee:

- Guaranteed path: upgrade from `N-1` to `N` release lines only.
- Example: `0.7.x` to `0.8.x` is guaranteed.
- Non-guaranteed path: skipping release lines (for example `0.6.x` to `0.8.x`).

What "guaranteed" means:
- We provide documented migration guidance for the guaranteed path.
- We classify known upgrade-impact changes using the event model on this page.
- We aim to keep `al upgrade` workflows predictable for that one-step path.

What it does not mean:
- It is not a guarantee that every repo custom state can be auto-migrated.
- It does not guarantee one-step upgrades for skipped release lines.

## Ephemeral artifacts and rollback scope

`.agent-layer/tmp/` is a scratch directory for agent run artifacts (plans, reports, scratch dumps). It is treated specially across the upgrade lifecycle:

- **Snapshots exclude tmp.** Pre-upgrade snapshots under `.agent-layer/state/upgrade-snapshots/` do not capture files under `.agent-layer/tmp/`. This keeps snapshot size bounded regardless of how much scratch state has accumulated.
- **Rollback does not restore tmp.** `al upgrade rollback <snapshot-id>` will not recreate any tmp file deleted during the upgrade. If you need to keep an in-progress agent artifact across an upgrade, copy it out of `.agent-layer/tmp/` first.
- **Tmp deletion is gated.** Interactive deletion requires a destructive double-confirm. Non-interactive deletion requires the dedicated `--apply-tmp-deletions` flag — `--apply-deletions` alone never touches tmp content. The interactive "delete all unknowns?" prompt is similarly scoped: it deletes everything **except** tmp, and the grouped tmp prompt always fires separately.

For full mechanics see [Ephemeral artifacts under .agent-layer/tmp/](./reference#ephemeral-artifacts-under-agent-layertmp) in the reference guide.

## Migration rules by release

Migration rules are published per release and versioned with docs/release notes.

| Target release | Supported source release lines | Event summary | Required manual actions | Notes |
| --- | --- | --- | --- | --- |
| `v0.10.2` | `0.10.x` | `safe auto`: Replaces Gemini CLI support and the retired Antigravity desktop launcher with Antigravity (`al agy`, `[agents.antigravity]`, repo-local `.agy/` config, and `agy --gemini_dir` containment). Adds `al probe agy` for observed permissions/MCP capability reporting. Removes `al gemini` entirely (no deprecation window); existing scripts must switch to `al agy`. Adds `.antigravitycli/` and `.agy/` to the gitignore template, keeps `/.gemini/` ignored for stale generated config safety, and stops generating `GEMINI.md`. Fresh installs default `[agents.antigravity] enabled = false`. | Run `al upgrade plan` then `al upgrade`. Existing `[agents.gemini] enabled = true/false` is migrated to `[agents.antigravity] enabled = true/false`; MCP server client lists are migrated from `gemini` to `antigravity`; stale Gemini `model` and `reasoning_effort` keys plus the retired Antigravity desktop table are removed (any pre-existing `[agents.antigravity]` enable flag from the retired desktop launcher is replaced by the migrated Gemini value or the default when legacy Gemini is present; current Antigravity enablement is preserved when no legacy Gemini table exists). Any stale `GEMINI.md` shim in the repo root is deleted (only when it carries the Agent Layer `GENERATED FILE` watermark; hand-authored files at that path survive). The upgrade snapshot captures the original. Run `al probe agy` after upgrade if you rely on Antigravity MCP behavior. | Migration manifest includes `config_delete_key` (`agents.antigravity`, gated for unknown-source upgrades unless legacy Gemini is present), `config_rename_key` (`agents.gemini.enabled` -> `agents.antigravity.enabled`), `config_replace_string` (`mcp.servers[].clients[]`: `gemini` -> `antigravity`), `config_delete_key` (`agents.gemini`), `config_set_default` (`agents.antigravity.enabled = false`), and `delete_generated_artifact` (`GEMINI.md`). As of v0.10.2 the agy v1.0.0 probe baseline writes and migrates Antigravity MCP config, but runtime MCP registration is not yet observed; re-check with `al probe agy` when upgrading agy. |
| `v0.10.1` | `0.10.x` | `safe auto`: Adds two new diff-scoped cleanup skills (`prune-new-tests`, `simplify-new-code`); renames `simplify-code` skill to `simplify-codebase` (full-repo scope) and removes the legacy directory; wires fresh-context reviewer subagents into `implement-plan`, `audit-and-fix-uncommitted-changes`, `verify-against-plan`, `address-pr-comments`, and `improve-codebase`; adds `al init --here` flag for in-place installs in subdirectories of existing repos; deep-merges Claude `agent_specific` configuration so `permissions.deny` is additive (arrays/scalars still replace); auto-writes a Codex per-repo `[projects."<repo root>"] trust_level = "trusted"` stanza to repo-local `.codex/config.toml`; ships `agent_specific.permissions.deny = ["AskUserQuestion"]` in the install seed so fresh `al init` disables Claude Code's clarification-question tool by default (existing repos unaffected); adds a human-gated merge phase to `ship-pr`. | Run `al upgrade plan` then `al upgrade`. The upgrade removes the legacy `.agent-layer/skills/simplify-code/` directory; if you customized that skill, back it up first. Existing repos do not inherit the new install-seed `permissions.deny = ["AskUserQuestion"]`; add it manually to `agents.claude.agent_specific.permissions.deny` if you want the new default. The Codex per-repo trust stanza is written to `.codex/config.toml` on next sync. | Migration manifest includes one `delete_file` operation (`.agent-layer/skills/simplify-code`). No config schema changes. Claude `agent_specific` object values are now deep-merged into `.claude/settings.json`; `permissions.deny` is additive and does not trigger an override warning. |
| `v0.10.0` | `0.9.x` | `safe auto`: Skills consolidated into a shared `.agents/skills/` projection for non-Claude clients (Codex, Gemini, Antigravity, VS Code/Copilot, Copilot CLI); per-client directories (`.codex/skills/`, `.gemini/skills/`, `.agent/skills/`, `.vscode/prompts/`, `.github/skills/`) retired and cleaned by sync. `chat.agentSkillsLocations` written to `.vscode/settings.json`. Gemini sync migrated from deprecated `tools.allowed` to the Policy Engine; `.gemini/policies/agent-layer.toml` generated with `allowRedirection = true`. `al upgrade` now auto-runs `al sync` on success. `al upgrade` overwrite prompts show compact `+N -M` line-stat summary with opt-in full diff view. `.agent-layer/tmp/` excluded from snapshots; rollback and bulk-delete scoped accordingly. `xhigh` added as a valid `reasoning_effort` for Claude; custom values pass through with a warning. `_generatedBy: agent-layer` provenance field added to `.mcp.json` and `.gemini/settings.json`. MCP catalog decoupled from `config.toml` install seed into an embedded `mcp-catalog.toml`. | No manual action required; run `al upgrade plan` then `al upgrade`. The automatic post-upgrade sync will clean retired per-client skill directories and write `.gemini/policies/agent-layer.toml`. If you have customized `.codex/skills/`, `.gemini/skills/`, or `.vscode/prompts/`, back up any custom content before upgrading — sync will remove Agent Layer-managed files from those paths. | Migration manifest has no operations. All structural changes are applied by `al sync` during the automatic post-upgrade sync step. No config schema changes. |
| `v0.9.2` | `0.9.x` | `safe auto`: GitHub Copilot CLI added as a supported agent client (`al copilot`, `[agents.copilot_cli]` config section). Context file (`.context.md`) added to plan/task artifact system for faster implementing-agent orientation. `max` reasoning effort supported for Claude Opus models. `--effort` flag now defers to `agent_specific.effortLevel` when set. Model catalogs updated (added `gemini-3.1-flash-lite`, `opus[1m]`, `gpt-5.4`; removed deprecated models). Dispatch System interface consolidation replaces package-level mutable stubs with proper dependency injection. Memory hygiene and instruction quality improvements across templates. Skills improved: `audit-documentation` and `audit-tests` fix autonomously, all skills get tradeoff checkpoints, `ship-pr` edge cases fixed. Stale Copilot artifacts cleaned when agent is disabled. Explicit upgrade success message added. | No manual action required; run `al upgrade plan` then `al upgrade`. If you want GitHub Copilot CLI support, add `[agents.copilot_cli]` with `enabled = true` to `config.toml` after upgrading or re-run `al wizard`. | Migration manifest includes one `config_set_default` operation (`agents.copilot_cli.enabled = false`). No breaking changes. |
| `v0.9.1` | `0.9.x` | `safe auto`: Instruction files reordered for primacy effect (`02_rules.md` → `00_rules.md`, `00_base.md` → `01_base.md`, `01_memory.md` → `02_memory.md`); cross-file duplicates removed and verbose sections compressed. New user-managed `04_conventions.md` seeded on init and updated via `append_to_file` migrations (UTC-only internals and No system Python moved from rules to conventions). `needs review`: 5 legacy built-in skills replaced by normalized workflow equivalents (`cleanup-code` → `simplify-code`, `continue-roadmap` → `complete-current-phase`, `find-issues` → `resolve-findings`, `fix-tests` → `repair-checks`, `update-roadmap` → `schedule-backlog`); 17 new skills added; 5 existing skills restructured. Migration manifest deletes 6 deprecated skill directories. New site docs for skills and skill design. | Run `al upgrade plan` then `al upgrade`. The upgrade renames instruction files automatically. If you have custom edits in `00_base.md`, `01_memory.md`, or `02_rules.md`, verify they transferred correctly after the rename. Review `04_conventions.md` after upgrade and remove any conventions that do not apply to your project. If you renamed or customized the deleted skills (`cleanup-code`, `continue-roadmap`, `find-issues`, `fix-tests`, `update-roadmap`, `mechanical-cleanup`), back them up before upgrading. | Migration manifest includes 3 `rename_file`, 2 `append_to_file`, and 6 `delete_file` operations. `04_conventions.md` is user-owned: seeded once, never overwritten, and excluded from upgrade plan diffs. New `append_to_file` migration kind supports duplicate-detection and atomic writes. |
| `v0.9.0` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Migration manifest support for `v0.9.0` includes canonical config-key migration (`agents.claude-vscode.enabled` -> `agents.claude_vscode.enabled`), required-field defaulting, legacy `.agent-layer/slash-commands/` -> `.agent-layer/skills/` rename, and automatic migration of all skills (built-in and user-authored) from flat format (`<name>.md`) to directory format (`<name>/SKILL.md`) with pre-flight conflict detection and user confirmation. Breaking-change metadata (`breaking_notice`, `breaking_details`) is now data-driven from the migration manifest. Upgrade output highlights readiness warnings and review-needed items in yellow for scanability. Unknown-file scanning now covers `docs/agent-layer/` in addition to `.agent-layer/`. Snapshot rollback accepts `created`-status snapshots for interrupted-upgrade recovery. New `CONTEXT.md` memory file template. `needs review`: [agentskills.io specification](https://agentskills.io/specification) alignment updates validation/normalization behavior (YAML frontmatter parsing, Unicode NFKC-aware name matching, rune-based limits, canonical `SKILL.md` naming). **Breaking:** Flat-format skills are no longer supported; all skills must use directory format after upgrading. | Run `al upgrade plan` then `al upgrade`. The upgrade will prompt to migrate any flat-format skills to directory format. If you have custom automation/scripts that still reference `.agent-layer/slash-commands/`, update them to `.agent-layer/skills/`. Use canonical `SKILL.md` naming (lowercase `skill.md` remains a compatibility fallback but triggers a warning). If you have custom files under `docs/agent-layer/` that are not memory file templates, the upgrade may prompt about them as unknown files. | Migration manifest includes one `config_rename_key`, one `config_set_default`, one directory rename, and one `migrate_skills_format` operation. Migration manifests now support `breaking`, `breaking_notice`, and `breaking_details` fields for data-driven breaking-change display. Flat-format skills (`<name>.md`) are no longer loaded; strict validation now catches malformed names/metadata earlier. |
| `v0.8.8` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Canonicalized Claude VS Code config key naming to snake_case (`agents.claude_vscode.enabled`), strengthened release/docs contract checks, and hardened stable-release docs publishing/version retention behavior. | No manual action required; run `al upgrade plan` then `al upgrade`. If any custom automation or docs still reference `agents.claude-vscode.enabled`, update them to `agents.claude_vscode.enabled`. | Migration manifest includes `config_rename_key` (`agents.claude-vscode.enabled` -> `agents.claude_vscode.enabled`) and `config_set_default` (`agents.claude_vscode.enabled = false`) to keep required-field invariants intact. |
| `v0.8.7` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Added quiet-mode support across runtime surfaces (`warnings.noise_mode = "quiet"` and one-off `--quiet`/`-q` client flags), plus wizard/config hardening and diff UX improvements: Escape back-navigation with first-step exit confirmation, explicit wizard section ordering policy, profile warning when replacing TOML-corrupt config, Claude reasoning-effort support (`low|medium|high`) with fail-loud model validation, explicit Gemini reasoning-effort unsupported-path errors, multiline TOML patch maintainability refactor, and colorized interactive upgrade diffs (plain-text fallback preserved). | No manual action required; run `al upgrade plan` then `al upgrade`. Optionally set `warnings.noise_mode = "quiet"` or use `al <client> --quiet` for one-off runs. Optionally set `[agents.claude] reasoning_effort = "low|medium|high"` when using supported Claude models. | No migration operations required. Existing configs remain valid. `noise_mode` now accepts `quiet`; new required-field migration guardrail test enforces future `config_set_default` parity for required fields introduced after baseline `0.8.1`. |
| `v0.8.6` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Fixed `.gitignore` template where inline comments on `/.claude/` and `/.claude-config/` patterns caused Git to treat them as literal pattern text, leaving both directories unignored. `al wizard` now prompts for opt-in repo-local Claude settings and caches isolation (`local_config_dir`). Documentation now clarifies that Claude auth remains globally shared due to an upstream credential-store limitation. | No manual action required; run `al upgrade plan` then `al upgrade`. Users who installed v0.8.5 in a new repo should verify `.claude/` is gitignored after upgrading. | No config schema changes. Template hash will change due to the gitignore fix. |
| `v0.8.5` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Consolidated release that includes strict unknown-key config validation, improved `.env` parsing, deterministic MCP tool-collision warnings, Gemini trusted-folder auto-write behavior, snapshot validation for zero-byte files, `al upgrade rollback --list`, agent-specific Claude/Codex passthrough config (`agents.<agent>.agent_specific`), opt-in repo-local Claude config isolation (`agents.claude.local_config_dir`), and hardened prompt-server dispatch/root validation for `al mcp-prompts`. | No manual action required; run `al upgrade plan` then `al upgrade`. Optionally enable new behavior by setting `local_config_dir = true` and/or adding `agent_specific` keys under Claude/Codex agent sections. | No migration operations are required. If Gemini trust-file writes fail, sync still completes and emits a warning with manual trust guidance. Config schema is unchanged. |
| `v0.8.4` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Config validation now silently strips transport-incompatible MCP fields instead of erroring. Version dispatch diagnostic no longer prints twice during version-pinned dispatch. Wizard config patching handles dotted sub-key removal. New scenario-based e2e test framework (internal). | No manual action required; run `al upgrade plan` then `al upgrade`. | No config schema changes. Configs that previously failed validation due to leftover transport-incompatible fields (e.g., `headers` on a stdio server) will now load successfully. |
| `v0.8.3` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Bug fixes only. `al doctor` no longer produces false "missing environment variables" warnings for MCP servers that reference built-in variables like `${AL_REPO_ROOT}`. `al wizard` now removes transport-incompatible fields (e.g., `headers` on stdio servers) during config patching, fixing a circular error where the wizard completed but sync failed. | No manual action required; run `al upgrade plan` then `al upgrade`. | No config schema changes. |
| `v0.8.2` | `0.8.x`, `0.7.x` (via migration chaining) | `safe auto`: Migration manifests are now chained during multi-version upgrades. Users jumping from 0.8.0 directly to 0.8.2 will now receive the `agents.claude-vscode.enabled` config prompt that was introduced in v0.8.1. Config resilience improvements ensure `al wizard`, `al doctor`, and `al upgrade` always work even on broken configs. Removed slash command `auto-approve` frontmatter; approval permissions are controlled entirely by `approvals.mode`. Slash command frontmatter now rejects unrecognized keys. | No manual action required; run `al upgrade plan` then `al upgrade`. If any custom slash commands contain `auto-approve` or other non-`description` frontmatter keys, remove them before upgrading. | Migration chaining loads all intermediate manifests between source and target versions. When source version is unknown, only the target manifest is loaded (backward compatible). |
| `v0.8.1` | `0.8.x` | `safe auto`: Added `[agents.claude-vscode]` config section for Claude Code VS Code Extension support. Added `approvals.mode = "yolo"` for maximum agent autonomy in sandboxed environments. `al vscode` now launches when either `[agents.vscode]` or `[agents.claude-vscode]` is enabled. | No manual action required; run `al upgrade plan` then `al upgrade`. If you use `[agents.vscode]` only (without `[agents.claude-vscode]`), behavior is unchanged. If you want Claude Code VS Code Extension support, add `[agents.claude-vscode]` with `enabled = true` to `config.toml`. | `CODEX_HOME` is now cleared from the VS Code process environment when `[agents.vscode]` is disabled, preventing stale Codex config leakage. |
| `v0.8.0` | `0.7.x` | `breaking/manual`: `al init` is now one-time scaffolding and no longer supports upgrade/repair; `al init --overwrite` and `al init --force` removed. `needs review`: `al upgrade` no longer supports a single destructive `--force` mode and now requires explicit apply categories. `safe auto`: `al upgrade` now creates automatic managed-file snapshots, auto-rolls back on upgrade-step failures, and supports manual restore via `al upgrade rollback <snapshot-id>`. | Replace any automation that runs `al init --force` or `al upgrade --force` with explicit apply flags (for example `al upgrade --yes --apply-managed-updates`). Include `--apply-memory-updates` and/or `--apply-deletions` only when intentionally applying those categories. For interactive flows, run `al upgrade plan` then `al upgrade`. Use `al upgrade rollback <snapshot-id>` only when you need to restore a previously applied snapshot. | `al upgrade` never overwrites `.agent-layer/.env` or `.agent-layer/config.toml`. Root `.gitignore` managed block is still updated automatically and is excluded from upgrade plans. Snapshots are stored under `.agent-layer/state/upgrade-snapshots/`. |
| `v0.7.0` | `0.6.x` | `breaking/manual`: Windows support removed (installer, launcher, release targets, code paths). `safe auto`: upgrade path hardening (pin recovery, init dispatch bypass, download progress/errors), upgrade contract published. | **Windows users:** Windows is no longer supported; remove `al-install.ps1` and `open-vscode.bat` if present and migrate to macOS or Linux. **All other users:** No manual action required; run `al upgrade plan` and `al upgrade`. | First release with published upgrade contract. |

Migration execution rules for supported release-line upgrades:
- Each supported target release ships an embedded migration manifest at `internal/templates/migrations/<target>.json`, including `min_prior_version`.
- `al upgrade` executes migration operations before template writes and emits a deterministic migration report.
- If source version resolution fails, source-agnostic operations still run; source-gated operations are skipped and reported.
- `.agent-layer/.env` is namespace-scoped: only keys prefixed with `AL_` are loaded. Non-`AL_` keys are ignored and there is no env-key migration path.

How this table is maintained:
- Add or update a row for every release.
- If a release includes `breaking/manual` items, list exact required actions.
- If no special migration is needed, keep the row explicit to avoid ambiguity.

## Documentation version retention and access

Agent Layer website docs are versioned per release, then retained with a bounded policy to keep the published set stable and small:

1. Keep the newest 4 patch releases from the newest minor line.
2. Keep the newest patch release for each of the newest 4 minor lines (including the newest minor line).
3. Keep stable releases only (prereleases are dropped).
4. Keep the union of both sets in newest-first order.

How to access older docs:

1. Use the docs version selector in the website navigation to switch between retained versions.
2. If a version is not listed there, it has been pruned from the hosted site by retention policy.
3. For pruned versions:
   - Use the [Changelog](/changelog) for release-level historical behavior.
   - Browse source docs at the matching tag in the main repo:
     - `https://github.com/conn-castle/agent-layer/tree/vX.Y.Z/site/docs`

### Ownership baseline and manifest policy

Upgrade ownership classification is deterministic and offline:

- Release manifests are committed in-repo under `internal/templates/manifests/<version>.json`.
- Backfill manifests are committed for `v0.6.0`, `v0.6.1`, and `v0.7.0`.
- New releases must add a manifest for the new tag as part of release prep.
- Runtime upgrade planning does not call GitHub/tag APIs to infer ownership.

Repo-local baseline state is stored at:

- `.agent-layer/state/managed-baseline.json`

`al upgrade plan` compares local files against baseline evidence plus embedded manifests and emits `unknown_no_baseline` when ownership cannot be proven safely.

## OS and shell capability matrix

Windows is not supported.

| Surface | macOS | Linux | Notes |
| --- | --- | --- | --- |
| Install via Homebrew | Supported | Supported | Requires Homebrew setup for platform. |
| Install via `al-install.sh` | Supported | Supported | Requires `curl` and `sha256sum` or `shasum`. |
| `al` CLI core commands | Supported | Supported | Includes `init`, `upgrade`, `sync`, `doctor`, client launch commands. |
| VS Code launchers | Supported | Supported | macOS: `.app`/`.command`; Linux: `.desktop`/`.sh`. |
| Shell completion: `bash` | Supported | Supported | `al completion bash --install`. |
| Shell completion: `zsh` | Supported | Supported | `al completion zsh --install`; may require `fpath` setup. |
| Shell completion: `fish` | Supported | Supported | `al completion fish --install`. |

## Commitment level and limitations

This contract is intended to be explicit without over-promising:

- We commit to best-effort adherence to this model and guarantee scope.
- If we cannot fully meet a guarantee in a specific release, we will document the limitation clearly in release notes and migration guidance.
- When in doubt, prefer explicit communication over silent assumptions.
