@forgeax/game 0.3.0 → 0.3.1

package/README.md

@@ -54,12 +54,16 @@ unknown non-empty directories fail closed.
 
 > [!NOTE]
 > Asset3D is optional and **disabled by default**. The two commands above never contact
-> the internal asset catalog, download a platform Provider, or add
+> the internal asset catalog, provision the bundled platform Provider, or add
 > `asset3d-search` to the project. Enable it only in an already initialized project:
 >
 > ```bash
-> npx -y @forgeax/game asset3d enable
+> npx -y @forgeax/game asset3d enable --base-url <aw-gateway-or-service-url>
 > ```
+>
+> The first enable prompts for the AW Sandbox Key with hidden input, validates it
+> through the packaged Provider, and stores it outside the project in a private
+> user credential file.
 
 ## Agent completion contract
 
@@ -151,29 +155,41 @@ a live unverifiable PID fails closed as `preview_ownership_unverified`.
 
 ## Asset3D installation and transaction
 
-Asset3D is an opt-in, project-local MCP integration for the internal catalog. Run it
-only after `init` and while connected to the internal network:
+Asset3D is an opt-in, project-local MCP integration for AW HybridSearch. Run it only
+after `init`, while connected to the internal network, using the gateway or service
+URL supplied by the asset-platform administrator:
 
 ```bash
-npx -y @forgeax/game asset3d enable
+npx -y @forgeax/game asset3d enable --base-url <aw-gateway-or-service-url>
 forgeax-game asset3d doctor --json
 ```
 
-`enable` first probes `http://21.214.216.8:5180/api/assets` with a body-free `HEAD`
-request. The current network-gated service returns `200` and requires no API Key, so
-the plugin reports `authentication=none`. It then reuses the exact verified Provider
-from `~/.forgeax/providers/asset3d-search/<sha256>/`, or downloads the digest-pinned
-platform release artifact over HTTPS when the cache is absent. Only after Provider
-verification and its MCP handshake succeed does the command merge the `forgeax` and
+`--base-url` accepts either the gateway root or the full
+`trpc.oasismetric.omcontentserver.http` service root. It can instead be supplied by
+`FORGEAX_ASSET_LIBRARY_BASE_URL`. On first use, `enable` reads the key with hidden TTY
+input. Non-interactive automation must inject `FORGEAX_ASSET3D_AW_SANDBOX_KEY` from
+its secret store. The key is validated by the Provider against `HybridSearch` before
+the command reports success.
+
+The validated key is stored in
+`~/.forgeax/credentials/asset3d-aw.json` as an owned, non-symlink `0600` file. Project
+`.forgeax/mcp.json` contains only the AW service URL and the credential-file path; it
+never contains the key or a signed asset URL. The Provider access check returns only
+the exact download origins required by the sandbox. Failed validation or installation
+rolls back a newly written credential.
+
+The npm package carries the digest-pinned Darwin arm64 Provider archive as an inert
+asset. `enable` reuses the exact verified Provider from
+`~/.forgeax/providers/asset3d-search/<sha256>/`, or provisions that packaged archive
+when the cache is absent. It never downloads Provider code from GitHub or another
+repository. Only after Provider verification and its MCP handshake succeed does it merge the `forgeax` and
 `asset3d-search` entries into `.forgeax/mcp.json` and project the approved Asset3D
 workflow into the Agent hosts selected during `install`.
 
 > [!IMPORTANT]
-> The internal catalog does **not** use `ANTHROPIC_API_KEY`. No model-provider key is
-> accepted, copied, or written by `asset3d enable`. If a future catalog returns
-> `401`/`403`, this release fails closed with `asset3d_api_key_contract_missing` until
-> that service publishes an explicit authentication header and validation contract;
-> an arbitrary secret is never guessed or persisted in project config.
+> Asset3D uses the AW-specific `X-Sandbox-Key` contract. It never reads
+> `ANTHROPIC_API_KEY` or another model-provider key. Do not pass keys as command-line
+> arguments, commit the user credential file, or copy a key into project MCP config.
 
 The transaction commands are normally driven by the installed Agent workflow:
 
@@ -191,18 +207,20 @@ forgeax-game asset3d uninstall
 <details>
 <summary>Maintainer-only local bundle installation</summary>
 
-The low-level command remains available for producing and validating platform release
+The low-level command remains available for producing and validating platform bundle
 artifacts. It is not the user onboarding path.
 
 ```bash
 forgeax-game asset3d install \
   --provider-bundle ./asset3d-search-provider-<commit>-<os>-<arch>.tar.gz \
   --sha256 <archive-sha256> \
-  --download-origin http://21.214.216.8:5180 \
-  --catalog-base-url http://21.214.216.8:5180
+  --download-origin https://<approved-download-host>:443 \
+  --aw-base-url <aw-gateway-or-service-url> \
+  --aw-credential-file /absolute/path/to/private-credential.json
 ```
 
-The catalog authority must also be an exact member of `--download-origin`.
+`--catalog-base-url` remains an explicit compatibility-only adapter for the retired
+directory service; normal users should not select it.
 
 </details>
 
@@ -227,5 +245,6 @@ and evidence boundaries.
 > acceptance gates.
 
 See [docs/runtime.md](docs/runtime.md) for the exact artifact and lifecycle contract.
-For the `0.3.0` onboarding release, migration, verification, and maintainer publish
-checklist, see [docs/release-0.3.0.md](docs/release-0.3.0.md).
+For the current Asset3D authentication update and maintainer publish checklist, see
+[docs/release-0.3.1.md](docs/release-0.3.1.md). The original two-command onboarding
+contract remains documented in [docs/release-0.3.0.md](docs/release-0.3.0.md).

package/dist/main.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/main.ts
-import { resolve as resolve13 } from "node:path";
+import { resolve as resolve15 } from "node:path";
 
 // src/mcp/protocol.ts
 var MCP_PROTOCOL_VERSION = "2024-11-05";
