AirCoding/AirPlan/docs/architecture/adr/ADR-0003-use-project-local-air-state.md

ADR-0003: Use Project-Local .air State

• Status: Accepted
• Date: 2026-05-27

Context

AirCoding sessions, artifacts, rules, plans, backups, and debug evidence must be resumable and portable with the project where possible, while still keeping private/local state out of normal source sharing.

Decision

Use project-local .air/ as the source of truth:

<project>/.air/shared/  # git-shareable project config, rules, plan docs
<project>/.air/local/   # private sessions, artifacts, backups, workspaces, local DBs

Session DBs live at:

<project>/.air/local/sessions/<session-id>/session.db

Consequences

• Project state can move with the project directory.
• .air/shared/ can be versioned; .air/local/ is gitignored by default.
• Runtime recovery uses project-local SQLite and artifacts.
• Global ~/.air/ remains config/cache/log/index state, not session source of truth.