@forgeax/engine-devkit 0.1.3 → 0.1.6

package/README.md

@@ -36,16 +36,28 @@ forgeax list --json
 forgeax describe project.build --json
 forgeax run project.build --input request.json --json
 forgeax exec program.mjs --json
-forgeax run rhi.capture
-forgeax run rhi.summary --artifact {ArtifactRef}
-forgeax run rhi.inspect --artifact {ArtifactRef} --work-index {workIndex}
+forgeax run rhi.summary --artifact .forgeax-debug/{runId}/frame.rhitape --digest {sha256}
+forgeax run rhi.inspect --artifact .forgeax-debug/{runId}/frame.rhitape --digest {sha256} --work-index {workIndex}
 ```
 
+> [!IMPORTANT]
+> `forgeax dev` is a source-development server and `forgeax preview` is a
+> verified static `dist/` server. Their `--json` startup envelopes expose
+> `mode`, `serves`, and the current `rhi.capture` capability. Neither command
+> silently invents a live capture attachment.
+
 Static deployment is an Engine-owned build product. A publishing host supplies
 the project root, public URL base, and dedicated output directory; DevKit owns
 the generated host, asset cooking, shader compilation, Pack index, and
 `forgeax-dist.json` closure.
 
+> [!IMPORTANT]
+> DevKit also closes the Engine builtin-mesh dependency boundary. During a
+> standalone build it adds a generated Pack descriptor only for builtin mesh
+> GUIDs absent from the project; the Geometry decoder turns those descriptors
+> into validated primitive meshes. Project-authored descriptors remain the
+> single declaration, so the generated Pack never creates a GUID collision.
+
 ```bash
 forgeax build ./games/my-game \
   --base /games/my-game/ \
@@ -78,13 +90,23 @@ through to another realm.
 
 ## RHI-debug operations
 
+The operation manifest describes the complete host contract, but a standalone
+CLI process does not own a running browser App. Consequently,
+`forgeax run rhi.capture --json` is a structured capability probe and returns
+`capture-unavailable` until a recorder-enabled live host supplies the
+`rhiCapture` eval root. Use the browser live bridge described by the
+`forgeax-engine-cli` skill to invoke that root; preserve the resulting tape's
+`digest` and `path` for the offline commands below. `rhi.summary` and
+`rhi.inspect` remain directly executable because they consume the persisted
+artifact rather than live App state.
+
 ```mermaid
 sequenceDiagram
   participant AI as "AI or CLI"
   participant H as "Host"
   participant D as "DevKit"
   participant R as "Fresh replay backend"
-  AI->>H: "rhi.capture"
+  AI->>H: "rhiCapture.captureFrame through the live host"
   H-->>AI: "one ArtifactRef"
   AI->>D: "rhi.summary + ArtifactRef"
   D-->>AI: "FrameModel and workIndex"
@@ -140,6 +162,10 @@ RhiNull readiness are not visual proof.
 Game projects keep authority in `forge.json`, package manifests,
 `package.json#forgeax.assets`, source Meta/Pack files, and imported game code.
 DevKit derives Vite and producer assembly from those facts.
+The [asset authority audit schema](../../asset-authority.schema.json) records
+the subject, execution, lifecycle, and runtime boundary for each producer; use
+the producer's inspect/rebuild or cold-cook evidence when a derived Catalog is
+stale instead of treating the runtime projection as author authority.
 
 `forge.json#entry` is the required game bootstrap authority. When that module
 is not also named by `forge.json.plugins[]`, DevKit adapts its named