# Project Documentation

Central index for design decisions, mission, editor framework docs, and repository workflow.
Before treating any document as current guidance, read [`authority.toml`](authority.toml).

## Core

| Document | Purpose |
|----------|---------|
| [authority.toml](authority.toml) | Machine-readable current/plan/evidence/historical/superseded classification |
| [mission.md](mission.md) | Why the editor framework exists, principles, audience, non-goals |
| [../README.md](../README.md) | Run/build instructions, controls, implementation checklist |

## Repository workflow

| Document | Purpose |
|----------|---------|
| [workflow/codex-workflow.md](workflow/codex-workflow.md) | Task lifecycle, scope deltas, and completion states |
| [workflow/documentation-policy.md](workflow/documentation-policy.md) | Authority hierarchy, lifecycle classes, and integrity audit |
| [workflow/verification-policy.md](workflow/verification-policy.md) | Fast, slice, and candidate verification tiers |
| [workflow/build-storage-policy.md](workflow/build-storage-policy.md) | Managed Cargo lanes, budgets, and safe pruning |
| [workflow/gitea-tracking-policy.md](workflow/gitea-tracking-policy.md) | Tracker state and mutation boundaries |
| [archive/](archive/) | Preserved non-current documentation records |

## 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 |
| [0039](adr/0039-inline-height-grid-terrain-foundation.md) | Inline authored height grids with deterministic runtime-only chunk hydration |
| [0040](adr/0040-terrain-material-layer-weights.md) | Four-channel terrain material layers, compact normalized weights, and raster transport |
| [0041](adr/0041-transactional-editor-physics-placement.md) | Paused editor physics ownership and transactional gravity placement |
| [0042](adr/0042-guarded-editor-shutdown-and-document-savepoints.md) | Guarded native editor exit and canonical per-document clean checkpoints |
| [0043](adr/0043-content-addressed-import-fingerprints.md) | Content-addressed imported-source identity and byte-preserving artifact publication |
| [0044](adr/0044-sandboxed-fbx-external-texture-dependencies.md) | Sandboxed FBX texture bundles, validation policy, and deduplicated loading |
| [0045](adr/0045-content-workspace-and-material-fallback-contract.md) | Path-agnostic content workspace, registry v3, model material defaults, and DefaultGrid fallback |
| [0046](adr/0046-schema-driven-material-inputs-and-processed-textures.md) | Schema-driven Material inputs, registry v3 Texture settings, ARM packing, and deterministic runtime textures |
| [0047](adr/0047-editor-authored-asset-documents.md) | Editor-dirty asset documents, explicit saves, recovery, and background derived publication |
| [0048](adr/0048-modular-editor-composition-and-debt-ratchet.md) | Thin editor composition, registry-only Inspector dispatch, and automated architecture debt ratchet |
| [0049](adr/0049-penpot-led-editor-visual-system.md) | Penpot-led visual tokens, responsive editor components, Source Sans Pro typography, and picker interaction |

## Editor framework

| Document | Purpose |
|----------|---------|
| [editor/release-notes.md](editor/release-notes.md) | Historical editor framework 1.0 snapshot |
| [editor/evaluations/](editor/evaluations/) | Dated acceptance evidence and Gitea evidence-publishing policy; not product specification |
| [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/design-system.md](editor/design-system.md) | Penpot-led visual tokens, reusable controls, responsive geometry, and material-inspector presentation |
| [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/content-workspace.md](editor/content-workspace.md) | File-manager content organization, destination-first import, stable IDs, and model material authoring |
| [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/terrain.md](editor/terrain.md) | Terrain schema, inspector workflow, chunk hydration, collision, and follow-on boundaries |
| [editor/physics-placement.md](editor/physics-placement.md) | Transactional gravity placement, diagnostics, isolation, and undo workflow |
| [editor/collider-authoring.md](editor/collider-authoring.md) | Collider shape authoring, hydration diagnostics, semantic overlays, and placement prerequisites |
| [editor/sample-regression-pack.md](editor/sample-regression-pack.md) | Five-area sample catalog, editor workflow, validation gates, and visual QA contract |
| [editor/evaluations/material-renderer-foundation/](editor/evaluations/material-renderer-foundation/) | Live screenshots and acceptance results for the renderer/material/component foundation |
| [editor/evaluations/terrain-sculpt-tools/](editor/evaluations/terrain-sculpt-tools/) | Live screenshot and acceptance results for modal terrain sculpt tools |
| [editor/evaluations/terrain-material-layers/](editor/evaluations/terrain-material-layers/) | Live screenshot and acceptance results for terrain material assignment, blending, painting, and history |
| [editor/evaluations/physics-placement/](editor/evaluations/physics-placement/) | Live screenshot and acceptance results for physics settling, cancel, commit, undo, and redo |
| [editor/evaluations/collider-diagnostics/](editor/evaluations/collider-diagnostics/) | Live screenshot and acceptance results for collider overlays, diagnostics, shape history, and placement preflight |
| [editor/evaluations/navigation-authoring/](editor/evaluations/navigation-authoring/) | Live screenshots and acceptance results for navigation authoring and runtime parity |
| [editor/evaluations/operator-invariants/](editor/evaluations/operator-invariants/) | Source acceptance results for production operator lifecycle, rollback, cleanup, and undo/redo invariants |
| [editor/evaluations/sample-regression-pack/](editor/evaluations/sample-regression-pack/) | Exact-implementation source and native acceptance evidence for the editor sample regression pack |
| [editor/evaluations/guarded-shutdown-savepoints/](editor/evaluations/guarded-shutdown-savepoints/) | Source and native acceptance evidence for guarded editor exit and per-document clean checkpoints |
| [editor/evaluations/scoped-ui-actions/](editor/evaluations/scoped-ui-actions/) | Exact-implementation source and native acceptance evidence for actions invoked during scoped egui rendering |
| [editor/evaluations/deterministic-asset-fingerprints/](editor/evaluations/deterministic-asset-fingerprints/) | Source, fresh-checkout, hash-stability, and native acceptance evidence for imported-source fingerprints |
| [editor/evaluations/fbx-external-texture-dependencies/](editor/evaluations/fbx-external-texture-dependencies/) | Source, validation, and native acceptance evidence for sandboxed FBX texture dependencies and override states |
| [editor/evaluations/content-workspace-m2/](editor/evaluations/content-workspace-m2/) | Native M2 evidence for Content Browser file-manager selection, context menus, managed-folder visibility, and Details resizing |
| [editor/evaluations/production-readiness/](editor/evaluations/production-readiness/) | Current versioned production gate, evidence matrix, candidate commands, soak protocol, and independent sign-off requirements |

## Plans

Plans describe desired scope and acceptance, never current implementation truth. Their authoritative
classification is in [`authority.toml`](authority.toml); completed plans are frozen as historical
records instead of being rewritten as status diaries.

Current active plans:

- [Content workspace and import authoring](../.cursor/plans/content_workspace_and_import_authoring_2026-07-13.plan.md)
- [Production-readiness program](../.cursor/plans/blacksite_production_readiness_2026-07-10.plan.md)
- [Production-readiness acceptance gate](../.cursor/plans/production_readiness_acceptance_2026-07-12.plan.md)

## 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/content_pipeline/ UI-independent content catalog, transaction, import, and processing engine
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).