@forgeax/game 0.3.7 → 0.3.9

package/README.md

@@ -9,8 +9,8 @@ creation, build, and Preview to the exact Engine SDK instead of carrying a secon
 runtime.
 
 > [!IMPORTANT]
-> The published package carries `forgeax-game` and scoped `game` binary aliases and resolves the exact
-> `@forgeax/engine-sdk@0.1.26` and `pnpm@11.7.0` dependencies. It has no
+> The package carries `forgeax-game` and scoped `game` binary aliases and resolves the exact
+> `@forgeax/engine-sdk@0.2.1` and `pnpm@11.7.0` dependencies. It has no
 > `@forgeax/game-runtime` dependency and no static Preview fallback.
 
 ## Supported flow
@@ -22,8 +22,8 @@ flowchart LR
     CARRIER["Exact npm SDK carrier"] --> GAME
     PLUGIN["@forgeax/game"] --> INSTALL
     PLUGIN --> INIT
-    GAME --> BUILD["Exact Engine CLI build --json"]
-    BUILD --> PREVIEW["Exact Engine CLI preview --json"]
+    GAME --> BUILD["Exact Engine CLI project build --json"]
+    BUILD --> PREVIEW["Exact Engine CLI project preview --json"]
     PREVIEW --> PROOF["Release-aware readiness proof"]
 ```
 
@@ -47,8 +47,6 @@ npx -y @forgeax/game init
 The first command writes the `forgeax` MCP member in the canonical Codex,
 Cursor, and Claude Code user configs. It preserves unrelated bytes and values,
 reports `CURRENT` on an idempotent rerun, and says which host must restart or reload.
-Existing older package-owned Asset3D MCP entries are also refreshed; absent or
-custom Asset3D entries are not added or overwritten.
 The second command must run from the intended blank directory. It creates the Engine
 game there, binds the exact release identity, and reports the canonical root and
 host-skill result. Existing exact games are read back and bound without recreation;
@@ -65,36 +63,21 @@ npx -y @forgeax/game@latest update --ide codex
 `plugin 0.3.4 -> 0.3.5`. It refreshes configuration, skills, and routing from the
 package being executed; it does not independently fetch another package.
 
-See [0.3.5 compatibility notes](docs/release-0.3.5.md) before upgrading games pinned
-to older Engine versions. This release recognizes strict v2 manifests without
-requiring the removed `entry` field, but does not migrate game dependencies.
+This version consumes the exact Engine SDK pin in package.json; it does not migrate game dependencies.
 
 > [!NOTE]
-> Asset3D is optional and **disabled by default**. The two commands above never contact
-> 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
-> ```
->
-> With no override, `enable` keeps the public AW depot. On the office network, pass
-> `--library ea` to select the EA depot and its local gateway. `--base-url` overrides
-> only the selected library's gateway. The first enable prompts for the Sandbox Key
-> with hidden input, validates it through
-> the packaged Provider, and stores it outside the project in a private user
-> credential file.
+> Asset3D is optional and disabled by default. After init, run
+> `npx -y @forgeax/game asset3d enable`. It directly validates the selected
+> service and stores credentials outside the project. See [Asset3D](docs/asset3d.md).
 
 ## Agent completion contract
 
 `init` records `.forgeax/game-authoring-baseline.json` before gameplay authoring. An
-untouched Empty template remains runnable, but once gameplay or assets change the
-connector refuses Preview until the Agent has replaced the template identity, kept a
-single game README heading, removed the Empty package output name, updated gameplay
-tests, and documented controls. A valid behavior test imports a named game-specific
-state transition or rule and exercises it with an assertion; merely renaming an Empty
-template test does not qualify. Authoring layout follows the installed Engine and
-`forge.json` (v2 uses `assets/` and `plugins[]`); the Studio-hosted
+untouched Empty template remains runnable. After making a game, replace the Empty
+identity and README, document controls, and test a real gameplay rule rather than
+renaming the template test. The connector checks completion evidence before Preview.
+Authoring layout follows the installed Engine and
+`forge.json` (Engine 0.2.1 uses `assets/` Packs and `roots`); the Studio-hosted
 `.forgeax/games/<slug>` layout is never created by this package.
 
 Every supported host receives the same packaged `forgeax-game` Skill and routing rule.
@@ -104,10 +87,10 @@ Preview `ready` verifies startup and ownership, not playable behavior. Agents us
 available browser tools for task-relevant interaction checks, or clearly report
 gameplay as unverified and provide manual checks. This guidance does not prescribe
 a game genre, UI implementation, browser brand, or additional blocking gate.
-An explicit request for an existing/library 3D asset requires the separately installed
-project-local `asset3d-search/search_asset` tool. When it is absent, Agents must report
-`BLOCKED(asset-library-tools-missing)` instead of relabeling procedural geometry or
-generation as an asset-library result.
+An explicit request for an existing/library 3D asset uses the enabled project's
+`asset3d candidates` and `asset3d import` CLI commands. No separate Agent MCP tool
+is required. Report CLI failures rather than relabeling procedural geometry or
+generation as an asset-library result. See the [Skill + CLI integration standard](docs/plugin-integration-standard.md).
 
 ## MCP transports
 
@@ -137,13 +120,11 @@ root and never accepts a caller-provided `target_dir`.
 | `forgeax_game_read_logs` | HTTP tool | Read a bounded Preview log tail for remote diagnosis |
 | `forgeax_game_write_file` | HTTP tool | Atomically create or hash-guard replacement of a text file |
 
