@forgeax/engine-devkit 0.1.3 → 0.1.6

package/dist/cli.mjs

@@ -11,7 +11,10 @@ import { fbxImporter } from '@forgeax/engine-fbx';
 import { fontImporter } from '@forgeax/engine-font/font-importer';
 import { gltfImporter } from '@forgeax/engine-gltf';
 import { imageImporter } from '@forgeax/engine-image/image-importer';
+import { BUILTIN_MESH_ASSETS } from '@forgeax/engine-pack/builtin';
+import { scanInventory } from '@forgeax/engine-pack/scanner';
 import { describeResourcePreviewFailure, validateCanonicalKitReceipt, createMaterialPreviewContribution, createMeshPreviewContribution, createVfxPreviewContribution, createTexturePreviewContribution, validatePreviewArtifactManifest } from '@forgeax/engine-preview';
+import { createMaterialPackCooker } from '@forgeax/engine-shader-compiler';
 import { createStandaloneRuntimeAssetBinding, ok, err } from '@forgeax/engine-types';
 import { createParticleCodeNativeCookerFromRoots } from '@forgeax/engine-vfx-compiler';
 import { pluginPack, reloadAssetHost } from '@forgeax/engine-vite-plugin-pack';
@@ -21,10 +24,12 @@ import { runCliGltf } from '@forgeax/engine-gltf/cli-gltf';
 import { scanEntries } from '@forgeax/engine-pack/cli-asset';
 import { AssetGuid } from '@forgeax/engine-pack/guid';
 import { execFile } from 'child_process';
+import { tmpdir } from 'os';
 import { promisify } from 'util';
 import { decodeTape, openReplay, buildFrameModel, createRhiDebugError } from '@forgeax/engine-rhi-debug';
-import { tmpdir } from 'os';
-import { build, createServer, preview } from 'vite';
+import { rhi, createShaderModule } from '@forgeax/engine-rhi-null';
+import { build, preview, createServer as createServer$1 } from 'vite';
+import { createServer } from 'net';
 import { startVitest } from 'vitest/node';
 import materialPreviewPlugin from '@forgeax/engine-preview/material';
 import meshPreviewPlugin from '@forgeax/engine-preview/mesh';
@@ -296,16 +301,17 @@ var init_dist = __esm({
   "src/dist.ts"() {
   }
 });
