refactor: update documentation and architecture references

- Changed design document paths in AGENTS.md for clarity and organization.
- Removed ARCHITECTURE.md as it has been integrated into the new design structure.
- Updated CONTEXT.md to reflect new command names and streamlined setup instructions.
- Revised README.md to simplify quick start commands and document registry.
- Added new ADRs for state store design, plugin system, instance state model, procedural model pipeline, simulation plugin, shared selection, and build configuration.
- Introduced design invariants document to outline architectural principles.
- Updated product vision document to clarify the core experience and target audience.
- Renamed npm script from "reference:pull" to "reference" for consistency.

Author: patrick204nqh

AGENTS.md

@@ -1,7 +1,7 @@
 # CCIV Project
 
-Designed architecture: `DESIGN.md` — read before any change (invariant).
-Current architecture state: `ARCHITECTURE.md` — changes as codebase evolves.
+Design invariants: `docs/design/invariants.md` — read before any change (locked).
+Architecture reference: `docs/design/architecture.md` — layer audit, file map, ADR index.
 
 ## Structure
 
@@ -17,10 +17,11 @@ Current architecture state: `ARCHITECTURE.md` — changes as codebase evolves.
   - `src/controls/` — OrbitControls from three/addons.
 - **`index.html`** — minimal HTML shell with inline CSS; loads `src/main.ts`.
 - **`scripts/`** — build tools.
-  - `pull-reference.mjs` — downloads + extracts external assets to `.cache/references/` (throwaway).
+  - `reference/pull.ts` — downloads external assets to `.cache/references/`.
   - `references.json` — list of external sources to pull.
-  - `build-model.mjs` — copies reference data into `src/models/<id>/`, renames with our conventions, generates config/textures.
-  - `models.json` — mapping from reference → owned model with mesh renames + material overrides.
+  - `pipeline/` — compile + publish stages for GLB artifacts.
+  - `build/` — procedural model generators (palm-island, ice-floe).
+  - `generate.ts` — CLI runner for procedural model generation.
 - **`public/textures/<model>/`** — owned textures (committed), copied from reference during build-model.
 
 ## Commands
@@ -35,14 +36,11 @@ npm run build
 # Preview production build
 npm run preview
 
-# Step 1: Pull external references → .cache/references/
-npm run model:pull
+# Setup after clone (compile models + publish manifest)
+npm run setup
 
-# Step 2: Build owned models from references
-npm run model:build
-
-# Step 3: Compile owned models to portable GLB artifacts
-npm run model:compile
+# Pull external references → .cache/references/
+npm run reference
 ```
 
 ## Skill sources (defined in bin/dev)
@@ -71,7 +69,6 @@ Add new sources by appending to `SOURCES` in `bin/dev:19-27`.
 - Coordinate convention: Y-up, Z-bow(+), X-starboard(-).
 - Ship model extracted into-code: `src/models/ship/` contains hardcoded Float32Array/Uint16Array geometry for all 7 mesh groups (hull, deck, sails, aft, rigging, details, interior).
 - Texture pipeline: external reference → `.cache/references/` (gitignored, throwaway). Then `scripts/build-model.mjs` copies textures to `public/textures/<model>/` and generates `src/textures/sources.ts`.
-- New models: add entry to `scripts/models.json`, run `build-model.mjs`. The model becomes owned code in `src/models/<id>/` with clean naming — no reference prefixes leak in.
 - Entity lifecycle: implement `SceneEntity` (in `src/entity/types.ts`) and attach via `entityManager.attach()`. Entities communicate via the event bus (`src/event-bus.ts`).
 - All Three.js scene graph interaction goes through `ISceneObject` (`src/scene/types.ts`). Never pass `THREE.Object3D` directly across module boundaries. `SceneObject` adapter wraps raw Three.js objects. Use `.object3D` escape hatch only when Three.js interop is unavoidable (TransformControls, raycaster).
 - Skills provide specialized instructions and workflows for specific tasks.

ARCHITECTURE.md

@@ -89,13 +89,13 @@ The asset pipeline transforms model configs into compiled GLB artifacts. Two sta
 - **compile** (`scripts/pipeline/compile.ts`) — reads `src/models/<id>/config.ts` for each model. For extracted models, reads geometry from `.cache/references/<asset>/data/`. For procedural models, imports the generator function and runs it. Outputs `public/models/<id>.glb`.
 - **publish** (`scripts/pipeline/publish.ts`) — scans `public/models/` for GLBs, reads metadata from configs, writes `public/models/manifest.json`.
 
-Run via: `npm run build:models`
+Run via: `npm run setup`
 
 ### Reference Downloads
 
 External asset sources are downloaded via a standalone tool, not part of the pipeline:
 
-- **`npm run reference:pull`** — downloads assets from Poly Haven etc. to `.cache/references/<asset>/`. Implementations in `scripts/reference/providers/`.
+- **`npm run reference`** — downloads assets from Poly Haven etc. to `.cache/references/<asset>/`. Implementations in `scripts/reference/providers/`.
 
 ### Model Creation Paths
 
@@ -128,7 +128,6 @@ Three ways to create a model, defined in `src/models/<id>/config.ts`:
 npm run dev              # Vite dev server with HMR
 npm run build            # production build
 npm run test             # run all tests
-npm run build:models     # compile all models to GLB + publish manifest
-npm run setup            # setup after clone (build:models)
-npm run reference:pull   # clone external references (optional, for customization)
+npm run setup            # setup after clone (compile models + publish manifest)
+npm run reference   # download external references (optional, for customization)
 ```

