> ## Documentation Index
> Fetch the complete documentation index at: https://ade-app.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration overview

> The `.ade/` directory, the shared-vs-local trust model, and what stays out of Git.

ADE keeps project state local. Everything ADE creates for a project lives under `.ade/` at the repository root, alongside your source tree but outside Git's control. Your code stays under normal version control; ADE's runtime bookkeeping stays out of it.

```text theme={null}
.ade/
  ade.db        # lanes, sessions, PR mappings, proof metadata, settings
  ade.yaml      # shared, version-controlled team config
  local.yaml    # per-user overrides (gitignored)
  worktrees/    # managed lane worktrees (one directory per lane)
  artifacts/    # proof artifacts (screenshots, recordings, traces)
  cache/        # derived data ADE can rebuild
  secrets/      # encrypted, machine-local credentials
```

## Shared vs. local config

ADE splits configuration into two files, both merged into one effective config at read time:

| File | Scope | In Git? | Holds |
| - | - | - | - |
| `.ade/ade.yaml` | Shared | Committed | Team-wide processes, stacks, tests, lane templates, automations, AI mode, and provider/Linear preferences. |
| `.ade/local.yaml` | Local | Gitignored | Personal overrides: ports, env vars, machine-specific paths, local-only processes. |

Keep secrets and machine-specific paths in local config. Shared config is visible to the whole team, so anything in it ships to every teammate.

## What stays local

| Area | Contains |
| - | - |
| Database (`ade.db`) | Lanes, sessions, PR mappings, proof metadata, and settings. |
| Worktrees | The isolated working copy for each lane. |
| Artifacts | Proof captures — screenshots, recordings, and traces. |
| Secrets | Encrypted, machine-local credentials. |
| Cache | Derived data ADE can regenerate on demand. |

## Trust model

Commands saved as shared project defaults can run on developer machines. ADE treats those definitions as sensitive: when the shared config changes, it requires a local trust confirmation before the new version can spawn processes. Review such changes the same way you'd review a CI script or Dockerfile. Local config isn't trust-gated — you only need to trust your own overrides.

## What's committed, and what isn't

ADE manages this for you. It writes a `.ade/.gitignore` that ignores everything under `.ade/` by default and allowlists only the authored files meant to travel with the repo — `ade.yaml`, lane templates, skills, and project icons. Runtime files (the database, worktrees, artifacts, cache, and secrets) stay out of Git automatically, so you don't have to maintain ignore rules by hand.

> [!WARNING]
>
> Never put provider keys, tokens, or other secrets in `.ade/ade.yaml` or any committed file. Secrets belong in the local encrypted store or `.ade/local.yaml`, both of which stay off the shared path.

> [card] [Permissions](https://ade-app.dev/docs/configuration/permissions.md)
>
> Lane scope, provider modes, and the shared-config trust model.

> [card] [Settings](https://ade-app.dev/docs/configuration/settings.md)
>
> Configure the app from the UI.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.