@forgeax/game 0.3.1 → 0.3.3

package/docs/asset3d.md

@@ -54,17 +54,22 @@ 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.
 
-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
+Normal installation writes the selected service root to `AW_API_BASE_URL`, the
+matching `AW_API_DEPOT_NAME=aw|ea`, and an absolute user credential-file path to
+`AW_API_CREDENTIAL_FILE`. The `AW_API_*` names are the packaged Provider's legacy
+environment contract. Installation 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` 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
+`asset3d enable` keeps the public AW depot by default. `--library ea` selects the EA
+depot and its office-network local gateway; `FORGEAX_ASSET_LIBRARY=ea` is the
+deployment equivalent. Gateway selection precedence is explicit `--base-url`, then
+`FORGEAX_ASSET_LIBRARY_BASE_URL`, then the selected library's built-in service.
+Gateway overrides never change the selected depot. The first interactive run asks
+for the 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.
 
@@ -107,6 +112,13 @@ idempotent. Uninstall removes only entries and Skill files that still match owne
 digests, leaving user-modified or unrelated content in place and reporting the
 collision.
 
+For user-scoped MCP hosts such as Codex, Cursor, and Claude, `enable` additionally
+registers a non-secret `asset3d-search` bridge command. The bridge resolves
+`.forgeax/asset3d-install.json` and the owned `.forgeax/mcp.json` entry from the host
+process working directory, rather than pinning a user config to one project. A
+project without an Asset3D installation receives a healthy MCP handshake with an
+empty tool list. Start a new Agent session after enabling so `search_asset` appears.
+
 The workflow package is projected beneath `art-3d-asset-library/` in exactly these
 mounts unless `--ide` selects a subset:
 
@@ -125,19 +137,22 @@ has its path, byte count, and digest in the ownership manifest.
 
 1. `asset3d begin` records a private journal with a new execution UUID, query digest,
    provider identity, exact Engine identity, requested count, and the only allowed
-   quarantine root. It returns the relative `output_dir` for `search_asset`; the
-   provider's `MCP_SHARED_PATH` is the same private `workspace/` root, so declared
-   manifest paths and transaction validation address identical bytes.
-2. The configured provider writes beneath that directory and returns one checked
-   `forgeax.asset3d-search-result/1.0.0` TextContent JSON object.
-3. `asset3d commit --provider-result-stdin` reads at most 1 MiB, validates exact
-   fields/counts/roles/digests/sorted relative paths, and ignores `downloaded_to`.
-4. The transaction rejects symlinks, special files, undeclared files, realpath escape,
+   quarantine root.
+2. `search_asset` accepts that execution UUID instead of an output path. The Game
+   Plugin bridge verifies the exact queries and injects the transaction-owned
+   provider directory beneath its private `workspace/` root.
+3. The configured provider writes beneath that directory and returns one checked
+   `forgeax.asset3d-search-result/1.0.0` TextContent JSON object. The bridge stores
+   those exact bytes against the execution; the agent does not copy the object.
+4. `asset3d commit --execution <uuid>` reads the stored result (at most 1 MiB),
+   validates exact fields/counts/roles/digests/sorted relative paths, and ignores
+   `downloaded_to`.
+5. The transaction rejects symlinks, special files, undeclared files, realpath escape,
    byte mismatch, or digest mismatch before a project asset write.
-5. A 30-second per-asset lock serializes publication at
+6. A 30-second per-asset lock serializes publication at
    `assets/3d/ea-3d/<safeAssetId>`. The complete prior directory is preserved as the
    refresh/rollback snapshot.
-6. With the game root as `cwd`, Game Plugin runs the exact released Engine CLI:
+7. With the game root as `cwd`, Game Plugin runs the exact released Engine CLI:
 
    ```text
    asset add assets/3d/ea-3d/<safeAssetId> --reimport-policy semantic-only --json
@@ -149,7 +164,7 @@ has its path, byte count, and digest in the ownership manifest.
    Each command must produce exactly one newline-terminated, at-most-1-MiB
    `CommandEnvelope@1.0.0`. Game Plugin does not filter diagnostic stdout into a
    synthetic success.
-7. Only after Engine readback succeeds does `.forgeax-asset.json` publish the provider
+8. Only after Engine readback succeeds does `.forgeax-asset.json` publish the provider
    commit, origin-set digest, exact Engine version/commit, per-file role/digest/bytes,
    Engine rows, and catalog readback. An Engine failure restores the whole previous
    asset directory.

package/docs/release-0.3.2.md

