# Spec Index

This directory contains normative design material for v0.4 contracts and features, including some
surfaces that now have partial implementations.

Use `spec/` for contracts that should drive implementation and tests.
Do not use it for execution planning or broad architecture essays.


## Authority Map

- `architecture/`: cross-cutting source-module layers, scene split direction, and external
  dependency policy.
- `api/`: cross-module public API conventions for naming, structs, bindings, and release review.
- `bindings/`: raw generated Python `ctypes` binding architecture, generation policy, and
  validation rules.
- `build/`: component-target, packaging, install/export, and package-consumer build contracts.
- `data/`: data-submodule layout, manifest/provenance rules, and scientific showcase-dataset
  policy.
- `docs/`: v0.4 documentation architecture, example coverage, gallery site, and AI-friendly
  authoring rules.
- `drp2/`: backend-agnostic rendering protocol contract, schemas, fixtures, DVZR replay, and
  native-runtime pressure rules.
- `examples/`: executable example taxonomy, generated example-page contract, gallery selection,
  and scientific showcase policy.
- `release/`: release readiness, RC process, communication/blog assets, and gallery outreach
  policy.
- `scene/`: scene-layer requirements, consumer-side object model, retained object semantics, and
  implementation boundary notes.
- `testing/`: test-runner scheduling, skip, fixture, and validation policy.

AI-facing usage policy starts in `docs/AI_DOCUMENTATION.md`. Scene/app defaults, copy-safe examples,
diagnostic shape, and Python scope then route to `scene/api/`, `scene/examples/`,
`scene/validation/`, `api/`, and `bindings/` respectively. Cross-cutting module placement questions
route to `architecture/`; protocol replay questions route to `drp2/`.


## Rules

1. If violating a statement should fail implementation work or conformance tests, it belongs in `spec/`.
2. If a document is primarily about sequencing, backlog, or what to do next, it belongs in `agents/`.
3. If a document is primarily explanatory, comparative, or tutorial-like, it belongs in `docs/`.
4. Keep top-level `spec/` limited to this index and intentionally global policy; put owned material
   in the nearest topic directory.
5. Avoid speculative API sketches in `spec/` unless they are directly needed to validate the written
   contract.


## Validation

Spec-owned executable checks should be runnable from the repository root.

Current entrypoint:

```bash
just spec-check
```

At the moment this validates the DRP2 fixture corpus and the DRP2 fixture-runner tests.
Scene spec changes that alter implemented behavior should also run the narrowest relevant
`just test scene` filter, because the scene spec now has multiple active source slices.