-The build plus Preview-readiness deadline is 150 seconds. Preview readiness starts
-with one bounded `CommandEnvelope@1.0.0`. Engines that expose
-`GET /.forgeax/preview-health` are bearer-authenticated and must echo the canonical
-root, exact release, build digest, and instance ID. Released Engine 0.1.7 emits the
-documented minimal Preview envelope instead; the connector binds its already verified
-release and fresh instance ID, then reads the served `forgeax-dist.json` and requires
-its SHA-256 to equal the build it just produced.
+The build plus Preview-readiness deadline is 150 seconds. Engine 0.2.1 emits
+structured `project build` and `project preview` envelopes. Where authenticated
+`GET /.forgeax/preview-health` is available, it must echo the canonical root,
+exact release, build digest, and instance ID; the connector also checks the
+served build artifact against the build it just produced.
 
 Any build or Preview failure is an MCP `isError` result. Agents must not probe or
 reuse an existing localhost port after a failed call: HTTP 200 is not ownership
@@ -178,107 +159,15 @@ Stop and cancellation signal only the verified owning Preview process, with a bo
 TERM/KILL cleanup. Dead state is removed under the lock; a matching orphan is adopted;
 a live unverifiable PID fails closed as `preview_ownership_unverified`.
 
-## Asset3D installation and transaction
+## Asset3D: Skill + CLI
 
-Asset3D is an opt-in, project-local MCP integration for AW or EA HybridSearch. Run it
-only after `init`. The no-argument command remains public-network compatible; select
-EA explicitly when connected to the office network:
+The installed `art-3d-asset-library` Skill guides candidate selection and result use.
+The package CLI calls the asset API directly, safely downloads Pack/GLB sources,
+and delegates import/build/catalog identity to Engine. There is no Asset3D MCP,
+Python Provider, per-platform bundle or legacy Skill payload.
 
-```bash
-# Public/default
-npx -y @forgeax/game asset3d enable
-
-# Office network
-npx -y @forgeax/game asset3d enable --library ea
-
-forgeax-game asset3d doctor --json
-```
-
-The library selection precedence is `--library`, then
-`FORGEAX_ASSET_LIBRARY`, then `aw`. Each library selects its matching built-in
-gateway. Gateway precedence is explicit `--base-url`, then
-`FORGEAX_ASSET_LIBRARY_BASE_URL`, then that library's built-in service. An override
-accepts either a gateway root or the full
-`trpc.oasismetric.omcontentserver.http` service root. 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 the selected depot's `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 selected service URL, matching
-`AW_API_DEPOT_NAME=aw|ea`, and the credential-file path; it never contains the key or
-a signed asset URL. The `AW_API_*` names are the packaged Provider's legacy
-environment contract. 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 digest-pinned Darwin arm64 and Linux x64 Provider archives
-as inert assets. `enable` selects only the archive matching the current host and
-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`.
-
-`enable` also registers a project-aware `asset3d-search` bridge in those hosts. The
-bridge entry contains no project path or credential: on each new Agent session it
-resolves the current directory's project-local Provider. In projects where Asset3D
-has not been enabled, the bridge connects normally but advertises no tools. Restart
-the selected Agent after the first successful `enable` so it discovers `search_asset`.
-
-> [!IMPORTANT]
-> Asset3D uses the shared `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:
-
-```bash
-
-forgeax-game asset3d begin --query "weathered oak tree" --json
-# Call asset3d-search/search_asset with the exact queries and returned execution UUID.
-# The bridge validates the transaction, injects its private output directory, and
-# stores the exact provider result for commit:
-forgeax-game asset3d commit --execution <uuid> --json
-
-forgeax-game asset3d doctor --json
-forgeax-game asset3d uninstall
-```
-
-<details>
-<summary>Maintainer-only local bundle installation</summary>
-
-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 https://<approved-download-host>:443 \
-  --aw-base-url <ea-gateway-or-service-url> \
-  --aw-credential-file /absolute/path/to/private-credential.json
-```
-
-`--catalog-base-url` remains an explicit compatibility-only adapter for the retired
-directory service; normal users should not select it.
-
-</details>
-
-Provider output is checked at a 1 MiB stdin boundary. The transaction ignores
-`downloaded_to`, accepts only declared relative manifest paths contained by its
-private quarantine, and publishes the whole asset directory under
-`assets/3d/ea-3d/<providerAssetId>`. It invokes only the exact released Engine CLI
-with `asset add ... --reimport-policy semantic-only --json`, then requires
-verify/list/inspect readback before committing provenance. Same-digest content is
-reused only after live file and catalog checks; changed content requires `--refresh`
-and rolls back the entire prior directory on failure.
-
-See [docs/asset3d.md](docs/asset3d.md) for the platform, origin, ownership, recovery,
-and evidence boundaries.
+See [usage and configuration](docs/asset3d.md) and the
+[capability authoring template](docs/plugin-integration-standard.md).
 
 ## Scope boundary
 
@@ -289,11 +178,4 @@ and evidence boundaries.
 > acceptance gates.
 
 See [docs/runtime.md](docs/runtime.md) for the exact artifact and lifecycle contract.
-For the current AW-default plus explicit EA environment contract and maintainer
-publish checklist, see [docs/release-0.3.4.md](docs/release-0.3.4.md). The AW-default
-plus explicit EA environment contract was introduced in
-[docs/release-0.3.3.md](docs/release-0.3.3.md). The original AW
-production default is recorded in [docs/release-0.3.2.md](docs/release-0.3.2.md), authenticated Provider
-delivery is documented in [docs/release-0.3.1.md](docs/release-0.3.1.md),
-and the original two-command onboarding contract remains documented in
-[docs/release-0.3.0.md](docs/release-0.3.0.md).
+For current asset configuration and the breaking simplification, see [Asset3D](docs/asset3d.md).