+
+// src/host.ts
+var host_exports = {};
+__export(host_exports, {
+  createViteConfig: () => createViteConfig,
+  devKitDdcRoots: () => devKitDdcRoots,
+  ignoreDevKitCatalogPath: () => ignoreDevKitCatalogPath
+});
 function ignoreDevKitCatalogPath(path) {
   const normalized = path.replace(/\\/g, "/");
-  if (normalized.split("/").includes("shaders")) return true;
-  if (!normalized.endsWith(".meta.json")) return false;
-  try {
-    const meta = JSON.parse(readFileSync(path, "utf8"));
-    return meta.importer === "game-default-target-profile";
-  } catch {
-    return false;
-  }
+  return normalized.split("/").includes("shaders");
 }
 function devKitDdcRoots(projectRoot2) {
   return {
@@ -319,6 +325,42 @@ function isResourcePreviewIgnoredPath(path) {
 function isProjectSourceIgnoredPath(path) {
   return ignoreDevKitCatalogPath(path) || path.endsWith(".wgsl.meta.json");
 }
+async function prepareBuiltinPack(projectRoots, generated, ignorePath) {
+  const inventory = await scanInventory(projectRoots, { ignorePath });
+  if (!inventory.ok) return void 0;
+  const declared = /* @__PURE__ */ new Set();
+  for (const declaration of inventory.value.declarations.values()) {
+    if (declaration.format === "pack.json") {
+      for (const asset of declaration.value.assets) declared.add(asset.guid.toLowerCase());
+      continue;
+    }
+    for (const asset of declaration.value.subAssets) declared.add(asset.guid.toLowerCase());
+  }
+  const missing = BUILTIN_MESH_ASSETS.filter((asset) => !declared.has(asset.guid.toLowerCase()));
+  if (missing.length === 0) return void 0;
+  const packPath = resolve(generated, "engine-builtins.pack.json");
+  await writeFile(
+    packPath,
+    `${JSON.stringify(
+      {
+        schemaVersion: "2.0.0",
+        kind: "internal-text-package",
+        assets: missing.map((asset) => ({
+          guid: asset.guid,
+          kind: "mesh",
+          payload: { geometry: asset.geometry },
+          refs: [],
+          artifacts: {}
+        }))
+      },
+      null,
+      2
+    )}
+`,
+    "utf8"
+  );
+  return packPath;
+}
 function findEngineWorkspaceRoot() {
   let cursor = dirname(fileURLToPath(import.meta.url));
   for (; ; ) {
@@ -334,6 +376,7 @@ async function engineWorkspacePackages() {
     const workspaceRoot = findEngineWorkspaceRoot();
     if (workspaceRoot === void 0) return /* @__PURE__ */ new Map();
     const packageRoot = resolve(workspaceRoot, "packages");
+    if (!existsSync(packageRoot)) return /* @__PURE__ */ new Map();
     const packages = /* @__PURE__ */ new Map();
     for (const entry of await readdir(packageRoot, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
@@ -428,6 +471,18 @@ async function createEngineWorkspaceResolver() {
     }
   };
 }
+async function consumerEngineAliases(projectRoot2) {
+  const root = resolve(projectRoot2, "node_modules", ".pnpm", "node_modules", "@forgeax");
+  try {
+    const entries2 = await readdir(root, { withFileTypes: true });
+    return entries2.filter((entry) => entry.isDirectory() && entry.name.startsWith("engine-")).map((entry) => ({
+      find: `@forgeax/${entry.name}`,
+      replacement: resolve(root, entry.name)
+    })).sort((a, b) => a.find.localeCompare(b.find));
+  } catch {
+    return [];
+  }
+}
 async function resolveCanonicalKit() {
   const packageJson = hostRequire.resolve("@forgeax/engine-preview/package.json");
   const root = resolve(packageJson, "..", "assets/canonical-kit");
@@ -502,6 +557,7 @@ function hostSource(facts, bootstrapRoot, canonicalEnvironmentGuid) {
   const plugins = bootstrapRoot === "resource-bootstrap" ? [] : [
     `webAudioPlugin()`,
     `audioPlugin()`,
+    `skinningPlugin()`,
     ...facts.physics === void 0 ? [] : [`physicsPlugin('${facts.physics === "2d" ? "rapier-2d" : "rapier-3d"}')`]
   ];
   const bootstrapPlugin = facts.bootstrapEntry === void 0 ? "" : `const bootstrapModule = await import(${JSON.stringify(
@@ -519,20 +575,24 @@ await app.pluginContext.plugin({
   },
 });`;
   return `import { forgeaxBundlerAdapter } from 'virtual:forgeax/bundler';
-import { createApp, createToolPreviewHost, createToolPreviewRecipe, fitToolPreviewCameraToAabb, gameHostPlugin, replayToolPreviewCapture } from '@forgeax/engine-app';
-import { createCatalogSource } from '@forgeax/engine-assets-runtime';
-import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine-plugin/loader';
-import { audioPlugin } from '@forgeax/engine-audio';
-import { webAudioPlugin } from '@forgeax/engine-audio-webaudio';
-import { physicsPlugin } from '@forgeax/engine-physics';
-import { createPrimitiveMesh } from '@forgeax/engine-geometry';
-import { createDevImportTransport } from '@forgeax/engine-runtime';
-import { mat4 } from '@forgeax/engine-math';
-import { CAMERA_PROJECTION_ORTHOGRAPHIC, Camera, DirectionalLight, Materials, MeshFilter, MeshRenderer, Skylight, SkyboxBackground, TONEMAP_NONE, TONEMAP_REINHARD_EXTENDED } from '@forgeax/engine-render';
-import { projectSceneAsset, Transform, worldInstantiateScene } from '@forgeax/engine-scene';
-import { createStandaloneRuntimeAssetBinding } from '@forgeax/engine-types';
-import { ParticleEffectPlayer, vfxGpuEffectContribution } from '@forgeax/engine-vfx';
-import { createVfxRuntimeHost } from '@forgeax/engine-vfx-render';
+import { createApp, createToolPreviewHost, createToolPreviewRecipe, fitToolPreviewCameraToAabb, gameHostPlugin, replayToolPreviewCapture } from '@forgeax/engine/app';
+import { createCatalogSource } from '@forgeax/engine/assets-runtime';
+import {
+  createRuntimeAssetImportTransport,
+  runtimeBinding,
+} from 'virtual:forgeax/pack-runtime';
+import { installCatalogLoader, projectPluginEntries } from '@forgeax/engine/plugin/loader';
+import { audioPlugin } from '@forgeax/engine/audio';
+import { webAudioPlugin } from '@forgeax/engine/audio-webaudio';
+import { physicsPlugin } from '@forgeax/engine/physics';
+import { skinningPlugin } from '@forgeax/engine/skinning';
+import { createPrimitiveMesh } from '@forgeax/engine/geometry';
+import { mat4 } from '@forgeax/engine/math';
+import { CAMERA_PROJECTION_ORTHOGRAPHIC, Camera, DirectionalLight, Materials, MeshFilter, MeshRenderer, Skylight, SkyboxBackground, TONEMAP_NONE, TONEMAP_REINHARD_EXTENDED } from '@forgeax/engine/render';
+import { Transform } from '@forgeax/engine/scene';
+import { type SceneAsset } from '@forgeax/engine/types';
+import { ParticleEffectPlayer, vfxGpuEffectContribution } from '@forgeax/engine/vfx';
+import { createVfxRuntimeHost } from '@forgeax/engine/vfx-render';
 
 const pluginCatalog = new Map([
 ${catalogModules(facts).map(
@@ -631,16 +691,39 @@ const resizeCanvas = () => {
 const resizeObserver = new ResizeObserver(resizeCanvas);
 resizeObserver.observe(canvas);
 resizeCanvas();
-const binding = import.meta.env.DEV
-  ? createStandaloneRuntimeAssetBinding(${JSON.stringify(facts.id)})
-  : undefined;
-const assetCatalog = binding === undefined
-  ? undefined
-  : createCatalogSource({ url: binding.catalogUrl, expectedScope: binding });
+const runtimeScopeBinding = runtimeBinding;
+if (runtimeScopeBinding === undefined) {
+  throw new Error('forgeax: Vite Pack runtime binding is required in the generated host');
+}
+const assetCatalog = createCatalogSource({
+  url: import.meta.env.DEV
+    ? runtimeScopeBinding.catalogUrl
+    : new URL('pack-index.json', document.baseURI).href,
+  ...(import.meta.env.DEV ? { expectedScope: runtimeScopeBinding } : {}),
+});
 const bundler = {
   ...forgeaxBundlerAdapter(),
-  ...(binding === undefined ? {} : { importTransport: createDevImportTransport(binding) }),
+  ...(import.meta.env.DEV
+    ? { importTransport: createRuntimeAssetImportTransport(runtimeScopeBinding) }
+    : {}),
 };
+const assetPreparation = new WeakMap();
+
+function prepareAssetRegistry(assets) {
+  const existing = assetPreparation.get(assets);
+  if (existing !== undefined) return existing;
+  const pending = (async () => {
+    assets.configureRuntimeBinding(runtimeScopeBinding);
+    assets.setCatalogSource(assetCatalog);
+    if (vfxRuntimeHost !== undefined) {
+      assets.installDecoder(vfxGpuEffectContribution.kind, vfxGpuEffectContribution.decoder);
+    }
+    const catalog = await assets.enumerateCatalog();
+    if (!catalog.ok) throw catalog.error;
+  })();
+  assetPreparation.set(assets, pending);
+  return pending;
+}
 
 function previewStable(value) {
   if (value instanceof ArrayBuffer) return 'ArrayBuffer:' + JSON.stringify(Array.from(new Uint8Array(value)));
@@ -701,13 +784,14 @@ async function previewOwnerFacts(assets, resource, payload) {
 }
 
 async function prepareProject(app) {
+await prepareAssetRegistry(app.assets);
 previewWorld = app.world;
 const assets = app.assets;
 let canonicalEnvironment;
 if (resource !== undefined) {
   if (resource.kind !== 'texture') {
     if (canonicalEnvironmentGuid === null) throw new Error('canonical preview environment is unavailable');
-    const environment = await assets.load(canonicalEnvironmentGuid, 'equirect');
+    const environment = await assets.loadByGuid(assets.parseGuid(canonicalEnvironmentGuid));
     if (!environment.ok) throw environment.error;
     if (environment.value.kind !== 'equirect') {
       throw new Error(\`canonical preview environment expected equirect, received \${environment.value.kind}\`);
@@ -722,7 +806,7 @@ if (resource !== undefined) {
     const attached = await vfxRuntimeHost.attachWorld({ world: app.world, assets });
     if (!attached.ok) throw attached.error;
   }
-  const loaded = await assets.load(resource.guid, resource.kind === 'vfx' ? 'particle-effect' : resource.kind);
+  const loaded = await assets.loadByGuid(assets.parseGuid(resource.guid));
   if (!loaded.ok) throw loaded.error;
   const payload = loaded.value;
   if (resource.kind === 'vfx' && payload.kind !== 'particle-effect') {
@@ -735,7 +819,7 @@ if (resource !== undefined) {
   const meshMaterialHandles = resource.kind === 'mesh' && payload.kind === 'mesh'
     ? await Promise.all(payload.materialSlots.map(async (slot) => {
         if (slot.defaultMaterial === undefined) return 0;
-        const material = await assets.load(slot.defaultMaterial, 'material');
+        const material = await assets.loadByGuid(assets.parseGuid(slot.defaultMaterial));
         if (!material.ok) throw material.error;
         if (material.value.kind !== 'material') {
           throw new Error('mesh material slot resolved to a non-material asset');
@@ -865,15 +949,13 @@ let defaultScene;
 let defaultSceneRoot;
 const defaultSceneGuid = ${JSON.stringify(facts.defaultScene)};
 if (defaultSceneGuid !== undefined) {
-  const loaded = await assets.load(defaultSceneGuid, 'scene');
+  const loaded = await assets.loadByGuid<SceneAsset>(assets.parseGuid(defaultSceneGuid));
   if (!loaded.ok) throw loaded.error;
-  const projected = await projectSceneAsset(app.world, loaded.value, (guid, kind) => assets.load(guid, kind));
-  if (!projected.ok) throw projected.error;
-  defaultScene = projected.value;
-  const handle = app.world.allocSharedRef('SceneAsset', projected.value);
-  const instantiated = worldInstantiateScene(app.world, handle);
+  defaultScene = loaded.value;
+  const handle = app.world.allocSharedRef('SceneAsset', loaded.value);
+  const instantiated = assets.instantiate<SceneAsset>(handle, app.world);
   if (!instantiated.ok) throw instantiated.error;
-  defaultSceneRoot = instantiated.value.root;
+  defaultSceneRoot = instantiated.value;
 }
 const uiRoot = document.querySelector('#game-ui');
 await app.pluginContext.plugin(gameHostPlugin({
@@ -912,8 +994,6 @@ if (query.has('forgeax-tool-replay')) {
     ...(resource === undefined ? {} : { resource }),
     canvas,
     app: {
-      ...(assetCatalog === undefined ? {} : { assetCatalog }),
-      ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
       plugins: [${plugins.join(", ")}],
       ...(vfxRuntimeHost === undefined ? {} : { features: [vfxRuntimeHost.feature] }),
     },
@@ -1018,12 +1098,16 @@ if (query.has('forgeax-tool-replay')) {
     window.addEventListener('pagehide', () => void host.value.dispose(), { once: true });
   }
 } else {
+  // WebDriver/headless browsers cannot satisfy the trusted-gesture requirement
+  // for pointer lock. Keep the game running and let its keyboard fallback own
+  // camera input; real browser users retain the normal click-to-lock path.
+  const pointerLockAllowed =
+    typeof navigator !== 'undefined' && navigator.webdriver === true ? () => false : undefined;
   const result = await createApp(
     canvas,
     {
-      ...(assetCatalog === undefined ? {} : { assetCatalog }),
-      ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
       plugins: [${plugins.join(", ")}],
+      ...(pointerLockAllowed === undefined ? {} : { pointerLockAllowed }),
     },
     bundler,
   );
@@ -1082,10 +1166,32 @@ function htmlSource(title) {
     <div id="app-shell"><canvas id="app"></canvas><div id="game-ui"></div></div><div id="forgeax-fatal" role="alert"></div>
     <script>
       (() => {
+        const formatStartupFailure = (reason) => {
+          if (reason instanceof Error) return reason.message;
+          if (reason !== null && typeof reason === 'object') {
+            const record = reason;
+            const lines = [];
+            for (const key of ['code', 'expected', 'hint']) {
+              if (typeof record[key] === 'string' && record[key].length > 0) {
+                lines.push(key + ': ' + record[key]);
+              }
+            }
+            const detail = record.detail;
+            if (detail !== null && typeof detail === 'object') {
+              for (const key of ['reason', 'guid']) {
+                if (typeof detail[key] === 'string' && detail[key].length > 0) {
+                  lines.push('detail.' + key + ': ' + detail[key]);
+                }
+              }
+            }
+            if (lines.length > 0) return lines.join('\\n');
+          }
+          return String(reason ?? 'Unknown startup failure');
+        };
         const show = (reason) => {
           const notice = document.querySelector('#forgeax-fatal');
           if (!(notice instanceof HTMLElement)) return;
-          const message = reason instanceof Error ? reason.message : String(reason ?? 'Unknown startup failure');
+          const message = formatStartupFailure(reason);
           notice.textContent = 'ForgeaX game failed to start.\\n' + message;
           notice.style.display = 'grid';
         };
@@ -1100,29 +1206,32 @@ function htmlSource(title) {
 }
 async function createViteConfig(facts, command2, base = "/", options = {}) {
   const bootstrapRoot = options.bootstrapRoot ?? "project-bootstrap";
-  const canonicalKit = bootstrapRoot === "resource-bootstrap" ? await resolveCanonicalKit() : void 0;
+  const canonicalKit = await resolveCanonicalKit();
   const generated = resolve(facts.root, ".forgeax", "generated");
   await mkdir(generated, { recursive: true });
+  const projectRoots = facts.assetRoots.map((root) => resolve(facts.root, root));
+  const ignorePath = bootstrapRoot === "resource-bootstrap" ? isResourcePreviewIgnoredPath : isProjectSourceIgnoredPath;
+  const builtinPack = await prepareBuiltinPack(projectRoots, generated, ignorePath);
   await Promise.all([
     writeFile(resolve(generated, "index.html"), htmlSource(facts.name)),
     writeFile(resolve(generated, "main.ts"), hostSource(facts, bootstrapRoot, canonicalKit?.guid))
   ]);
   const roots = [
-    ...facts.assetRoots.map((root) => resolve(facts.root, root)),
+    ...projectRoots,
+    ...builtinPack === void 0 ? [] : [builtinPack],
     ...canonicalKit === void 0 ? [] : [canonicalKit.root]
   ];
   const importers = [...projectImporters(facts)];
   const runtimeBinding = createStandaloneRuntimeAssetBinding(facts.id);
   const engineWorkspaceResolver = await createEngineWorkspaceResolver();
+  const consumerAliases = await consumerEngineAliases(facts.root);
   const plugins = [
     ...engineWorkspaceResolver === void 0 ? [] : [engineWorkspaceResolver],
     forgeaxShader(),
     pluginPack({
       roots,
-      base,
       runtimeBinding,
       ddc: devKitDdcRoots(facts.root),
-      scriptablePack: {},
       refresh: command2 === "serve" ? reloadAssetHost() : void 0,
       importers: [
         audioImporter,
@@ -1132,8 +1241,8 @@ async function createViteConfig(facts, command2, base = "/", options = {}) {
         fontImporter,
         ...importers
       ],
-      cookers: [createParticleCodeNativeCookerFromRoots(roots)],
-      ...bootstrapRoot === "resource-bootstrap" ? { ignorePath: isResourcePreviewIgnoredPath } : { ignorePath: isProjectSourceIgnoredPath }
+      cookers: [createMaterialPackCooker(roots), createParticleCodeNativeCookerFromRoots(roots)],
+      ignorePath
     })
   ];
   return {
@@ -1142,8 +1251,11 @@ async function createViteConfig(facts, command2, base = "/", options = {}) {
     configFile: false,
     publicDir: facts.assetPublicDir === void 0 ? false : resolve(facts.root, facts.assetPublicDir),
     plugins,
-    resolve: { dedupe: ["@forgeax/engine-app", "@forgeax/engine-ecs", "@forgeax/engine-runtime"] },
-    server: { fs: { allow: [facts.root, ...roots] } },
+    resolve: {
+      alias: consumerAliases,
+      dedupe: ["@forgeax/engine"]
+    },
+    server: { ...options.server, fs: { allow: [facts.root, ...roots] } },
     build: {
       target: "esnext",
       outDir: options.outDir ?? resolve(facts.root, "dist"),
@@ -1167,7 +1279,7 @@ async function readJson(path) {
 function firstUnsupportedStandaloneRealm(entries2, inheritedRealm = "engine") {
   for (const entry of entries2) {
     const realm = entry.realm ?? inheritedRealm ?? "engine";
-    if (realm === "host") return { id: entry.id, realm };
+    if (realm !== "engine") return { id: entry.id, realm };
     if (entry.group === true) {
       const unsupported = firstUnsupportedStandaloneRealm(
         entry.config,
@@ -1285,13 +1397,10 @@ async function readProjectFacts(rootInput = process.cwd()) {
     }
   };
 }
-function isCommandError(value) {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
-  const candidate = value;
-  return typeof candidate.code === "string" && typeof candidate.expected === "string" && typeof candidate.hint === "string" && candidate.detail !== null && typeof candidate.detail === "object" && !Array.isArray(candidate.detail);
-}
 function commandError(cause, fallbackCode) {
-  if (isCommandError(cause)) return cause;
+  if (cause !== null && typeof cause === "object" && "code" in cause && "expected" in cause && "hint" in cause && "detail" in cause) {
+    return cause;
+  }
   return {
     code: fallbackCode,
     expected: "the ForgeaX command to complete",
@@ -1303,16 +1412,33 @@ var init_project = __esm({
   "src/project.ts"() {
   }
 });
-function failure(error) {
-  return { ok: false, error };
+
+// src/types.ts
+function parseProjectPortOption(value, provided) {
+  if (!provided) return { ok: true, value: void 0 };
+  if (value !== void 0 && /^(0|[1-9]\d*)$/.test(value)) {
+    const port = Number(value);
+    if (Number.isSafeInteger(port) && port <= 65535) return { ok: true, value: port };
+  }
+  return {
+    ok: false,
+    error: {
+      code: "cli-parse-error",
+      expected: "--port to be 0 or an integer from 1 to 65535",
+      hint: "Omit --port for strict 5173, pass a positive port for a strict binding, or pass 0 for an OS-assigned port.",
+      detail: { option: "--port", received: value ?? null }
+    }
+  };
 }
-function producerFailure(stderr, fallback, detail) {
-  try {
-    const parsed = JSON.parse(stderr.at(-1) ?? "");
-    if (isCommandError(parsed)) return failure(parsed);
-  } catch {
+function resolveProjectPort(port) {
+  return { port: port ?? 5173, strictPort: port !== 0 };
+}
+var init_types = __esm({
+  "src/types.ts"() {
   }
-  return failure({ ...fallback, detail: { ...detail, diagnostic: stderr.join("\n") } });
+});
+function failure(error) {
+  return { ok: false, error };
 }
 async function sourcesAt(path) {
   const info = await stat(path);
@@ -1397,15 +1523,16 @@ async function addGltf(sourcePath, dryRun2) {
     stderrWrite: (line) => stderr.push(line)
   });
   if (exitCode !== 0) {
-    return producerFailure(
-      stderr,
-      {
+    try {
+      return failure(JSON.parse(stderr.at(-1) ?? ""));
+    } catch {
+      return failure({
         code: "asset-add-failed",
         expected: "the glTF producer to create or reuse a valid sidecar",
-        hint: "Inspect the glTF source and its external references."
-      },
-      { source: sourcePath }
-    );
+        hint: "Inspect the glTF source and its external references.",
+        detail: { source: sourcePath, diagnostic: stderr.join("\n") }
+      });
+    }
   }
   return { ok: true, value: { source: sourcePath, metaPath: `${sourcePath}.meta.json` } };
 }
@@ -1448,15 +1575,16 @@ async function entries(options) {
     { stdoutWrite: (line) => stdout.push(line), stderrWrite: (line) => stderr.push(line) }
   );
   if (!result.ok) {
-    return producerFailure(
-      stderr,
-      {
+    try {
+      return failure(JSON.parse(stderr.at(-1) ?? ""));
+    } catch {
+      return failure({
         code: "asset-authority-invalid",
         expected: "all asset roots and sidecars to pass the pack scanner",
-        hint: "Repair the first invalid asset authority reported by the scanner."
-      },
-      {}
-    );
+        hint: "Repair the first invalid asset authority reported by the scanner.",
+        detail: { diagnostic: stderr.join("\n") }
+      });
+    }
   }
   return { ok: true, value: { facts: facts.value, entries: result.value } };
 }
@@ -1541,7 +1669,6 @@ var init_package = __esm({
         "@forgeax/engine-audio-webaudio": "workspace:*",
         "@forgeax/engine-fbx": "workspace:*",
         "@forgeax/engine-font": "workspace:*",
-        "@forgeax/engine-geometry": "workspace:*",
         "@forgeax/engine-gltf": "workspace:*",
         "@forgeax/engine-image": "workspace:*",
         "@forgeax/engine-input": "workspace:*",
@@ -1551,6 +1678,7 @@ var init_package = __esm({
         "@forgeax/engine-preview": "workspace:*",
         "@forgeax/engine-project": "workspace:*",
         "@forgeax/engine-rhi-debug": "workspace:*",
+        "@forgeax/engine-rhi-null": "workspace:*",
         "@forgeax/engine-render": "workspace:*",
         "@forgeax/engine-render-graph": "workspace:*",
         "@forgeax/engine-runtime": "workspace:*",
@@ -1568,7 +1696,6 @@ var init_package = __esm({
         vitest: "4.1.5"
       },
       devDependencies: {
-        "@forgeax/engine-rhi-null": "workspace:*",
         "@types/node": "^20.14.0"
       },
       forgeax: {
@@ -1694,6 +1821,7 @@ function createInitPlan(facts, sdk) {
     value: {
       root: facts.root,
       version: sdk?.sdkVersion ?? devkitVersion,
+      ...sdk === void 0 ? {} : { pnpmVersion: sdk.requirements.pnpm },
       archiveBacked: sdk !== void 0,
       dependencyChanges,
       scriptChanges
@@ -1714,23 +1842,8 @@ async function applyInitPlan(facts, plan, options) {
   for (const change of plan.scriptChanges) scripts[change.name] = change.to;
   manifest.scripts = scripts;
   if (plan.archiveBacked) {
-    manifest.packageManager = "pnpm@10.33.2";
-    const pnpmValue = manifest.pnpm;
-    const pnpm = pnpmValue !== null && typeof pnpmValue === "object" ? pnpmValue : {};
-    manifest.pnpm = {
-      ...pnpm,
-      onlyBuiltDependencies: [
-        "@forgeax/engine-codec",
-        "@forgeax/engine-fbx",
-        "@forgeax/engine-wgpu-wasm",
-        "esbuild"
-      ],
-      supportedArchitectures: {
-        os: ["darwin", "linux", "win32"],
-        cpu: ["x64", "arm64"],
-        libc: ["glibc", "musl"]
-      }
-    };
+    if (plan.pnpmVersion === void 0) throw new Error("sdk-pnpm-version-missing");
+    manifest.packageManager = `pnpm@${plan.pnpmVersion}`;
   }
   await writeFile(resolve(facts.root, "package.json"), `${JSON.stringify(manifest, null, 2)}
 `);
@@ -1796,6 +1909,270 @@ var init_sdk = __esm({
   "src/sdk.ts"() {
   }
 });
+function agentOnboarding(sdk, projectRoot2) {
+  const root = projectRoot2 ?? sdk.root;
+  return {
+    read: [
+      resolve(root, "AGENTS.md"),
+      resolve(root, "skills", "forgeax-engine-sdk", "SKILL.md"),
+      resolve(root, "skills", "forgeax-engine-sdk", "references", "feature-catalog.md")
+    ],
+    next: projectRoot2 === void 0 ? {
+      cwd: root,
+      argv: ["node", "./bin/forgeax.mjs", "new", "../my-game"]
+    } : { cwd: root, argv: ["pnpm", "exec", "forgeax", "list", "--json"] }
+  };
+}
+function sdkInitPath(sdk) {
+  return resolve(sdk.root, ...SDK_INIT_PATH);
+}
+function commandFailure(code, expected, hint, detail = {}) {
+  return { ok: false, error: { code, expected, hint, detail } };
+}
+function sdkProjectInstallArgs(store) {
+  const common = [
+    "install",
+    "--frozen-lockfile",
+    "--ignore-scripts",
+    "--side-effects-cache=true",
+    "--child-concurrency=1"
+  ];
+  return store === void 0 ? common : [...common, "--offline", "--config.trust-lockfile=true", "--store-dir", store];
+}
+function sdkBootstrapInstallArgs(store) {
+  const common = [
+    "install",
+    "--frozen-lockfile",
+    "--child-concurrency=1",
+    "--side-effects-cache=true"
+  ];
+  return store === void 0 ? common : [...common, "--offline", "--config.trust-lockfile=true", "--store-dir", store];
+}
+function supportedPnpm(version) {
+  const [major = 0, minor = 0] = version.split(".").map(Number);
+  return major === 11 && minor >= 7;
+}
+async function currentPnpm() {
+  try {
+    const result = await execFileAsync("pnpm", ["--version"], { maxBuffer: 1024 * 1024 });
+    const version = result.stdout.trim();
+    if (version.length === 0) throw new Error("pnpm returned an empty version");
+    return { ok: true, value: version };
+  } catch (cause) {
+    return commandFailure(
+      "pnpm-unavailable",
+      "pnpm 11.7.0 or newer in the pnpm 11 line to be available on PATH",
+      "Install or activate pnpm 11, then rerun forgeax init from the SDK root.",
+      { reason: cause instanceof Error ? cause.message : String(cause) }
+    );
+  }
+}
+function matchesState(sdk, state) {
+  if (state === null || typeof state !== "object" || Array.isArray(state)) return false;
+  const value = state;
+  return value.schemaVersion === SDK_INIT_SCHEMA_VERSION && value.sdkVersion === sdk.manifest.sdkVersion && value.engineCommit === sdk.manifest.engineCommit && typeof value.pnpm === "string" && supportedPnpm(value.pnpm) && value.node === process.versions.node && value.platform === process.platform && value.arch === process.arch;
+}
+async function readSdkInitState(sdk) {
+  try {
+    const value = JSON.parse(await readFile(sdkInitPath(sdk), "utf8"));
+    return matchesState(sdk, value) ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function requireSdkInitialization(sdk) {
+  const state = await readSdkInitState(sdk);
+  if (state === void 0) {
+    return commandFailure(
+      "sdk-not-initialized",
+      "the downloaded SDK to be initialized for this Node/pnpm/platform tuple",
+      "Run ./bin/forgeax init from the SDK root once, then run forgeax new outside the SDK.",
+      {
+        sdkRoot: sdk.root,
+        sdkVersion: sdk.manifest.sdkVersion,
+        pnpm: sdk.manifest.requirements.pnpm,
+        node: process.versions.node,
+        platform: process.platform,
+        arch: process.arch
+      }
+    );
+  }
+  return { ok: true, value: state };
+}
+async function copyBootstrapInputs(sdk, root) {
+  const template = sdk.templates.get(sdk.defaultTemplate);
+  if (template === void 0) throw new Error("sdk-default-template-missing");
+  for (const name of ["package.json", "pnpm-lock.yaml", "pnpm-workspace.yaml"]) {
+    await cp(resolve(template, name), resolve(root, name));
+  }
+  try {
+    await cp(resolve(template, ".npmrc"), resolve(root, ".npmrc"));
+  } catch (cause) {
+    if (cause === null || typeof cause !== "object" || !("code" in cause) || cause.code !== "ENOENT") {
+      throw cause;
+    }
+  }
+}
+async function sdkInitCommand(sdk, options = {}) {
+  const pnpmResult = await currentPnpm();
+  if (!pnpmResult.ok) return pnpmResult;
+  if (!supportedPnpm(pnpmResult.value)) {
+    return commandFailure(
+      "pnpm-version-unsupported",
+      "pnpm >=11.7.0 <12",
+      "Activate pnpm 11.7.0 or newer in the pnpm 11 line, then rerun forgeax init.",
+      { actual: pnpmResult.value, expected: sdk.manifest.requirements.pnpm }
+    );
+  }
+  const state = {
+    schemaVersion: SDK_INIT_SCHEMA_VERSION,
+    sdkVersion: sdk.manifest.sdkVersion,
+    engineCommit: sdk.manifest.engineCommit,
+    pnpm: pnpmResult.value,
+    node: process.versions.node,
+    platform: process.platform,
+    arch: process.arch
+  };
+  const report = {
+    ...state,
+    root: sdk.root,
+    store: sdk.store === void 0 ? "registry" : "offline",
+    onboarding: agentOnboarding(sdk)
+  };
+  if (options.dryRun === true || options.install === false) return { ok: true, value: report };
+  let staging;
+  try {
+    staging = await mkdtemp(resolve(tmpdir(), "forgeax-sdk-init-"));
+    await copyBootstrapInputs(sdk, staging);
+    await execFileAsync("pnpm", sdkBootstrapInstallArgs(sdk.store), {
+      cwd: staging,
+      env: { ...process.env, CI: "true" },
+      maxBuffer: 16 * 1024 * 1024
+    });
+    await mkdir(resolve(sdk.root, ".forgeax"), { recursive: true });
+    await writeFile(sdkInitPath(sdk), `${JSON.stringify(state, null, 2)}
+`);
+    return { ok: true, value: report };
+  } catch (cause) {
+    return commandFailure(
+      "sdk-init-failed",
+      "the SDK dependency closure to install and build native packages successfully",
+      "Inspect the pnpm output, repair Node/pnpm or platform permissions, then rerun forgeax init from the SDK root.",
+      { reason: cause instanceof Error ? cause.message : String(cause), sdkRoot: sdk.root }
+    );
+  } finally {
+    if (staging !== void 0) await rm(staging, { recursive: true, force: true });
+  }
+}
+var execFileAsync, SDK_INIT_PATH, SDK_INIT_SCHEMA_VERSION;
+var init_sdk_bootstrap = __esm({
+  "src/sdk-bootstrap.ts"() {
+    execFileAsync = promisify(execFile);
+    SDK_INIT_PATH = [".forgeax", "sdk-init.json"];
+    SDK_INIT_SCHEMA_VERSION = "1.0.0";
+  }
+});
+
+// src/sdk-update.ts
+function parseVersion(version) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    version
+  );
+  if (match === null) return void 0;
+  const major = match[1];
+  const minor = match[2];
+  const patch = match[3];
+  if (major === void 0 || minor === void 0 || patch === void 0) return void 0;
+  const prerelease = match[4]?.split(".");
+  if (prerelease?.some(
+    (identifier) => identifier.length === 0 || /^\d+$/.test(identifier) && /^0\d+/.test(identifier)
+  )) {
+    return void 0;
+  }
+  return {
+    core: [major, minor, patch],
+    ...prerelease === void 0 ? {} : { prerelease }
+  };
+}
+function compareNumericIdentifier(current, latest) {
+  if (current.length !== latest.length) return latest.length > current.length ? 1 : -1;
+  if (current === latest) return 0;
+  return latest > current ? 1 : -1;
+}
+function comparePrerelease(current, latest) {
+  const length = Math.max(current.length, latest.length);
+  for (let index = 0; index < length; index += 1) {
+    const currentIdentifier = current[index];
+    const latestIdentifier = latest[index];
+    if (currentIdentifier === void 0) return 1;
+    if (latestIdentifier === void 0) return -1;
+    if (currentIdentifier === latestIdentifier) continue;
+    const currentNumeric = /^\d+$/.test(currentIdentifier);
+    const latestNumeric = /^\d+$/.test(latestIdentifier);
+    if (currentNumeric && latestNumeric) {
+      return compareNumericIdentifier(currentIdentifier, latestIdentifier);
+    }
+    if (currentNumeric !== latestNumeric) return latestNumeric ? -1 : 1;
+    return latestIdentifier > currentIdentifier ? 1 : -1;
+  }
+  return 0;
+}
+function newerSdkVersion(currentVersion, latestVersion) {
+  const current = parseVersion(currentVersion);
+  const latest = parseVersion(latestVersion);
+  if (current === void 0 || latest === void 0) return false;
+  for (let index = 0; index < current.core.length; index += 1) {
+    const precedence = compareNumericIdentifier(
+      current.core[index] ?? "0",
+      latest.core[index] ?? "0"
+    );
+    if (precedence !== 0) return precedence > 0;
+  }
+  if (current.prerelease !== void 0 && latest.prerelease === void 0) return true;
+  if (current.prerelease === void 0 || latest.prerelease === void 0) return false;
+  return comparePrerelease(current.prerelease, latest.prerelease) > 0;
+}
+function offline() {
+  return ["1", "true"].includes((process.env.npm_config_offline ?? "").toLowerCase());
+}
+async function checkSdkUpdate(currentVersion) {
+  if (process.env.FORGEAX_DISABLE_UPDATE_CHECK === "1") {
+    return { status: "skipped", currentVersion, reason: "disabled" };
+  }
+  if (offline()) return { status: "skipped", currentVersion, reason: "offline" };
+  try {
+    const registry = process.env.npm_config_registry ?? "https://registry.npmjs.org/";
+    const response = await fetch(
+      new URL("@forgeax%2Fengine-sdk", `${registry.replace(/\/$/, "")}/`),
+      {
+        headers: { accept: "application/vnd.npm.install-v1+json" },
+        signal: AbortSignal.timeout(2e3)
+      }
+    );
+    if (!response.ok) throw new Error(`registry-http-${response.status}`);
+    const metadata = await response.json();
+    const latestVersion = metadata["dist-tags"]?.latest;
+    if (typeof latestVersion !== "string") throw new Error("registry-latest-version-missing");
+    return newerSdkVersion(currentVersion, latestVersion) ? {
+      status: "available",
+      currentVersion,
+      latestVersion,
+      migrationRisk: UPDATE_MIGRATION_RISK
+    } : { status: "current", currentVersion, latestVersion };
+  } catch (cause) {
+    return {
+      status: "unavailable",
+      currentVersion,
+      reason: cause instanceof Error ? cause.message : String(cause)
+    };
+  }
+}
+var UPDATE_MIGRATION_RISK;
+var init_sdk_update = __esm({
+  "src/sdk-update.ts"() {
+    UPDATE_MIGRATION_RISK = "Install a newer SDK in a separate directory. Existing games remain pinned and are not migrated automatically; review release notes and migrate and test each game before changing its Engine version.";
+  }
+});
 function slash(path) {
   return path.split(sep).join("/");
 }
@@ -2161,6 +2538,20 @@ async function canonicalProspectivePath(path) {
     }
   }
 }
+async function configureSdkStore(root, store) {
+  if (store === void 0) return;
+  const path = resolve(root, ".npmrc");
+  let content = "";
+  try {
+    content = await readFile(path, "utf8");
+  } catch (cause) {
+    if (!isMissingPathError(cause)) throw cause;
+  }
+  const lines = content.split(/\r?\n/).filter((line) => line.trim().length > 0 && !/^\s*store-dir\s*=/.test(line));
+  lines.push(`store-dir=${store}`);
+  await writeFile(path, `${lines.join("\n")}
+`);
+}
 function containsOrEquals(parent, child) {
   const path = relative(parent, child);
   return path === "" || path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path);
@@ -2171,25 +2562,14 @@ function nodeSupported() {
 }
 function pnpmSupported(version) {
   const [major = 0, minor = 0] = version.split(".").map(Number);
-  return major === 10 && minor >= 33;
-}
-function sdkInstallArgs(store) {
-  if (store === void 0) return ["install", "--frozen-lockfile"];
-  return [
-    "install",
-    "--offline",
-    "--frozen-lockfile",
-    "--side-effects-cache=false",
-    "--store-dir",
-    store
-  ];
+  return major === 11 && minor >= 7;
 }
 async function doctorCommand(options = {}) {
   const facts = await readProjectFacts(options.root);
   if (!facts.ok) return facts;
   let pnpm;
   try {
-    pnpm = (await execFileAsync("pnpm", ["--version"], { cwd: facts.value.root })).stdout.trim();
+    pnpm = (await execFileAsync2("pnpm", ["--version"], { cwd: facts.value.root })).stdout.trim();
   } catch (cause) {
     return {
       ok: false,
@@ -2217,7 +2597,7 @@ async function doctorCommand(options = {}) {
       ok: false,
       error: {
         code: "pnpm-version-unsupported",
-        expected: "pnpm >=10.33.0 <11",
+        expected: "pnpm >=11.7.0 <12",
         hint: "Enable the packageManager-declared pnpm version with Corepack and retry.",
         detail: { actual: pnpm }
       }
@@ -2256,12 +2636,20 @@ async function doctorCommand(options = {}) {
   };
 }
 async function initCommand(options = {}) {
-  const facts = await readProjectFacts(options.root);
-  if (!facts.ok) return facts;
   try {
     const sdk = await findSdkContext();
+    const root = await canonicalProspectivePath(options.root ?? process.cwd());
+    if (sdk !== void 0 && root === await canonicalProspectivePath(sdk.root)) {
+      return sdkInitCommand(sdk, options);
+    }
+    const facts = await readProjectFacts(root);
+    if (!facts.ok) return facts;
     const plan = createInitPlan(facts.value, sdk?.manifest);
     if (!plan.ok) return plan;
+    if (sdk !== void 0 && options.dryRun !== true) {
+      const initialized = await requireSdkInitialization(sdk);
+      if (!initialized.ok) return initialized;
+    }
     const applied = await applyInitPlan(facts.value, plan.value, options);
     if (!applied.ok || options.dryRun === true) return applied;
     if (sdk !== void 0) {
@@ -2271,12 +2659,31 @@ async function initCommand(options = {}) {
         resolve(template, "pnpm-lock.yaml"),
         resolve(facts.value.root, "pnpm-lock.yaml")
       );
+      await copyFile(
+        resolve(template, "pnpm-workspace.yaml"),
+        resolve(facts.value.root, "pnpm-workspace.yaml")
+      );
+      try {
+        await readFile(resolve(facts.value.root, ".npmrc"), "utf8");
+      } catch (cause) {
+        if (!isMissingPathError(cause)) throw cause;
+        try {
+          await copyFile(resolve(template, ".npmrc"), resolve(facts.value.root, ".npmrc"));
+        } catch (templateCause) {
+          if (!isMissingPathError(templateCause)) throw templateCause;
+        }
+      }
       await copySdkSkills(sdk, facts.value.root);
       await installProjectSkills(facts.value.root, sdk.manifest);
+      await configureSdkStore(
+        facts.value.root,
+        sdk.store === void 0 ? void 0 : await canonicalProspectivePath(sdk.store)
+      );
     }
     if (options.install === false) return applied;
-    const installArgs = sdk === void 0 ? ["install", "--frozen-lockfile=false"] : sdkInstallArgs(sdk.store);
-    await execFileAsync("pnpm", installArgs, {
+    const store = sdk === void 0 || sdk.store === void 0 ? void 0 : await canonicalProspectivePath(sdk.store);
+    const installArgs = sdk === void 0 ? ["install", "--frozen-lockfile=false"] : sdkProjectInstallArgs(store);
+    await execFileAsync2("pnpm", installArgs, {
       cwd: facts.value.root,
       env: { ...process.env, CI: "true" },
       maxBuffer: 16 * 1024 * 1024
@@ -2354,12 +2761,15 @@ async function newCommand(options = {}) {
         value: { root, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
       };
     }
+    const initialized = await requireSdkInitialization(sdk);
+    if (!initialized.ok) return initialized;
     const parent = dirname(root);
     await mkdir(parent, { recursive: true });
     let staging = await mkdtemp(
       resolve(parent, `.${basename(root)}.forgeax-staging-`)
     );
     const committedNames = [];
+    let committed = false;
     try {
       for (const name of await readdir(template)) {
         await cp(resolve(template, name), resolve(staging, name), {
@@ -2370,14 +2780,12 @@ async function newCommand(options = {}) {
       }
       await copySdkSkills(sdk, staging);
       await installProjectSkills(staging, sdk.manifest);
-      await execFileAsync("pnpm", sdkInstallArgs(sdk.store), {
-        cwd: staging,
-        env: { ...process.env, CI: "true" },
-        maxBuffer: 16 * 1024 * 1024
-      });
+      const store = sdk.store === void 0 ? void 0 : await canonicalProspectivePath(sdk.store);
+      await configureSdkStore(staging, store);
       if (!targetExists) {
         await rename(staging, root);
         staging = void 0;
+        committedNames.push(...await readdir(root));
       } else {
         for (const name of await readdir(staging)) {
           await rename(resolve(staging, name), resolve(root, name));
@@ -2386,29 +2794,57 @@ async function newCommand(options = {}) {
         await rm(staging, { recursive: true, force: true });
         staging = void 0;
       }
+      committed = true;
+      await execFileAsync2("pnpm", sdkProjectInstallArgs(store), {
+        cwd: root,
+        env: { ...process.env, CI: "true" },
+        maxBuffer: 16 * 1024 * 1024
+      });
+      const sdkUpdate = await checkSdkUpdate(sdk.manifest.sdkVersion);
       return {
         ok: true,
-        value: { root, template: templateId, sdkVersion: sdk.manifest.sdkVersion }
+        value: {
+          root,
+          template: templateId,
+          sdkVersion: sdk.manifest.sdkVersion,
+          onboarding: agentOnboarding(sdk, root),
+          sdkUpdate
+        }
       };
     } catch (cause) {
       if (staging !== void 0) await rm(staging, { recursive: true, force: true });
-      await Promise.all(
-        committedNames.map((name) => rm(resolve(root, name), { recursive: true, force: true }))
-      );
+      if (committed) {
+        if (!targetExists) {
+          await rm(root, { recursive: true, force: true });
+          return { ok: false, error: commandError(cause, "project-create-failed") };
+        }
+        const cleanupNames = /* @__PURE__ */ new Set([...committedNames, "node_modules"]);
+        await Promise.all(
+          [...cleanupNames].map(
+            (name) => rm(resolve(root, name), { recursive: true, force: true })
+          )
+        );
+      } else {
+        await Promise.all(
+          committedNames.map((name) => rm(resolve(root, name), { recursive: true, force: true }))
+        );
+      }
       return { ok: false, error: commandError(cause, "project-create-failed") };
     }
   } catch (cause) {
     return { ok: false, error: commandError(cause, "project-create-failed") };
   }
 }
-var execFileAsync;
+var execFileAsync2;
 var init_bootstrap_commands = __esm({
   "src/bootstrap-commands.ts"() {
     init_init();
     init_project();
     init_sdk();
+    init_sdk_bootstrap();
+    init_sdk_update();
     init_skill_install();
-    execFileAsync = promisify(execFile);
+    execFileAsync2 = promisify(execFile);
   }
 });
 
@@ -2467,7 +2903,7 @@ function withoutEntry(entries2, id) {
 }
 async function mutateDependency(root, action, dependency) {
   if (dependency === void 0) return;
-  await execFileAsync2("pnpm", [action, dependency], { cwd: root, maxBuffer: 16 * 1024 * 1024 });
+  await execFileAsync3("pnpm", [action, dependency], { cwd: root, maxBuffer: 16 * 1024 * 1024 });
 }
 async function pluginInstallCommand(options) {
   const root = resolve(options.root ?? process.cwd());
@@ -2569,489 +3005,10 @@ async function pluginUninstallCommand(options) {
     };
   }
 }
-var execFileAsync2;
+var execFileAsync3;
 var init_plugin_authoring = __esm({
   "src/plugin-authoring.ts"() {
-    execFileAsync2 = promisify(execFile);
-  }
-});
-var RhiError;
-var init_dist2 = __esm({
-  "../rhi/dist/index.mjs"() {
-    RhiError = class extends Error {
-      code;
-      expected;
-      hint;
-      detail;
-      constructor(args2) {
-        super(`[RhiError ${args2.code}] expected: ${args2.expected}; hint: ${args2.hint}`);
-        this.name = "RhiError";
-        this.code = args2.code;
-        this.expected = args2.expected;
-        this.hint = args2.hint;
-        this.detail = args2.detail;
-      }
-    };
-  }
-});
-function readPassLabel(desc) {
-  if (desc && typeof desc.label === "string" && desc.label.length > 0) {
-    return desc.label;
-  }
-  return "<unnamed>";
-}
-function readRecord(handle) {
-  if (handle === null || typeof handle !== "object") return void 0;
-  const tagged = handle;
-  return tagged[BOOKKEEPING_KEY];
-}
-function isHandleDestroyed(handle) {
-  if (readRecord(handle)?.destroyed === true) {
-    return err(
-      new RhiError({
-        code: "destroy-after-destroy",
-        expected: "GPU buffer/texture handle has not been destroyed yet",
-        hint: "object already destroyed; track lifecycle in caller or check isDestroyed before re-destroy"
-      })
-    );
-  }
-  return ok(void 0);
-}
-function acquireCanvasContext(_canvas) {
-  return ok(new RhiNullCanvasContext());
-}
-function createShaderModule(_device, _desc) {
-  return Promise.resolve(ok({}));
-}
-function requestAdapter(_opts, _compatibleSurface) {
-  return Promise.resolve(ok(new RhiNullAdapter()));
-}
-var RhiNullRenderPassEncoder, RhiNullComputePassEncoder, DeviceCounter, RhiNullCommandEncoder, BOOKKEEPING_KEY, Bookkeeper, nextDeviceId, RhiNullDevice, EMPTY_FEATURES, EMPTY_LIMITS, NEVER, RhiNullQueue, RhiNullAdapter, RhiNullCanvasContext, rhi;
-var init_dist3 = __esm({
-  "../rhi-null/dist/index.mjs"() {
-    init_dist2();
-    RhiNullRenderPassEncoder = class {
-      /** Number of draw* calls issued on this pass (AC-06 readback). */
-      drawCount = 0;
-      bindGroupCount = 0;
-      /** Most recent setVertexBuffer / setBindGroup ownership validation; ok unless
-       *  a foreign handle was passed (AC-09 readback). */
-      lastValidation = ok(void 0);
-      bookkeeper;
-      counter;
-      passName;
-      constructor(bookkeeper, counter, passName) {
-        this.bookkeeper = bookkeeper;
-        this.counter = counter;
-        this.passName = passName;
-      }
-      setPipeline(_pipeline) {
-      }
-      setVertexBuffer(_slot, buffer, _offset, _size) {
-        this.lastValidation = this.bookkeeper.validateOwnership(buffer);
-      }
-      setIndexBuffer(_buffer, _format, _offset, _size) {
-      }
-      setBindGroup(_index, bindGroup, _dynamicOffsetsData, _dynamicOffsetsDataStart, _dynamicOffsetsDataLength) {
-        this.bindGroupCount++;
-        this.counter?.recordBindGroup();
-        this.lastValidation = this.bookkeeper.validateOwnership(bindGroup);
-      }
-      draw(_vertexCount, _instanceCount, _firstVertex, _firstInstance) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      drawIndexed(_indexCount, _instanceCount, _firstIndex, _baseVertex, _firstInstance) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      end() {
-        this.counter?.recordPassName(this.passName);
-      }
-      setViewport(_x, _y, _w, _h, _minDepth, _maxDepth) {
-      }
-      setScissorRect(_x, _y, _w, _h) {
-      }
-      setBlendConstant(_color) {
-      }
-      setStencilReference(_reference) {
-      }
-      drawIndirect(_indirectBuffer, _indirectOffset) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      drawIndexedIndirect(_indirectBuffer, _indirectOffset) {
-        this.drawCount++;
-        this.counter?.recordDraw();
-      }
-      pushDebugGroup(_groupLabel) {
-      }
-      popDebugGroup() {
-      }
-      insertDebugMarker(_markerLabel) {
-      }
-      executeBundles(_bundles) {
-        return ok(void 0);
-      }
-      beginOcclusionQuery(_queryIndex) {
-        return ok(void 0);
-      }
-      endOcclusionQuery() {
-        return ok(void 0);
-      }
-    };
-    RhiNullComputePassEncoder = class {
-      /** Number of dispatchWorkgroups calls issued on this pass (readback). */
-      dispatchCount = 0;
-      /** Most recent setBindGroup ownership validation (AC-09 readback). */
-      lastValidation = ok(void 0);
-      bookkeeper;
-      counter;
-      passName;
-      constructor(bookkeeper, counter, passName) {
-        this.bookkeeper = bookkeeper;
-        this.counter = counter;
-        this.passName = passName;
-      }
-      setPipeline(_pipeline) {
-      }
-      setBindGroup(_index, bindGroup, _dynamicOffsets) {
-        this.lastValidation = this.bookkeeper.validateOwnership(bindGroup);
-      }
-      dispatchWorkgroups(_x, _y, _z) {
-        this.dispatchCount++;
-        this.counter?.recordDispatch();
-      }
-      dispatchWorkgroupsIndirect(indirectBuffer, _indirectOffset) {
-        this.lastValidation = this.bookkeeper.validateOwnership(indirectBuffer);
-        this.dispatchCount++;
-        this.counter?.recordDispatch();
-      }
-      end() {
-        this.counter?.recordPassName(this.passName);
-      }
-    };
-    DeviceCounter = class {
-      constructor(device) {
-        this.device = device;
-      }
-      device;
-      recordDraw() {
-        this.device.totalDrawCount++;
-      }
-      recordDispatch() {
-        this.device.totalDispatchCount++;
-      }
-      recordBindGroup() {
-        this.device.totalBindGroupCount++;
-      }
-      recordPassName(name) {
-        this.device.framePassNames.push(name);
-      }
-    };
-    RhiNullCommandEncoder = class {
-      bookkeeper;
-      counter;
-      constructor(bookkeeper, device) {
-        this.bookkeeper = bookkeeper;
-        this.counter = new DeviceCounter(device);
-      }
-      beginRenderPass(desc) {
-        const label = readPassLabel(desc);
-        return new RhiNullRenderPassEncoder(this.bookkeeper, this.counter, label);
-      }
-      beginComputePass(desc) {
-        const label = readPassLabel(desc);
-        return new RhiNullComputePassEncoder(this.bookkeeper, this.counter, label);
-      }
-      copyBufferToBuffer(_source, _sourceOffsetOrDestination, _destinationOrSize, _destinationOffset, _size) {
-      }
-      copyBufferToTexture(_source, _destination, _copySize) {
-      }
-      copyTextureToBuffer(_source, _destination, _copySize) {
-      }
-      copyTextureToTexture(_source, _destination, _copySize) {
-      }
-      clearBuffer(_buffer, _offset, _size) {
-      }
-      resolveQuerySet(_querySet, _firstQuery, _queryCount, _destination, _destinationOffset) {
-        return ok(void 0);
-      }
-      writeTimestamp(_querySet, _queryIndex) {
-      }
-      pushDebugGroup(_groupLabel) {
-      }
-      popDebugGroup() {
-      }
-      insertDebugMarker(_markerLabel) {
-      }
-      finish() {
-        return ok(this.bookkeeper.register("CommandBuffer"));
-      }
-    };
-    BOOKKEEPING_KEY = /* @__PURE__ */ Symbol("forgeax-rhi-null-bookkeeping");
-    Bookkeeper = class {
-      deviceId;
-      nextHandleId = 0;
-      records = /* @__PURE__ */ new Map();
-      constructor(deviceId) {
-        this.deviceId = deviceId;
-      }
-      /**
-       * Register a freshly-minted handle of the given kind, returning a plain
-       * object that carries its ledger row. The caller casts the return value to
-       * the concrete brand (`as unknown as Buffer` etc.).
-       */
-      register(kind) {
-        const id = this.nextHandleId++;
-        const record = {
-          id,
-          kind,
-          destroyed: false,
-          sourceDeviceId: this.deviceId
-        };
-        this.records.set(id, record);
-        return { [BOOKKEEPING_KEY]: record };
-      }
-      /**
-       * Mark a handle destroyed. Fail-fasts on a second destroy
-       * ('destroy-after-destroy') or on a handle issued by a different device
-       * ('rhi-not-available'); otherwise flips the destroyed flag and returns ok.
-       */
-      destroy(handle) {
-        const ownership = this.validateOwnership(handle);
-        if (!ownership.ok) return ownership;
-        const destroyedCheck = isHandleDestroyed(handle);
-        if (!destroyedCheck.ok) return destroyedCheck;
-        ownership.value.destroyed = true;
-        return ok(void 0);
-      }
-      /**
-       * Report whether a handle has already been destroyed (true once destroy()
-       * has flipped its flag). Used by command-stream methods that must not
-       * consume a stale handle.
-       */
-      isDestroyed(handle) {
-        return readRecord(handle)?.destroyed === true;
-      }
-      /**
-       * Validate that a handle was issued by THIS device. Returns the ledger row on
-       * success so callers can mutate it (e.g. flip destroyed); returns
-       * 'rhi-not-available' for a foreign handle (AC-09 — no silent pass).
-       */
-      validateOwnership(handle) {
-        const record = readRecord(handle);
-        if (record === void 0 || record.sourceDeviceId !== this.deviceId) {
-          return err(
-            new RhiError({
-              code: "rhi-not-available",
-              expected: "handle was issued by this RhiNull device",
-              hint: "do not pass a handle created on a different RhiNull device into this device; create resources on the device they are used with"
-            })
-          );
-        }
-        return ok(record);
-      }
-      /**
-       * Return all ledger rows as a readonly array. M3 unit tests (w17) read this
-       * to assert create/destroy pairing, BGL/PSO shape counts, and resource
-       * lifecycle coverage (AC-05/06/07). Returns a snapshot of the current Map
-       * so callers can iterate without a stale reference after further mutations.
-       */
-      allRecords() {
-        return [...this.records.values()];
-      }
-      /** Report the total number of records in the ledger. */
-      recordCount() {
-        return this.records.size;
-      }
-    };
-    nextDeviceId = 0;
-    RhiNullDevice = class {
-      internalBookkeeper;
-      nullQueue;
-      encoderFactory;
-      /** Per-frame total draw count across all pass encoders executed this frame
-       *  (aggregated by the command encoder on finish, then reset). M3 unit tests
-       *  (w17) read this to assert draw count >= 1 (AC-06). */
-      totalDrawCount = 0;
-      /** Per-frame total direct and indirect compute dispatch count. */
-      totalDispatchCount = 0;
-      /** Per-frame total bind group set count (AC-06 / AC-05 readback). */
-      totalBindGroupCount = 0;
-      /** Per-frame pass names executed this frame, in schedule order (AC-04). */
-      framePassNames = [];
-      /** The per-device handle ledger — exposed so M3 tests can assert create/destroy
-       *  pairing and BGL/PSO shape counts (AC-05/06/07). */
-      get bookkeeper() {
-        return this.internalBookkeeper;
-      }
-      constructor(queue, encoderFactory) {
-        this.internalBookkeeper = new Bookkeeper(nextDeviceId++);
-        this.nullQueue = queue;
-        this.encoderFactory = encoderFactory;
-      }
-      get caps() {
-        return {
-          backendKind: "null",
-          compute: true,
-          timestampQuery: false,
-          timestampPeriodNanoseconds: null,
-          indirectDrawing: true,
-          textureCompressionBc: false,
-          textureCompressionEtc2: false,
-          textureCompressionAstc: false,
-          // 3 wgpu-native-only reserved flags stay false on non-native backends
-          // (D-5); the headless backend is not a native runtime.
-          multiDrawIndirect: false,
-          pushConstants: false,
-          textureBindingArray: false,
-          samplerAliasing: true,
-          firstInstanceIndirect: true,
-          storageBuffer: true,
-          storageTexture: true,
-          rgba16floatRenderable: true,
-          rg11b10ufloatRenderable: true,
-          float32Filterable: true,
-          maxColorAttachments: 8
-        };
-      }
-      get features() {
-        return EMPTY_FEATURES;
-      }
-      get limits() {
-        return EMPTY_LIMITS;
-      }
-      get queue() {
-        return this.nullQueue;
-      }
-      // forgeax-async-whitelist: dom-native — spec `GPUDevice.lost` Promise
-      // passthrough. The headless backend never loses a device (no GPU), so the
-      // Promise stays unsettled for the lifetime of the device, mirroring a live
-      // device that never transitions to the lost state.
-      get lost() {
-        return NEVER;
-      }
-      createBuffer(_desc) {
-        return ok(this.internalBookkeeper.register("Buffer"));
-      }
-      createTexture(_desc) {
-        return ok(this.internalBookkeeper.register("Texture"));
-      }
-      destroyBuffer(buf) {
-        return this.internalBookkeeper.destroy(buf);
-      }
-      destroyQuerySet(querySet) {
-        return this.internalBookkeeper.destroy(querySet);
-      }
-      destroyTexture(tex) {
-        return this.internalBookkeeper.destroy(tex);
-      }
-      createTextureView(_texture, _desc) {
-        return ok(this.internalBookkeeper.register("TextureView"));
-      }
-      createSampler(_desc) {
-        return ok(this.internalBookkeeper.register("Sampler"));
-      }
-      createBindGroupLayout(_desc) {
-        return ok(this.internalBookkeeper.register("BindGroupLayout"));
-      }
-      createBindGroup(_desc) {
-        return ok(this.internalBookkeeper.register("BindGroup"));
-      }
-      createPipelineLayout(_desc) {
-        return ok(this.internalBookkeeper.register("PipelineLayout"));
-      }
-      createRenderPipeline(_desc) {
-        return ok(this.makePipeline("RenderPipeline"));
-      }
-      createComputePipeline(_desc) {
-        return ok(this.makePipeline("ComputePipeline"));
-      }
-      createQuerySet(desc) {
-        if (desc.type === "timestamp") {
-          return err(
-            new RhiError({
-              code: "feature-not-enabled",
-              expected: "caps.timestampQuery === true (timestamp-query feature)",
-              hint: "RhiNull is structural-only and cannot produce GPU timestamp ticks"
-            })
-          );
-        }
-        return ok(this.internalBookkeeper.register("QuerySet"));
-      }
-      createCommandEncoder(_desc) {
-        return ok(this.encoderFactory(this.internalBookkeeper, this));
-      }
-      /**
-       * Mint a pipeline handle whose object also carries the no-op
-       * `getBindGroupLayout(index)` ops method (D-2). The prod auto-layout path
-       * (debug-draw.ts) and the existing mock unit tests both call
-       * `pipeline.getBindGroupLayout(n)`; returning a legal BindGroupLayout brand
-       * (recorded in the ledger) keeps those consumers from crashing on a missing
-       * method.
-       */
-      makePipeline(kind) {
-        const handle = this.internalBookkeeper.register(kind);
-        const getBindGroupLayout = (_index) => this.internalBookkeeper.register("BindGroupLayout");
-        return Object.assign(handle, { getBindGroupLayout });
-      }
-    };
-    EMPTY_FEATURES = /* @__PURE__ */ new Set();
-    EMPTY_LIMITS = {};
-    NEVER = new Promise(() => {
-    });
-    RhiNullQueue = class {
-      writeBuffer(_buffer, _bufferOffset, _data, _dataOffset, _size) {
-        return ok(void 0);
-      }
-      writeTexture(_destination, _data, _dataLayout, _size) {
-        return ok(void 0);
-      }
-      copyExternalImageToTexture(_source, _destination, _copySize) {
-        return ok(void 0);
-      }
-      submit(_commandBuffers) {
-        return ok(void 0);
-      }
-      // forgeax-async-whitelist: dom-native — spec `GPUQueue.onSubmittedWorkDone`
-      // never rejects. The headless backend has no pending GPU work, so it resolves
-      // immediately (AC-12: read-back idioms must not hang).
-      onSubmittedWorkDone() {
-        return Promise.resolve(void 0);
-      }
-    };
-    RhiNullAdapter = class {
-      features = /* @__PURE__ */ new Set();
-      limits = {};
-      // forgeax-async-whitelist is not needed: this returns Promise<Result<...>>
-      // per the spec contract; never rejects.
-      requestDevice(_opts) {
-        const device = new RhiNullDevice(
-          new RhiNullQueue(),
-          (bookkeeper, dev) => new RhiNullCommandEncoder(bookkeeper, dev)
-        );
-        return Promise.resolve(ok(device));
-      }
-    };
-    RhiNullCanvasContext = class {
-      configure(_desc) {
-        return ok(void 0);
-      }
-      unconfigure() {
-      }
-      getConfiguration() {
-        return void 0;
-      }
-      getCurrentTexture() {
-        return ok({});
-      }
-    };
-    rhi = {
-      requestAdapter,
-      acquireCanvasContext,
-      createShaderModule
-    };
+    execFileAsync3 = promisify(execFile);
   }
 });
 function createCliRhiDebugOperationContext() {
@@ -3059,7 +3016,7 @@ function createCliRhiDebugOperationContext() {
     captureFrame: async () => err(
       createRhiDebugError("capture-unavailable", {
         stage: "capture",
-        cause: "the standalone CLI has no live App capture provider"
+        cause: "the standalone CLI has no live App capture provider; start a recorder-enabled live host and invoke its rhiCapture root"
       })
     ),
     async readArtifact(artifact) {
@@ -3122,7 +3079,6 @@ function createCliRhiDebugOperationContext() {
 }
 var init_cli_context = __esm({
   "src/rhi-debug/cli-context.ts"() {
-    init_dist3();
   }
 });
 function createRhiDebugOperationContext(host) {
@@ -3427,7 +3383,7 @@ async function sdkInstallCommand(options) {
   try {
     staging = await mkdtemp(resolve(parent, `.${basename(root)}.forgeax-sdk-staging-`));
     download = await mkdtemp(resolve(parent, `.${basename(root)}.forgeax-sdk-download-`));
-    await execFileAsync3(
+    await execFileAsync4(
       process.env.FORGEAX_NPM_CLIENT ?? "npm",
       [
         "install",
@@ -3460,7 +3416,15 @@ async function sdkInstallCommand(options) {
         await rename(resolve(staging, name), resolve(root, name));
       }
     }
-    return { ok: true, value: { root, sdkVersion: version, source: "@forgeax/engine-sdk" } };
+    return {
+      ok: true,
+      value: {
+        root,
+        sdkVersion: version,
+        source: "@forgeax/engine-sdk",
+        next: { cwd: root, argv: ["node", "./bin/forgeax.mjs", "init"] }
+      }
+    };
   } catch (cause) {
     return { ok: false, error: commandError(cause, "sdk-install-failed") };
   } finally {
@@ -3468,11 +3432,11 @@ async function sdkInstallCommand(options) {
     if (download !== void 0) await rm(download, { recursive: true, force: true });
   }
 }
-var execFileAsync3;
+var execFileAsync4;
 var init_sdk_install = __esm({
   "src/sdk-install.ts"() {
     init_project();
-    execFileAsync3 = promisify(execFile);
+    execFileAsync4 = promisify(execFile);
   }
 });
 async function shaderCheckCommand(options = {}) {
@@ -3543,6 +3507,21 @@ __export(commands_exports, {
 function runRhiDebugCommand(name, input, context) {
   return runRhiDebugOperation(name, input, context);
 }
+async function materializeViteDevPort(port) {
+  if (port !== 0) return port;
+  const reservation = createServer();
+  await new Promise((resolveListen, rejectListen) => {
+    reservation.once("error", rejectListen);
+    reservation.listen(0, "127.0.0.1", resolveListen);
+  });
+  const address = reservation.address();
+  const assigned = typeof address === "object" && address !== null ? address.port : 0;
+  await new Promise((resolveClose, rejectClose) => {
+    reservation.close((error) => error === void 0 ? resolveClose() : rejectClose(error));
+  });
+  if (assigned === 0) throw new Error("OS did not assign an ephemeral preview port");
+  return assigned;
+}
 async function buildCommand(options = {}) {
   const facts = await readProjectFacts(options.root);
   if (!facts.ok) return facts;
@@ -3645,13 +3624,38 @@ async function devCommand(options = {}) {
   const facts = await readProjectFacts(options.root);
   if (!facts.ok) return facts;
   const previous = process.cwd();
+  let server;
   try {
+    const { createServer: createServer2 } = await import('vite');
+    const { createViteConfig: createViteConfig2 } = await Promise.resolve().then(() => (init_host(), host_exports));
+    const port = resolveProjectPort(options.port);
+    const vitePort = { ...port, port: await materializeViteDevPort(port.port) };
     process.chdir(facts.value.root);
-    const server = await createServer(await createViteConfig(facts.value, "serve"));
-    await server.listen();
+    server = await createServer2(
+      await createViteConfig2(facts.value, "serve", "/", {
+        server: vitePort
+      })
+    );
+    await server.listen(vitePort.port);
     if (options.json !== true) server.printUrls();
-    return { ok: true, value: { root: facts.value.root, urls: server.resolvedUrls } };
+    return {
+      ok: true,
+      value: {
+        root: facts.value.root,
+        urls: server.resolvedUrls,
+        mode: "dev",
+        serves: "source",
+        capabilities: {
+          "rhi.capture": {
+            available: false,
+            realm: "host",
+            reason: "standalone-dev-server-has-no-live-app-cli-attachment"
+          }
+        }
+      }
+    };
   } catch (cause) {
+    await server?.close();
     process.chdir(previous);
     return { ok: false, error: commandError(cause, "dev-server-failed") };
   }
@@ -3661,15 +3665,31 @@ async function previewCommand(options = {}) {
   const verified = await verifyDist(resolve(root, "dist"));
   if (!verified.ok) return verified;
   try {
+    const port = resolveProjectPort(options.port);
     const server = await preview({
       root,
       configFile: false,
       base: verified.value.base,
-      preview: { open: false, port: 0, strictPort: false },
+      preview: { open: false, ...port },
       build: { outDir: resolve(root, "dist") }
     });
     if (options.json !== true) server.printUrls();
-    return { ok: true, value: { root, urls: server.resolvedUrls } };
+    return {
+      ok: true,
+      value: {
+        root,
+        urls: server.resolvedUrls,
+        mode: "preview",
+        serves: "dist",
+        capabilities: {
+          "rhi.capture": {
+            available: false,
+            realm: "host",
+            reason: "static-dist-host-does-not-install-dev-capture"
+          }
+        }
+      }
+    };
   } catch (cause) {
     return { ok: false, error: commandError(cause, "preview-server-failed") };
   }
@@ -3719,6 +3739,7 @@ var init_commands = __esm({
     init_dist();
     init_host();
     init_project();
+    init_types();
     init_assets();
     init_bootstrap_commands();
     init_plugin_authoring();
@@ -4091,7 +4112,7 @@ function hasStaticToolDeclarations(entry) {
   return Array.isArray(Reflect.get(entry.config, "tools"));
 }
 async function createViteModuleLoader(root) {
-  const server = await createServer({
+  const server = await createServer$1({
     root,
     appType: "custom",
     configFile: false,
@@ -4293,7 +4314,7 @@ __export(contributions_exports, {
   createBuildContribution: () => createBuildContribution,
   createDefaultContributions: () => createDefaultContributions
 });
-function commandFailure(error) {
+function commandFailure2(error) {
   return { ok: false, error: { ...error, detail: error.detail } };
 }
 function createBuildContribution(projectRoot2 = process.cwd()) {
@@ -4302,7 +4323,7 @@ function createBuildContribution(projectRoot2 = process.cwd()) {
     async (options) => {
       const { buildCommand: buildCommand2 } = await Promise.resolve().then(() => (init_commands(), commands_exports));
       const result = await buildCommand2({ ...options, root: options.root ?? projectRoot2 });
-      return result.ok ? result.value : commandFailure(result.error);
+      return result.ok ? result.value : commandFailure2(result.error);
     }
   );
 }
@@ -4312,7 +4333,7 @@ function createAuthorContribution(projectRoot2 = process.cwd()) {
     async (options) => {
       const { pluginInstallCommand: pluginInstallCommand2 } = await Promise.resolve().then(() => (init_plugin_authoring(), plugin_authoring_exports));
       const result = await pluginInstallCommand2({ ...options, root: options.root ?? projectRoot2 });
-      return result.ok ? result.value : commandFailure(result.error);
+      return result.ok ? result.value : commandFailure2(result.error);
     }
   );
 }
@@ -4348,6 +4369,36 @@ var init_runtime = __esm({
   }
 });
 
+// src/cli-output.ts
+function agentOnboardingLines(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return [];
+  const onboarding = value.onboarding;
+  if (onboarding === null || typeof onboarding !== "object" || Array.isArray(onboarding)) return [];
+  const candidate = onboarding;
+  const lines = Array.isArray(candidate.read) ? candidate.read.filter((path) => typeof path === "string").map((path) => `[forgeax] read: ${path}`) : [];
+  if (typeof candidate.next?.cwd === "string" && Array.isArray(candidate.next.argv) && candidate.next.argv.every((part) => typeof part === "string")) {
+    lines.push(`[forgeax] next cwd: ${candidate.next.cwd}`);
+    lines.push(`[forgeax] next: ${candidate.next.argv.join(" ")}`);
+  }
+  return lines;
+}
+function sdkUpdateLines(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return [];
+  const update = value.sdkUpdate;
+  if (update === null || typeof update !== "object" || Array.isArray(update)) return [];
+  const candidate = update;
+  if (candidate.status !== "available" || typeof candidate.currentVersion !== "string" || typeof candidate.latestVersion !== "string" || typeof candidate.migrationRisk !== "string") {
+    return [];
+  }
+  return [
+    `[forgeax] update available: @forgeax/engine-sdk ${candidate.currentVersion} -> ${candidate.latestVersion}`,
+    `[forgeax] update note: ${candidate.migrationRisk}`
+  ];
+}
+function renderForgeaxUsage() {
+  return "Usage: forgeax new [directory] [--template empty|game-default]\n       forgeax <init|doctor|test|dev|build|package|serve|preview> [directory]\n       forgeax package [directory] [--output release/game-web.zip]\n       forgeax run <rhi.capture|rhi.summary|rhi.inspect> [options]\n       forgeax run <operation-id> --input <request.json>\n       forgeax asset <add|verify|inspect|list> [subject]\n       forgeax shader check [path]\n       forgeax plugin <install|uninstall> <module-or-id> [options]\n       forgeax skill <install|verify> [--root directory]\n       forgeax sdk install <directory> [--version VERSION]\n";
+}
+
 // src/cli.ts
 init_commands();
 
@@ -4547,13 +4598,16 @@ async function execCommand(options) {
 }
 
 // src/cli.ts
-var args = process.argv.slice(2);
+init_types();
+var rawArgs = process.argv.slice(2);
+var args = [...rawArgs];
 var primary = args.shift();
 var nested = primary === "asset" || primary === "shader" || primary === "plugin" || primary === "skill" || primary === "sdk" ? args.shift() : void 0;
 var command = primary === "asset" || primary === "shader" || primary === "plugin" || primary === "skill" || primary === "sdk" ? `${primary}.${nested ?? ""}` : primary;
 var json = args.includes("--json");
 var dryRun = args.includes("--dry-run");
 var noInstall = args.includes("--no-install");
+var help = rawArgs.includes("--help") || rawArgs.includes("-h");
 function option(name) {
   const index = args.indexOf(name);
   return index < 0 ? void 0 : args[index + 1];
@@ -4570,6 +4624,7 @@ var optionValueIndexes = new Set(
     "--input",
     "--output",
     "--root",
+    "--port",
     "--template",
     "--version",
     "--work-index"
@@ -4608,6 +4663,18 @@ var commands = [
   "describe",
   "exec"
 ];
+function projectServerOptions() {
+  const parsedPort = parseProjectPortOption(option("--port"), args.includes("--port"));
+  if (!parsedPort.ok) return parsedPort;
+  return {
+    ok: true,
+    value: {
+      root: projectRoot,
+      json,
+      ...parsedPort.value === void 0 ? {} : { port: parsedPort.value }
+    }
+  };
+}
 async function run(value) {
   switch (value) {
     case "new": {
@@ -4624,8 +4691,10 @@ async function run(value) {
       return doctorCommand({ root: projectRoot});
     case "test":
       return testCommand({ root: projectRoot});
-    case "dev":
-      return devCommand({ root: projectRoot, json });
+    case "dev": {
+      const options = projectServerOptions();
+      return options.ok ? devCommand(options.value) : options;
+    }
     case "build": {
       const base = option("--base");
       const outDir = option("--out-dir");
@@ -4643,10 +4712,14 @@ async function run(value) {
         ...output === void 0 ? {} : { output }
       });
     }
-    case "preview":
-      return previewCommand({ root: projectRoot, json });
-    case "serve":
-      return devCommand({ root: projectRoot, json });
+    case "preview": {
+      const options = projectServerOptions();
+      return options.ok ? previewCommand(options.value) : options;
+    }
+    case "serve": {
+      const options = projectServerOptions();
+      return options.ok ? devCommand(options.value) : options;
+    }
     case "plugin.install": {
       const module = positionals[0];
       const id = option("--id");
@@ -4823,10 +4896,10 @@ async function run(value) {
     }
   }
 }
-if (command === void 0 || !commands.includes(command)) {
-  process.stderr.write(
-    "Usage: forgeax new [directory] [--template empty|game-default]\n       forgeax <init|doctor|test|dev|build|package|serve|preview> [directory]\n       forgeax package [directory] [--output release/game-web.zip]\n       forgeax run <rhi.capture|rhi.summary|rhi.inspect> [options]\n       forgeax run <operation-id> --input <request.json>\n       forgeax asset <add|verify|inspect|list> [subject]\n       forgeax shader check [path]\n       forgeax plugin <install|uninstall> <module-or-id> [options]\n       forgeax skill <install|verify> [--root directory]\n       forgeax sdk install <directory> [--version VERSION]\n"
-  );
+if (help && primary !== "run") {
+  process.stdout.write(renderForgeaxUsage());
+} else if (command === void 0 || !commands.includes(command)) {
+  process.stderr.write(renderForgeaxUsage());
   process.exitCode = 2;
 } else {
   const stdoutWrite = process.stdout.write;
@@ -4846,9 +4919,23 @@ if (command === void 0 || !commands.includes(command)) {
   const envelope = result.ok ? { schemaVersion: "1.0.0", command, ok: true, value: result.value } : { schemaVersion: "1.0.0", command, ok: false, error: result.error };
   if (json) stdoutWrite.call(process.stdout, `${JSON.stringify(envelope)}
 `);
-  else if (result.ok) process.stdout.write(`[forgeax] ${command} ready
+  else if (result.ok) {
+    process.stdout.write(`[forgeax] ${command} ready
+`);
+    for (const line of agentOnboardingLines(result.value)) process.stdout.write(`${line}
 `);
-  else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
+    for (const line of sdkUpdateLines(result.value)) process.stdout.write(`${line}
+`);
+    if (command === "sdk.install") {
+      const value = result.value;
+      if (typeof value.next?.cwd === "string" && Array.isArray(value.next.argv) && value.next.argv.every((part) => typeof part === "string")) {
+        process.stdout.write(`[forgeax] next cwd: ${value.next.cwd}
+`);
+        process.stdout.write(`[forgeax] next: ${value.next.argv.join(" ")}
+`);
+      }
+    }
+  } else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
 `);
   if (!result.ok) process.exitCode = result.error.code === "cli-parse-error" ? 2 : 1;
 }