# Project Documentation

Central index for design decisions, mission, and editor framework docs. Agents and contributors should keep this map current—see [`.cursor/rules/documentation.mdc`](../.cursor/rules/documentation.mdc).

## Core

| Document | Purpose |
|----------|---------|
| [mission.md](mission.md) | Why the editor framework exists, principles, audience, non-goals |
| [../README.md](../README.md) | Run/build instructions, controls, implementation checklist |

## Architecture Decision Records (ADRs)

Immutable-style log of significant decisions. Add a new numbered ADR when changing boundaries, formats, or policies.

| ADR | Topic |
|-----|-------|
| [0001](adr/0001-roadmap-architecture.md) | Crate split, sim/protocol direction, milestone north star |
| [0002](adr/0002-bevy-version-and-migration-policy.md) | Bevy upgrade cadence and verification |
| [0003](adr/0003-editor-framework-mission.md) | Editor as reusable in-process framework |
| [0004](adr/0004-editor-hot-reload.md) | Dev-only `game_hot` dylib hot reload |
| [0005](adr/0005-prefab-instance-and-asset-registry.md) | Prefab instances + stable asset registry |
| [0006](adr/0006-scene-schema-versioning.md) | Scene schema versioning and validation |
| [0007](adr/0007-editor-plugin-extensibility.md) | EditorPlugin extensibility surface |
| [0008](adr/0008-editor-module-boundaries.md) | Editor domain modules, lib/bin split, plugin group |
| [0009](adr/0009-authoring-vs-hydrated.md) | Authoring vs hydrated components; strip-on-save |
| [0010](adr/0010-actor-kind-and-inspector.md) | ActorKind, validation, actor inspector |
| [0011](adr/0011-scene-sun-policy.md) | Project sun vs scene directional policy |
| [0012](adr/0012-zero-tech-debt-editor.md) | Zero tech debt / no dual inspector |
| [0013](adr/0013-rendering-tiers-and-post-process-volumes.md) | GI tiers, post-process volumes, editor model |
| [0014](adr/0014-unified-viewport-model.md) | Unified viewport render target and clean game-view overlay |
| [0015](adr/0015-viewport-camera-stack-ownership.md) | Viewport camera FX ownership, GI auto-forward for local shadows |
| [0016](adr/0016-unified-rendering-contract.md) | Requested/effective render stack, Solari eligibility, emissive materials |
| [0017](adr/0017-normalized-static-mesh-assets.md) | Normalized static mesh assets and renderer placement |
| [0018](adr/0018-componentized-actor-inspector-and-materials.md) | Componentized actor inspector, imported asset refs, collider split, material overrides |
| [0019](adr/0019-local-bevy-render-timeout-patch.md) | Local `bevy_render` patch for transient Linux swapchain timeouts |

## Editor framework

| Document | Purpose |
|----------|---------|
| [editor/release-notes.md](editor/release-notes.md) | Editor framework 1.0 baseline |
| [editor/evaluations/](editor/evaluations/) | Horizon gate sign-offs (R1–R6) |
| [editor/architecture.md](editor/architecture.md) | Viewport / PIE / settings data flow |
| [editor/roadmap.md](editor/roadmap.md) | Phased editor roadmap and status |
| [editor/brp.md](editor/brp.md) | BRP automation and authoring-only policy |
| [editor/debt-audit.md](editor/debt-audit.md) | Zero-debt phase gates |

## Working plans (not canonical long-term)

Detailed milestone and feature plans live in [`.cursor/plans/`](../.cursor/plans/). Promote stable outcomes into ADRs or `docs/` when shipped.

| Plan | Topic |
|------|-------|
| `project_roadmap_*.plan.md` | M0–M8 program index |
| `editor_framework_mission_roadmap_*.plan.md` | Editor mission + phased roadmap |
| `project_settings_and_pie_eject_*.plan.md` | M1.5: settings, rendering parity, PIE eject |
| `rendering_unification_*.plan.md` | Unified rendering stack, Hybrid Auto GI, emissive materials |
| `static_mesh_asset_refactor_*.plan.md` | Static mesh renderer, normalized model artifacts, inspector redesign |
| `component_system_refactor_*.plan.md` | Component registry, imported asset refs, collider split, material overrides |

## Crate responsibilities (quick reference)

```
crates/protocol/   Tick rate, input intent, message shapes
crates/sim/        Fixed-step gameplay; no rendering
crates/shared/     Authoring components + hydration
crates/game/       Client presentation, GamePlugin, rendering
crates/editor/     In-process egui editor, BRP, PIE
crates/settings/   Project settings, active/effective render profile contracts
```

When adding a crate or moving responsibilities, update this table and ADR 0001 (or a follow-up ADR).