---
title: Reference
description: Configuration, environment variables, and CLI behavior.
sidebar_position: 3
---

This page is the authoritative reference for configuration, environment variables, and the `al` CLI. It is written for the moments when you want certainty: configuring a repo, debugging a launch, or reviewing what `al` will change.

If you are setting up Agent Layer for the first time, start with [Getting started](./getting-started).
For upgrade policy commitments (event model, guarantees, migration rules, and platform matrix), use [Upgrades](./upgrades).

Agent Layer is explicit by design. It prefers failing fast over guessing, and it treats generated files as disposable outputs rather than hand-maintained sources. When you need to know exactly what will change on disk, this is the contract.

## In this page

- [Configuration](#configuration)
- [Environment variables](#environment-variables)
- [CLI guide](#cli-guide)

## Configuration

`.agent-layer/config.toml` is the primary structured configuration file. It is the single source of truth for approvals, agents, MCP servers, and warning thresholds. If you treat one file as the contract, make it this one—everything else is derived from it.

`al wizard` updates `config.toml` and `.agent-layer/.env`. Everything else is edited by hand.

Most repos only need a few deliberate choices: pick an approvals mode, enable the agents you actually use, and add MCP servers one at a time. The file is validated on every run, so mistakes surface immediately instead of becoming “mystery behavior” later.

:::caution
Never put secrets in `config.toml`. Secrets belong in `.agent-layer/.env`.
:::

### Example

```toml
[approvals]
# one of: "all", "mcp", "commands", "none", "yolo"
mode = "all"

[agents.antigravity]
enabled = true

[agents.claude]
enabled = true
# model = "..."
# reasoning_effort is optional for Opus models only.
# reasoning_effort = "medium" # low | medium | high | xhigh | max (custom values pass through with a warning)
# local_config_dir isolates Claude Code settings and caches per repo.
# When true, al claude sets CLAUDE_CONFIG_DIR=<repo>/.claude-config.
# For al vscode, CLAUDE_CONFIG_DIR is set only when both local_config_dir
# and agents.claude_vscode are enabled. Otherwise, al vscode clears only
# stale repo-local values and preserves user-defined non-repo values.
# Note: auth is stored globally by Claude Code in the OS credential store
# (macOS Keychain service "Claude Code-credentials"; Linux libsecret/gnome-keyring)
# regardless of this setting (upstream limitation).
# local_config_dir = false
# Optional agent-specific passthrough config for Claude (arbitrary JSON keys).
# Object values are deep-merged into .claude/settings.json; arrays and scalar values are replaced at their key.
# Overlapping managed keys, such as permissions.allow, override Agent Layer-managed
# values and trigger a sync warning. permissions.deny is additive and does not warn.
# [agents.claude.agent_specific]

[agents.claude_vscode]
enabled = true

[agents.codex]
enabled = true
# model is optional; when omitted, Agent Layer does not pass a model setting and the client uses its default.
# model = "gpt-5.3-codex"
# reasoning_effort is optional; when omitted, the client uses its default.
# reasoning_effort = "xhigh" # codex only
# Optional agent-specific passthrough config for Codex (arbitrary TOML tables/keys).
# These are appended to .codex/config.toml and can override top-level managed keys.
# Agent Layer already writes [projects."<repo root>"] trust_level = "trusted".
# [agents.codex.agent_specific]
# [agents.codex.agent_specific.features]
# apps = false              # disable built-in Codex apps (Github, Gmail, etc.) to reduce tool surface
# multi_agent = true
# prevent_idle_sleep = true

[agents.vscode]
enabled = true

[agents.copilot_cli]
enabled = true
# model is optional; when omitted, the client uses its default.
# model = "..."
# reasoning_effort is not currently supported for Copilot CLI in Agent Layer.

[mcp]
# MCP servers are external tool servers projected into client configs.

[[mcp.servers]]
id = "filesystem"
enabled = false
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem@2026.1.14", "${AL_REPO_ROOT}"]

[warnings]
# Optional thresholds for warning checks. Omit or comment out to disable.
# Warn when a newer Agent Layer version is available during sync runs.
version_update_on_sync = true
# Warning output noise control: "default" keeps all warnings, "reduce" hides suppressible non-critical warnings,
# and "quiet" suppresses agent-layer informational output (warnings still print in `al doctor`).
noise_mode = "default"
instruction_token_threshold = 10000
mcp_server_threshold = 15
mcp_tools_total_threshold = 60
mcp_server_tools_threshold = 25
mcp_schema_tokens_total_threshold = 30000
mcp_schema_tokens_server_threshold = 20000
```

Agent-specific passthrough keys in `agents.codex.agent_specific` or `agents.claude.agent_specific` override Agent Layer-managed keys when they collide. Agent Layer emits a warning on every sync if you override managed keys. Codex project trust is managed automatically for the current absolute repo root. Claude `permissions.deny` is the one exception: it is deep-merged additively into `.claude/settings.json` and does not warn.

### Sections at a glance

| Section | Purpose |
| --- | --- |
| `[approvals]` | auto-approval policy for commands and MCP tools |
| `[agents.*]` | enablement and model selection per client |
| `[[mcp.servers]]` | external MCP server definitions |
| `[warnings]` | optional thresholds for token and server limits, plus sync update warnings |

### Approvals

`[approvals]` controls auto-approval behavior.

### Agents

Each agent has an `enabled` flag and optional `model` value. Claude supports `reasoning_effort` (`low`, `medium`, `high`, `xhigh`, `max`) for Opus models; `max` is session-only and is passed via the `--effort` CLI flag (it is not written to settings.json). Custom values outside the catalog pass through with a sync-time warning so new effort levels work before agent-layer is updated. Codex supports `reasoning_effort` with its own set of options. Copilot CLI supports `model` but not `reasoning_effort`. Omit `reasoning_effort` (and `model`) to use the client defaults. Claude also supports `local_config_dir` (boolean, default `false`); when `true`, `al claude` sets `CLAUDE_CONFIG_DIR` to a repo-local directory for per-repo settings and caches isolation. Note: auth credentials are stored globally by Claude Code in the OS credential store (macOS Keychain service `"Claude Code-credentials"`; Linux libsecret/gnome-keyring) regardless of this setting (upstream limitation). For `al vscode`, `CLAUDE_CONFIG_DIR` is set only when both `local_config_dir` is `true` and `agents.claude_vscode` is enabled; otherwise `al vscode` clears only stale repo-local values and preserves user-defined non-repo values.

Supported agents:

- `antigravity`
- `claude`
- `claude_vscode`
- `codex`
- `vscode`
- `copilot_cli`

### MCP servers

Each `[[mcp.servers]]` entry must include:

- `id`
- `enabled`
- `transport` (`http` or `stdio`)

Optional fields:

- `clients` to restrict which clients receive a server (valid values: `antigravity`, `claude`, `vscode`, `codex`, `copilot`; note that `claude_vscode` uses the `claude` client)
- `http_transport` (`sse` or `streamable`) for HTTP servers
- `headers` for HTTP auth and metadata
- `command`, `args`, `env` for stdio servers

#### Secrets, placeholders, and client projection

Agent Layer is designed to keep secrets out of your canonical config and out of any files you might commit:

- Put secrets in `.agent-layer/.env` (only `AL_`-prefixed variables are loaded).
- Reference secrets in `config.toml` using placeholders like `${AL_GITHUB_TOKEN}`.
- Let `al sync` project those placeholders into each client's supported format.

Agent Layer never writes resolved secret values back into `config.toml`. Generated client outputs are treated as build artifacts, and some clients require concrete values in their own config formats. When that happens, those outputs are gitignored by default.

Here is how placeholder projection works for MCP servers:

| Client | Placeholder syntax in generated config |
| --- | --- |
| Claude Code (`.mcp.json`) | `${AL_TOKEN}` |
| Antigravity (`.agy/antigravity-cli/mcp_config.json`) | `${AL_TOKEN}` |
| VS Code (`.vscode/mcp.json`) | `${env:AL_TOKEN}` |
| Codex (`.codex/config.toml`) | headers become env-var references; URLs/commands/args/env values are resolved because Codex does not support placeholders |
| Copilot CLI (`.copilot/mcp-config.json`) | `${AL_TOKEN}` (env vars resolved at runtime by the client) |

Practical guidance:

- Prefer secrets in headers (`headers = { Authorization = "Bearer ${AL_TOKEN}" }`) over secrets in URLs.
- For maximum portability, keep non-Authorization secret headers as exact placeholders (for example `"X-Api-Key" = "${AL_API_KEY}"`), not mixed into longer strings.
- Some services use API keys in URLs (for example the seeded Tavily template). In that case, remember clients like Codex may require a fully resolved URL and will write it only into gitignored outputs.

#### HTTP example

```toml
[[mcp.servers]]
id = "example-api"
enabled = true
transport = "http"
url = "https://example.com/mcp"
headers = { Authorization = "Bearer ${AL_EXAMPLE_TOKEN}" }
```

#### Stdio example

```toml
[[mcp.servers]]
id = "ripgrep"
enabled = true
transport = "stdio"
command = "npx"
args = ["-y", "mcp-ripgrep@0.4.0"]
```

### Warnings

Warning thresholds are optional. When a threshold is omitted, its warning is disabled. All values must be positive integers.

Warnings are used by:

- `al sync` for instruction token thresholds (and optional update warnings)
- `al doctor` for MCP server and schema thresholds

Warning output now includes source and severity labels so operators can distinguish internal/config issues from network or external-dependency issues.

Set `version_update_on_sync = true` to opt in to update warnings during `al sync` and `al <client>`; omit it or set it to `false` to keep update warnings limited to `al init`, `al doctor`, and `al wizard`.

Set `noise_mode` to control warning verbosity:

- `default`: keep all warnings (recommended)
- `reduce`: hide only suppressible non-critical warnings
- `quiet`: suppress agent-layer informational output (warnings still print in `al doctor`)

### Validation rules

Agent Layer validates `config.toml` on every run. Common validation rules:

- `approvals.mode` must be one of `all`, `mcp`, `commands`, `none`, `yolo`
- `enabled` flags must be set for all agents and MCP servers
- MCP transport must be `http` or `stdio`
- `http_transport` (when set) must be `sse` or `streamable`
- HTTP servers cannot set `command` or `args`
- Stdio servers cannot set `url` or `headers`

## Environment variables

Agent Layer uses a small set of environment variables for versioning and offline behavior. It also loads secrets from `.agent-layer/.env`.

This surface area is intentionally small. Configuration should live in the repo where it can be reviewed, while environment variables act as escape hatches for CI, offline work, and temporary overrides.

### Versioning and cache

| Variable | Purpose |
| --- | --- |
| `AL_VERSION` | force a version (overrides the repo pin) |
| `AL_NO_NETWORK` | disable update checks and downloads |
| `AL_CACHE_DIR` | override the pinned-version cache directory |

These variables only affect version dispatch, update checks, and downloads. They do not disable MCP server networking.

For supported upgrade paths and release-line compatibility guarantees, see [Upgrades](./upgrades#compatibility-guarantees).

:::caution Known issue in v0.6.0 and earlier
In versions 0.6.0 and earlier, the internal `AL_SHIM_ACTIVE` environment variable can leak into VS Code's integrated terminal when launching via `al vscode`. This causes subsequent `al` commands in that terminal to fail with:

```
version dispatch already active (current X.Y.Z, requested A.B.C)
```

**Workaround:** Clear the `AL_SHIM_ACTIVE` environment variable in the affected terminal before running `al` commands:
- `bash`/`zsh`: `unset AL_SHIM_ACTIVE`

This issue is fixed in v0.6.1 and later, where `AL_SHIM_ACTIVE` is automatically stripped from child process environments.
:::

### Secrets from `.agent-layer/.env`

Only variables prefixed with `AL_` are loaded from `.agent-layer/.env`.

Rules:

- Your existing process environment takes precedence
- Empty values in `.env` are ignored
- `.env` is always gitignored

Example:

```env
AL_CONTEXT7_API_KEY=your-key-here
AL_TAVILY_API_KEY=your-key-here
# Optional: only when using a GitHub MCP server
AL_GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here
```

### Built-in placeholder

`${AL_REPO_ROOT}` is a built-in placeholder for the absolute repo root. Use it in MCP server command arguments or paths when you want runtime expansion.

Example:

```toml
[[mcp.servers]]
id = "filesystem"
enabled = true
transport = "stdio"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem@2026.1.14", "${AL_REPO_ROOT}"]
```

## CLI guide

The `al` CLI syncs repo-local configuration and launches your chosen client. This section focuses on behavior, safety, and the files each command touches. Use it as a runbook when you want to know exactly what a command will change. For exact flags, run `al --help` or `al <command> --help`.

The command surface is intentionally small. Most of the time you only need one rhythm: `al init` once, `al <client>` every day, `al doctor` when something feels off.

### Command map

| Command | Purpose |
| --- | --- |
| `al init` | Initialize a repo with Agent Layer templates and memory files. |
| `al upgrade` | Apply template-managed updates and update the repo pin (interactive by default; non-interactive requires `--yes` plus one or more apply flags; line-level diff previews shown by default, configurable with `--diff-lines`). |
| `al upgrade plan` | Show a dry-run, plain-language categorized upgrade plan with line-level diff previews (configurable with `--diff-lines`). |
| `al upgrade prefetch` | Download and cache a release binary ahead of time (use `--version X.Y.Z` explicitly on dev builds). |
| `al upgrade rollback --list` | List available upgrade snapshot IDs and statuses before rollback. |
| `al upgrade rollback <snapshot-id>` | Restore an applied upgrade snapshot by ID (snapshot IDs are JSON filename stems under `.agent-layer/state/upgrade-snapshots/`). |
| `al upgrade repair-gitignore-block` | Restore `.agent-layer/gitignore.block` from templates and reapply the root `.gitignore` managed block. |
| `al wizard` | Interactive configuration plus profile mode (`--profile`) and backup cleanup (`--cleanup-backups`). |
| `al sync` | Regenerate client configs without launching a client. |
| `al <client>` | Sync and launch a client (agy/claude/codex/copilot/vscode). |
| `al probe agy` | Run the Antigravity capability probe and print JSON. |
| `al doctor` | Validate configuration and probe enabled MCP servers. |
| `al completion` | Print or install shell completions (bash/zsh/fish). |
| `al --version` | Print the installed Agent Layer version. |
| `al help` | Show help for any command. |

### Init

`al init` sets up Agent Layer in a repository.

If `.agent-layer/` already exists, `al init` errors; use `al upgrade plan` and `al upgrade` instead.

It is scaffolding: it creates the files that make behavior explicit and repeatable, so day-to-day work becomes “edit the source of truth, regenerate outputs,” not “hunt for the right config format.”

**What it does**

- Creates `.agent-layer/` (configuration, instructions, approvals, MCP servers)
- Creates `docs/agent-layer/` (project memory files)
- Installs a managed `.gitignore` block

**Steps (high level)**

1. Creates required directories.
2. Writes template-managed files under `.agent-layer/` and `docs/agent-layer/` (seeds user-owned files only when missing).
3. Adds or updates the managed `.gitignore` block.
4. If running interactively, prompts to run the wizard unless `--no-wizard` is set.

**Files and directories it touches**

Typical `.agent-layer/` files include:

- `config.toml` (seeded if missing; user-owned), `commands.allow`, `instructions/`, `skills/`
- `al.version` (repo pin; required)
- `.env` (seeded if missing; user-owned secrets, always gitignored)
- `.gitignore` (internal ignores) and `gitignore.block` (root `.gitignore` template)
- `.agent-layer/state/managed-baseline.json` (managed ownership baseline state; gitignored)

**Gitignore template**

`.agent-layer/gitignore.block` is the template file. It must contain only ignore patterns and comments (no managed markers and no template hash). Agent Layer copies it verbatim and injects the managed header and template hash only when updating the root `.gitignore`. If the template file contains managed markers or a hash line, `al sync` will error; run `al upgrade` to restore the template file.

Typical project memory files under `docs/agent-layer/`:

- `ISSUES.md`, `BACKLOG.md`, `ROADMAP.md`, `DECISIONS.md`, `COMMANDS.md`, `CONTEXT.md`

**Wizard prompt**

By default, `al init` prompts to run the setup wizard after seeding files. Use `--no-wizard` to skip it.
In non-interactive environments, the wizard is skipped.

**Version pinning and network**

- If you are running a release build, `al init` writes `.agent-layer/al.version`.
- You can set the initial pin explicitly with `--version X.Y.Z` (or `--version latest`).
- `.agent-layer/al.version` is required for supported usage. If it is missing or invalid, run `al upgrade` to repair it.
- Pin file parsing ignores blank lines and `#` comments, and expects exactly one version line.
- If the pin file is empty, invalid, or contains multiple version lines, dispatch warns and falls back to the current CLI version; run `al upgrade` to rewrite a valid pin.
- Update checks and pinned downloads require network access unless `AL_NO_NETWORK=1` is set.
- For upgrade contract details and release-versioned migration notes, see [Upgrades](./upgrades).

### Upgrade

`al upgrade` applies template-managed updates in an existing repo.

**What it does**

- Updates `.agent-layer/al.version` to match the currently running `al` binary
- Prompts before overwriting managed template files unless apply flags are explicitly selected
- Shows a compact per-file summary (path with `+N -M` line stats) before overwrite decisions, and asks "View the full diff?" (default no) before printing unified diff bodies; per-file overwrite prompts always render the full diff
- Runs `al sync` automatically after a successful upgrade so retired projection paths and freshly-introduced templates are reconciled (sync warnings surface on stderr; sync failures are wrapped and suppress the success banner)
- In the default interactive flow, prompts about unknown files under `.agent-layer/` and `docs/agent-layer/` and only deletes them if you explicitly approve
- In non-interactive or explicit-category apply (e.g., `--yes --apply-managed-updates`), requires the separate `--apply-deletions` flag before unknown files outside `.agent-layer/tmp/` are eligible for deletion
- **Treats `.agent-layer/tmp/` as protected ephemeral storage:** files under that directory are never deleted by `--apply-deletions`, never bulk-deleted by the interactive "delete all unknowns?" prompt, and never restored by rollback. Tmp deletion requires either an interactive double-confirm or the dedicated `--apply-tmp-deletions` flag (in addition to `--yes`). See [Ephemeral artifacts under .agent-layer/tmp/](#ephemeral-artifacts-under-agent-layertmp)
- Never overwrites `.agent-layer/config.toml` or `.agent-layer/.env`
- Creates an automatic snapshot for managed upgrade targets and auto-rolls back if an upgrade step fails
- Stores snapshots under `.agent-layer/state/upgrade-snapshots/`
- **Snapshots exclude `.agent-layer/tmp/`** — ephemeral run artifacts there can total hundreds of MB and would balloon snapshot size with no rollback benefit
- Supports snapshot discovery and manual restore via `al upgrade rollback --list` and `al upgrade rollback <snapshot-id>`

Use `--diff-lines N` to raise the per-file diff preview cap (default: 40 lines).
For a concise team/CI runbook, see [Upgrade checklist](./upgrade-checklist).

### Upgrade apply flags

| Flag | Effect |
| --- | --- |
| `--yes` | Run non-interactively. Requires at least one apply flag below. |
| `--apply-managed-updates` | Apply managed template updates without prompts. |
| `--apply-memory-updates` | Apply updates to memory files under `docs/agent-layer/`. |
| `--apply-deletions` | Apply deletions of unknown files **outside** `.agent-layer/tmp/`. Has no effect on tmp content. |
| `--apply-tmp-deletions` | Apply destructive deletion of files **under** `.agent-layer/tmp/`. Required (in addition to `--yes`) for any non-interactive tmp deletion. |

`--apply-deletions` and `--apply-tmp-deletions` are independent. Pass both to delete every unknown file non-interactively; pass either alone to scope deletions to one bucket.

### Ephemeral artifacts under .agent-layer/tmp/

`.agent-layer/tmp/` is the canonical scratch directory for agent run artifacts (plans, reports, scratch dumps, intermediate logs). Contents are ephemeral by design — agents are instructed to delete artifacts when no longer needed, and Agent Layer tooling treats the directory as low-value, high-volume state.

Because tmp can balloon to hundreds of MB across many runs, Agent Layer applies stricter rules than for other unknown files:

**Snapshots do not capture tmp.** When `al upgrade` creates a pre-upgrade snapshot under `.agent-layer/state/upgrade-snapshots/`, files under `.agent-layer/tmp/` are excluded. Snapshots stay small and a corrupted tmp file cannot make a snapshot unreadable.

**Rollback does not restore tmp.** `al upgrade rollback <snapshot-id>` will not recreate any tmp file the user deleted during the upgrade. If you need to preserve a specific in-progress agent artifact, copy it out of `.agent-layer/tmp/` before running `al upgrade`.

**Interactive deletion requires a destructive double-confirm.** When the upgrade prompt asks `Delete all N file(s) under .agent-layer/tmp/?`, the default is **no**. Answering `y` triggers a second confirmation: `DESTRUCTIVE: deleting .agent-layer/tmp/ permanently removes ephemeral agent run artifacts and may impact ongoing work. Are you absolutely sure?` — also defaulting to `no`. Both prompts must be answered yes to delete tmp content. The "delete all unknowns?" prompt at the top of the unknowns flow does NOT cover tmp; the grouped tmp prompt always fires regardless of how the user answered the top-level prompt.

**Non-interactive deletion requires a separate flag.** `al upgrade --yes --apply-deletions` will delete other unknowns but **leaves tmp untouched** and prints `Info: skipping deletions under .agent-layer/tmp/ (pass --apply-tmp-deletions to include them; this is destructive and may impact ongoing agent work)`. To wipe tmp non-interactively, pass `--apply-tmp-deletions` explicitly:

```bash
al upgrade --yes --apply-deletions --apply-tmp-deletions
```

Use this only when you are sure no agent run artifacts you care about live under `.agent-layer/tmp/`.

### Upgrade rollback

`al upgrade rollback <snapshot-id>` restores a previously applied managed-file snapshot.

- `al upgrade rollback --list` shows available snapshot IDs and statuses
- Snapshot IDs are the `.json` filename stems in `.agent-layer/state/upgrade-snapshots/`
- Only snapshots in `applied` status are rollback-eligible
- Rollback fails loudly when a snapshot is missing, malformed, or non-rollbackable
- Rollback does **not** restore `.agent-layer/tmp/`. Snapshots intentionally exclude tmp content; if you need to keep in-progress agent artifacts, copy them out of `.agent-layer/tmp/` before upgrading.

### Upgrade prefetch

`al upgrade prefetch` downloads and verifies a release binary into the local Agent Layer cache without applying template updates.

- Use it to pre-warm CI runners or offline environments.
- In release builds, it defaults to the currently running `al` version.
- In dev builds, pass `--version X.Y.Z` explicitly.

### Repair gitignore block

`al upgrade repair-gitignore-block` restores `.agent-layer/gitignore.block` to the embedded template and reapplies the root `.gitignore` managed block.

Use this when `.agent-layer/gitignore.block` is invalid (for example it accidentally includes managed markers or template-hash lines).

### Upgrade plan

`al upgrade plan` is a read-only upgrade preview. It does not write files.

It compares your repository state against templates embedded in the currently running `al` binary (not an older repo-pinned binary).

Use it before `al upgrade` to understand what would change:

- Template additions
- Template updates
- Template renames (heuristic, confidence-annotated)
- Template removals/orphans
- Config key migrations (when migration manifests are present)
- Pin version change (`current -> target`)
- Readiness checks (for example unresolved placeholders, process-env vs `.env` collisions, ignored empty `.env` assignments, path-expansion anomalies, stale VS Code `--no-sync` outputs, floating dependency specs, and stale disabled-agent artifacts)

`al upgrade plan` also includes line-level diff previews for changed files. Use `--diff-lines N` to raise the per-file diff preview cap (default: 40 lines).

Each diff preview still carries internal ownership metadata (`upstream template delta`, `local customization`, `mixed upstream and local`, `unknown no baseline`) used by upgrade decision logic, but `al upgrade plan` text output intentionally hides ownership diagnostics.

`al upgrade plan` supports plain-language text output only.

### Wizard

`al wizard` guides you through approvals, enabled agents, model selection, MCP servers, and warning thresholds.

Use it when you want to get to a safe, working configuration quickly, or when you would rather answer questions than hand-edit TOML.

**What it edits**

- `.agent-layer/config.toml`
- `.agent-layer/.env`

The wizard rewrites `config.toml` in a deterministic preferred section order and creates backups (`.bak`) before modifying `.agent-layer/config.toml` or `.agent-layer/.env`. Inline comments on modified lines may be moved to leading comments or removed; the original formatting is preserved in the backup files.

Additional modes:

- `al wizard --profile /path/to/profile.toml`: preview-only profile rewrite diff
- `al wizard --profile /path/to/profile.toml --yes`: apply profile and run sync
- `al wizard --cleanup-backups`: delete `.agent-layer/config.toml.bak` and `.agent-layer/.env.bak`

**Navigation**

- **Arrow keys**: Navigate options
- **Space / x**: Toggle selection (multi-select steps)
- **Enter**: Confirm and continue
- **Esc**: Go back to the previous step (on the first step, prompts to exit)
- **Ctrl+C**: Exit immediately without saving changes

Secret prompt controls:

- `skip`: disable the current default MCP server for this run
- `cancel`: exit without applying changes

It is safe to re-run when you want to revisit settings.

### Sync

`al sync` regenerates client configs from `.agent-layer/` without launching a client.

Think of sync as a build step. You can run it any time you want to refresh generated outputs without starting a client.

**What it does**

- Validates `.agent-layer/config.toml`
- Reads `.agent-layer/instructions/`, `.agent-layer/skills/`, `.agent-layer/commands.allow`, and `.agent-layer/.env`
- Regenerates client outputs and launchers

**Steps (high level)**

1. Load and validate `config.toml`, then resolve secrets from `.agent-layer/.env`.
2. Parse instructions and skills to build client-specific outputs.
3. Write generated configs and launchers for enabled clients.
4. Emit warnings if any thresholds in `[warnings]` are exceeded.

**Skill format**

Skill sources align with the [agentskills.io specification](https://agentskills.io/specification), with explicit backward-compatibility behavior documented below.

`.agent-layer/skills/` uses directory format:

- `.agent-layer/skills/<name>/SKILL.md` (canonical; lowercase `skill.md` is accepted as a compatibility fallback)

Frontmatter fields:

- Required: `name`, `description`
- Optional: `license`, `compatibility`, `metadata`, `allowed-tools`

Validation notes (`al doctor`):

- Name checks are NFKC-normalized and normalization-aware when matching `name` to the canonical source name.
- Name limits: max 64 Unicode characters, lowercase letters/digits/hyphens only, no leading/trailing/consecutive hyphens.
- Description limit: max 1024 Unicode characters.
- Compatibility limit (when present): max 500 Unicode characters.
- Size recommendation: `al doctor` warns when a skill source exceeds 500 lines.
- Missing `name` remains load-compatible (name is derived from path), but `al doctor` warns.
- Missing or empty `description` fails load/sync (fail-loud).
- Directory skills using lowercase `skill.md` load for compatibility, but `al doctor` warns to use canonical `SKILL.md`.

Example:

```md
---
name: code-audit
description: Run a code quality audit.
---
# Your command body here
```

**Generated outputs**

Common outputs include:

- `.agents/skills/`
- `.agy/antigravity-cli/settings.json`, `.agy/antigravity-cli/mcp_config.json`, `.claude/settings.json`, `.claude/skills/`, `.mcp.json`
- `.codex/` (generated config and rules)
- `.copilot/mcp-config.json`
- `.vscode/mcp.json` and a managed block in `.vscode/settings.json`
- `.github/copilot-instructions.md`
- `AGENTS.md`, `CLAUDE.md`
- repo-local VS Code launchers under `.agent-layer/` when VS Code is enabled (for example `open-vscode.command`, `open-vscode.sh`, and `open-vscode.app/`)

These files are derived outputs and safe to delete. Running `al sync` will recreate them.

**Warnings**

`al sync` evaluates instruction token thresholds from `[warnings]` and emits warnings if they are exceeded. If `version_update_on_sync = true`, it also checks for a newer Agent Layer release.

### Launch a client

`al <client>` syncs before launch by default. Supported clients:

- `al agy`
- `al claude`
- `al codex`
- `al copilot`
- `al vscode`

These commands read `.agent-layer/`, regenerate client outputs, and then launch the selected client.

This is the default workflow for day-to-day use: you get a clean regenerate and a launch in one command, which keeps behavior consistent even when you switch tools.

`al <client>` forwards any extra arguments to the underlying client. If you need to use Agent Layer flags as well, place `--` before the client arguments. `--no-sync` is supported by `al vscode` and must appear before `--`. For an explicit false value, use `--no-sync=false` (space-separated values like `--no-sync false` are not supported and will be passed through).

`al vscode` preflight now fails fast with clear guidance when:

- `code` is missing on `PATH`
- `.vscode/settings.json` has a malformed managed block marker state

Examples:

```bash
al claude -- --help
al vscode --no-sync -- --reuse-window
```

### Doctor

`al doctor` validates configuration, checks for missing secrets, and probes enabled MCP servers.

Use it as your early warning system. It is the fastest way to answer “is my config valid,” “are my secrets present,” and “are my tools reachable.”

**What it does**

- Validates `.agent-layer/config.toml`
- Reports missing `AL_` secrets referenced by your config
- Connects to each enabled MCP server and lists tools
- Evaluates MCP warning thresholds from `[warnings]`
- Checks for newer releases and warns if you are behind

**Steps (high level)**

1. Validate configuration and resolve secrets from `.agent-layer/.env`.
2. Probe each enabled MCP server and collect tool metadata.
3. Compute warning thresholds and report any overages.
4. Check for release updates (unless networking is disabled).

**Timeouts and network**

- `al doctor` waits up to 30 seconds per enabled MCP server before timing out.
- It uses network access for MCP servers and update checks. Set `AL_NO_NETWORK=1` to disable update checks and pinned downloads.

### Completion

`al completion` prints shell completion scripts to stdout or installs them in the standard user location.

```bash
al completion zsh
al completion zsh --install
```

Supported shells: `bash`, `zsh`, `fish`.

### Help and version

```bash
al --help
al help <command>
al --version
```

Use these to confirm available commands, flags, and the installed version.