@@ -0,0 +1,90 @@
+# `@forgeax/game` 0.3.2 release guide
+
+Version `0.3.2` keeps Asset3D opt-in while making the documented AW production
+service the default selected by `asset3d enable`. Test and pre-release environments
+remain explicit overrides.
+
+## 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 production Asset3D without passing an address:
+
+```bash
+npx -y @forgeax/game asset3d enable
+npx -y @forgeax/game asset3d doctor --json
+```
+
+> [!IMPORTANT]
+> Asset3D remains disabled until the user runs `asset3d enable`. A no-argument enable
+> selects production; it does not make `install` or `init` contact AW.
+
+To select a non-production environment, pass its gateway or complete service URL:
+
+```bash
+npx -y @forgeax/game asset3d enable \
+  --base-url <test-gateway-or-service-url>
+```
+
+## Environment selection
+
+| Priority | Input | Selected environment |
+|--:|:--|:--|
+| 1 | `--base-url` | Explicit caller-selected service, normally test or pre-release |
+| 2 | `FORGEAX_ASSET_LIBRARY_BASE_URL` | Automation or deployment override |
+| 3 | No override | Documented AW production service |
+
+The built-in production root is:
+
+```text
+http://lb-pl74wsqg-5wi8ujmy1fq2746r.clb.usw-tencentclb.com:8008/trpc.oasismetric.omcontentserver.http
+```
+
+Every selection is normalized so `HybridSearch` is appended exactly once. The
+selected endpoint is validated by the packaged Provider before project configuration
+is published.
+
+## Authentication and safety
+
+The first enable reads an AW Sandbox Key with hidden terminal input. Automation may
+inject `FORGEAX_ASSET3D_AW_SANDBOX_KEY` from a secret store. The plugin never accepts
+`ANTHROPIC_API_KEY` or another model credential as an Asset3D key.
+
+The key remains in the private user credential file. Project MCP configuration
+contains only the selected service URL and the credential-file path. Failed access
+validation or installation rolls back a newly written credential and leaves the
+project disabled.
+
+## Release gates
+
+- [ ] Default resolution selects the exact documented production root.
+- [ ] Explicit CLI URL overrides the environment and production default.
+- [ ] Environment URL overrides the production default when CLI input is absent.
+- [ ] Real production access check succeeds with a valid AW Sandbox Key.
+- [ ] Real production `search_asset` downloads a valid GLB.
+- [ ] Game Plugin transaction validates and commits the asset through Engine.
+- [ ] `doctor` reports the production Provider live in a fresh installed project.
+- [ ] Exact npm tarball and embedded Provider pass the package and secret gates.
+- [ ] Registry-downloaded tarball matches the audited candidate.
+
+> [!WARNING]
+> Provider access and Engine import do not prove visible Play acceptance. If a game
+> consumes the imported asset, verify that game separately in its owned Preview and
+> report the Play result as a distinct gate.
+
+## 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.2.tgz
+```

package/docs/release-0.3.3.md

@@ -0,0 +1,73 @@
+# `@forgeax/game` 0.3.3 release guide
+
+Version `0.3.3` adds the EA depot without removing the public AW path. The packaged
+provider is unchanged; one explicit library selection binds the matching depot and
+gateway together.
+
+> [!IMPORTANT]
+> EA is currently available only through the office-network `local` gateway.
+> There is no reachability-based fallback: silently changing libraries would make
+> identical queries resolve to different assets.
+
+## User contract
+
+```bash
+# Public/default
+npx -y @forgeax/game@0.3.3 asset3d enable
+
+# Office network
+npx -y @forgeax/game@0.3.3 asset3d enable --library ea
+
+npx -y @forgeax/game@0.3.3 asset3d doctor --json
+```
+
+The selected mode writes these non-secret provider settings:
+
+| Mode | Depot | Built-in gateway |
+|:--|:--|:--|
+| Default or `--library aw` | `aw` | Existing public AW service |
+| `--library ea` | `ea` | `http://test-ultrongw.woa.com/trpc.oasismetric.omcontentserver.http` |
+
+`FORGEAX_ASSET_LIBRARY=aw|ea` is the deployment selector. `--base-url` and
+`FORGEAX_ASSET_LIBRARY_BASE_URL` remain gateway overrides and never change the
+selected depot. The project stores only the service URL, depot name, private
+credential-file path, and live-derived download origins.
+
+## Transaction-bound search
+
+`search_asset` accepts the execution UUID returned by `asset3d begin`; it no longer
+accepts a caller-selected `output_dir`. The Game Plugin bridge verifies the execution
+and exact query list, then injects the private quarantine path before invoking the
+packaged provider. This removes agent path guesses such as `assets` from the tool
+contract while preserving the existing provider implementation.
+
+The bridge also persists the exact checked TextContent by execution. A normal commit
+is now `asset3d commit --execution <uuid> --json`; agents no longer reconstruct large
+provider JSON as shell input.
+
+`asset3d enable` now installs the generic `asset3d-search` bridge into every Agent
+host previously selected by `install`. The user-level launch command carries no key
+and no project path; it discovers the active project's owned Provider configuration
+from its working directory. Disabled projects advertise zero Asset3D tools. Start a
+new Agent session after enabling so the host refreshes its MCP tool inventory.
+
+## Verified migration
+
+- [x] EA access check succeeded through the packaged provider.
+- [x] Query `wooden barrel` returned EA asset `SM_Prop_Bucket_001.zip`.
+- [x] The provider downloaded and converted the result to GLB.
+- [x] Delivered result was 565,650 bytes with SHA-256
+  `17897a89e652170e7ab98b08dd71f10c4289e58b38caac52e0b41e44b5f72185`.
+- [x] The primary GLB was 314,908 bytes.
+- [ ] Registry publication and registry-downloaded tarball verification.
+
+## Release gates
+
+```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.3.tgz
+```

package/package.json

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