Initial commit: AirCoding V1.0.0 Alpha architecture baseline

Complete architecture document set with multi-model review remediation:
- Frozen interface contracts, runtime semantics, DB schemas
- Event/tool/error/provider registries
- Scheduler and main agent state machines
- C4 module/code views, solution architecture, baseline V1
- Multi-model review reports and joint assessment
- Phase-gate remediation complete (P0/P1/P2/UX resolved)
- Implementation plan with T-000A through T-045
- Reference folders kept as placeholders only

AirPlan/docs/architecture/adr/ADR-0001-use-airplan-as-the-workflow-root.md

@@ -0,0 +1,15 @@
+# ADR-0001: Use AirPlan As The Workflow Root
+
+- Status: Accepted
+- Date: YYYY-MM-DD
+
+## Context
+This project needs a durable workflow root for planning, execution state, architecture context, validation evidence, and resumable AI sessions.
+
+## Decision
+Store project workflow artifacts under `AirPlan/`, use the repo-root `AGENTS.md` only as a bootstrap shim, and let `aireng` plus `airdo` maintain plan, todo, ADR, and C4 context there.
+
+## Consequences
+- Planning and execution context stay resumable across sessions.
+- Global workflow docs live in one predictable location.
+- Plugin runtime state does not clutter the main project tree.

AirPlan/docs/architecture/adr/ADR-0002-use-bun-typescript-monorepo.md

@@ -0,0 +1,28 @@
+# ADR-0002: Use Bun TypeScript Monorepo For AirCoding Runtime
+
+- Status: Accepted
+- Date: 2026-05-27
+
+## Context
+
+AirCoding needs a self-owned runtime that can support CLI, TUI, agent orchestration, provider adapters, contracts, and toolchain packages without becoming a wrapper around an existing coding agent.
+
+## Decision
+
+Use TypeScript on Bun with Bun workspaces and Turborepo. Organize MVP packages as:
+
+```text
+packages/cli
+packages/tui
+packages/runtime
+packages/llm
+packages/toolchain-cpp
+packages/contracts
+```
+
+## Consequences
+
+- Runtime, UI, providers, and toolchains share compileable contracts.
+- Worker agents can run as independent Bun child processes.
+- Python remains subprocess-only for existing scripts/libraries, not the core runtime.
+- Future language support is added through `toolchain-*` packages.

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