@@ -2946,7 +2946,7 @@ var RELEASE_IDENTITY_MIME = "application/vnd.forgeax.game-release-identity+json"
 var RELEASE_IDENTITY = Object.freeze({
   schema: RELEASE_IDENTITY_SCHEMA,
   gamePackage: "@forgeax/game",
-  gameVersion: "0.3.0",
+  gameVersion: "0.3.1",
   gameBin: "forgeax-game",
   engineSdkPackage: ENGINE_SDK_PACKAGE,
   engineSdkVersion: ENGINE_VERSION,
@@ -3226,9 +3226,9 @@ async function startHttpMcpServer(spec, options) {
 }
 
 // src/cli/dispatch.ts
-import { existsSync as existsSync10, readFileSync as readFileSync14, writeFileSync as writeFileSync12 } from "node:fs";
-import { arch as arch2, homedir as homedir4, platform as platform2 } from "node:os";
-import { join as join12, resolve as resolve12 } from "node:path";
+import { existsSync as existsSync12, readFileSync as readFileSync15, writeFileSync as writeFileSync11 } from "node:fs";
+import { arch as arch2, homedir as homedir5, platform as platform2 } from "node:os";
+import { join as join11, resolve as resolve14 } from "node:path";
 
 // src/install/clients.ts
 import { homedir as homedir2 } from "node:os";
@@ -3355,7 +3355,7 @@ function launchSpec(mode) {
   }
   return {
     command: "npx",
-    args: ["-y", "-p", "@forgeax/game@0.3.0", "forgeax-game", "mcp"]
+    args: ["-y", "-p", "@forgeax/game@0.3.1", "forgeax-game", "mcp"]
   };
 }
 
@@ -4164,6 +4164,7 @@ import {
   chmodSync as chmodSync4,
   copyFileSync as copyFileSync3,
   existsSync as existsSync8,
+  lstatSync as lstatSync7,
   mkdirSync as mkdirSync9,
   mkdtempSync as mkdtempSync2,
   readFileSync as readFileSync12,
@@ -4186,12 +4187,11 @@ var PROVIDER_RECEIPT_SCHEMA = "forgeax.asset3d-search-receipt/1.0.0";
 var K0_PACKAGE_SHA256 = "0c3fc5d448b94efadb7fe03ee48ef3d8964434c2789505297a99c3a2715dd83b";
 var RESULT_SCHEMA_SHA256 = "ab6e5e1e794d5428efef362fe32d4c54b6541e12539bae5f6ff27680c9f380ba";
 var RECEIPT_SCHEMA_SHA256 = "e0dc9e9fe9872f09af9fca6d0c17d22aca63c2b546c55c0b669c581f7059b9c4";
-var ASSET3D_PROVIDER_COMMIT = "68749b1f36164a1e2ea8c67110676614bb9a013e";
-var DEFAULT_ASSET3D_CATALOG_ORIGIN = "http://21.214.216.8:5180";
-var DEFAULT_ASSET3D_PROVIDER_RELEASES = Object.freeze({
+var ASSET3D_PROVIDER_COMMIT = "c181c48fbffc933a7ce9a0836f7878ca5e6d77e1";
+var BUNDLED_ASSET3D_PROVIDERS = Object.freeze({
   "darwin-arm64": {
-    sha256: "00ea7c977a705f2a9807c90d864c021c54c174d7f8295c2d263022d968480357",
-    url: "https://github.com/ForgeaXGame/forgeax-game-plugin/releases/download/asset3d-provider-68749b1f36164a1e2ea8c67110676614bb9a013e/asset3d-search-provider-68749b1f36164a1e2ea8c67110676614bb9a013e-darwin-arm64.tar.gz"
+    sha256: "c8d2afd7ba68ae4b3540c927a2ff7133a82ea90975d09cab1d10b003fbbdeed3",
+    relativePath: "asset3d/provider/asset3d-search-provider-c181c48fbffc933a7ce9a0836f7878ca5e6d77e1-darwin-arm64.tar.gz"
   }
 });
 var INSTALL_SCHEMA = "forgeax.asset3d-install/1.0.0";
@@ -4311,6 +4311,22 @@ var K0_FILES = [
   "scripts/workflow.test.mjs"
 ];
 var SKILL_ID = "art-3d-asset-library";
+function packagedAsset3dProvider(relativePathInput, assetsRootInput) {
+  const assetsRoot = realpathSync7(assetsRootInput ?? defaultAssetsRoot());
+  const relativePath = relativePathInput.replaceAll("\\", "/");
+  if (!relativePath || relativePath.startsWith("/") || relativePath.split("/").some((part) => part === "" || part === "." || part === "..")) {
+    throw new Error("asset3d_bundled_provider_path_invalid");
+  }
+  const candidate = resolve10(assetsRoot, relativePath);
+  if (!confined3(assetsRoot, candidate) || !existsSync8(candidate)) {
+    throw new Error("asset3d_bundled_provider_missing: reinstall @forgeax/game");
+  }
+  const metadata = lstatSync7(candidate);
+  if (!metadata.isFile() || metadata.isSymbolicLink()) {
+    throw new Error("asset3d_bundled_provider_invalid: expected a regular package file");
+  }
+  return realpathSync7(candidate);
+}
 function confined3(root, candidate) {
   const rel = relative8(root, candidate);
   return rel === "" || !isAbsolute3(rel) && rel !== ".." && !rel.startsWith(`..${sep5}`);
@@ -4485,7 +4501,7 @@ function filesUnder2(root, directory = root) {
     })();
   });
 }
-function launchEntries(projectRoot, providerCache, origins, gamePluginLaunch, catalogBaseUrl) {
+function launchEntries(projectRoot, providerCache, origins, gamePluginLaunch, catalogBaseUrl, awApiBaseUrl, awCredentialFile) {
   const quarantine = resolve10(projectRoot, ".forgeax", "asset3d-quarantine");
   const workspace = resolve10(quarantine, "workspace");
   return {
@@ -4506,7 +4522,9 @@ function launchEntries(projectRoot, providerCache, origins, gamePluginLaunch, ca
         MCP_WORKSPACE_ROOT: workspace,
         MCP_GAME_RUNTIME_ROOT: resolve10(quarantine, "game-runtime"),
         AW_DOWNLOAD_ORIGINS: origins.compactJson,
-        ...catalogBaseUrl ? { ASSET3D_CATALOG_BASE_URL: catalogBaseUrl } : {}
+        ...catalogBaseUrl ? { ASSET3D_CATALOG_BASE_URL: catalogBaseUrl } : {},
+        ...awApiBaseUrl ? { AW_API_BASE_URL: awApiBaseUrl } : {},
+        ...awCredentialFile ? { AW_API_CREDENTIAL_FILE: awCredentialFile } : {}
       },
       toolCallTimeoutsMs: { default: 30000, tools: { search_asset: 195000 } }
     }
@@ -4676,6 +4694,14 @@ async function publishAsset3d(options, provisioned) {
   if (catalogBaseUrl && !origins.values.includes(catalogBaseUrl)) {
     throw new Error("catalog_origin_not_authorized: --catalog-base-url must also be a --download-origin");
   }
+  if (Boolean(options.awApiBaseUrl) !== Boolean(options.awCredentialFile)) {
+    throw new Error("asset3d_aw_config_invalid: AW API base URL and credential file must be configured together");
+  }
+  const awApiBaseUrl = options.awApiBaseUrl;
+  const awCredentialFile = options.awCredentialFile ? resolve10(options.awCredentialFile) : undefined;
+  if (awCredentialFile && !isAbsolute3(options.awCredentialFile)) {
+    throw new Error("asset3d_credential_path_invalid: absolute path required");
+  }
   const assetsRoot = options.assetsRoot ?? defaultAssetsRoot();
   const asset3dAssets = existsSync8(resolve10(assetsRoot, "asset3d", "vibegame-art-3d-asset-library-2.0.0.tgz")) ? resolve10(assetsRoot, "asset3d") : assetsRoot;
   const k0 = resolve10(asset3dAssets, "vibegame-art-3d-asset-library-2.0.0.tgz");
@@ -4687,7 +4713,7 @@ async function publishAsset3d(options, provisioned) {
     command: realpathSync7(options.executable ?? process.argv[1]),
     args: ["mcp"]
   };
-  const entries = launchEntries(projectRoot, provisioned.cache, origins, gamePluginLaunch, catalogBaseUrl);
+  const entries = launchEntries(projectRoot, provisioned.cache, origins, gamePluginLaunch, catalogBaseUrl, awApiBaseUrl, awCredentialFile);
   if (options.verifyMcp !== false)
     await verifyProviderMcp(entries["asset3d-search"]);
   const configPath = resolve10(forgeax, "mcp.json");
@@ -4731,6 +4757,13 @@ async function installAsset3d(options) {
   const cacheRoot = resolve10(options.cacheRoot ?? join10(homedir3(), ".forgeax", "providers", "asset3d-search"));
   return publishAsset3d(options, provisionBundle(archive, options.expectedSha256, cacheRoot, options.python));
 }
+function prepareAsset3dProvider(options) {
+  if (/^https?:/i.test(options.providerBundle))
+    throw new Error("asset3d_remote_artifact_unsupported");
+  const archive = realpathSync7(options.providerBundle);
+  const cacheRoot = resolve10(options.cacheRoot ?? join10(homedir3(), ".forgeax", "providers", "asset3d-search"));
+  return provisionBundle(archive, options.expectedSha256, cacheRoot, options.python).cache;
+}
 async function installProvisionedAsset3d(options) {
   return publishAsset3d(options, useProvisionedCache(options.providerCache, options.expectedSha256));
 }
@@ -5406,93 +5439,211 @@ function doctorAsset3d(projectRootInput, options = {}) {
   return { installed: true, recovered, engine: { version: release.version, commit: release.commit }, provider: { commit: install.providerCommit, cache: install.providerCache, live: existsSync9(resolve11(install.providerCache, "venv", "bin", "python")) } };
 }
 
-// src/asset3d/catalog-access.ts
-async function probeAsset3dCatalog(inputOrigin, request2 = fetch) {
-  const origin = canonicalizeOrigins([inputOrigin]).values[0];
-  const controller = new AbortController;
-  const timeout = setTimeout(() => controller.abort(), 1e4);
-  let status;
+// src/asset3d/aw-access.ts
+import { spawnSync as spawnSync5 } from "node:child_process";
+import { existsSync as existsSync10 } from "node:fs";
+import { resolve as resolve12 } from "node:path";
+var AW_SERVICE_PATH = "/trpc.oasismetric.omcontentserver.http";
+var ACCESS_CHECK_SCHEMA = "forgeax.asset3d-access-check/1.0.0";
+function normalizeAwServiceRoot(input) {
+  let parsed;
   try {
-    status = (await request2(`${origin}/api/assets`, {
-      method: "HEAD",
-      redirect: "manual",
-      signal: controller.signal
-    })).status;
+    parsed = new URL(input);
   } catch {
-    throw new Error("asset3d_catalog_unreachable: connect to the internal network and retry");
-  } finally {
-    clearTimeout(timeout);
+    throw new Error("asset3d_base_url_invalid: expected an HTTP(S) AW gateway or service URL");
+  }
+  if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new Error("asset3d_base_url_invalid: credentials, query, and fragment are forbidden");
+  }
+  let path = parsed.pathname.replace(/\/+$/, "");
+  if (path.endsWith(`${AW_SERVICE_PATH}/HybridSearch`))
+    path = path.slice(0, -"/HybridSearch".length);
+  else if (!path.endsWith(AW_SERVICE_PATH))
+    path = `${path}${AW_SERVICE_PATH}`;
+  parsed.pathname = path;
+  return parsed.toString().replace(/\/$/, "");
+}
+function resolveAwServiceRoot(explicit) {
+  const configured = explicit || process.env.FORGEAX_ASSET_LIBRARY_BASE_URL;
+  if (!configured) {
+    throw new Error("asset3d_base_url_required: pass --base-url <AW gateway/service URL> or set FORGEAX_ASSET_LIBRARY_BASE_URL");
+  }
+  return normalizeAwServiceRoot(configured);
+}
+function checkAwProviderAccess(options) {
+  const command = resolve12(options.providerCache, "bin", "asset3d-search");
+  if (!existsSync10(command))
+    throw new Error("asset3d_provider_not_prepared");
+  const result = spawnSync5(command, ["--check-aw-access"], {
+    encoding: "utf8",
+    timeout: 45000,
+    maxBuffer: 128 * 1024,
+    env: {
+      ...process.env,
+      ASSET3D_CATALOG_BASE_URL: "",
+      AW_API_BASE_URL: options.serviceRoot,
+      AW_API_CREDENTIAL_FILE: resolve12(options.credentialFile),
+      AW_API_SANDBOX_KEY: ""
+    }
+  });
+  let payload;
+  try {
+    payload = JSON.parse(result.stdout);
+  } catch {
+    throw new Error("asset3d_access_validation_failed: Provider returned an invalid response");
   }
-  if (status >= 200 && status < 300)
-    return { origin, authentication: "none" };
-  if (status === 401 || status === 403) {
-    throw new Error("asset3d_api_key_contract_missing: the catalog requires authentication but does not publish a supported key contract");
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("asset3d_access_validation_failed: Provider returned an invalid response");
   }
-  throw new Error(`asset3d_catalog_probe_failed: HEAD /api/assets returned ${status}`);
-}
-
-// src/asset3d/release.ts
-import { createHash as createHash8 } from "node:crypto";
-import { mkdtempSync as mkdtempSync3, rmSync as rmSync7, writeFileSync as writeFileSync11 } from "node:fs";
-import { tmpdir as tmpdir3 } from "node:os";
-import { basename as basename4, join as join11 } from "node:path";
-var MAX_PROVIDER_ARCHIVE_BYTES = 256 * 1024 * 1024;
-async function downloadProviderRelease(release, request2 = fetch) {
-  if (!/^[a-f0-9]{64}$/.test(release.sha256))
-    throw new Error("provider_bundle_digest_invalid");
-  let url = new URL(release.url);
-  if (url.protocol !== "https:")
-    throw new Error("asset3d_provider_release_url_invalid: HTTPS is required");
-  let response;
-  for (let redirects = 0;redirects <= 5; redirects++) {
-    response = await request2(url, { method: "GET", redirect: "manual" });
-    if (![301, 302, 303, 307, 308].includes(response.status))
-      break;
-    const location = response.headers.get("location");
-    if (!location)
-      throw new Error("asset3d_provider_download_failed: redirect has no location");
-    url = new URL(location, url);
-    if (url.protocol !== "https:")
-      throw new Error("asset3d_provider_download_failed: HTTPS downgrade rejected");
-    response = undefined;
+  const envelope = payload;
+  if (result.status !== 0 || envelope.ok !== true) {
+    const code = envelope.error?.code === "asset3d_access_validation_inconclusive" ? "asset3d_access_validation_inconclusive" : "asset3d_api_key_invalid_or_unavailable";
+    throw new Error(`${code}: verify the AW service address, internal network, and Sandbox Key`);
   }
-  if (!response || response.status !== 200 || !response.body) {
-    throw new Error(`asset3d_provider_download_failed: release artifact returned ${response?.status ?? "too_many_redirects"}`);
+  if (envelope.schemaVersion !== ACCESS_CHECK_SCHEMA || envelope.value?.authentication !== "sandbox-key" || !Array.isArray(envelope.value.downloadOrigins)) {
+    throw new Error("asset3d_access_validation_failed: Provider returned an invalid response");
   }
-  const declared = Number(response.headers.get("content-length") ?? "0");
-  if (Number.isFinite(declared) && declared > MAX_PROVIDER_ARCHIVE_BYTES) {
-    throw new Error("asset3d_provider_download_too_large");
+  const origins = canonicalizeOrigins(envelope.value.downloadOrigins).values;
+  return { serviceRoot: options.serviceRoot, authentication: "sandbox-key", downloadOrigins: origins };
+}
+
+// src/asset3d/credentials.ts
+import { chmodSync as chmodSync5, existsSync as existsSync11, lstatSync as lstatSync9, readFileSync as readFileSync14, statSync as statSync7, unlinkSync as unlinkSync4 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { dirname as dirname11, isAbsolute as isAbsolute5, resolve as resolve13 } from "node:path";
+var AW_CREDENTIAL_SCHEMA = "forgeax.asset3d-credential/1.0.0";
+var AW_KEY_ENV = "FORGEAX_ASSET3D_AW_SANDBOX_KEY";
+var MAX_CREDENTIAL_BYTES = 4096;
+function validateKey(value) {
+  if (!value || value.length > 2048 || [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127;
+  })) {
+    throw new Error("asset3d_api_key_invalid: expected a non-empty printable key");
   }
-  const chunks = [];
-  let total = 0;
-  const reader = response.body.getReader();
-  for (;; ) {
-    const { done, value } = await reader.read();
-    if (done)
-      break;
-    if (!value)
-      continue;
-    total += value.byteLength;
-    if (total > MAX_PROVIDER_ARCHIVE_BYTES) {
-      await reader.cancel();
-      throw new Error("asset3d_provider_download_too_large");
-    }
-    chunks.push(value);
+  return value;
+}
+function defaultAwCredentialFile() {
+  const configured = process.env.FORGEAX_ASSET3D_CREDENTIAL_FILE;
+  return resolve13(configured || resolve13(homedir4(), ".forgeax", "credentials", "asset3d-aw.json"));
+}
+function readAwCredential(pathInput) {
+  const path = resolve13(pathInput);
+  if (!isAbsolute5(pathInput))
+    throw new Error("asset3d_credential_path_invalid: absolute path required");
+  if (!existsSync11(path))
+    return;
+  try {
+    const metadata = lstatSync9(path);
+    const wrongOwner = typeof process.getuid === "function" && metadata.uid !== process.getuid();
+    if (!metadata.isFile() || metadata.isSymbolicLink() || wrongOwner)
+      throw new Error;
+    if ((metadata.mode & 63) !== 0 || metadata.size < 1 || metadata.size > MAX_CREDENTIAL_BYTES)
+      throw new Error;
+    const parsed = JSON.parse(readFileSync14(path, "utf8"));
+    if (Object.keys(parsed).sort().join(",") !== "provider,sandboxKey,schemaVersion")
+      throw new Error;
+    if (parsed.schemaVersion !== AW_CREDENTIAL_SCHEMA || parsed.provider !== "aw" || typeof parsed.sandboxKey !== "string")
+      throw new Error;
+    return validateKey(parsed.sandboxKey);
+  } catch {
+    throw new Error("asset3d_credential_invalid: credential file must be an owned 0600 regular file with the supported schema");
   }
-  const bytes = Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total);
-  const actual = createHash8("sha256").update(bytes).digest("hex");
-  if (actual !== release.sha256) {
-    throw new Error(`provider_bundle_digest_mismatch: expected ${release.sha256}, got ${actual}`);
+}
+async function promptAwKey() {
+  if (!process.stdin.isTTY || !process.stdout.isTTY || typeof process.stdin.setRawMode !== "function") {
+    throw new Error(`asset3d_api_key_required: set ${AW_KEY_ENV} or rerun in an interactive terminal`);
   }
-  const root = mkdtempSync3(join11(tmpdir3(), "forgeax-asset3d-release-"));
-  const archive = join11(root, basename4(url.pathname) || "provider.tar.gz");
+  process.stdout.write("AW Asset3D Sandbox Key (input hidden): ");
+  const input = process.stdin;
+  const previousRaw = input.isRaw;
+  input.setRawMode(true);
+  input.resume();
+  input.setEncoding("utf8");
   try {
-    writeFileSync11(archive, bytes, { mode: 384, flag: "wx" });
-  } catch (error) {
-    rmSync7(root, { recursive: true, force: true });
-    throw error;
-  }
-  return { archive, cleanup: () => rmSync7(root, { recursive: true, force: true }) };
+    const value = await new Promise((resolveValue, reject) => {
+      let collected = "";
+      const onData = (chunk) => {
+        for (const character of chunk) {
+          if (character === "\x03") {
+            input.off("data", onData);
+            reject(new Error("asset3d_api_key_input_cancelled"));
+            return;
+          }
+          if (character === "\r" || character === `
+`) {
+            input.off("data", onData);
+            resolveValue(collected);
+            return;
+          }
+          if (character === "" || character === "\b")
+            collected = collected.slice(0, -1);
+          else
+            collected += character;
+        }
+      };
+      input.on("data", onData);
+    });
+    process.stdout.write(`
+`);
+    return validateKey(value);
+  } finally {
+    input.setRawMode(previousRaw ?? false);
+    input.pause();
+  }
+}
+async function acquireAwKey(path) {
+  const fromEnvironment = process.env[AW_KEY_ENV];
+  if (fromEnvironment)
+    return { key: validateKey(fromEnvironment), source: "environment" };
+  const stored = readAwCredential(path);
+  if (stored)
+    return { key: stored, source: "stored" };
+  return { key: await promptAwKey(), source: "prompt" };
+}
+function writeAwCredential(pathInput, keyInput) {
+  if (!isAbsolute5(pathInput))
+    throw new Error("asset3d_credential_path_invalid: absolute path required");
+  const path = resolve13(pathInput);
+  const key = validateKey(keyInput);
+  const parent = dirname11(path);
+  ensurePrivateDir(parent);
+  const parentMetadata = lstatSync9(parent);
+  const wrongParentOwner = typeof process.getuid === "function" && parentMetadata.uid !== process.getuid();
+  if (!parentMetadata.isDirectory() || parentMetadata.isSymbolicLink() || wrongParentOwner) {
+    throw new Error("asset3d_credential_path_invalid: parent must be an owned regular directory");
+  }
+  chmodSync5(parent, 448);
+  const existed = existsSync11(path);
+  if (existed)
+    readAwCredential(path);
+  const previous = existed ? readFileSync14(path) : undefined;
+  const previousMode = existed ? statSync7(path).mode & 511 : undefined;
+  const bytes = `${JSON.stringify({ schemaVersion: AW_CREDENTIAL_SCHEMA, provider: "aw", sandboxKey: key }, null, 2)}
+`;
+  const changed = !previous || !previous.equals(Buffer.from(bytes));
+  if (changed)
+    atomicWrite(path, bytes, 384);
+  chmodSync5(path, 384);
+  let active = true;
+  return {
+    path,
+    changed,
+    commit() {
+      active = false;
+    },
+    rollback() {
+      if (!active || !changed)
+        return;
+      if (previous) {
+        atomicWrite(path, previous, previousMode ?? 384);
+        chmodSync5(path, previousMode ?? 384);
+      } else {
+        unlinkSync4(path);
+      }
+      active = false;
+    }
+  };
 }
 
 // src/cli/dispatch.ts
@@ -5507,8 +5658,8 @@ Usage:
   forgeax-game preview stop [--game <slug>] [--target-dir <path>] [--json]
   forgeax-game devkit install
   forgeax-game agents update
-  forgeax-game asset3d enable [--ide ${CLIENT_CHOICES.join(",")}]
-  forgeax-game asset3d install --provider-bundle <archive> --sha256 <hex> --download-origin <scheme://host:port> [--catalog-base-url <scheme://host:port>] [...]
+  forgeax-game asset3d enable [--base-url <AW gateway/service URL>] [--ide ${CLIENT_CHOICES.join(",")}]
+  forgeax-game asset3d install --provider-bundle <archive> --sha256 <hex> --download-origin <scheme://host:port> [--aw-base-url <URL> --aw-credential-file <absolute path>] [...]
   forgeax-game asset3d uninstall
   forgeax-game asset3d begin --query <text> [--query <text> ...] --json
   forgeax-game asset3d commit --execution <uuid> --provider-result-stdin --json [--refresh]
@@ -5560,23 +5711,23 @@ function requireProject() {
   return project.root;
 }
 function updateAgentsFile(root) {
-  const path = join12(root, "AGENTS.md");
-  const existing = existsSync10(path) ? readFileSync14(path, "utf8") : undefined;
+  const path = join11(root, "AGENTS.md");
+  const existing = existsSync12(path) ? readFileSync15(path, "utf8") : undefined;
   const content = upsertBlock(existing, ROUTING_TEXT);
   if (content === existing)
     return { path, changed: false };
-  writeFileSync12(path, content);
+  writeFileSync11(path, content);
   return { path, changed: true };
 }
 function removeAgentsBlock(root) {
-  const path = join12(root, "AGENTS.md");
-  if (!existsSync10(path))
+  const path = join11(root, "AGENTS.md");
+  if (!existsSync12(path))
     return { path, changed: false };
-  const existing = readFileSync14(path, "utf8");
+  const existing = readFileSync15(path, "utf8");
   const content = removeBlock(existing);
   if (content === existing)
     return { path, changed: false };
-  writeFileSync12(path, content);
+  writeFileSync11(path, content);
   return { path, changed: true };
 }
 async function installCommand(args) {
@@ -5675,7 +5826,7 @@ async function useCommand(args) {
     throw new Error(`game ${JSON.stringify(slug)} not found. Available: ${listGames(root).join(", ") || "(none)"}`);
   }
   if (listGames(root).length > 1) {
-    writeFileSync12(join12(root, ".forgeax", "active-game.json"), `${JSON.stringify({ version: 1, slug }, null, 2)}
+    writeFileSync11(join11(root, ".forgeax", "active-game.json"), `${JSON.stringify({ version: 1, slug }, null, 2)}
 `, "utf8");
   }
   process.stdout.write(`Active game: ${slug}
@@ -5777,7 +5928,7 @@ async function uninstallCommand(args) {
     const agents = removeAgentsBlock(root);
     process.stdout.write(`${agents.changed ? "REMOVED" : "ABSENT "} routing block: ${agents.path}
 `);
-    process.stdout.write(`KEPT    your games and project metadata: ${join12(root, ".forgeax")}
+    process.stdout.write(`KEPT    your games and project metadata: ${join11(root, ".forgeax")}
 `);
   } else {
     process.stdout.write(`INFO  no ForgeaX project bound; only client configuration was touched.
@@ -6007,54 +6158,93 @@ function canonicalAsset3dClients(value) {
     throw new Error(`asset3d_client_invalid: ${invalid.join(", ")}`);
   return [...new Set(values)];
 }
+function parseAsset3dEnableArgs(args) {
+  const ideArgs = [];
+  let baseUrl;
+  for (let index = 0;index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--base-url") {
+      const value = args[++index];
+      if (!value)
+        throw new Error("--base-url requires an AW gateway/service URL");
+      baseUrl = value;
+      continue;
+    }
+    if (arg.startsWith("--base-url=")) {
+      baseUrl = arg.slice("--base-url=".length);
+      continue;
+    }
+    if (arg === "--ide") {
+      const value = args[++index];
+      if (!value)
+        throw new Error("--ide requires a comma-separated client list");
+      ideArgs.push("--ide", value);
+      continue;
+    }
+    if (arg.startsWith("--ide=")) {
+      ideArgs.push(arg);
+      continue;
+    }
+    throw new Error("usage: forgeax-game asset3d enable [--base-url <AW gateway/service URL>] [--ide codex,claude,cursor,...]");
+  }
+  return { requested: parseIdeSelector(ideArgs, "invalid --ide selector"), baseUrl };
+}
 async function asset3dCommand(args) {
   const [operation, ...rest] = args;
   const projectRoot = requireProject();
   try {
     if (operation === "enable") {
-      const requested = parseIdeSelector(rest, "usage: forgeax-game asset3d enable [--ide codex,claude,cursor,...]");
-      const selection = selectClients(projectRoot, requested);
+      const parsed = parseAsset3dEnableArgs(rest);
+      const selection = selectClients(projectRoot, parsed.requested);
       reportMissingClients(selection.missing);
       if (selection.selected.length === 0) {
         throw new Error("asset3d_client_missing: run `forgeax-game install --ide <client>` before enabling Asset3D");
       }
-      const access = await probeAsset3dCatalog(DEFAULT_ASSET3D_CATALOG_ORIGIN);
+      const serviceRoot = resolveAwServiceRoot(parsed.baseUrl);
       const os = platform2() === "win32" ? "windows" : platform2();
       const cpu = arch2();
       const target = `${os}-${cpu}`;
-      const release = DEFAULT_ASSET3D_PROVIDER_RELEASES[target];
-      if (!release)
+      const bundled = BUNDLED_ASSET3D_PROVIDERS[target];
+      if (!bundled)
         throw new Error(`asset3d_provider_target_unreleased: ${target}`);
-      const providerCache = resolve12(homedir4(), ".forgeax", "providers", "asset3d-search", release.sha256);
-      const clients = selection.selected.filter((id) => (id in SKILL_MOUNTS));
-      const common = {
-        projectRoot,
-        expectedSha256: release.sha256,
-        downloadOrigins: [access.origin],
-        catalogBaseUrl: access.origin,
-        clients,
-        gamePluginLaunch: launchSpec("npx"),
-        replaceOwned: true
-      };
-      let result;
-      if (existsSync10(providerCache)) {
-        result = await installProvisionedAsset3d({ ...common, providerCache });
-      } else {
-        const downloaded = await downloadProviderRelease(release);
-        try {
-          result = await installAsset3d({ ...common, providerBundle: downloaded.archive });
-        } finally {
-          downloaded.cleanup();
-        }
+      const providerCache = resolve14(homedir5(), ".forgeax", "providers", "asset3d-search", bundled.sha256);
+      let preparedCache = providerCache;
+      if (!existsSync12(providerCache)) {
+        const providerBundle = packagedAsset3dProvider(bundled.relativePath);
+        preparedCache = prepareAsset3dProvider({ providerBundle, expectedSha256: bundled.sha256 });
       }
-      process.stdout.write(`${result.changed ? "ENABLED" : "CURRENT"} Asset3D provider ${result.providerCommit}; catalog=${access.origin}; authentication=${access.authentication}; skillFiles=${result.skillFiles}
+      const credentialFile = defaultAwCredentialFile();
+      const credential = await acquireAwKey(credentialFile);
+      const credentialWrite = writeAwCredential(credentialFile, credential.key);
+      const clients = selection.selected.filter((id) => (id in SKILL_MOUNTS));
+      try {
+        const access = checkAwProviderAccess({ providerCache: preparedCache, serviceRoot, credentialFile });
+        const result = await installProvisionedAsset3d({
+          projectRoot,
+          providerCache: preparedCache,
+          expectedSha256: bundled.sha256,
+          downloadOrigins: access.downloadOrigins,
+          awApiBaseUrl: access.serviceRoot,
+          awCredentialFile: credentialFile,
+          clients,
+          gamePluginLaunch: launchSpec("npx"),
+          replaceOwned: true
+        });
+        credentialWrite.commit();
+        process.stdout.write(`${result.changed ? "ENABLED" : "CURRENT"} Asset3D provider ${result.providerCommit}; service=${access.serviceRoot}; authentication=${access.authentication}; skillFiles=${result.skillFiles}
 `);
-      return 0;
+        return 0;
+      } catch (error) {
+        credentialWrite.rollback();
+        throw error;
+      }
     }
     if (operation === "install") {
       let providerBundle;
       let expectedSha256;
       let catalogBaseUrl;
+      let awApiBaseUrl;
+      let awCredentialFile;
       const downloadOrigins = [];
       let clients;
       let replaceOwned = false;
@@ -6064,7 +6254,7 @@ async function asset3dCommand(args) {
           replaceOwned = true;
           continue;
         }
-        if (arg === "--provider-bundle" || arg === "--sha256" || arg === "--download-origin" || arg === "--catalog-base-url" || arg === "--ide") {
+        if (arg === "--provider-bundle" || arg === "--sha256" || arg === "--download-origin" || arg === "--catalog-base-url" || arg === "--aw-base-url" || arg === "--aw-credential-file" || arg === "--ide") {
           const value = rest[++index];
           if (!value)
             throw new Error(`${arg} requires a value`);
@@ -6076,6 +6266,10 @@ async function asset3dCommand(args) {
             downloadOrigins.push(value);
           else if (arg === "--catalog-base-url")
             catalogBaseUrl = value;
+          else if (arg === "--aw-base-url")
+            awApiBaseUrl = resolveAwServiceRoot(value);
+          else if (arg === "--aw-credential-file")
+            awCredentialFile = resolve14(value);
           else
             clients = canonicalAsset3dClients(value);
           continue;
@@ -6084,7 +6278,17 @@ async function asset3dCommand(args) {
       }
       if (!providerBundle || !expectedSha256)
         throw new Error("usage: forgeax-game asset3d install --provider-bundle <archive> --sha256 <hex> --download-origin <origin> [...]");
-      const result = await installAsset3d({ projectRoot, providerBundle, expectedSha256, downloadOrigins, ...catalogBaseUrl ? { catalogBaseUrl } : {}, ...clients ? { clients } : {}, replaceOwned });
+      const result = await installAsset3d({
+        projectRoot,
+        providerBundle,
+        expectedSha256,
+        downloadOrigins,
+        ...catalogBaseUrl ? { catalogBaseUrl } : {},
+        ...awApiBaseUrl ? { awApiBaseUrl } : {},
+        ...awCredentialFile ? { awCredentialFile } : {},
+        ...clients ? { clients } : {},
+        replaceOwned
+      });
       process.stdout.write(`${result.changed ? "INSTALLED" : "CURRENT"} Asset3D provider ${result.providerCommit}; originSetDigest=${result.originSetDigest}; skillFiles=${result.skillFiles}
 `);
       return 0;
@@ -6259,7 +6463,7 @@ function parseMcpArgs(args) {
     } else
       throw new Error(`unknown MCP option: ${arg}`);
   }
-  return { transport, host, port, root: resolve13(root), requireAuth, allowedOrigins };
+  return { transport, host, port, root: resolve15(root), requireAuth, allowedOrigins };
 }
 async function runMcp(args) {
   const options = parseMcpArgs(args);

package/docs/asset3d.md

@@ -13,19 +13,24 @@ second importer or Preview server.
 > inside an already initialized Engine game.
 
 > [!IMPORTANT]
-> Provider archives are platform-specific release artifacts and are not embedded in
-> the platform-neutral npm package. Installation deliberately returns
+> Provider archives are platform-specific artifacts. The npm package embeds the
+> currently released Darwin arm64 archive so a cache-empty user does not depend on a
+> private source repository or release download. Installation deliberately returns
 > `provider_platform_mismatch` when an archive target differs from the current host.
-> Each published target therefore needs its own digest, offline verification, MCP
+> Each bundled target therefore needs its own digest, offline verification, MCP
 > handshake, and real service-path evidence.
 
 ## Trust and data flow
 
 ```mermaid
 flowchart LR
-    B["Digest-pinned local provider bundle"] --> C["Managed digest cache"]
-    K["Exact K0 workflow TGZ"] --> S["Nine project Skill mounts"]
+    U["Hidden key input or automation secret"] --> CRED["Private user credential file"]
+    B["Provider archive bundled in npm"] --> C["Managed digest cache"]
+    PKG["Exact K0 workflow TGZ"] --> S["Nine project Skill mounts"]
     C --> M["Project-local stdio MCP"]
+    CRED --> M
+    M --> H["AW HybridSearch access check"]
+    H --> D["Exact signed-download origins"]
     M --> Q["Private transaction quarantine"]
     Q --> V["Checked result and file manifest"]
     V --> A["Atomic asset-directory publication"]
@@ -34,7 +39,14 @@ flowchart LR
     R --> P["Per-file provenance and terminal result"]
 ```
 
-The provider is the only network adapter. Installed download authorities are
+The provider is the only network adapter. `asset3d enable` invokes its bounded
+`--check-aw-access` mode before publishing project configuration. That mode calls AW
+`HybridSearch` with the documented `X-Sandbox-Key` header and required 3D search
+fields, then emits only `authentication=sandbox-key` plus the canonical origins of
+returned short-lived `res_url` values. Asset IDs, candidates, signed URLs, request
+bodies, and the key are never returned by the access check.
+
+Installed download authorities are
 lexically exact `http://host:port` or `https://host:port` values: explicit port,
 no path (including `/`), no query, fragment, userinfo, or wildcard. The canonical
 one-to-eight member set is sorted and encoded as compact JSON in
@@ -42,33 +54,41 @@ one-to-eight member set is sorted and encoded as compact JSON in
 digest. The provider is responsible for enforcing that set on both initial and
 redirect requests.
 
-When installation supplies `--catalog-base-url`, the exact pathless authority is
-written only to the project-local provider environment. It must also appear in
-`--download-origin`. The provider first attempts the bounded `/api/search` route;
-only an explicit `404` or `405` permits a bounded `/api/assets` fallback, and the
-selected asset is fetched through `/api/download/assets`. Other upstream failures
-remain failures rather than silently expanding to a full-catalog scan. Without the
-option, the provider retains the managed AW search adapter.
+Normal installation writes the normalized AW service root to `AW_API_BASE_URL` and an
+absolute user credential-file path to `AW_API_CREDENTIAL_FILE`. It never writes
+`AW_API_SANDBOX_KEY` into project MCP configuration. `--catalog-base-url` remains a
+maintainer-only compatibility adapter for the retired directory service; when used,
+its authority must also appear in `--download-origin`.
 
 ## Installation ownership
 
-`asset3d enable` probes the default internal catalog with `HEAD /api/assets`. A `2xx`
-response selects `authentication=none`; the current service follows this path and no
-API Key is required. `401` or `403` without an explicit supported authentication
-contract fails closed as `asset3d_api_key_contract_missing`. The plugin never treats
-an Anthropic or other model-provider credential as an Asset3D credential.
-
-The command reuses an exact verified cache when present. Otherwise it downloads the
-platform release archive over HTTPS, follows at most five HTTPS redirects, enforces a
-256 MiB bound, and verifies the pinned SHA-256 before any provisioning. Bundle schema,
-provider commit, platform, Python range, and checked result/receipt schema digests are
-then verified before invoking the offline bundle verifier. Provisioning uses system
+`asset3d enable` requires an AW gateway or full service URL through `--base-url` or
+`FORGEAX_ASSET_LIBRARY_BASE_URL`. No private-network endpoint is compiled into the
+package. The first interactive run asks for the AW Sandbox Key with terminal echo
+disabled. Automation can supply `FORGEAX_ASSET3D_AW_SANDBOX_KEY` from a secret store;
+command-line key arguments are deliberately unsupported.
+
+The credential is stored outside the project at
+`~/.forgeax/credentials/asset3d-aw.json` by default. The directory is `0700`; the
+file must be regular, owned by the current user, non-symlink, at most 4 KiB, and
+`0600`. The Provider accepts only the versioned AW credential schema. A failed access
+check or downstream installation rolls back a newly written value. An existing valid
+credential makes repeat enablement idempotent. The plugin never treats Anthropic or
+another model-provider credential as an Asset3D key.
+
+The command reuses an exact verified cache when present. Otherwise it opens the
+platform archive carried by the installed `@forgeax/game` package and verifies the
+pinned SHA-256 before any provisioning. No Provider download or source-repository
+authentication occurs during `asset3d enable`. Bundle schema, provider commit,
+platform, Python range, and checked result/receipt schema digests are then verified
+before invoking the offline bundle verifier. Provisioning uses system
 Python 3.11 or 3.12 and the Provider's hash-locked `--provision` flow. The published
 cache is keyed by archive digest under `~/.forgeax/providers/asset3d-search/`.
 
 The low-level `asset3d install --provider-bundle ...` command remains a maintainer
-surface for release production and controlled evidence; users enable the pinned
-release rather than selecting an arbitrary archive.
+surface for bundle production and controlled evidence; users enable the pinned
+archive carried by their installed Game Plugin rather than selecting an arbitrary
+archive.
 
 The installer merges, rather than replaces, the complete `.forgeax/mcp.json` object.
 Unrelated top-level keys and servers survive. The owned entries are local stdio only:

package/docs/release-0.3.1.md

@@ -0,0 +1,107 @@
+# `@forgeax/game` 0.3.1 release guide
+
+Version `0.3.1` keeps the two-command ForgeaX onboarding contract from `0.3.0` and
+replaces the Asset3D default route with the documented AW `HybridSearch` contract.
+Asset3D remains optional and disabled until a user explicitly enables it.
+
+## User contract
+
+The ordinary setup flow is unchanged:
+
+```bash
+npx -y @forgeax/game install --ide codex,cursor,claude
+cd /path/to/a-genuinely-empty-directory
+npx -y @forgeax/game init
+```
+
+Inside an initialized project, enable AW Asset3D separately:
+
+```bash
+npx -y @forgeax/game asset3d enable --base-url <aw-gateway-or-service-url>
+npx -y @forgeax/game asset3d doctor --json
+```
+
+`--base-url` can be replaced by `FORGEAX_ASSET_LIBRARY_BASE_URL`. The first
+interactive enable asks for the AW Sandbox Key with hidden input. CI or another
+non-interactive host must inject `FORGEAX_ASSET3D_AW_SANDBOX_KEY` from its own secret
+store.
+
+> [!IMPORTANT]
+> Do not place the key on the command line, in `.forgeax/mcp.json`, in a repository
+> `.env`, or in a release artifact. `ANTHROPIC_API_KEY` is unrelated and is never
+> accepted as an Asset3D credential.
+
+## What changed
+
+| Area | `0.3.0` | `0.3.1` |
+|:--|:--|:--|
+| Search adapter | Explicit internal directory catalog | AW `HybridSearch` through the packaged Provider |
+| Authentication | Network gate, reported `authentication=none` | Required `X-Sandbox-Key`, validated before success |
+| Service address | Compiled catalog origin | Explicit `--base-url` or environment configuration |
+| Credential storage | None | User-level versioned JSON, directory `0700`, file `0600` |
+| Project MCP config | Catalog origin and download origins | AW service URL, credential-file path, exact download origins |
+| Failure behavior | Failed when an unknown auth contract appeared | Invalid key/network/address fails closed; new credential is rolled back |
+| Provider delivery | Private external release URL | Digest-pinned archive embedded in the npm package |
+
+The Provider accepts either an AW gateway root or the complete
+`trpc.oasismetric.omcontentserver.http` service root and appends `HybridSearch`
+exactly once. Its request includes `depot_name`, `asset_type=1`, text content type,
+the query, `similarity_score`, and page size. Short-lived signed `res_url` values stay
+inside the Provider; the access check exposes only their canonical origins for the
+download sandbox.
+
+## Security and artifact gates
+
+Before publishing, the exact npm tarball and Provider archive must pass all of these
+checks:
+
+- [ ] TypeScript typecheck, full Game Plugin test suite, and build.
+- [ ] Provider AW/catalog/security tests and Python compile check.
+- [ ] Two independently built Provider archives are byte-identical.
+- [ ] Provider verifier provisions the archive under its exact SHA-256 cache key.
+- [ ] Real AW access check succeeds without printing the key or a signed URL.
+- [ ] Real search/download and Engine import/readback succeed in a fresh project.
+- [ ] Package artifact gate accepts only the declared files and immutable digests.
+- [ ] Secret scan covers source diff, npm tarball, its embedded workflow TGZ and
+  Provider archive, manifests, and file names.
+- [ ] Registry-downloaded npm tarball is byte-identical to the audited candidate.
+
+> [!WARNING]
+> A successful search or download is not Preview acceptance. Release evidence must
+> report Provider access, download, Engine import/readback, and visible Play as
+> separate gates. AW responses do not establish license or commercial-use clearance;
+> those remain asset-release requirements.
+
+## Provider inclusion
+
+The pinned Darwin arm64 Provider identity for this release is:
+
+```text
+provider commit: c181c48fbffc933a7ce9a0836f7878ca5e6d77e1
+archive sha256: c8d2afd7ba68ae4b3540c927a2ff7133a82ea90975d09cab1d10b003fbbdeed3
+```
+
+The exact archive is embedded beneath `assets/asset3d/provider/` in the npm tarball.
+`asset3d enable` verifies this SHA-256 before provisioning and does not fetch Provider
+code from GitHub, Gongfeng, or another repository. This makes cache-empty enablement
+depend only on npm installation, local Python 3.11/3.12, the explicitly configured AW
+service, and a valid user-supplied AW key.
+
+The repository intentionally does not track the generated 17.2 MB Provider binary.
+Release packaging injects the already audited archive through
+`FORGEAX_ASSET3D_PROVIDER_BUNDLE`; the package artifact gate rejects any tarball that
+omits it or contains different bytes.
+
+## Maintainer commands
+
+```bash
+bun run typecheck
+bun test test/*.test.ts
+FORGEAX_ASSET3D_PROVIDER_BUNDLE=<audited-provider-archive> bun run build
+FORGEAX_ASSET3D_PROVIDER_BUNDLE=<audited-provider-archive> \
+  npm pack --ignore-scripts --json --pack-destination <audited-directory>
+bun scripts/check-package-artifact.ts <audited-directory>/forgeax-game-0.3.1.tgz
+```
+
+Publishing, npm registry readback, and any merge request are separate irreversible or
+remote-state steps. Record the exact Git heads and artifact digests at each boundary.

package/package.json

@@ -1,7 +1,7 @@
 {
   "packageManager": "bun@1.3.14",
   "name": "@forgeax/game",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "private": false,
   "type": "module",
   "description": "@forgeax/game — an MCP/CLI connector for exact released ForgeaX Engine games and Engine-owned Preview.",
@@ -22,6 +22,7 @@
     "assets",
     "docs/asset3d.md",
     "docs/release-0.3.0.md",
+    "docs/release-0.3.1.md",
     "README.md"
   ],
   "scripts": {