@forgeax/game 0.2.4 → 0.3.0

package/README.md

@@ -1,252 +1,231 @@
 # `@forgeax/game`
 
 [![npm](https://img.shields.io/npm/v/@forgeax/game?label=npm)](https://www.npmjs.com/package/@forgeax/game)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](./package.json)
-[![MCP](https://img.shields.io/badge/MCP-stdio-6f42c1)](https://modelcontextprotocol.io/)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.13-339933?logo=node.js&logoColor=white)](./package.json)
+[![MCP](https://img.shields.io/badge/MCP-stdio%20%7C%20streamable--http-6f42c1)](https://modelcontextprotocol.io/)
 
-ForgeaX game development as a self-contained plugin for MCP-capable agent clients.
-One executable provides both surfaces:
-
-- `forgeax-game` with no arguments runs the stdio MCP server.
-- `forgeax-game <command>` performs one-time setup and project operations.
-
-The package has one exact runtime dependency, `@forgeax/game-runtime@0.3.33`, and
-externalizes it from the Game bundle.
+Two-command MCP/CLI onboarding for ForgeaX Engine games. The Game Plugin delegates
+creation, build, and Preview to the exact Engine SDK instead of carrying a second
+runtime.
 
 > [!IMPORTANT]
-> The normal user path does **not** require a ForgeaX source checkout, Bun workspace,
-> or a manually started Studio. The plugin installs the matching Skill and obtains a
-> versioned ForgeaX Runtime artifact on first use, then builds and serves a static game
-> preview itself. `FORGEAX_START_COMMAND` is an advanced override for private or
-> development deployments only.
+> The published package carries `forgeax-game` and scoped `game` binary aliases and resolves the exact
+> `@forgeax/engine-sdk@0.1.7` and `pnpm@11.7.0` dependencies. It has no
+> `@forgeax/game-runtime` dependency and no static Preview fallback.
+
+## Supported flow
+
+```mermaid
+flowchart LR
+    INSTALL["npx -y @forgeax/game install --ide codex,cursor,claude"] --> HOSTS["Agent MCP entries"]
+    INIT["npx -y @forgeax/game init"] --> GAME["Engine game in current directory"]
+    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"]
+    PREVIEW --> PROOF["Release-aware readiness proof"]
+```
 
-## Install
+`install` verifies the unbound package identity before changing any Agent config.
+`init` creates the default empty game in a genuinely blank current directory through
+the exact Engine carrier, then binds routing and host skills. The connector never asks
+users to download an SDK, unpack a carrier, run a third Engine command, or set a
+mutable SDK path/environment override.
 
-### New client setup
+## Two-command onboarding
 
-Run this once per machine to add the ForgeaX MCP server to the selected agent client.
+Requirements: Node.js `>=22.13.0` and a genuinely blank target directory for `init`.
+The exact package and Engine carrier are resolved by npm and the Game Plugin.
 
 ```bash
 npx -y @forgeax/game install --ide codex,cursor,claude
+cd ./empty-game-directory
+npx -y @forgeax/game init
 ```
 
-For ZCode, use `--ide zcode`; this writes its native user configuration to
-`~/.zcode/cli/config.json` and can run from any directory:
+The first command writes only 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.
+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;
+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
+> `asset3d-search` to the project. Enable it only in an already initialized project:
+>
+> ```bash
+> npx -y @forgeax/game asset3d enable
+> ```
+
+## 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. Standalone source remains in `<game-root>/src`; 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.
+They require UI to mount under the Engine Host `uiRoot` or `#game-ui`. The released
+standalone Host provides `#game-ui`; direct `document.body` mutation is rejected.
+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.
+
+## MCP transports
+
+Local Agent clients should use the default stdio transport installed by
+`forgeax-game install`. For a shared local daemon, bind only to loopback:
 
 ```bash
-npx -y @forgeax/game install --ide zcode
+forgeax-game mcp --transport http --host 127.0.0.1 --port 18940 --root "$PWD"
 ```
 
-Configure several clients in one pass:
+The Streamable HTTP endpoint is `http://127.0.0.1:18940/mcp`. A non-loopback
+listener requires `FORGEAX_REMOTE_MCP_TOKEN`; `--require-auth` also enforces bearer
+authentication on loopback. HTTP mode adds bounded game-file tools under the fixed
+root and never accepts a caller-provided `target_dir`.
 
-```bash
-npx -y @forgeax/game install --ide codex,claude,cursor,zcode
+## MCP surface
+
+| Surface | Kind | Contract |
+|:--|:--|:--|
+| `forgeax://status` | Resource | Read-only game, Engine release, DevKit, and Preview identity |
+| `forgeax_status_lite` | Tool | Resource fallback for clients without MCP resource support |
+| `forgeax_run_current_game` | Tool | Exact Engine build followed by start/reuse of Engine-owned Preview |
+| `forgeax_generate_image` | Tool | Existing image-generation helper; outside the G0 Preview cutover |
+| `forgeax_generate_3d` | Tool | Generation fallback used only for misses after the Asset3D search lifecycle |
+| `forgeax_game_list_files` | HTTP tool | List non-hidden files below the selected game |
+| `forgeax_game_read_file` | HTTP tool | Read one UTF-8 game file and return its SHA-256 |
+| `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.
+
+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
+evidence. Only a successful result containing `preview.status: ready`, `preview_url`,
+`preview.root`, `preview.build_digest`, and `preview.instance_id` authorizes a Preview
+claim. If another game owns the Engine port, stop that game explicitly or report the
+blocker; never substitute its URL.
+
+## Preview ownership
+
+Per game, connector-owned state lives at:
+
+```text
+<project>/.forgeax/run/engine-preview/<sha256(canonical-game-root)>/
+├── lock
+├── state.json
+├── stdout.log
+└── stderr.log
 ```
 
-Omitting `--ide` configures every supported client. User-scoped clients can be
-installed before a project exists; Trae and VS Code use project scope and are written
-when `install` runs inside the project. The original WorkBuddy name remains accepted
-as an alias of the current CodeBuddy client:
+The directory is `0700`; files are `0600`; logs rotate at 8 MiB and keep two prior
+files. Reuse requires the build/Engine/instance identity, unchanged process-start
+identity, and either authenticated health or the exact served dist digest after MCP
+restart. PID alone never authorizes a signal.
 
 ```bash
-npx -y @forgeax/game install --ide trae,workbuddy
+forgeax-game preview stop --target-dir ./my-game
+forgeax-game preview stop --target-dir ./my-game --json
 ```
 
-Before writing any config, the installer launches the exact command it intends to
-store and completes a real `initialize` → `tools/list` → `resources/list` handshake.
-Existing config files are merged, and a changed file is backed up beside the original
-with the `.bak.latest` suffix.
+Stop and cancellation signal only the verified owning Preview process, with a bounded
+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`.
 
-### Create a project
+## Asset3D installation and transaction
 
-Choose an empty directory and initialize a game there:
+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:
 
 ```bash
-cd /path/to/empty-directory
-npx -y @forgeax/game init
+npx -y @forgeax/game asset3d enable
+forgeax-game asset3d doctor --json
 ```
 
-`init` creates the ForgeaX project, installs the matching Engine SDK, and mounts the
-bundled Skills for every client that already has a ForgeaX MCP entry. Use
-`--game <slug>` to choose a game name or `--ide zcode` when initializing a project
-for ZCode specifically.
+`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
+`asset3d-search` entries into `.forgeax/mcp.json` and project the approved Asset3D
+workflow into the Agent hosts selected during `install`.
 
 > [!IMPORTANT]
-> `init` does not install the user-level MCP entry. A new machine must run
-> `install --ide zcode` once before `init`. A user who already has the `forgeax`
-> entry configured in ZCode can run `init` directly for each new project.
-
-### Refresh an existing project
+> 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.
 
-For a project that was initialized previously, use `update` instead of running the
-same `init` again:
+The transaction commands are normally driven by the installed Agent workflow:
 
 ```bash
-cd /path/to/existing-forgeax-project
-npx -y @forgeax/game update
-```
 
-If the project has no game-development Skills yet, use:
+forgeax-game asset3d begin --query "weathered oak tree" --json
+# Call the configured asset3d-search/search_asset MCP tool with the returned output_dir.
+# Pass its complete TextContent JSON to commit on stdin:
+forgeax-game asset3d commit --execution <uuid> --provider-result-stdin --json < result.json
 
-```bash
-npx -y @forgeax/game devkit install
+forgeax-game asset3d doctor --json
+forgeax-game asset3d uninstall
 ```
 
-After installing or refreshing ZCode Skills, open the project as a ZCode workspace,
-refresh Settings → Skills, and start a new session. Check Settings → MCP Servers or
-run `/mcp status` to confirm `forgeax` is connected.
+<details>
+<summary>Maintainer-only local bundle installation</summary>
 
-For local package development or offline use, pin the currently running executable:
+The low-level command remains available for producing and validating platform release
+artifacts. It is not the user onboarding path.
 
 ```bash
-bun src/main.ts install --ide codex --local
+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
 ```
 
-## Commands
-
-| Command | Purpose |
-|:--|:--|
-| `install [--ide a,b] [--local]` | Verify the MCP launch command, then merge client configuration |
-| `init [--game <slug>] [--ide ...]` | Create a project/game, install routing rules, and materialize the bundled Engine SDK |
-| `use <slug>` | Activate an existing game through the server |
-| `doctor` | Check Node, project binding, service tiers, and client configuration |
-| `devkit install` | Install the game-development Skill and host rules; use `forgeax-install` only when available |
-| `agents update` | Insert or refresh only the managed ForgeaX block in `AGENTS.md` |
-| `update [--ide ...]` | Verify the published launch command, refresh installed client entries, and update project routing rules |
-
-`init` can create the minimal `.forgeax/` instance and game in an ordinary empty
-directory. It also installs `.forgeax/engine-sdk/`, containing declarations, API
-metadata, both canonical templates (`game-default` and `game-empty`), authoring
-skills, and the Engine implementation source generated from the same Engine pin as the
-selected Runtime package. `use`, `devkit install`, and `agents update` operate on the nearest
-project root. Runtime extraction and startup are automatic; a running server is not
-an `init` prerequisite.
+The catalog authority must also be an exact member of `--download-origin`.
 
-## MCP surface
+</details>
 
-The server intentionally exposes only high-frequency development-loop operations.
-Installation and project mutation stay in the CLI so models do not reconsider
-one-time actions on every turn.
+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.
 
-| Entry | Kind | Use |
-|:--|:-:|:--|
-| `forgeax://status` | Resource | Preferred read-only project, service, and next-action status |
-| `forgeax_status_lite` | Tool | Status fallback for clients without MCP resource support |
-| `forgeax_run_current_game` | Tool | Build or reuse the active game's static preview, return its URL and health identity, and identify the runtime log file |
-| `forgeax_generate_image` | Tool | Text-to-image, or image-to-image with a local `image`; saves a PNG/JPG into the active game's `assets/` and returns its path |
-| `forgeax_generate_3d` | Tool | Text-to-3D (`prompt`) or image-to-3D (public https `image` URL); runs the async job to completion and saves a `.glb` into `assets/` |
+See [docs/asset3d.md](docs/asset3d.md) for the platform, origin, ownership, recovery,
+and evidence boundaries.
 
-When this plugin cold-starts the managed Runtime, runtime output is written to:
+## Scope boundary
 
-```text
-<project>/.forgeax/logs/runtime/runtime.log
-```
-
-Read that file with the host client's normal file tools. Runtime process output is
-captured there; exceptions thrown inside the browser remain in the browser console.
-The run result reports the Runtime version, instance identity, selected ports, and
-whether the log belongs to the current plugin-owned process; status reports the
-cached Runtime installation state.
-
-Runtime artifacts are cached per platform and version under `~/.forgeax/runtimes/`.
-The selected `@forgeax/game-runtime-<platform>-<arch>` package carries the archive,
-so first run verifies and extracts npm-installed bytes without another download.
-The cache uses a checksum-verified ready
-marker and keeps the previous version until a new version has started successfully.
-`forgeax_run_current_game` reports `runtime.version`, `engine_sdk.commit`, and a
-combined `engine.identity`; those must match before preview acceptance.
-
-The game SDK is available at `.forgeax/engine-sdk/`. Use its declaration files and
-`templates/game-default` or `templates/game-empty` before writing imports. If an API
-is absent, inspect `source/<package>/src/` instead of guessing.
-
-### Asset generation (LiteLLM)
-
-`forgeax_generate_image` and `forgeax_generate_3d` produce art and 3D assets through a
-LiteLLM gateway and save them into the active game's `assets/` directory, returning the
-project-relative path to reference from game code. Configure via environment:
-
-| Variable | Required | Default |
-|:--|:-:|:--|
-| `FORGEAX_LITELLM_API_KEY` | yes | — (secret; never commit it) |
-| `FORGEAX_LITELLM_BASE_URL` | no | the shared ForgeaX gateway |
-| `FORGEAX_GEN_IMAGE_MODEL` | no | `gemini-3-pro-image` |
-| `FORGEAX_GEN_3D_TEXT_MODEL` | no | `tripo-3d-text` |
-| `FORGEAX_GEN_3D_IMAGE_MODEL` | no | `tripo-3d-image` |
-| `FORGEAX_COS_BUCKET` / `FORGEAX_COS_REGION` | for local image-to-3D | — |
-| `FORGEAX_COS_SECRET_ID` / `FORGEAX_COS_SECRET_KEY` | for local image-to-3D | — (secret; never commit) |
-
-- **Text-to-image / image-to-image**: `forgeax_generate_image({ prompt, image? })`. A
-  local `image` path switches to editing that image with the prompt.
-- **Text-to-3D**: `forgeax_generate_3d({ prompt })` — submits, polls to completion
-  (~1–2 min), and downloads the `.glb`.
-- **Image-to-3D**: `forgeax_generate_3d({ image })`. `image` is a **public https URL**,
-  or a **local file path** when COS is configured — the file is uploaded to the COS
-  bucket and passed to the backend as a short-lived presigned URL (the private bucket
-  stays private; the URL expires within the hour). This makes the "generate a concept
-  image, then turn it into a mesh" flow work end to end. Without COS, only a public URL
-  is accepted, because the 3D endpoint rejects local paths and inline base64.
-
-## Supported clients
-
-| Client ID | Config path | Scope |
-|:--|:--|:-:|
-| `codex` | `~/.codex/config.toml` | User |
-| `claude` | `~/.claude.json` | User |
-| `cursor` | `~/.cursor/mcp.json` | User |
-| `trae` | `<project>/.trae/mcp.json` | Project |
-| `codebuddy` / `workbuddy` | `~/.codebuddy/.mcp.json` | User |
-| `windsurf` | `~/.codeium/windsurf/mcp_config.json` | User |
-| `vscode` | `<project>/.vscode/mcp.json` | Project |
-| `zcode` | `~/.zcode/cli/config.json` | User |
-| `opencode` | `~/.config/opencode/opencode.json` | User |
-
-> [!NOTE]
-> `workbuddy` is an accepted installer alias. Both names target CodeBuddy's current
-> MCP file, so selecting both does not create duplicate entries.
->
-> The OpenCode entry follows its stable configuration schema (`mcp.<name>`,
-> `type: "local"`, and an argv-style `command`). It is process-verified with
-> OpenCode 1.17.9: `opencode mcp list` starts this package and reports
-> `forgeax connected`. If a future client release changes the schema, `doctor`
-> will still report whether the configured entry matches what this package writes.
->
-> ZCode uses its native `mcp.servers.<name>` user configuration rather than the
-> `.agents/mcp.json` fallback. Project Skills are installed under `.zcode/skills`;
-> start a new ZCode session and run `/mcp status` after installation.
-
-## Game development Skill
-
-The canonical Skill lives at the repository root in `skills/forgeax-game/`. Package
-builds derive the copy shipped under `assets/`; there is no second handwritten source.
-The Skill contains the MCP/file/browser decision loop, failure recovery, current
-engine-project map, example-selection rules, scaffold/template authority, and the
-real Studio-versus-Play validation boundary.
-
-The published package also carries the host-install metadata needed to expose that
-Skill directly to Codex, Claude Code, Cursor and other configured clients. A harness
-checkout is optional compatibility support, not a user prerequisite. Inside a ForgeaX
-project, `install`, `init`, and `update` refresh it automatically. It can also be
-installed explicitly:
-
-```bash
-npx -y @forgeax/game devkit install
-```
-
-When the project already has a `.forgeax-harness/install-manifest.json`, the command
-may replay that project's recorded `forgeax-install` specification. Otherwise the
-published package uses its bundled host-install metadata and writes only its managed
-Skill/rule blocks. It never reports a successful user install while silently requiring
-a missing harness checkout.
-
-## Develop
-
-```bash
-bun run typecheck
-bun test
-bun run build
-node dist/main.js help
-```
+> [!WARNING]
+> G0/A0 packed and controlled-fixture evidence is supporting evidence only. It does
+> not prove Studio, Editor, RuntimeInstance, host permission parity, visible Play, or
+> real EA/provider access. Those remain separate downstream integration and terminal
+> acceptance gates.
 
-The handshake end-to-end test builds `dist/main.js`, executes that file through its
-Node shebang, and verifies the real MCP surface.
+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).

package/assets/asset3d/schemas/receipt-1.0.0.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "forgeax.asset3d-search-receipt/1.0.0",
+  "title": "ForgeaX Asset3D Search Receipt",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "provider",
+    "providerCommit",
+    "originSetDigest"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "forgeax.asset3d-search-receipt/1.0.0"
+    },
+    "provider": {
+      "const": "ea-3d"
+    },
+    "providerCommit": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{40}$"
+    },
+    "originSetDigest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  }
+}