@forgeax/engine-devkit 0.1.4 → 0.1.6

package/dist/cli.mjs

@@ -27,7 +27,9 @@ import { execFile } from 'child_process';
 import { tmpdir } from 'os';
 import { promisify } from 'util';
 import { decodeTape, openReplay, buildFrameModel, createRhiDebugError } from '@forgeax/engine-rhi-debug';
-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';
@@ -299,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 {
@@ -574,17 +577,20 @@ 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 {
+  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 { 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 { 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';
 
@@ -685,17 +691,39 @@ const resizeCanvas = () => {
 const resizeObserver = new ResizeObserver(resizeCanvas);
 resizeObserver.observe(canvas);
 resizeCanvas();
-const runtimeScopeBinding = createStandaloneRuntimeAssetBinding(${JSON.stringify(facts.id)});
+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,
-  expectedScope: runtimeScopeBinding,
+  ...(import.meta.env.DEV ? { expectedScope: runtimeScopeBinding } : {}),
 });
 const bundler = {
   ...forgeaxBundlerAdapter(),
-  ...(import.meta.env.DEV ? { importTransport: createDevImportTransport(runtimeScopeBinding) } : {}),
+  ...(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)));
@@ -756,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}\`);
@@ -777,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') {
@@ -790,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');
@@ -920,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({
@@ -967,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] }),
     },
@@ -1081,8 +1106,6 @@ if (query.has('forgeax-tool-replay')) {
   const result = await createApp(
     canvas,
     {
-      ...(assetCatalog === undefined ? {} : { assetCatalog }),
-      ...(vfxRuntimeHost === undefined ? {} : { assetDecoders: [vfxGpuEffectContribution] }),
       plugins: [${plugins.join(", ")}],
       ...(pointerLockAllowed === undefined ? {} : { pointerLockAllowed }),
     },
@@ -1230,9 +1253,9 @@ async function createViteConfig(facts, command2, base = "/", options = {}) {
     plugins,
     resolve: {
       alias: consumerAliases,
-      dedupe: ["@forgeax/engine-app", "@forgeax/engine-ecs", "@forgeax/engine-runtime"]
+      dedupe: ["@forgeax/engine"]
     },
-    server: { fs: { allow: [facts.root, ...roots] } },
+    server: { ...options.server, fs: { allow: [facts.root, ...roots] } },
     build: {
       target: "esnext",
       outDir: options.outDir ?? resolve(facts.root, "dist"),
@@ -1256,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,
@@ -1374,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",
@@ -1392,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);
@@ -1486,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` } };
 }
@@ -1537,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 } };
 }
@@ -1630,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:*",
@@ -1640,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:*",
@@ -1657,7 +1696,6 @@ var init_package = __esm({
         vitest: "4.1.5"
       },
       devDependencies: {
-        "@forgeax/engine-rhi-null": "workspace:*",
         "@types/node": "^20.14.0"
       },
       forgeax: {
@@ -1871,6 +1909,20 @@ 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);
 }
@@ -1885,7 +1937,7 @@ function sdkProjectInstallArgs(store) {
     "--side-effects-cache=true",
     "--child-concurrency=1"
   ];
-  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+  return store === void 0 ? common : [...common, "--offline", "--config.trust-lockfile=true", "--store-dir", store];
 }
 function sdkBootstrapInstallArgs(store) {
   const common = [
@@ -1894,7 +1946,7 @@ function sdkBootstrapInstallArgs(store) {
     "--child-concurrency=1",
     "--side-effects-cache=true"
   ];
-  return store === void 0 ? common : [...common, "--offline", "--trust-lockfile", "--store-dir", store];
+  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);
@@ -1984,7 +2036,8 @@ async function sdkInitCommand(sdk, options = {}) {
   const report = {
     ...state,
     root: sdk.root,
-    store: sdk.store === void 0 ? "registry" : "offline"
+    store: sdk.store === void 0 ? "registry" : "offline",
+    onboarding: agentOnboarding(sdk)
   };
   if (options.dryRun === true || options.install === false) return { ok: true, value: report };
   let staging;
@@ -2019,6 +2072,107 @@ var init_sdk_bootstrap = __esm({
     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("/");
 }
@@ -2646,9 +2800,16 @@ async function newCommand(options = {}) {
         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 });
@@ -2681,6 +2842,7 @@ var init_bootstrap_commands = __esm({
     init_project();
     init_sdk();
     init_sdk_bootstrap();
+    init_sdk_update();
     init_skill_install();
     execFileAsync2 = promisify(execFile);
   }
@@ -2849,491 +3011,12 @@ var init_plugin_authoring = __esm({
     execFileAsync3 = 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
-    };
-  }
-});
 function createCliRhiDebugOperationContext() {
   return {
     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) {
@@ -3396,7 +3079,6 @@ function createCliRhiDebugOperationContext() {
 }
 var init_cli_context = __esm({
   "src/rhi-debug/cli-context.ts"() {
-    init_dist3();
   }
 });
 function createRhiDebugOperationContext(host) {
@@ -3734,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 {
@@ -3817,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;
@@ -3919,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") };
   }
@@ -3935,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") };
   }
@@ -3993,6 +3739,7 @@ var init_commands = __esm({
     init_dist();
     init_host();
     init_project();
+    init_types();
     init_assets();
     init_bootstrap_commands();
     init_plugin_authoring();
@@ -4365,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,
@@ -4622,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();
 
@@ -4821,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];
@@ -4844,6 +4624,7 @@ var optionValueIndexes = new Set(
     "--input",
     "--output",
     "--root",
+    "--port",
     "--template",
     "--version",
     "--work-index"
@@ -4882,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": {
@@ -4898,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");
@@ -4917,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");
@@ -5097,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;
@@ -5120,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}
+`);
+    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}
 `);
-  else process.stderr.write(`[forgeax] ${result.error.code}: ${result.error.hint}
+        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;
 }