docs: adopt xmake, thin-C-API-first, arena hooks, LDC2/DMD split

docs/superpowers/specs/2026-09-13-libvct-design.md

@@ -690,11 +690,11 @@ A corpus of input IR + expected FileCheck patterns; CI runs the full matrix.
 
 ### 12.1 Language & toolchain
 
-Written in D. Primary compiler: **LDC2**; **DMD** supported as a secondary build target. **Zero runtime dependencies** — only a D compiler to build, and a system C compiler discovered at runtime for the C path.
+Written in D. **LDC2 is used for release builds** (best codegen); **DMD is used for debug builds** (faster compile/iteration). **Zero runtime dependencies** — only a D compiler to build, and a system C compiler discovered at runtime for the C path.
 
 ### 12.2 Build system
 
-`dub` for normal development, **plus** a plain `build.d`/Makefile path for no-dub builds. Both MUST produce identical artifacts.
+**`xmake`** is the build system — not `dub`. A single `xmake.lua` drives all targets: the release profile uses LDC2, the debug profile uses DMD. No external package manager is required to build.
 
 ### 12.3 Artifacts
 
@@ -705,8 +705,8 @@ Written in D. Primary compiler: **LDC2**; **DMD** supported as a secondary build
 
 ### 12.4 API surfaces
 
-- **Native D API** (primary, full feature set).
-- **Thin `extern(C)` C API** (v1): opaque handles for `Context`/`Module`/`Builder`/`Config`, functions to build IR, run the pipeline, and query diagnostics. No logic lives in the shim.
+- **Thin `extern(C)` C API** (v1, the primary public surface): opaque handles for `Context`/`Module`/`Builder`/`Config`, functions to build IR, run the pipeline, and query diagnostics. No logic lives in the shim.
+- **Native D API** (full feature set): the implementation surface; the C API is a thin shim over it, so the D API is exercised by every C API call.
 
 ### 12.5 Module visibility
 
@@ -718,7 +718,7 @@ Written in D. Primary compiler: **LDC2**; **DMD** supported as a secondary build
 - A `Context` owns one or more **arenas**; an arena is the unit of reclamation. Default: one arena per `Module`, freed wholesale.
 - All IR and optimizer objects are arena-owned and non-GC; passes mutate in place under epoch guards.
 - GC is permitted only on cold paths (driver, diagnostics, CLI).
-- `Context` accepts an **`ArenaAllocator` interface** so embedders can supply backing memory.
+- **Arena hooks are exposed**: `Context` accepts an **`ArenaAllocator` interface** (`allocate`/`reset`/`destroy`) so embedders can supply their own backing memory; a default bump allocator ships in-tree.
 
 ### 12.7 `Config`
 
@@ -740,10 +740,10 @@ Same `Config` + same input ⇒ byte-identical output, independent of thread coun
 
 ### 12.11 Resolutions
 
-- C API in v1 (thin shim).
-- Custom `ArenaAllocator` hooks exposed.
-- LDC2 primary + DMD secondary.
-- `dub` + no-dub build path.
+- Thin C API first (the primary public surface in v1).
+- `ArenaAllocator` hooks exposed.
+- LDC2 for release builds; DMD for debug builds.
+- `xmake` as the build system (not `dub`).
 
 ---