CONTEXT.md

@@ -1,6 +1,6 @@
 # CCIV — The Vessel
 
-A 3D ship viewer and environment editor built with Three.js + Vite + TypeScript. Explore a fully realized vessel in a dynamic ocean scene with stormy atmosphere, ship's log telemetry, and a dual-mode editor/viewer interface.
+A 3D ship viewer and environment editor built with Three.js + Vite + TypeScript.
 
 ```sh
 npm install
@@ -19,21 +19,8 @@ npm run dev
 ## Quick start
 
 ```sh
-# Build all models (compile GLBs + publish manifest)
-npm run build:models
-
-# Start dev server
-npm run dev
-```
-
-## Project structure
-
-```
-src/                   Runtime code
-scripts/               Build pipeline + reference downloader
-public/models/         Compiled GLB artifacts
-public/textures/       Owned textures
-docs/superpowers/      Specs and design documents
+npm run setup     # compile models + publish manifest
+npm run dev       # start dev server
 ```
 
 ## Commands
@@ -43,9 +30,18 @@ docs/superpowers/      Specs and design documents
 | `npm run dev` | Dev server with HMR |
 | `npm run build` | Production build |
 | `npm test` | Run all tests |
-| `npm run build:models` | Compile all models → GLB + publish manifest |
-| `npm run reference:pull` | Download external references → `.cache/references/` |
+| `npm run setup` | Compile all models → GLB + publish manifest |
+| `npm run reference` | Download external references → `.cache/references/` |
 
-## Architecture
+## Document registry
 
-See [`docs/architecture.md`](docs/architecture.md) for full diagrams, data flow, and module dependency graph.
+| Path | Contents |
+|---|---|
+| `docs/design/invariants.md` | Locked architectural golden rules (read before changes) |
+| `docs/design/architecture.md` | Layer compliance audit, module map, ADR index |
+| `docs/adr/` | Architecture Decision Records (ADR-001 through ADR-012) |
+| `docs/product/vision.md` | Product direction, audience, non-goals |
+| `docs/references/` | External model geometry references |
+| `docs/superpowers/` | Feature specs and implementation plans (historical) |
+| `CONTEXT.md` | Domain glossary for AI agents and developers |
+| `AGENTS.md` | AI agent instructions |

README.md

@@ -1,4 +1,4 @@
-# ADR-001: StateStore with Dotted-Path Subscriptions
+# ADR-006: StateStore with Dotted-Path Subscriptions
 
 ## Status
 Accepted

…/decisions/ADR-001-state-store-design.md docs/adr/ADR-006-state-store-design.mddocs/decisions/ADR-001-state-store-design.md renamed to docs/adr/ADR-006-state-store-design.md docs/decisions/ADR-001-state-store-design.md renamed to docs/adr/ADR-006-state-store-design.md

@@ -1,4 +1,4 @@
-# ADR-002: Plugin System with Mode-Based Activation
+# ADR-007: Plugin System with Mode-Based Activation
 
 ## Status
 Accepted

docs/decisions/ADR-002-plugin-system.md docs/adr/ADR-007-plugin-system.mddocs/decisions/ADR-002-plugin-system.md renamed to docs/adr/ADR-007-plugin-system.md

@@ -1,4 +1,4 @@
-# ADR-003: InstanceState as Flat Record for Placed Props
+# ADR-008: InstanceState as Flat Record for Placed Props
 
 ## Status
 Accepted

…ecisions/ADR-003-instance-state-model.md docs/adr/ADR-008-instance-state-model.mddocs/decisions/ADR-003-instance-state-model.md renamed to docs/adr/ADR-008-instance-state-model.md docs/decisions/ADR-003-instance-state-model.md renamed to docs/adr/ADR-008-instance-state-model.md

@@ -1,4 +1,4 @@
-# ADR-004: Procedural Model Pipeline via Three.js Generators
+# ADR-009: Procedural Model Pipeline via Three.js Generators
 
 ## Status
 Accepted

…ons/ADR-004-procedural-model-pipeline.md …adr/ADR-009-procedural-model-pipeline.mddocs/decisions/ADR-004-procedural-model-pipeline.md renamed to docs/adr/ADR-009-procedural-model-pipeline.md docs/decisions/ADR-004-procedural-model-pipeline.md renamed to docs/adr/ADR-009-procedural-model-pipeline.md

@@ -1,4 +1,4 @@
-# ADR-005: Simulation as Plugin via EntityManager
+# ADR-010: Simulation as Plugin via EntityManager
 
 ## Status
 Accepted

…s/decisions/ADR-005-simulation-plugin.md docs/adr/ADR-010-simulation-plugin.mddocs/decisions/ADR-005-simulation-plugin.md renamed to docs/adr/ADR-010-simulation-plugin.md docs/decisions/ADR-005-simulation-plugin.md renamed to docs/adr/ADR-010-simulation-plugin.md

@@ -1,4 +1,4 @@
-# ADR-006: Shared Selection via Kernel.selectedObject
+# ADR-011: Shared Selection via Kernel.selectedObject
 
 ## Status
 Accepted