[Xget7]

Summary

An agent-facing map of how the repo is composed and what each pipeline stage does on Metal and Vulkan, checked against the code.
AGENTS.md points every session at it and asks a change to a stage, GPU layout or package dependency to update it in the same PR.

 AGENTS.md
+  Architecture (...): read docs/ARCHITECTURE.md before exploring; ... updates it in the same PR.
 docs/
+└── ARCHITECTURE.md
+    ├── Packages     # dependency chain; ownership stays in CONTRIBUTING.md#code-layout
+    ├── Load         # decode, bake, reorder, tree, pack (shared, CPU)
+    └── Frame        # upload, selection, cull, sort, raster, present, submission: Metal | Vulkan

A pipeline table that had been circulating was stale; the page records the current state:

Stage	Was believed	Code says
Metal upload	Shared staging -> Private by blit, 64k-splat chunks	Zero copy into Shared buffers (MetalWorld.mm)
Decode threads	2 threads	One loader thread per platform, plus 2 TileLoader threads for tilesets
Formats	SPZ, PLY for tooling	SPZ v1-v4 (zstd for v4), .lodsplat, tilesets; PLY for tooling
Metal present	RGBA16F, blit to drawable	RGBA16F only with GPU sort, fullscreen render-pass blit or MetalFX upscale
Vulkan policy	All of it	Only sort depth and subpixel threshold (VulkanFrameCompute.h)

Evidence

• Before: no page covered the load pipeline or the per-backend frame; the pasted table had the errors above.
• After: three read-only subagents verified each stage against the code with file references, then a two-axis review (standards and spec) spot-checked about 15 claims (GpuSplat 32 bytes, kStagingBytes, 7 draw batches, kLoaderThreads, 3M sort capacity, frames in flight, loader thread names, swapchain format order) and all held after fixes.
• Where it ran: Mac, reading the code at ddd53b5.
• Checks: every relative link in the page resolves (the next PR in the stack enforces it). No build or device run: docs only.

Merge Danger

Door: Two-way.

Blast Radius: Docs

The page copies a few volatile constants (2 MiB staging, batch fractions, 3M capacity, 254/255) because they are what a reader asks for; they can drift when the code changes without the page.
The AGENTS.md line costs one line of context in every agent session.