xyz-platform-context

High-level domain documentation for XYZ Reality's HoloConstruct platform. Aimed at developers joining the project and AI copilots that need architectural context to make informed code changes.

Conventions

Guideline	Why
Keep files concise — explain the "what" and "why", link out for deep details	Avoids stale duplicates of implementation docs
Note pitfalls and gotchas explicitly	Saves hours of debugging
Include goals and planned work	Gives direction even when Jira is unavailable
Use plain language over code	This isn't API reference; it's conceptual grounding

Domains

Domain	Path	Description
Dashboard Page	dashboard/	In-browser analytics + 3D viewer replacing PowerBI
Canvas Page	canvas/	AI chat interface — natural-language → streaming TSX dashboards
Agent Pipeline	agent-pipeline/	FastAPI backend for the Canvas: phases, SSE, MCP tools, caching
Commissioning	commissioning/	Flag-gated MVP: asset register, checklists, 3D linking, handover readiness — on a temporary Supabase bridge

Add new domains as folders here. Each domain gets a README.md and topic files.

Running tests

hc-frontend's suite cannot be installed with the tokens a cloud agent session has — npm ci 401s on the private @xyzreality/dhtmlx-gantt. There is a working stub-and-install round it in running-tests-in-agent-sessions.md. Read it before deferring any work with "can't run the tests here".

Planning

Cross-cutting ticket plans live in planning/. One file per ticket, named PLT-XXXX-slug.md.

Ticket	File	Confidence
PLT-2729 — Issues scroll + sticky search	PLT-2729-issues-scroll-visibility.md	7/10
PLT-2731 — Issues loading performance	PLT-2731-issues-loading-performance.md	6/10
PLT-2750 — Camera state on projection switch	PLT-2750-camera-projection-modes.md	8/10
PLT-2751 — 360 zoom controls bug	PLT-2751-360-zoom-slider-bug.md	4/10

Domain-specific plans live alongside their domain (e.g. canvas/planning/, agent-pipeline/planning/).

Relationship to docs/

The existing docs/ folder contains deep technical references (DuckDB schemas, API mappings, Mermaid diagrams). This folder is the entry point — read here first, then follow links into docs/ when you need implementation specifics.

XYZ_AgentPipeline/docs/ has been consolidated here — all pipeline design docs and plans are now under agent-pipeline/ and canvas/.