Upgrades

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
• Upgrade event model
• Compatibility guarantees
• Migration rules by release
• Documentation version retention and access
• OS and shell capability matrix
• Commitment level and limitations
• 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 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.

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.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 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).
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 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.