# 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 and Solari local-light authoring policy |
| [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) | Superseded local `bevy_render` patch for transient Linux swapchain timeouts |
| [0020](adr/0020-jackdaw-inspired-editor-roadmap.md) | Jackdaw-inspired roadmap source policy and attribution requirements |
| [0021](adr/0021-brush-authoring-schema.md) | Brush authoring schema and hydration contract |
| [0022](adr/0022-bevy-0-19-upgrade.md) | Bevy 0.19 / Avian 0.7 upgrade and compatibility patches |
| [0023](adr/0023-transactional-scene-persistence-and-recovery.md) | Atomic scene writes, user-local recovery snapshots, and restore/discard policy |
| [0024](adr/0024-versioned-editor-session-state.md) | Versioned machine-local session state and safe abnormal-shutdown resume |
| [0025](adr/0025-project-root-is-a-startup-boundary.md) | Pre-engine project validation, activation, and sandbox contract |
| [0026](adr/0026-stable-scene-composition-and-active-document.md) | Stable scene IDs, subscene ownership, tabs, and active-world materialization |
| [0027](adr/0027-stable-prefab-ownership-and-variants.md) | Stable prefab ownership, nested override identity/layering, transactional source writes, variants, and local conversion |
| [0028](adr/0028-authoritative-project-content-validation.md) | Shared editor/headless dependency manifest and project content findings |
| [0029](adr/0029-validation-gated-build-profiles-and-packaging.md) | Shared validation-gated build profiles, runtime packaging, and metadata |
| [0030](adr/0030-audio-authoring-and-bus-schema.md) | Serializable audio sources/listeners, stable clip references, and project bus graph |
| [0031](adr/0031-animation-authoring-runtime-contract.md) | glTF animation artifacts, stable controller states, runtime hydration, and exact-signature retargeting |
| [0032](adr/0032-versioned-navigation-bake-and-runtime-query.md) | Rerecast bake artifacts, Polyanya runtime queries, and editor/runtime ownership |
| [0033](adr/0033-dedicated-skinned-mesh-renderer.md) | Dedicated skinned renderer, static/skinned import boundary, and scene migration |
| [0034](adr/0034-registry-driven-authoring-components.md) | Stable component IDs, reflected lifecycle/history, composition, and independent active state |
| [0035](adr/0035-shared-material-assets-and-renderer-slots.md) | Shared Material/Material Instance assets, stable renderer slots, and runtime-only property blocks |
| [0036](adr/0036-surface-abi-and-solari-parity.md) | Constrained Surface ABI v1, raster/Solari evaluator parity, and deformed-geometry boundary |
| [0037](adr/0037-collaborative-authored-file-safety.md) | Exact authored-file revisions, observational Git status, and optional ownership providers |
| [0038](adr/0038-non-blocking-native-dialog-broker.md) | Worker-owned native waits with one-shot main-thread workflow completion |

## 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/visual-language.md](editor/visual-language.md) | Editor chrome, viewport, selection, gizmo, and visualizer language |
| [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 |
| [editor/brushes.md](editor/brushes.md) | Brush authoring schema, hydration behavior, and MVP limits |
| [editor/operator-regression-testing.md](editor/operator-regression-testing.md) | Reusable modal-tool and operator invariant harness |
| [editor/session-recovery.md](editor/session-recovery.md) | Clean restart, abnormal shutdown, session schema, and privacy boundary |
| [editor/project-launcher.md](editor/project-launcher.md) | Project manifests, explicit startup roots, recents, and sandbox scaffolding |
| [editor/build-and-package.md](editor/build-and-package.md) | Editor/headless package profiles, output, exclusions, and metadata |
| [editor/multi-scene-composition.md](editor/multi-scene-composition.md) | Independent scene tabs, composition ownership, validation, and recovery |
| [editor/prefab-authoring.md](editor/prefab-authoring.md) | Linked instances, scoped overrides/source Apply, conflicts, variants, unpacking, and local conversion |
| [editor/audio-authoring.md](editor/audio-authoring.md) | Audio clips, source/listener authoring, audition, buses, runtime parity, and validation |
| [editor/animation-authoring.md](editor/animation-authoring.md) | glTF rigs/clips, controller states, preview, runtime requests, stable moves, and validation |
| [editor/navigation-authoring.md](editor/navigation-authoring.md) | Bounds/obstacles/areas/links, deterministic bake, overlay, path preview, and runtime queries |
| [editor/extensibility.md](editor/extensibility.md) | Static authoring component registration, lifecycle, composition, and history contract |
| [editor/material-system.md](editor/material-system.md) | Shared material assets and instances, renderer-slot assignment, Surface evaluators, migration, and diagnostics |
| [editor/collaborative-file-safety.md](editor/collaborative-file-safety.md) | Guarded authored writes, compact Git/read-only status, conflict recovery, and ownership providers |
| [editor/native-dialogs.md](editor/native-dialogs.md) | Non-blocking native dialog acquisition and main-thread result application |
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |

## 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 |
| `jackdaw_feature_roadmap_*.plan.md` | Jackdaw-inspired production roadmap; tracked in Gitea as `BS-JD-*` issues |
| `blacksite_production_readiness_*.plan.md` | M6-M7 reliability, content production, shipping, and acceptance gates |
| `animation_authoring_*.plan.md` | M7 glTF skeletal animation import, preview, controller, and runtime acceptance |
| `navigation_authoring_*.plan.md` | M7 navigation bounds, deterministic bake, diagnostics, preview, and runtime query API |
| `renderer_material_component_foundation_*.plan.md` | Renderer/material slots, skinned pose lifecycle, Surface ABI, and component foundation |
| `source_control_collaboration_safety_*.plan.md` | Exact authored-file guards, observational Git status, conflict recovery, and provider contract |
| `production_readiness_acceptance_*.plan.md` | Release-candidate evidence matrix, blocker sequence, clean-checkout checks, soak, budgets, and independent sign-off |
| `material_library_and_targeted_drop_*.plan.md` | Dedicated Material Library, exact viewport slot/primitive/brush targeting, hover preview, cancel, and grouped history |

## 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).