@@ -0,0 +1,30 @@
+# 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:
+
+```text
+<project>/.air/shared/  # git-shareable project config, rules, plan docs
+<project>/.air/local/   # private sessions, artifacts, backups, workspaces, local DBs
+```
+
+Session DBs live at:
+
+```text
+<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.

AirPlan/docs/architecture/adr/ADR-0004-use-eventstore-domain-tables-and-projectionstore.md

@@ -0,0 +1,28 @@
+# ADR-0004: Use EventStore, Domain Tables, And ProjectionStore
+
+- Status: Accepted
+- Date: 2026-05-27
+
+## Context
+
+AirCoding needs live TUI/HUD updates, crash recovery, scheduling queries, tool/run evidence, and resumable session state. Raw message storage alone is insufficient for scheduling and recovery.
+
+## Decision
+
+Use an event-driven runtime with:
+
+```text
+EventBus        # live ephemeral/durable event publication
+EventStore      # durable event validation and transactional persistence
+Domain tables   # scheduling/recovery/query source of truth
+ProjectionStore # derived TUI/HUD view model
+```
+
+Canonical messages are stored as Anthropic content JSON. Domain tables store tasks, agents, tool runs, command runs, artifacts, diagnostics, evidence, workspaces, summaries, and UI state.
+
+## Consequences
+
+- Scheduler and recovery query domain tables instead of parsing message history.
+- TUI/HUD consumes ProjectionStore, not DB/EventBus directly.
+- Durable event insert and corresponding domain table update happen in one SQLite transaction.
+- Event payloads and persistence policy are governed by `event-registry-v1.md`.

AirPlan/docs/architecture/adr/ADR-0005-use-independent-worker-processes-and-ndjson-ipc.md

@@ -0,0 +1,30 @@
+# ADR-0005: Use Independent Worker Processes And NDJSON IPC
+
+- Status: Accepted
+- Date: 2026-05-27
+
+## Context
+
+A single agent process doing all work would cause context explosion, reduce responsiveness, and make parallel execution fragile. AirCoding needs workers that can be monitored, retried, cancelled, and recovered independently.
+
+## Decision
+
+Run Executor, Reviewer, Debugger, Compactor, and ExperienceMiner as independent Bun child processes. Use NDJSON over stdio for IPC.
+
+IPC messages use:
+
+```text
+kind: event
+kind: control
+kind: log
+```
+
+The Scheduler owns process lifecycle, heartbeat monitoring, timeout handling, and WorkerResult collection.
+
+## Consequences
+
+- Main Agent remains responsive.
+- Workers have bounded task context.
+- Scheduler can detect lost workers through heartbeat/process state.
+- stdout is reserved for protocol; stderr is crash/fatal fallback.
+- Worker loops may be role-specific rather than one generic shared loop.

AirPlan/docs/architecture/adr/ADR-0006-align-execution-layer-with-claude-code.md

@@ -0,0 +1,30 @@
+# ADR-0006: Align Execution Layer With Claude Code Quality Discipline
+
+- Status: Accepted
+- Date: 2026-05-27
+
+## Context
+
+AirCoding's usefulness depends heavily on safe, correct code modifications. The user explicitly prioritized Claude Code-level execution quality over broad but loose tool behavior.
+
+## Decision
+
+Align execution-layer primitives with Claude Code as much as possible:
+
+- read before edit
+- exact conservative replacements
+- small patches
+- no unrelated refactors
+- no premature abstractions
+- schema-validated tool use
+- permission checks before side effects
+- verification before completion
+- build/test/debug evidence collection
+- root-cause failure diagnosis
+- explicit blocker escalation for architecture/interface conflicts
+
+## Consequences
+
+- `fs.edit`, `fs.patch`, `shell.run`, WorkerResult, and review gates must preserve this discipline.
+- Codex/OpenCode may inform tool breadth/UI/runtime ideas, but not at the cost of execution quality.
+- Workers should fail or block rather than guessing unsafe edits.

AirPlan/docs/architecture/adr/ADR-0007-use-toolregistry-permissionengine-and-capability-manifests.md

@@ -0,0 +1,21 @@
+# ADR-0007: Use ToolRegistry, PermissionEngine, And Capability Manifests
+
+- Status: Accepted
+- Date: 2026-05-27
+
+## Context
+
+AirCoding needs a growing tool surface across filesystem, shell, git, build, debug, GUI, network, memory, and future plugins. Tools must be extensible without bypassing safety boundaries.
+
+## Decision
+
+Use ToolRegistry for schema-validated tool execution, PermissionEngine for all side-effect decisions, and CapabilityRegistry for built-in/future tool bundles.
+
+Capabilities declare dependencies and permissions. Doctor/setup detects and installs/fixes dependencies according to permission policy. Capability tools are not privileged above built-ins.
+
+## Consequences
+
+- All tool calls share lifecycle events, artifacts, errors, and evidence behavior.
+- Plugin/capability extension is possible without opening a permission bypass.
+- Doctor owns dependency installation rather than arbitrary plugin scripts.
+- MVP tool names and schemas are frozen in `tool-registry-v1.md`.

AirPlan/docs/architecture/adr/ADR-0008-use-anthropic-canonical-messages-with-provider-adapters.md

@@ -0,0 +1,21 @@
+# ADR-0008: Use Anthropic Canonical Messages With Provider Adapters
+
+- Status: Accepted
+- Date: 2026-05-27
+
+## Context
+
+AirCoding needs provider flexibility while preserving a stable internal representation for prompts, tools, messages, context compaction, and session persistence.
+
+## Decision
+
+Use Anthropic canonical content blocks internally. ContextAssembler emits Anthropic canonical messages. Provider adapters convert at the LLM boundary to Anthropic, OpenAI, OpenRouter, ollama, or compatible endpoints.
+
+Provider capability matrix controls whether a model can satisfy the task and whether conversion is lossless, lossy, or unsupported.
+
+## Consequences
+
+- Same-provider model switching has low conversion cost.
+- Cross-provider differences are localized to adapters.
+- Unsupported required features block before model call.
+- Tool/result/message persistence remains stable across providers.

AirPlan/docs/architecture/adr/ADR-0009-target-linux-first-with-tiered-platform-support.md

@@ -0,0 +1,21 @@
+# ADR-0009: Target Linux First With Tiered Platform Support
+
+- Status: Accepted
+- Date: 2026-05-27
+
+## Context
+
+AirCoding's first deep workflow targets C++ development and local agent execution, which depend heavily on POSIX shell/process/filesystem semantics and local toolchains.
+
+## Decision
+
+Use Linux x86_64 as tier-1 MVP platform, Linux arm64 and WSL2 as tier-2, macOS as experimental, and Windows native as experimental/post-MVP.
+
+MVP shell/process/C++ workflows target POSIX-like Linux behavior.
+
+## Consequences
+
+- Release gates block on tier-1 Linux.
+- Platform detection and path classification must be platform-aware.
+- Windows native deep support and MSVC workflows are deferred.
+- VibeBox ARM Linux remains compatible as a downstream branch but does not define mainline MVP release blockers.