# Maintenance and change procedure

Status: maintainer runbook · Version 0.1.0 · 2026-08-21

## Change a visual rule

1. Open the relevant normative document and state the rule in measurable language.
2. Record the decision and consequence in `DECISIONS-AND-OPEN-QUESTIONS.md`.
3. Update affected schemas, catalogs, prompt packets and Site copy in the same change.
4. Add or update a reference specimen and at least two Scene fixtures.
5. Run `npm run release`; inspect the Site at desktop and mobile widths; review generated checksums.

## Add a Component

1. Assign a stable namespaced ID and semantic subtype.
2. Produce an RGBA asset under neutral authoring light.
3. Record dimensions, footprint, orientation, anchors, states, light behavior, accessibility and provenance.
4. Validate against `component.schema.json`.
5. Test neutral workshop plus two environmental fixtures.
6. Add it to the catalog only after acceptance.

Never replace a published asset under the same ID and version. Correct it with a new asset version and migration note.

## Add a Scene

1. Declare Purpose, Realm, Areas, environment, camera and accessibility summary.
2. Place instances by Component ID with transforms and state.
3. Declare relationships, portals, authored views and Overlay exclusions.
4. Validate the Scene record.
5. Test without Panels, Overlays and Chrome; its spatial meaning must remain legible.
6. Add the visual fixture, JSON file, Site entry and download package together.

## Change canon grounding

Use only a validated authoritative canon source. Copy the new canonical file and manifest into `references/canon/`, update provenance, compare term meanings, migrate schemas and fixtures, then release a new system version. Never infer canonical definitions from this visual package.

## Release

Run:

```sh
npm run release
```

This synchronizes public artifacts, validates the system, builds the Site and recreates all ZIPs and SHA-256 checksums. Perform visual QA after the automated run. Copy the complete ZIP to the requested delivery location only after all checks pass.