# Phase 2: Client Engine Documentation - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in 02-CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-05-02
**Phase:** 02-client-engine-documentation
**Areas discussed:** Scope of engine surface, Asset catalogue method, Doc structure & depth (incl. Phaser-vs-Pixi matrix)
**Areas deferred to Claude's discretion:** Phaser-vs-Pixi methodology (resolved inside Doc structure & depth Q4)

---

## Scope of Engine Surface

### Q1: Include in-game UI / HUD / menus in CDOC-01?

| Option | Description | Selected |
|--------|-------------|----------|
| Yes — same depth as engine primitives | HUD, menus, inventory, message-board reader as first-class engine features | ✓ |
| Yes — inventory only | One-line summaries; defer per-screen reverse to Phase 6 | |
| No — engine primitives only | Treat UI as content; Phase 6 reverses on demand | |

**User's choice:** Yes — same depth as engine primitives.

### Q2: Document original admin model?

| Option | Description | Selected |
|--------|-------------|----------|
| Document as anti-port reference | Catalog Ctrl+E/Ctrl+Q surface, mark REJECTED-AS-PORTED with reason | ✓ |
| One-paragraph note + link to CONCERNS.md | Acknowledge + defer | |
| Skip entirely | Phase 7 does its own discovery | |

**User's choice:** Document as anti-port reference.

### Q3: DnD-only object/event citation strategy?

| Option | Description | Selected |
|--------|-------------|----------|
| Cite .dnd.json descriptor; quote .gml as illustrative | Descriptor canonical, GML inline with caveat | ✓ |
| Cite transcompiled .gml only | More natural reading, propagates lossiness | |
| Cite both inline every time | Most rigorous, most verbose | |

**User's choice:** Cite descriptor; .gml illustrative only.

### Q4: MVP-tag features per CDOC-01 entry?

| Option | Description | Selected |
|--------|-------------|----------|
| Yes — explicit mvp:yes\|no per feature | Phase 6 cherry-picks CLI-08 slice without re-reading 320 objects | ✓ |
| Section break only | "MVP slice" subsection per feature category | |
| No tag | Phase 6 does its own slice analysis | |

**User's choice:** Explicit per-feature mvp tag.

---

## Asset Catalogue Method

### Q1: Primary CDOC-02 source-of-truth format?

| Option | Description | Selected |
|--------|-------------|----------|
| Auto-gen tools/asset-catalog → JSON + Markdown index | TS Node CLI; re-runnable; CI-checkable | ✓ |
| Hand-curated Markdown only | Lower upfront tooling cost; high drift risk | |
| JSON manifest only | Saves Markdown maintenance; humans read JSON less fluently | |

**User's choice:** Auto-gen JSON + Markdown index.

### Q2: Metadata fields per asset class?

| Option | Description | Selected |
|--------|-------------|----------|
| Extraction meta.json fields only | Pure aggregator; minimum surface | |
| + derived/computed fields | Palette/format detection, density buckets | |
| + semantic tags (used-where, behavior class) | Cross-reference assets to consuming objects/scripts/rooms | |
| **All three (user write-in)** | All three tiers, augmented with semantic cross-refs | ✓ |

**User's choice:** All three tiers.
**Notes:** "very unlikely to be another extraction in the future, as the legacy source will see no updates." — re-extraction drift cost is low, so the build-once cross-ref tier is worth the development cost.

### Q3: Opaque BMP handling?

| Option | Description | Selected |
|--------|-------------|----------|
| Catalog records imageBytes length + magic-byte format | Preserves Phase 1 D-12 revision; no decode | ✓ |
| Decode BMP→PNG inline during catalog build | Pulls AST-01 work into Phase 2; violates D-12 | |

**User's choice:** Length + magic-byte format; no decode.

### Q4: Catalogue unknown-DnD-actions list?

| Option | Description | Selected |
|--------|-------------|----------|
| Yes — Phase 2 prerequisite | Resolution required before CDOC-01 ships | ✓ |
| No — separate concern | Phase 1 carry; cite descriptors as opaque | |

**User's choice:** Phase 2 prerequisite.

---

## Doc Structure & Depth

### Q1: Top-level organization of docs/extracted-engine/?

| Option | Description | Selected |
|--------|-------------|----------|
| By engine subsystem (rendering, input, collision, animation, scene/room, save/load, audio, UI, networking, admin-anti-port) | One MD per subsystem; reads top-down | ✓ |
| By extracted resource type | Mirrors extracted/ tree; ~534 docs | |
| Hybrid — subsystem + auto-gen per-resource appendix | Most info, highest authoring cost | |

**User's choice:** By engine subsystem.

### Q2: Reverse-engineering depth per script/object?

| Option | Description | Selected |
|--------|-------------|----------|
| Functional clusters with citation + key-script call-out | Group by behavior, quote 5-30 line snippets inline | ✓ |
| Every script reverse-engineered to natural language | 198 scripts × 320 objects' events; multi-week effort | |
| Skeleton + on-demand deepening | One-line summaries; deepen on demand | |

**User's choice:** Functional clusters with citations.

### Q3: Authoring approach?

| Option | Description | Selected |
|--------|-------------|----------|
| Hand-authored prose + auto-generated indices/cross-refs | Mix matches Phase 1 D-19 pattern | ✓ |
| Fully hand-authored | Total control, drift risk | |
| Skeleton-generator first | Reduces blank-page; tooling cost upfront | |

**User's choice:** Hand-authored prose + auto-generated indices.

### Q4: Phaser-vs-Pixi matrix location and rigor?

| Option | Description | Selected |
|--------|-------------|----------|
| MATRIX.md — paper analysis, weighted scoring, recommend Phaser unless hard knockout | Per-row feature mapping, weights documented | ✓ |
| Same + small prototype spike for worst-fit feature | Higher confidence, more time | |
| Skip matrix — STACK.md + brief note | Risks not satisfying CDOC-03 acceptance | |

**User's choice:** MATRIX.md with paper analysis, weighted scoring, hard-knockout rule.

---

## Claude's Discretion

The Phaser-vs-Pixi methodology gray area was not selected for explicit discussion; Claude resolved it inside Doc structure & depth Q4. Specifically:
- Paper-analysis matrix (D-12)
- Hard-knockout rule promotes PixiJS only on workaround-invasive Phaser gaps (D-13)
- ADR at `docs/adr/0001-client-engine.md` cites MATRIX directly (D-14)

Inside selected areas, doc-writer judgment is preserved on:
- Subsystem MD list (D-09) — additions allowed during planning if extraction surfaces a coherent subsystem.
- Functional-cluster grouping criteria (D-10) — left to writer's judgment provided every script and event remains reachable from at least one subsystem doc via the auto-generated cross-ref index.

## Deferred Ideas

- Prototype spike for Phaser-vs-Pixi (only if D-13 fires)
- Full per-script reverse engineering (deepen on Phase 6 demand)
- docs/asset-pipeline/ design notes (Phase 6/7)
- Modernized admin UI design (Phase 7 PAR-07)
- Server engine documentation (Phase 3)
- Round-trip doc → schema → doc generators