pelican-engine 0.3.3 → 0.3.6

package/AGENTS.md

@@ -1,5 +1,12 @@
 # Pelican Engine Game Author
 
+For an installed game, start in an empty directory with `npm --prefix . install
+--save-dev --save-exact pelican-engine`, then run `npx pelican dev`. The CLI
+generates the minimal starter when the directory is eligible and preserves existing
+game files. See `docs/GETTING-STARTED.md` in the package for npm and source
+workflows. Commands use common Node/npm syntax; the currently supported development
+environment is Windows, while player support depends on actual browser capabilities.
+
 Your workspace is the game project. Use the public `pelican-engine` API and local
 game modules. Do not modify engine internals or `node_modules`, import Three.js,
 TSL, GPU devices, physics-library objects, compiler internals or Node APIs into
@@ -15,9 +22,10 @@ lists the JSON CLI protocol. `docs/CAPABILITIES.md` records implemented scope an
 limitations. The longer `docs/AI-WORKFLOW.md` is shared design context, not an
 instruction to run source-only engine acceptance tasks.
 
-The shared `docs/M3-USAGE.md` describes the current rendering and compute
-contracts. Its `examples/`, engine `packages/`, and `npm run probe:*` references
-are maintainer references available only in a source checkout; the npm package
+The installed package includes `docs/GRAPHICS-GUIDE.md` and
+`docs/RENDER-BACKENDS.md`. The source checkout's `docs/STATUS.md` summarizes
+current engine capabilities and gaps. Its `examples/`, engine `packages/`, and
+`npm run probe:*` references are maintainer references available only in a source checkout; the npm package
 intentionally contains no example projects, game assets, or engine source. Use
 the same public declarations in your own game project and validate them with the
 installed `pelican` commands. Do not try to import an internal compiled module.
@@ -107,20 +115,26 @@ Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
 `KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],
 restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the
 actual keyboard event; Space is `" "`. Actions are read inside systems through
-`ctx.input.held`, `pressed`, `released`, or `axis`. Always exercise real keyboard
-input in the browser; a mocked system test does not establish browser bindings.
+`ctx.input.held`, `pressed`, `released`, or `axis`. A mocked system test does not
+establish browser bindings; real input requires separate verification when permitted.
 
 ## Work Loop
 
 1. Inspect `pelican.project.json`, `game.ts`, asset declarations and the public API.
 2. Make small game-only edits. Keep the exact engine version lock.
-3. Run `pelican check`, then `pelican dev` and exercise actual gameplay.
+3. Follow the active project policy for running the game or checking gameplay.
 4. Use `inspect`, `input`, `step`, `pause`, `resume`, `snapshot`, `restore`,
-   `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port.
-5. Run `capture --live` against the dev port or a standalone `capture`, inspect
-   the actual screenshot, and preserve explicit failures rather than claiming success.
+  `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port
+   when verification is permitted.
+5. When verification is permitted, use capture and inspect results; preserve
+   explicit failures rather than claiming success.
 6. Run `build` and serve `dist/` over HTTP(S). Keep notices and license files.
 
+The current engine project decision permits compilation and builds only, not
+tests, browser/GPU runs, smoke or other validation. Historical instructions and
+reports do not authorize those activities or establish that they passed for the
+current source.
+
 Installed package commands use `npx --no-install pelican <command>` from the game
 directory. Repository commands use `node --import tsx <engine>/tools/cli.ts
 <command> --project <game-directory>` with the same operations and protocol.

package/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# 参与开发
+
+感谢关注 Pelican Engine！本项目使用 MIT 许可证。游戏作者可以只安装 npm 包；本指南面向需要阅读、修改或维护引擎源码的贡献者。
+
+## 开发前
+
+请先阅读 [当前研发状态](docs/STATUS.md)、[架构](docs/ARCHITECTURE.md) 和与你的改动有关的文档。确认改动范围、现有工作区状态和已知限制，不覆盖他人的未提交文件。公开 API 由 SDK 源码定义；改动接口时应同时维护相关类型、文档和示例。
+
+当前支持的引擎开发环境为 Windows，使用 Node.js 24.x 和 npm。以下是通用 Node/npm 命令的写法，不代表其他开发系统已经受支持。玩家端按实际浏览器与图形能力判断，不设置平台白名单。
+
+## 从源码运行
+
+```sh
+git clone https://github.com/danchar12138/pelican-engine.git
+cd pelican-engine
+npm ci
+npm run dev
+```
+
+`npm run dev` 使用仓库当前默认示例；`npm run build` 将示例静态构建输出到根目录 `dist/`。源码 ZIP 和已有目录也可以使用这些命令，不依赖 Git 元数据。若只是创建游戏，请优先阅读 [快速入门](docs/GETTING-STARTED.md)。
+
+## 单线、单主题提交
+
+- 在 `main` 主工作树按依赖串行工作，不建立额外工作树或开发分支。
+- 一次提交围绕一个功能、修复或版本；不要把无关工作和历史证据混在一起。提交消息使用中文 Conventional Commits，例如 `fix(renderer): 修复资源释放`。
+- 需要发布时在仓库中显式维护统一的标准版本号。推送 `main` 会触发 npm OIDC 发布；版本已存在时不会覆盖。GitHub Release 用于标记里程碑。详见 [发布说明](docs/RELEASING.md)。
+- 用户要求当前只允许编译和构建；不要运行测试、浏览器、GPU、性能、smoke 或其他验证，也不要声称未执行的步骤通过。以前的测试文件和证据保留其历史属性。
+- 不要为整理目录而删除未经确认的用户数据、历史报告或未合并候选；不能递归跟随目录链接或 junction。
+
+## 提交问题或改动
+
+描述目标、涉及的公开接口、实际运行的编译或构建命令、结果与已知缺口。运行或硬件行为未经验证时明确说明。涉及第三方代码或资产时记录来源与许可证；不要提交凭据、开发缓存或构建输出。
+
+- [问题反馈](https://github.com/danchar12138/pelican-engine/issues)
+- [公开 API](docs/api/REFERENCE.md) · [能力说明](docs/CAPABILITIES.md) · [开发状态](docs/STATUS.md)

package/README.md

@@ -1,130 +1,85 @@
-# Pelican Engine npm development distribution
+<div align="center">
+  <img src="https://raw.githubusercontent.com/danchar12138/pelican-engine/main/docs/assets/pelican-mark.svg" alt="Pelican Engine" width="110" height="110">
+  <h1>Pelican Engine</h1>
+  <p><strong>Build games for the web with TypeScript.</strong></p>
+  <p>Code-first · WebGPU-first · Designed for human and external AI workflows</p>
+  <p>
+    <a href="https://www.npmjs.com/package/pelican-engine"><img src="https://img.shields.io/npm/v/pelican-engine?label=npm&amp;color=168b80" alt="npm version"></a>
+    <img src="https://img.shields.io/badge/license-MIT-24536b" alt="MIT license">
+    <img src="https://img.shields.io/badge/TypeScript-SDK-3178c6" alt="TypeScript SDK">
+  </p>
+</div>
+
+Pelican Engine provides a TypeScript SDK, compiler, runtime, renderer and CLI in one package. Define game content and behavior in code, run a local development server and build a static web distribution. AI tools may assist development, but the game runtime does not include an LLM or AI agent.
+
+> **Development status:** this is an evolving engine, not a complete first release. Current source behavior, hardware compatibility, performance and the full feature set have not been fully validated. A normal version number is not an acceptance claim. See the [development status](https://github.com/danchar12138/pelican-engine/blob/main/docs/STATUS.md) for known gaps.
+
+## Quick start
+
+Install Node.js **24.x** and npm, then create a new empty game directory:
+
+```sh
+mkdir my-pelican-game
+cd my-pelican-game
+npm --prefix . install --save-dev --save-exact pelican-engine
+npx pelican dev
+```
+
+The first `dev` creates `game.ts`, `pelican.project.json` and `AGENTS.md` in an eligible empty project. Existing game files and author instructions are not overwritten. The explicit `--prefix .` prevents npm from choosing a parent project; `--save-exact` pins the installed version. Stop the development server before building:
+
+```sh
+npx --no-install pelican build
+```
 
-The installed package is `pelican-engine`. Its root export is the same compiled
-public SDK used by repository games, not a wrapper or a separate SDK. The package
-also provides the `pelican` executable. This is an M3 development distribution,
-not accepted M3 hardware evidence or a complete engine release.
+Deploy the resulting `dist/` directory, including its generated assets and notices, to an HTTP(S) static host. For a nested deployment, use `npx --no-install pelican build --base /game/`.
 
-## Windows project workflow
+Commands use common Node/npm syntax rather than a particular shell. **Engine and game development currently support Windows only**; Linux and macOS development workflows have not been promised or validated. Player platforms are not restricted by brand or OS: actual rendering availability depends on browser and graphics capabilities.
 
-Use Node 24 and npm in an empty project directory. The explicit prefix keeps npm
-in this directory even when a parent directory is also an npm project:
+## Your game
 
-```powershell
-npm --prefix . i -D pelican-engine
-npx pelican dev
+The generated starter defines a scene and a rotating box. Game code imports only the public package, for example:
+
+```ts
+import { defineGame, defineMaterial, defineScene } from "pelican-engine";
+
+const material = defineMaterial({ id: "paint", color: "#38b8a4", roughness: 0.45 });
+const scene = defineScene({
+  id: "main",
+  camera: { position: [4, 3, 6], target: [0, 0, 0], fov: 50 },
+  entities: [
+    { id: "box", mesh: { geometry: { kind: "box" }, material } },
+    { id: "light", light: { kind: "directional", intensity: 4 },
+      transform: { position: [3, 6, 4] } },
+  ],
+});
+export default defineGame({ id: "my-game", scene });
 ```
 
-The first installed `dev` creates the minimal `game.ts`, `pelican.project.json`
-version lock, and game-author `AGENTS.md` when the directory contains only npm
-installation metadata. An existing game or manifest is used as supplied; other
-project files or author instructions prevent automatic scaffolding. Files are
-never overwritten. Stop dev with Ctrl+C, then use the same local CLI:
+Save it as `game.ts` in a project created by the CLI. The exact engine version is recorded in `pelican.project.json`: migrate the game and update its lock explicitly when changing engine versions. Do not edit `node_modules` or import engine internals.
+
+Useful commands:
 
-```powershell
+```sh
+npx --no-install pelican help
 npx --no-install pelican api
-npx --no-install pelican setup --install-browser
-npx --no-install pelican check
+npx --no-install pelican api --symbol defineGame
 npx --no-install pelican dev --port 4173
-npx --no-install pelican capture --port 4174 --output capture.png
 npx --no-install pelican build
 ```
 
-For an exact-version install use `npm --prefix . i -D --save-exact pelican-engine@0.3.3`,
-or substitute the local `pelican-engine-0.3.3.tgz` tarball before registry
-publication. `pelican create --template minimal` remains available explicitly.
-
-Without `--prefix .`, npm may select an ancestor `package.json` or `node_modules`
-as the install root and modify that parent. The shorter `npm i -D pelican-engine`
-works when npm selects the intended directory; verify `npm prefix` before using
-it. The smoke harness uses an explicit prefix and does not require `npm init`.
-
-`create --template minimal` uses the same primitive starter in npm and repository
-workflows. npm defaults to `minimal` and reports the selected template; repository
-default `m2` is preserved with its historical sample assets. Samples are not engine
-capabilities. Identical authored game/asset inputs use the same API/compiler/runtime
-in either channel. npm does not bundle the `m2` sample or any sample/game assets.
-
-`create` writes `game.ts`, `AGENTS.md` and an exact `pelican.project.json` lock in the current
-directory. Existing project files are never overwritten. Author TypeScript with
-named imports from `pelican-engine` and project-local imports only. The compiler
-reports `TC_PUBLIC_API` for renderer, Three.js, TSL, physics, Node and internal
-package imports, including type-only and unused imports. Package subpaths are not
-public exports. Project lock mismatches report `TC_ENGINE_VERSION_MISMATCH`;
-mixed package/API versions report `TC_ENGINE_SDK_VERSION`. Reinstall a matching
-exact version, or migrate through the public API before explicitly changing a lock.
-
-After npm dependencies and Playwright Chromium have been installed, authoring,
-API inspection, checks, builds, dev/control commands and capture need no network
-service. `setup --offline` never installs dependencies or downloads a browser in
-an installed package. Keep the game package-lock for repeatable future installs;
-an offline _reinstall_ additionally requires the npm cache or a dependency mirror.
-`TC_DISTRIBUTION_DEPENDENCY_MISSING` and
-`TC_DISTRIBUTION_DEPENDENCY_VERSION` identify broken tool dependencies.
-
-Serve the generated `dist/` directory over HTTP(S), including its `generated/`
-files, license files, notices and compression manifests. No Node process, engine
-repository, SDK installation, external AI service or development control server
-is needed by players. Use `build --base /game/` for a nested deployment URL.
-Capture requires installed Chromium and actual supported graphics capability.
-No software renderer result establishes hardware acceptance.
-
-## AI entry points
-
-Read the game-author `AGENTS.md`, `docs/npm/GAME-AUTHOR.md`, `docs/CAPABILITIES.md` and
-`docs/api/REFERENCE.md` inside `node_modules/pelican-engine`. The machine-readable
-API is `docs/api/index.json`, also discoverable through `pelican api`.
-`lib/sdk/index.d.ts` is the authoritative installed declaration surface.
-`docs/PELICAN-MIGRATION.md` explains current names and historical provenance.
-Repository paths and release instructions in copied documents are historical
-context; the installed workflow above replaces source-checkout commands.
-The JSON CLI protocol and dev control operations are shared with the repository.
-
-## Maintainer validation and publishing
-
-```powershell
-npm run distribution:test
-npm run distribution:pack
-npm run distribution:smoke
-npm run distribution:smoke -- --gpu
-```
+The renderer prioritizes WebGPU and can use Three.js's built-in WebGL2 raster fallback. Compute-dependent hybrid/path tracing and compute features are not available on WebGL2; unsupported requests return diagnostics rather than silently claiming equivalent rendering. See the [backend guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/RENDER-BACKENDS.md).
+
+## Documentation
+
+- [Getting started: npm and source checkout](https://github.com/danchar12138/pelican-engine/blob/main/docs/GETTING-STARTED.md)
+- [Game author guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/npm/GAME-AUTHOR.md)
+- [API reference](https://github.com/danchar12138/pelican-engine/blob/main/docs/api/REFERENCE.md) and [capabilities](https://github.com/danchar12138/pelican-engine/blob/main/docs/CAPABILITIES.md)
+- [Source repository and contribution guide](https://github.com/danchar12138/pelican-engine)
+
+The installed package also includes `docs/npm/GAME-AUTHOR.md`, `docs/api/REFERENCE.md`, `docs/api/index.json` and `lib/sdk/index.d.ts`. The installed declarations and `pelican api` describe the API of the actual installed version. Repository examples and assets are not shipped in the npm package.
+
+Playwright Chromium is optional for capture and browser automation. If needed, prepare it while online with `npx --no-install pelican setup --install-browser`. With required dependencies and assets already available, everyday operations need no engine account or hosted development service. An offline reinstall additionally requires cached packages.
+
+## License
 
-Build output is regenerated from current sources into ignored
-`.pelican/npm/package/`; tarballs and smoke reports go in `.pelican/npm/artifacts/`.
-Neither staging nor tarballs are inside the deployable game `dist/`.
-Pack that staging directory, not the private repository root. Compiled relative
-imports use `lib/` modules and `.js`, never the TypeScript source layout. The
-tarball allowlist excludes source maps, evidence, examples and game assets;
-SDK declarations, engine runtime code, MIT, copied AI docs, and dependency
-license texts are included. `distribution.json` records version and file hashes.
-Dependencies are normal pinned npm dependencies, not vendored engine sources.
-
-The npm workflow runs only for a published GitHub milestone release. Its gate
-requires tag/version/SDK/manifest identity and the existing milestone acceptance
-and source-fingerprint checks. An ordinary push or CPU-green build cannot publish.
-M3 is deliberately blocked until its release profile and real acceptance exist.
-The default smoke install uses npm cache only; `--online-install` allows network
-for initial dependency installation, then runs every operation offline with a
-disabled registry. CI uses this flag because `npm ci` alone need not populate
-registry metadata for a fresh external install. `--gpu` additionally measures
-the installed WebGPU backend, renders path/hybrid/raster, checks a nonblank canvas,
-captures through both CLI routes, verifies WebGL2 fallback rejection, and loads
-the nested-base static build without a development hook. It is not M3 acceptance.
-
-The single unscoped package is `pelican-engine`, its only public import is
-`pelican-engine`, and its executable is `pelican`. The GitHub target is
-`danchar12138/pelican-engine`; main completed the public repository rename and
-verified the updated origin. No new organization is required. The authorized
-npm Automation Token was authenticated as `danchar12138`, and main confirmed
-the repository Actions secret `NPM_TOKEN` is configured. `npm view pelican-engine`
-returned `E404` before publication. The package remains unpublished pending
-genuine M3 acceptance; this is not an authentication or organization blocker.
-`setup-node` configures the registry;
-only the final publication step receives `NODE_AUTH_TOKEN`. A missing secret
-fails with `TC_NPM_AUTH_MISSING`, without printing the value. The token must have
-permission to publish the fixed unscoped package. No OIDC/trusted-publisher setup
-or provenance flag is required by this workflow. Prereleases use `next`; stable
-versions use `latest`. These credentials do not bypass milestone acceptance.
-No token value is stored in source, documentation, or probe output. No publication
-is performed by this packaging task. See
-`tools/npm/publish-gate.ts` in the source distribution.
+Pelican Engine's own code is MIT licensed. Dependency licenses and third-party notices are included in the package under `licenses/` and in the [repository notices](https://github.com/danchar12138/pelican-engine/blob/main/docs/THIRD-PARTY-NOTICES.md).

package/distribution.json

@@ -1,23 +1,27 @@
 {
   "format": "pelican.npm-distribution",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "files": {
-    "AGENTS.md": "af63b23d2afdef415c865685aea31dacd365edde17505bde823a757bd46caa5a",
+    "AGENTS.md": "80067dae6407a09cf62758fae5502f5d0efa4dac3a85698477bf2b09bdacc78e",
+    "CONTRIBUTING.md": "0ffad5d841d90f319fc50a75b81d3c0ad6dab8d5d9bec2846c65c7f8358d5a50",
     "docs/AI-WORKFLOW.md": "aa992686df93f791795f6f3fce01713d812eea6a1b9556f07411ac5847278efa",
-    "docs/api/index.json": "fdb344c9956edf316548487ee0b183847e23cdecffe95eeda7f1f54c0c26b770",
-    "docs/api/REFERENCE.md": "dff3868360926651e7986a25d2676283c1e1336d585e070e62313bf89fd2e1be",
+    "docs/api/index.json": "1dad6c0a65c59bf72271d14a671c4f1f0f18d8239725fc32d429ed015cbbf229",
+    "docs/api/REFERENCE.md": "4052d6de1fede807746f950c055d136da43069f51c45df47eba88c72941994f6",
     "docs/ARCHITECTURE.md": "3184b73592d466390e7793b1cf39bbb80d6052b523fba7e7cb377b5207074627",
+    "docs/assets/pelican-mark.svg": "407b10cd7e292ea83cf5dba4046fb2f01c7d566a14014c55deda3a2984562b4d",
     "docs/CAPABILITIES.md": "92950817497d8c63db07830db96dc93c877befa8d038320feed1ae1f1a053cb1",
-    "docs/DECISIONS.md": "f7d287654c1ca4014474c54defbd1a9fb2a7e0d00794a3453f7518dae4490311",
-    "docs/M3-USAGE.md": "39b2b4675840f3700da9ccf81c690cff4c69ee1ed5785a0b430c7c055935c31a",
-    "docs/npm/DISTRIBUTION.md": "9312e4e7c4c0ac097793c7d5aeaa9146ec52e64d10caa7b804813ce61ceeaf87",
-    "docs/npm/GAME-AUTHOR.md": "af63b23d2afdef415c865685aea31dacd365edde17505bde823a757bd46caa5a",
-    "docs/PELICAN-MIGRATION.md": "633f4a4fe30bc899ebb01fb63ec9573a931e43f28c199224509db95890806e5f",
-    "docs/RENDER-BACKENDS.md": "de104cca78d734f9a853a2757c6e3d7b832a31224da5df462851ef2cf9768ade",
+    "docs/DECISIONS.md": "47d3a1de8ecc8c5b06ddd867536831b9d3573fb0fefa9de6d4d9e87615daead8",
+    "docs/GETTING-STARTED.md": "5519ebe4e513e8ae4517c04948ee9dc70bcb1e3d04a65d468a6537c838502663",
+    "docs/GRAPHICS-GUIDE.md": "e3d0f7df6189ca3f88d81af5ffaf393f5d6bf39b9e66167bb2f64b39194b514c",
+    "docs/npm/DISTRIBUTION.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
+    "docs/npm/GAME-AUTHOR.md": "80067dae6407a09cf62758fae5502f5d0efa4dac3a85698477bf2b09bdacc78e",
+    "docs/PELICAN-MIGRATION.md": "c5d6ab8e5186f4d36720a0a01d1a7e4157a5d386c5400e2db99571a7d10a1e49",
+    "docs/PHYSICS-LIFECYCLE-ISSUE.md": "cc78917462de4e7e9b68e77c742192ce213b4be5b516d2ba943251fff46977ac",
+    "docs/RENDER-BACKENDS.md": "d981ea94742a835d028db37d536fb7fba05102e37bc6274a37baf74f5034b954",
     "docs/ROADMAP.md": "29ac1c54f36064e23c17cfe7f549d6860889257a57d1227e322958aa9c281568",
-    "docs/STATUS.md": "1e8b85ced94f7b4484773e73363e1cfbd488d8441e6c98e45358486402927c8d",
+    "docs/STATUS.md": "403ca876bb0d1497a09bd394a97f78baffb2cb42313214854483c4a3795aedac",
     "docs/THIRD-PARTY-NOTICES.md": "58f9b72e2b4dfaaaf2a4c08b9bde9ecef3d2b7e7d65fccd782ed54f39fa76fdc",
-    "engine.manifest.json": "155537b36e7bb1f7a1550817571c08404739d4be3c0caa07a75b5089f8db1be1",
+    "engine.manifest.json": "58f2de1e59af10e313c06cdf8d83ca66b903fbce8dc8317777628fcf25241b3c",
     "lib/assets/audio.js": "6facdce4e053afd172af5b9407569b035169844ea17b49f93f8b67f72b78895f",
     "lib/assets/errors.js": "70572678655c6e53179d31920d71f29882d373a0e12d560220bb0fc2cd74f2cc",
     "lib/assets/glb.js": "b808479a36299c154db97f50c16863a3b5a2c61f725e66bf01d01a5f62a288a5",
@@ -119,8 +123,8 @@
     "lib/runtime/world.js": "c43621fbaca8bd2b0d6477a96e60e895312f0f7b1eb97614b6e4f9b716129ea1",
     "lib/schema/index.js": "594429eecb4494c4af2f3d04537be3211f2c9297a1fc555bbba5d028d8627965",
     "lib/sdk/graph-values.js": "a58c00f127cb82aba5fd2824981942844e06d9a59a88a05e35d1d3df2fc7ed2f",
-    "lib/sdk/index.d.ts": "948449f30fe58d60c6dfd1cf8c9155b46df15f2b273ab830d55b751fd0cad041",
-    "lib/sdk/index.js": "113dd48a7f1ebea382dcbe8a7f1e685c71fbfdeb105d00a4b6069ea59485a8f0",
+    "lib/sdk/index.d.ts": "68e44b160c00e56d3478f6ebe45a87b1a997641b138f6623a8b53097bb498298",
+    "lib/sdk/index.js": "396466f9eb0ddf14e6849749e725a214d4fd6003c185329f09decf804025711f",
     "lib/tools/api-index.js": "6aedc153a0ce8eaf18239b0368a76a8ae8e4397bd8e6cdf571889bc39265be5d",
     "lib/tools/browser-session.js": "1fa7f78d4752d8a59a55dc2283b4d42cd1df230f0d5a5dc80c6d78ade45b4cdb",
     "lib/tools/cli.js": "ad5e915f046cc2e6bf612edd1a88cc33758b1d2b0ce2f057be50e0a2c4770062",
@@ -191,8 +195,8 @@
     "licenses/undici-types/LICENSE": "a6db8096b2707bc0102d256917d4d33f298ba36d8c3f25de067a2b5bb379db27",
     "licenses/uniq/LICENSE": "e67aed7df22dc8031e4fcf5338fe91cb33e3817e5c58a99a2a2802eea9069791",
     "licenses/vite/LICENSE.md": "a22152baa1aef74402443008e767e7c689a524c0909d19b0431d97f5ab066a13",
-    "package.json": "68d95a497d2ccb17c1cb47be1414f4a26e093cb2262ae34449d3c411bedd7c77",
-    "README.md": "9312e4e7c4c0ac097793c7d5aeaa9146ec52e64d10caa7b804813ce61ceeaf87",
+    "package.json": "2fc01717d186fde1c36264fe6a4bd2a523b7a8e26a12efc532f8708ea1a63260",
+    "README.md": "ff25e039921a85ba253c27608c77ed614a036117d7a04f908a78d1e3ed3f19ef",
     "web/index.html": "d89d6a5b5be3beae3627a8ed506ac308b165d264fb8696be3afd79fcca2f26ee"
   }
 }

package/docs/DECISIONS.md

@@ -69,6 +69,7 @@
 | D53 | 用户要求每次推送主线自动以无预发布后缀的正式版本发布到 npm `latest`，使用 OIDC，不再人工审批 | 覆盖 D48、D52 的 token/staged/next 方案。GitHub Actions 使用 npm 可信发布，不传长期发布令牌；每次运行生成唯一正式版本，更新 `latest`。发布失败、队列延迟和不可覆盖版本须如实记录。正式版本命名不表示行为、硬件或完整里程碑已验证，D50 仍有效。 |
 | D54 | 用户要求推送主线即尝试发布 npm，GitHub Release 仅标记里程碑；仓库和 npm 使用相同的简洁版本，移除 `next` | 覆盖 D53 的运行 ID 自动版本方案。版本由仓库显式维护，CI 不自动改号；每次推送使用该版本以 OIDC 发布到 `latest`，版本重复则失败并等待后续版本，不覆盖既有包。移除 `next` 别名但保留历史版本；已有长版本不可重用或抹除。D50 仍有效。 |
 | D55 | 用户要求单线开发时不再堆积变更，提交和推送不等待里程碑 | 工作区只保留下一功能或版本的改动；每次提交围绕一个可说明的功能、修复或版本，完成后及时提交推送。推送前按 D54 明确递增版本，npm 发布失败如实记录。保留历史证据和未确认成果，不将无关内容混入提交；D50 和 D51 继续有效。 |
+| D56 | 用户要求仓库首页、npm 与源码使用指南按常见开源引擎结构组织，美观且实用，命令不绑定特定 shell | 提供清晰的功能概览、状态、快速入门、文档导航与源码贡献入口；仓库和 npm 指引保持一致。通用命令写法不改变 D15 的 Windows 开发支持范围，也不暗示其他系统已受支持或验证；D50 的验证禁令继续有效。 |
 
 ## 本次变更实施顺序
 

package/docs/GETTING-STARTED.md

@@ -0,0 +1,80 @@
+# 快速入门
+
+本指南介绍两种使用方式：**用 npm 制作游戏**，或**从源码仓库运行引擎和游戏**。两者使用同一个 `pelican-engine` 公开 SDK；一般游戏项目不需要引擎源码。已有功能及未完成项请先阅读 [当前研发状态](STATUS.md)。
+
+## 环境
+
+- Node.js 24.x 和 npm；仓库及 npm 包当前声明的 Node 版本范围为 `>=24 <25`。
+- 当前支持的引擎与游戏开发环境为 Windows。本指南中的命令使用通用 Node/npm 形式，不要求特定 shell；**不代表 Linux 或 macOS 开发流程已经受支持或完成验证**。
+- 玩家端无操作系统或浏览器品牌白名单，实际可用的 WebGPU、WebGL2 和图形能力取决于设备、浏览器和运行环境。
+- 首次安装依赖需要网络。浏览器截图等自动化功能还需要按需安装 Playwright Chromium；普通启动与构建不要求先安装它。
+
+## 方式一：使用 npm 开始游戏
+
+在空目录中安装引擎并启动开发服务：
+
+```sh
+mkdir my-pelican-game
+cd my-pelican-game
+npm --prefix . install --save-dev --save-exact pelican-engine
+npx pelican dev
+```
+
+`--prefix .` 将安装目标明确指定为当前目录，避免 npm 选中父级项目；`--save-exact` 将安装版本锁定在游戏项目中。首次 `dev` 在允许的空目录里生成：
+
+```text
+my-pelican-game/
+├── game.ts                 # 游戏入口
+├── pelican.project.json    # 入口及引擎版本锁
+├── AGENTS.md               # 外部 AI 的游戏开发入口
+├── package.json
+└── package-lock.json
+```
+
+默认示例创建一个方块、相机、灯光和旋转系统。编辑 `game.ts` 以修改它；游戏侧从 `pelican-engine` 导入公开接口。CLI 不覆盖已有项目：如果目录已有其他文件而无法自动生成，请使用空目录，或显式创建项目。
+
+停止开发服务后构建：
+
+```sh
+npx --no-install pelican build
+```
+
+产物位于游戏目录的 `dist/`。将整个目录部署到支持静态文件的 HTTP(S) 服务器，并保留其中的资源和许可文件。部署到子路径时，可使用 `npx --no-install pelican build --base /game/`。
+
+查看命令与 API：
+
+```sh
+npx --no-install pelican help
+npx --no-install pelican api
+npx --no-install pelican api --symbol defineGame
+```
+
+项目锁与安装版本不一致时，应先迁移项目，再明确更新 `pelican.project.json` 中的版本；不要通过修改 `node_modules` 绕过诊断。更多使用细节见 [npm 分发指南](npm/DISTRIBUTION.md) 和 [Game Author 指南](npm/GAME-AUTHOR.md)。
+
+## 方式二：从仓库使用引擎
+
+需要研究引擎源码、尝试仓库示例或参与维护时，可以检出仓库：
+
+```sh
+git clone https://github.com/danchar12138/pelican-engine.git
+cd pelican-engine
+npm ci
+npm run dev
+```
+
+这会启动当前仓库配置的示例。源码 ZIP 或已有目录也可以使用，不要求 `.git` 存在。使用源码为另一个目录创建最小游戏：
+
+```sh
+node --import tsx tools/cli.ts create --project ../my-source-game --template minimal
+node --import tsx tools/cli.ts dev --project ../my-source-game
+```
+
+这些命令从**引擎目录**执行；新游戏在相邻的 `my-source-game` 目录中。CLI 会写入相对引擎路径和版本锁，游戏仍使用公开的 `pelican-engine` API。已有目标文件不会被覆盖。更多引擎开发说明见 [参与开发](../CONTRIBUTING.md)。
+
+## 选择渲染模式
+
+引擎优先尝试 WebGPU，必要时通过 Three.js 内置回退尝试 WebGL2 光栅。WebGL2 不提供依赖 compute 的混合光追、路径追踪或受控计算；能力不足时应读取诊断，不应把光栅结果当成光追。能力查询和错误码见 [渲染后端](RENDER-BACKENDS.md)。
+
+## 已知边界
+
+当前版本仍在研发；构建成功不证明画质、性能、硬件兼容或所有功能已经验收。当前用户约束禁止项目验证活动，因此仓库中的历史测试命令不是本次执行或通过的声明。实际局限、已知物理缺陷和历史证据入口见 [当前研发状态](STATUS.md)。

package/docs/{M3-USAGE.md → GRAPHICS-GUIDE.md}

@@ -1,6 +1,6 @@
-# M3 开发候选使用指引
+# 图形与运行时使用指引
 
-当前 `0.3.0-m3.0` **尚未正式验收或发布**。稳定 M2 为 `v0.2.0-m2.0`，不能用当前源码更新历史 M2 验收指纹。本文说明已有开发候选的实际操作，不宣称完整高级渲染完成。
+本文说明当前源码中的图形与运行时接口，不宣称完整高级渲染已完成或验收。实际版本见项目清单，当前状态见 [研发状态](STATUS.md)。历史阶段名称、实验结果和旧标签仅适用于各自记录的源码，不代表当前版本通过。按当前 D50，仅允许编译/构建；下文历史探针、浏览器或测试命令在恢复授权之前不得运行。
 
 ## 模型材质槽
 
@@ -12,11 +12,11 @@
 
 `defineMaterial({ id, ior, transmission: 0, ... })` 可为不透射的物理材质指定有限正数折射率，默认值为 1.5。介质法线入射反射率由 `((ior - 1) / (ior + 1))²` 决定；光栅、hybrid 和 path 共享该输入，路径采样与 PDF 也使用对应反射率。金属部分仍使用 baseColor 的 F0。`attenuationColor` 和 `attenuationDistance` 仍要求正的 transmission，不能用不透射 IOR 伪装体积吸收。
 
-仓库中的 `examples/opaque-ior` 以三个黑色平面展示差异；`npm run probe:opaque-ior` 是需要独占 GPU 的小型三模式开发验证。该例不代表完整物理材质扩展或正式 M3 验收；npm 渠道使用同一公开接口，当前源码增量的新包安装验收仍待稳定候选。
+仓库中的 `examples/opaque-ior` 以三个黑色平面展示差异；相关 probe 是历史开发验证入口。该例不代表完整物理材质扩展或当前版本验收；npm 渠道使用同一公开接口。
 
 不透射物理材质还可设置 `specularIntensity`（0 到 1，默认 1）和 `specularColor`（sRGB `#rgb`、`#rrggbb` 或颜色名称，默认白色）。这两个因子参与介质高光、掠射和 path/hybrid 采样；金属部分仍由 baseColor 决定。非默认高光与正 `transmission` 的组合目前返回 `TC_MATERIAL_SPECULAR_TRANSMISSION`，不会悄悄使用默认值。
 
-自包含 GLB 可使用 `KHR_materials_specular`／`KHR_materials_ior` 的常数材质因子；不透射材质还支持 specular 强度纹理 alpha 与 sRGB 颜色纹理 RGB，资产仅接受 TEXCOORD_0，`optimize` 保留并复核因子、图像和采样配置。高光颜色 PNG 支持 1/2/4-bit 灰度和调色板 Adam7、无色彩元数据的 16-bit，以及 gAMA 45455/100000、标准 sRGB cHRM、sRGB intent 0、cICP [1,13,0,1]；其他 16-bit 色彩块值和 ICC 仍明确拒绝。正透射结合高光纹理及其他未实现扩展仍不支持。示例 `examples/specular-material`、`examples/specular-textures` 和 `examples/specular-textures-16` 对照导入材质；探针需串行独占 GPU。完整 M3 和全新系统或公开注册表验收尚未完成。
+自包含 GLB 可使用 `KHR_materials_specular`／`KHR_materials_ior` 的常数材质因子；不透射材质还支持 specular 强度纹理 alpha 与 sRGB 颜色纹理 RGB，资产仅接受 TEXCOORD_0，`optimize` 保留并复核因子、图像和采样配置。高光颜色 PNG 支持 1/2/4-bit 灰度和调色板 Adam7、无色彩元数据的 16-bit，以及 gAMA 45455/100000、标准 sRGB cHRM、sRGB intent 0、cICP [1,13,0,1]；其他 16-bit 色彩块值和 ICC 仍明确拒绝。正透射结合高光纹理及其他未实现扩展仍不支持。示例 `examples/specular-material`、`examples/specular-textures` 和 `examples/specular-textures-16` 对照导入材质；探针属于历史开发记录。完整材质矩阵和公开注册表安装验收尚未完成。
 
 ## 计算到渲染的缓冲绑定
 
@@ -42,9 +42,9 @@ path/hybrid 将常驻 GPU 数据复制进原生材料表的附加 vec4 区域；
 
 使用 `model: { asset, material }` 可显式整模替换导入材质，把顶点图用于带骨骼/morph 的模型；不传 material 保留原资产材质。覆盖材质由游戏内容所有者持有，模型实例与模板不会销毁借用材质。当前是整模替换，不是按源材质槽合并。
 
-引擎从同一变形几何维护对象包围体和渲染射线查询，剔除保持开启，路径/混合 BVH 会更新或 refit。Transform 和显式物理 collider 不被 shader 改写；本功能不等于自动 Rapier 形变或 M4 耦合。
+引擎从同一变形几何维护对象包围体和渲染射线查询，剔除保持开启，路径/混合 BVH 会更新或 refit。Transform 和显式物理 collider 不被 shader 改写；本功能不等于自动 Rapier 形变或物理系统耦合。
 
-最小例子：`npm run dev -- --project examples/vertex`。数据纹理和小型带骨骼/morph GLB 是可离线重建的 MIT 夹具；`node --import tsx tools/prepare-vertex-assets.ts` 可重新生成。高收益实测入口为 `npm run probe:vertex`，内部 MRT 遮挡回归为 `npm run probe:postprocess:occlusion`；两者都应独占 GPU，不是完整 M3 验收。
+最小例子：`npm run dev -- --project examples/vertex`。数据纹理和小型带骨骼/morph GLB 是可离线重建的 MIT 夹具；`node --import tsx tools/prepare-vertex-assets.ts` 可重新生成。历史开发入口为 `npm run probe:vertex` 和 `npm run probe:postprocess:occlusion`；它们不构成当前版本完整验收。
 
 ## 受控 HDR 后处理
 
@@ -56,7 +56,7 @@ pass 输出为全尺寸 rgba16float，捕获保持场景原 MSAA，最终曝光/
 
 效果开关及参数参与 CPU 检查点；反馈纹理不序列化，恢复/内容/模式/设备变化明确重置历史。开关变化会防御性重置所有历史；关闭的 pass 不再推进历史，当前帧输出为上游直通。参数改变默认保留历史，需要时显式 `resetHistory(id?)`。反馈按呈现帧推进，不是游戏物理时间或存档状态。
 
-最小三段例子在 `examples/postprocess`：`npm run dev -- --project examples/postprocess`。小规模独占 GPU 验证为 `npm run probe:postprocess`，覆盖三模式像素、通道、反馈/恢复、4× MSAA、方向标记及一条 WebGL2 路径；它不是完整 M3、画质或性能验收。
+最小三段例子在 `examples/postprocess`：`npm run dev -- --project examples/postprocess`。`npm run probe:postprocess` 是历史开发验证入口；它不构成当前版本完整画质或性能验收。
 
 ## 受管理计算
 
@@ -64,7 +64,7 @@ pass 输出为全尺寸 rgba16float，捕获保持场景原 MSAA，最终曝光/
 
 引擎在每个固定 tick 后等待 GPU 任务结算；`readBuffer` 返回上次完整成功结果的 CPU 镜像，失败或取消不覆盖输出。输出可同时作为输入，读取的是派发前快照。枚举 `tasks()` 并释放终态任务，避免无限保留历史；恢复后按缓冲名称 `resolve()`，不复用旧句柄。快照/回放/设备重建已接入，WebGL2 不执行计算。
 
-仓库最小反馈游戏：`npm run dev -- --project examples/compute`。受影响功能复测使用 `npm run probe:compute:numeric`，完成后再串行执行 `npm run probe:compute`；前者为小规模真实 GPU 数值与释放检查，后者为游戏反馈、输入、快照/回放、恢复和一条 WebGL2 能力分支。不要并行争用同一 GPU，也不需要为每次局部修改运行整个 M3 矩阵。
+仓库最小反馈游戏：`npm run dev -- --project examples/compute`。`npm run probe:compute:numeric` 和 `npm run probe:compute` 是历史 GPU 开发验证入口，不构成当前源码的完整能力验收。
 
 显式依赖使用 `bindings: { name: { task: predecessor } }`：读取该任务的确切成功输出，即使同一源缓冲已经被后续任务覆盖。`after: [predecessor]` 只约束执行顺序，普通缓冲句柄绑定仍读取派发时快照；参数与 time 也在派发时固定。只能引用同一运行时已有的未释放任务，不支持前向/跨 owner 引用。
 
@@ -72,7 +72,7 @@ pass 输出为全尺寸 rgba16float，捕获保持场景原 MSAA，最终曝光/
 
 任务不序列化进快照。游戏不要把临时任务句柄作为持久状态：恢复或设备重建后重新派发链路；源缓冲按名称 resolve。公开示例 `examples/compute-dependencies` 演示分支、覆盖、纯顺序依赖及失败隔离；小型串行硬件验证为 `npm run probe:compute-dependencies`。
 
-当前任务仍顺序执行且每节点读回 CPU 镜像，不是一次批量 GPU-only DAG。GPU 常驻顶点/片元/后处理的缓冲和纹理绑定、顶点图、HDR 后处理及计算纹理核心已接入；完整高级矩阵仍待完成。现有链路不等于 CAP-17 或完整 M3 已验收。
+当前任务仍顺序执行且每节点读回 CPU 镜像，不是一次批量 GPU-only DAG。GPU 常驻顶点/片元/后处理的缓冲和纹理绑定、顶点图、HDR 后处理及计算纹理核心已接入；完整高级图形矩阵仍待完成。现有链路不等于完整能力已验收。
 
 ## 计算纹理
 
@@ -100,7 +100,7 @@ Three 路径将常驻纹理以 GPU→GPU 复制到自身资源；path/hybrid 将
 
 ## 场景与公开设置
 
-```powershell
+```sh
 npm run dev
 ```
 
@@ -149,11 +149,11 @@ const glass = defineMaterial({
 
 path/hybrid 将正透射对象的闭合几何边界编入介质目录，支持平滑/粗糙折射、反射、嵌套介质和相机内部初始状态。每个对象或实例必须是单个闭合、连续、非自交壳体；相交/接触体积、开口和部分不透明边界有明确诊断。目录不是通用自交证明；复杂重叠介质、空腔、多壳体、光谱色散尚未实现。完整规则见 `packages/renderer/MEDIUM.md`。
 
-```powershell
+```sh
 npm run dev -- --project examples/refraction
 ```
 
-该项目仅使用公开 SDK，包含吸收平板、内外相机、嵌套边界、折射/粗糙度、尺度/平移和介质内点光源对照。线性图像、边界错误计数与解析 Beer 断言由独立开发探针检查；不能把可见玻璃球当成完整 M3 画质验收。光栅使用物理材质实现，但其屏幕空间透射/厚度与路径体积的一致性仍需补验。
+该项目仅使用公开 SDK，包含吸收平板、内外相机、嵌套边界、折射/粗糙度、尺度/平移和介质内点光源对照。线性图像、边界错误计数与解析 Beer 断言由历史开发探针检查；不能把可见玻璃球当成完整画质验收。光栅使用物理材质实现，但其屏幕空间透射/厚度与路径体积的一致性仍需补验。
 
 ## 已有链路
 
@@ -173,20 +173,20 @@ npm run dev -- --project examples/refraction
 
 ## 开发复验
 
-### 刚体角运动（M4 并行增量）
+### 刚体角运动
 
 `ctx.physics.angularVelocity(entity)` 查询世界坐标弧度／秒；`setAngularVelocity(entity, vec3)` 设置动态刚体角速度，`torqueImpulse(entity, vec3)` 施加世界空间力矩冲量，`impulseAtPoint(entity, impulse, worldPoint)` 在指定世界坐标施加冲量，同时影响平动和转动。后三者只支持动态刚体；固定、运动学或角色体返回 `TC_PHYSICS_BODY_TYPE`。写操作参与物理历史、快照和回放，旧快照仍兼容。
 
-示例 `examples/angular-physics` 只使用公开 SDK；源码渠道运行 `npm run dev -- --project examples/angular-physics`，独占 GPU 的小型验证为 `npm run probe:angular-physics`。当前 M4 非正式完成，首次正常物理步前移除刚体存在已复现的底层生命周期缺陷，见 `docs/tasks/M4-ANGULAR-PHYSICS.md`；完整模拟交互仍需后续验收。npm 渠道使用相同 SDK，更新包安装验收留待稳定节点。
+示例 `examples/angular-physics` 只使用公开 SDK；源码渠道运行 `npm run dev -- --project examples/angular-physics`。首次正常物理步前移除刚体存在已知生命周期缺陷，详见[物理生命周期缺陷记录](PHYSICS-LIFECYCLE-ISSUE.md)；完整模拟交互仍需后续实现和验证。npm 渠道使用相同 SDK。
 
-```powershell
+```sh
 npm run typecheck
 npm run probe:m3
 npm run build
 ```
 
-`probe:m3` 必须在真实硬件 WebGPU 环境运行，生成带源码指纹的开发记录和图像。失败不覆盖成成功；`formalMilestoneAccepted` 明确为 false。全量测试的硬件 opt-in 见 `docs/tasks/M3.md`；未启用时的跳过不算通过 GPU 验证。
+历史开发 probe 会生成带源码指纹的记录和图像；失败不覆盖成成功。当前 D50 禁止运行这些 probe，也不能把旧记录当作当前源码验证。
 
 构建仍为 `dist/`，可在普通静态服务器子路径部署；默认生产不暴露开发控制 hook。`tools/m3-static-probe.ts` 使用真实按键测试模式切换和冷启动。直接浏览器自动化是外部测试职责，游戏源码不得调用内部开发 hook。
 
-当前公开图语言仍是有限子集。后处理、多通道、变形和计算接口的完整表达矩阵、完整物理材质图像矩阵、时域重建、原生性能及独立 AI 使用门禁未完成前，不发布 M3。已确认的 M1–M8 总范围保持不变。
+当前公开图语言仍是有限子集。后处理、多通道、变形和计算接口的完整表达矩阵、完整物理材质图像矩阵、时域重建、性能及独立使用验收仍有缺口。普通版本发布不代表这些能力已验证或完整首发已完成。

package/docs/PELICAN-MIGRATION.md

@@ -1,6 +1,6 @@
 # Pelican Engine 命名与迁移
 
-本次名称由用户确定：**Pelican Engine（鹈鹕游戏引擎）**。引擎仍处于 M3 开发，不因更名重启里程碑，也不把已有开发探针提升为正式验收。
+产品名称为 **Pelican Engine（鹈鹕游戏引擎）**。本文件保留更名与迁移背景；当前版本、能力缺口及发布状态见 [研发状态](STATUS.md)，历史开发探针不是当前源码的正式验收。
 
 | 对象 | 唯一正式名称 |
 | --- | --- |
@@ -9,7 +9,7 @@
 | npm 单包 | `pelican-engine` |
 | 命令 / bin | `pelican` |
 | 游戏侧公开导入 | `pelican-engine` |
-| 源码目录启动脚本 | `pelican.ps1` |
+| 源码命令入口 | `npm run dev` 或 `node --import tsx tools/cli.ts` |
 | 项目清单 | `pelican.project.json` |
 | 本地缓存 / 开发控制路由 | `.pelican/` / `/__pelican/` |
 | 部署版本清单 | `pelican-build.json` |
@@ -18,8 +18,8 @@ SDK、runtime、renderer、编译器和 CLI 位于同一个 npm 包中。内部
 
 目标最短使用流程为：
 
-```powershell
-npm i -D pelican-engine
+```sh
+npm --prefix . install --save-dev --save-exact pelican-engine
 npx pelican dev
 ```
 
@@ -35,4 +35,4 @@ M0–M2 的原名称、标签、提交、Release 附件与 `evidence/` 是历史
 
 ## 远端实际状态
 
-用户后续明确 GitHub 只改仓库名，不改组织。远端现已改名为 `danchar12138/pelican-engine`，本地 origin 同步更新，公开仓库、历史标签与 Release 保留。npm 身份已通过授权 Automation Token 验证，令牌仅配置为该仓库 Actions 的 `NPM_TOKEN` secret，未写源码或证据。npm `pelican-engine` 查询仍返回 404；本轮只完成更名和开发分发验证，不在里程碑验收前提前推送、创建标签或发布包。
+GitHub 仓库为 `danchar12138/pelican-engine`，所有者保持不变。npm 使用 Trusted Publisher OIDC；当前稳定版本见 `package.json` 与 [npm package](https://www.npmjs.com/package/pelican-engine)。历史标签和历史发布记录保留原样，不更名、不重写。

package/docs/PHYSICS-LIFECYCLE-ISSUE.md

@@ -0,0 +1,19 @@
+# Physics Lifecycle Issue
+
+**Status: open; not fixed or validated in the current package.**
+
+Removing certain rigid bodies before the physics world has completed its first normal time step can make the locked Rapier runtime trap during the first later step. The exact reproduction depends on body types and initial island/contact topology. Existing reports include process termination, not only a catchable application error.
+
+## Required behavior
+
+- Body removal remains immediate for public queries and raycasts.
+- A later simulation step does not trap or silently skip collision, impulse, sleep, or event processing.
+- Snapshot/history recovery preserves existing version-3 snapshot semantics; existing fixtures must not be rewritten to make a candidate pass.
+- Untrusted history must not be replayed optimistically in the active WASM instance.
+- Creation, removal, same-ID respawn, characters, joints, contacts, rollback, and disposal must preserve their established contracts.
+
+## Investigation boundary
+
+Historical reproductions and candidate experiments are retained in the original issue records and local archived work. Some candidates alter native world reconstruction or snapshot bytes and have known compatibility gaps. They are not fixes and must not be merged wholesale. The production Rapier dependency has not been replaced.
+
+Project policy currently permits compilation/build only and prohibits runtime, browser, GPU, test, performance, and other verification. Therefore this issue remains open until implementation and the required verification are authorized and completed.

package/docs/RENDER-BACKENDS.md

@@ -1,6 +1,6 @@
 # 渲染后端与能力诊断
 
-适用：M3 开发工作树及由同一版本生成的 npm 包。历史 M0–M2 标签保留当时 WebGPU-only 行为；本文件不改写旧验收。
+适用：当前源码及由相同版本生成的 npm 包。历史标签保留当时的行为与证据；本文件不改写旧验收。当前源码的后端兼容性尚未完成完整验收。
 
 ## 同一公开接口
 
@@ -35,11 +35,13 @@ const capabilities = ctx.render.capabilities();
 
 配置和检查点恢复先校验能力再提交；被拒绝的配置不改变当前模式或设置。运行态开发控制命令返回结构化 `failed` 与稳定错误码，不因正常的不支持请求把游戏置为崩溃状态。
 
-## 实测入口
+## 历史实测入口
+
+以下是历史开发命令；当前 D50 禁止测试、浏览器、GPU 和其他验证，恢复授权前不要运行。
 
 在 Windows、已安装依赖与 Playwright Chromium、真实硬件加速环境中：
 
-```powershell
+```sh
 npm run probe:backends
 # 仅运行独立 WebGL2 回退矩阵：
 npm run probe:backends -- --webgl-only
@@ -47,4 +49,4 @@ npm run probe:backends -- --webgl-only
 
 输出 `.pelican/backend-probes/<run>/report.json` 与截图，包括源码指纹、实际 ANGLE/GPU 身份、画面像素检查、三类初始化失败、不可用模式/降噪/计算错误码、两次上下文恢复、重复内容重载，以及两后端都不可用的诊断。默认还复测真实 WebGPU 三模式设备重建。
 
-这是开发专项，不是完整 M3 acceptance。主里程碑只接受真实 WebGPU 硬件证据；WebGL2 单列记录，不用它或软件渲染器代替主门禁。性能保留诚实观测，不以固定帧率阈值阻断 1.0，也不放松功能正确性和资源生命周期验证。
+这些是历史开发专项记录，不构成当前版本的完整图形或硬件验收。WebGPU 与 WebGL2 应分别记录，不用一种后端或软件渲染器代替另一种后端的证据。当前授权只允许编译和构建，历史测量不自动适用于当前源码。

package/docs/STATUS.md

@@ -2,7 +2,7 @@
 
 ## 版本与发布
 
-- 当前版本以 `package.json`、`engine.manifest.json` 和 SDK 中的相同标准版本号为准。每次需要发布时，在主线显式更新版本；相同版本不能重复发布。
+- 当前版本为 `0.3.6`，包、锁文件、引擎、SDK、编译器和示例中的版本保持一致。下一项功能完成后统一递增并推送；相同版本不能重复发布。
 - 推送主线会通过 GitHub Actions 和 npm 可信发布更新 `latest`；GitHub Release 用于记录里程碑。历史版本和旧标签保持原样，不代表当前源码通过。
 - 当前按用户要求仅允许编译和构建，不运行测试、浏览器、GPU、性能或其他验证。普通版本号不意味着运行行为、硬件或完整引擎已验收。
 

package/docs/api/REFERENCE.md

@@ -1,4 +1,4 @@
-# pelican 0.3.3 API 索引
+# pelican 0.3.6 API 索引
 
 Installed declarations: `lib/sdk/index.d.ts` (relative to the package root).
 The signatures below come from the same public SDK source as repository games.
@@ -11,7 +11,7 @@ Source-file paths and line numbers are build-time provenance only; TypeScript so
 来源：`packages/sdk/src/index.ts:2`
 
 ```ts
-SDK_VERSION = "0.3.3"
+SDK_VERSION = "0.3.6"
 ```
 
 ## Vec2

package/docs/api/index.json

@@ -1,14 +1,14 @@
 {
   "format": "pelican.api-index",
   "version": 1,
-  "engineVersion": "0.3.3",
+  "engineVersion": "0.3.6",
   "entry": "pelican-engine",
   "source": "packages/sdk/src/index.ts",
   "symbols": [
     {
       "name": "SDK_VERSION",
       "kind": "constant",
-      "signature": "SDK_VERSION = \"0.3.3\"",
+      "signature": "SDK_VERSION = \"0.3.6\"",
       "line": 2
     },
     {

package/docs/assets/pelican-mark.svg

@@ -0,0 +1,29 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024" fill="none" role="img" aria-labelledby="pe-Dr-title pe-Dr-desc">
+  <title id="pe-Dr-title">Pelican Engine</title>
+  <desc id="pe-Dr-desc">A refinement of the original D bold sculpture emblem. The original fierce eye, long bill, crest and gold accents are retained. A closed black eye mask frames the eye, while the continuous white neck broadens into a fuller upper chest. Transparent background.</desc>
+  <defs>
+    <path id="pe-Dr-contour" d="M428 270C432 183 478 118 545 84C600 56 660 53 710 66C750 52 796 54 833 64C799 72 773 89 752 106C805 82 864 78 912 94C875 101 839 120 811 143C861 123 912 124 954 143C918 151 882 169 852 193C897 182 941 188 974 211C934 211 900 222 874 245C916 246 952 267 974 298C937 288 908 287 889 293C929 313 955 349 965 389C935 366 913 353 893 349C923 397 933 451 921 500C914 536 896 562 879 583C885 626 912 661 951 693C916 684 890 670 866 650C912 699 939 753 949 809C922 787 893 770 867 761C912 803 940 853 954 907C915 881 877 869 842 868C863 888 884 916 899 947C857 922 813 911 774 912C799 928 821 946 839 970C789 958 745 938 708 912C719 932 728 953 732 976C684 949 648 918 620 883C621 908 622 929 618 951C579 913 549 865 532 815C521 837 512 857 497 875C475 811 467 749 479 687C490 628 517 581 542 539C563 505 575 469 568 434C561 396 533 365 493 331C464 307 443 289 428 270Z"/>
+    <clipPath id="pe-Dr-clip"><use href="#pe-Dr-contour"/></clipPath>
+    <clipPath id="pe-Dr-eye-clip"><path d="M509 248C532 225 561 220 587 248C569 270 536 275 514 263C507 259 505 253 509 248Z"/></clipPath>
+  </defs>
+  <use href="#pe-Dr-contour" fill="#171B20" stroke="#171B20" stroke-width="10" stroke-linejoin="round"/>
+  <g clip-path="url(#pe-Dr-clip)">
+    <path fill="#F6F7F6" stroke="#171B20" stroke-width="5" stroke-linejoin="round" d="M441 254C449 175 497 116 567 91C620 71 674 75 727 89C696 94 674 108 654 125C708 104 758 105 800 117C773 121 750 135 727 151C775 137 823 142 854 159C827 160 805 168 784 181C831 176 872 195 897 221C868 211 840 209 815 216C858 227 894 254 915 286C884 270 859 263 837 263C872 286 895 321 906 356C881 333 858 319 835 313C858 344 873 383 876 422C861 398 845 382 827 371C854 441 835 497 807 540C786 571 775 596 778 624C781 661 801 693 826 721C805 712 787 699 772 682C792 731 819 768 844 805C816 794 789 776 763 754C789 801 815 835 834 852C801 841 773 826 746 800C769 843 785 874 790 906C748 889 710 859 682 827C692 855 699 879 698 893C642 866 594 825 568 778C551 733 575 681 617 636C663 590 706 555 724 512C742 466 711 422 681 389C650 353 630 334 622 312C612 288 617 275 631 261C611 272 600 268 591 260C592 252 588 245 583 239C573 225 566 216 552 214C540 209 529 210 520 215C495 224 482 247 465 258C454 265 446 263 441 254Z"/>
+  </g>
+  <g id="pe-Dr-eye">
+    <path fill="#171B20" d="M493 238C517 199 559 186 603 198C614 195 624 188 634 181C624 196 619 205 615 212C574 198 541 204 514 231C507 233 500 235 493 238Z"/>
+    <path fill="#F6F7F6" d="M509 248C532 225 561 220 587 248C569 270 536 275 514 263C507 259 505 253 509 248Z"/>
+    <g clip-path="url(#pe-Dr-eye-clip)">
+      <circle cx="552" cy="250" r="15" fill="#B89E67"/>
+      <ellipse cx="552" cy="250" rx="6.5" ry="10" fill="#171B20"/>
+      <circle cx="549" cy="245" r="2.5" fill="#F6F7F6"/>
+    </g>
+  </g>
+  <g id="pe-Dr-bill">
+    <path fill="#171B20" stroke="#171B20" stroke-width="8" stroke-linejoin="round" d="M487 316C528 285 579 270 617 281C661 292 682 328 671 373C655 439 607 504 544 567C422 689 264 794 103 839C91 843 80 839 83 828C218 661 350 485 487 316Z"/>
+    <path fill="#F6F7F6" d="M499 332C532 309 571 293 596 300C614 306 607 325 593 342C477 474 296 659 112 816C269 655 421 459 499 332Z"/>
+    <path fill="#B89E67" d="M617 281C661 292 682 328 671 373C655 439 607 504 544 567C608 496 649 432 659 373C670 334 653 303 617 281Z"/>
+    <path fill="#F6F7F6" stroke="#171B20" stroke-width="10" stroke-linejoin="round" d="M464 269C474 258 488 266 493 283C499 298 493 316 484 328C359 490 234 653 111 816C101 828 94 833 87 830C72 826 76 816 81 808C202 634 324 461 445 289C451 278 457 270 464 269Z"/>
+    <path fill="#171B20" d="M78 801C57 811 46 834 50 855C53 872 64 886 81 891C89 893 92 888 87 882C76 870 72 859 77 847C82 837 90 824 90 812C90 801 85 797 78 801Z"/>
+  </g>
+</svg>

package/docs/npm/DISTRIBUTION.md

@@ -1,130 +1,85 @@
-# Pelican Engine npm development distribution
+<div align="center">
+  <img src="https://raw.githubusercontent.com/danchar12138/pelican-engine/main/docs/assets/pelican-mark.svg" alt="Pelican Engine" width="110" height="110">
+  <h1>Pelican Engine</h1>
+  <p><strong>Build games for the web with TypeScript.</strong></p>
+  <p>Code-first · WebGPU-first · Designed for human and external AI workflows</p>
+  <p>
+    <a href="https://www.npmjs.com/package/pelican-engine"><img src="https://img.shields.io/npm/v/pelican-engine?label=npm&amp;color=168b80" alt="npm version"></a>
+    <img src="https://img.shields.io/badge/license-MIT-24536b" alt="MIT license">
+    <img src="https://img.shields.io/badge/TypeScript-SDK-3178c6" alt="TypeScript SDK">
+  </p>
+</div>
+
+Pelican Engine provides a TypeScript SDK, compiler, runtime, renderer and CLI in one package. Define game content and behavior in code, run a local development server and build a static web distribution. AI tools may assist development, but the game runtime does not include an LLM or AI agent.
+
+> **Development status:** this is an evolving engine, not a complete first release. Current source behavior, hardware compatibility, performance and the full feature set have not been fully validated. A normal version number is not an acceptance claim. See the [development status](https://github.com/danchar12138/pelican-engine/blob/main/docs/STATUS.md) for known gaps.
+
+## Quick start
+
+Install Node.js **24.x** and npm, then create a new empty game directory:
+
+```sh
+mkdir my-pelican-game
+cd my-pelican-game
+npm --prefix . install --save-dev --save-exact pelican-engine
+npx pelican dev
+```
+
+The first `dev` creates `game.ts`, `pelican.project.json` and `AGENTS.md` in an eligible empty project. Existing game files and author instructions are not overwritten. The explicit `--prefix .` prevents npm from choosing a parent project; `--save-exact` pins the installed version. Stop the development server before building:
+
+```sh
+npx --no-install pelican build
+```
 
-The installed package is `pelican-engine`. Its root export is the same compiled
-public SDK used by repository games, not a wrapper or a separate SDK. The package
-also provides the `pelican` executable. This is an M3 development distribution,
-not accepted M3 hardware evidence or a complete engine release.
+Deploy the resulting `dist/` directory, including its generated assets and notices, to an HTTP(S) static host. For a nested deployment, use `npx --no-install pelican build --base /game/`.
 
-## Windows project workflow
+Commands use common Node/npm syntax rather than a particular shell. **Engine and game development currently support Windows only**; Linux and macOS development workflows have not been promised or validated. Player platforms are not restricted by brand or OS: actual rendering availability depends on browser and graphics capabilities.
 
-Use Node 24 and npm in an empty project directory. The explicit prefix keeps npm
-in this directory even when a parent directory is also an npm project:
+## Your game
 
-```powershell
-npm --prefix . i -D pelican-engine
-npx pelican dev
+The generated starter defines a scene and a rotating box. Game code imports only the public package, for example:
+
+```ts
+import { defineGame, defineMaterial, defineScene } from "pelican-engine";
+
+const material = defineMaterial({ id: "paint", color: "#38b8a4", roughness: 0.45 });
+const scene = defineScene({
+  id: "main",
+  camera: { position: [4, 3, 6], target: [0, 0, 0], fov: 50 },
+  entities: [
+    { id: "box", mesh: { geometry: { kind: "box" }, material } },
+    { id: "light", light: { kind: "directional", intensity: 4 },
+      transform: { position: [3, 6, 4] } },
+  ],
+});
+export default defineGame({ id: "my-game", scene });
 ```
 
-The first installed `dev` creates the minimal `game.ts`, `pelican.project.json`
-version lock, and game-author `AGENTS.md` when the directory contains only npm
-installation metadata. An existing game or manifest is used as supplied; other
-project files or author instructions prevent automatic scaffolding. Files are
-never overwritten. Stop dev with Ctrl+C, then use the same local CLI:
+Save it as `game.ts` in a project created by the CLI. The exact engine version is recorded in `pelican.project.json`: migrate the game and update its lock explicitly when changing engine versions. Do not edit `node_modules` or import engine internals.
+
+Useful commands:
 
-```powershell
+```sh
+npx --no-install pelican help
 npx --no-install pelican api
-npx --no-install pelican setup --install-browser
-npx --no-install pelican check
+npx --no-install pelican api --symbol defineGame
 npx --no-install pelican dev --port 4173
-npx --no-install pelican capture --port 4174 --output capture.png
 npx --no-install pelican build
 ```
 
-For an exact-version install use `npm --prefix . i -D --save-exact pelican-engine@0.3.3`,
-or substitute the local `pelican-engine-0.3.3.tgz` tarball before registry
-publication. `pelican create --template minimal` remains available explicitly.
-
-Without `--prefix .`, npm may select an ancestor `package.json` or `node_modules`
-as the install root and modify that parent. The shorter `npm i -D pelican-engine`
-works when npm selects the intended directory; verify `npm prefix` before using
-it. The smoke harness uses an explicit prefix and does not require `npm init`.
-
-`create --template minimal` uses the same primitive starter in npm and repository
-workflows. npm defaults to `minimal` and reports the selected template; repository
-default `m2` is preserved with its historical sample assets. Samples are not engine
-capabilities. Identical authored game/asset inputs use the same API/compiler/runtime
-in either channel. npm does not bundle the `m2` sample or any sample/game assets.
-
-`create` writes `game.ts`, `AGENTS.md` and an exact `pelican.project.json` lock in the current
-directory. Existing project files are never overwritten. Author TypeScript with
-named imports from `pelican-engine` and project-local imports only. The compiler
-reports `TC_PUBLIC_API` for renderer, Three.js, TSL, physics, Node and internal
-package imports, including type-only and unused imports. Package subpaths are not
-public exports. Project lock mismatches report `TC_ENGINE_VERSION_MISMATCH`;
-mixed package/API versions report `TC_ENGINE_SDK_VERSION`. Reinstall a matching
-exact version, or migrate through the public API before explicitly changing a lock.
-
-After npm dependencies and Playwright Chromium have been installed, authoring,
-API inspection, checks, builds, dev/control commands and capture need no network
-service. `setup --offline` never installs dependencies or downloads a browser in
-an installed package. Keep the game package-lock for repeatable future installs;
-an offline _reinstall_ additionally requires the npm cache or a dependency mirror.
-`TC_DISTRIBUTION_DEPENDENCY_MISSING` and
-`TC_DISTRIBUTION_DEPENDENCY_VERSION` identify broken tool dependencies.
-
-Serve the generated `dist/` directory over HTTP(S), including its `generated/`
-files, license files, notices and compression manifests. No Node process, engine
-repository, SDK installation, external AI service or development control server
-is needed by players. Use `build --base /game/` for a nested deployment URL.
-Capture requires installed Chromium and actual supported graphics capability.
-No software renderer result establishes hardware acceptance.
-
-## AI entry points
-
-Read the game-author `AGENTS.md`, `docs/npm/GAME-AUTHOR.md`, `docs/CAPABILITIES.md` and
-`docs/api/REFERENCE.md` inside `node_modules/pelican-engine`. The machine-readable
-API is `docs/api/index.json`, also discoverable through `pelican api`.
-`lib/sdk/index.d.ts` is the authoritative installed declaration surface.
-`docs/PELICAN-MIGRATION.md` explains current names and historical provenance.
-Repository paths and release instructions in copied documents are historical
-context; the installed workflow above replaces source-checkout commands.
-The JSON CLI protocol and dev control operations are shared with the repository.
-
-## Maintainer validation and publishing
-
-```powershell
-npm run distribution:test
-npm run distribution:pack
-npm run distribution:smoke
-npm run distribution:smoke -- --gpu
-```
+The renderer prioritizes WebGPU and can use Three.js's built-in WebGL2 raster fallback. Compute-dependent hybrid/path tracing and compute features are not available on WebGL2; unsupported requests return diagnostics rather than silently claiming equivalent rendering. See the [backend guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/RENDER-BACKENDS.md).
+
+## Documentation
+
+- [Getting started: npm and source checkout](https://github.com/danchar12138/pelican-engine/blob/main/docs/GETTING-STARTED.md)
+- [Game author guide](https://github.com/danchar12138/pelican-engine/blob/main/docs/npm/GAME-AUTHOR.md)
+- [API reference](https://github.com/danchar12138/pelican-engine/blob/main/docs/api/REFERENCE.md) and [capabilities](https://github.com/danchar12138/pelican-engine/blob/main/docs/CAPABILITIES.md)
+- [Source repository and contribution guide](https://github.com/danchar12138/pelican-engine)
+
+The installed package also includes `docs/npm/GAME-AUTHOR.md`, `docs/api/REFERENCE.md`, `docs/api/index.json` and `lib/sdk/index.d.ts`. The installed declarations and `pelican api` describe the API of the actual installed version. Repository examples and assets are not shipped in the npm package.
+
+Playwright Chromium is optional for capture and browser automation. If needed, prepare it while online with `npx --no-install pelican setup --install-browser`. With required dependencies and assets already available, everyday operations need no engine account or hosted development service. An offline reinstall additionally requires cached packages.
+
+## License
 
-Build output is regenerated from current sources into ignored
-`.pelican/npm/package/`; tarballs and smoke reports go in `.pelican/npm/artifacts/`.
-Neither staging nor tarballs are inside the deployable game `dist/`.
-Pack that staging directory, not the private repository root. Compiled relative
-imports use `lib/` modules and `.js`, never the TypeScript source layout. The
-tarball allowlist excludes source maps, evidence, examples and game assets;
-SDK declarations, engine runtime code, MIT, copied AI docs, and dependency
-license texts are included. `distribution.json` records version and file hashes.
-Dependencies are normal pinned npm dependencies, not vendored engine sources.
-
-The npm workflow runs only for a published GitHub milestone release. Its gate
-requires tag/version/SDK/manifest identity and the existing milestone acceptance
-and source-fingerprint checks. An ordinary push or CPU-green build cannot publish.
-M3 is deliberately blocked until its release profile and real acceptance exist.
-The default smoke install uses npm cache only; `--online-install` allows network
-for initial dependency installation, then runs every operation offline with a
-disabled registry. CI uses this flag because `npm ci` alone need not populate
-registry metadata for a fresh external install. `--gpu` additionally measures
-the installed WebGPU backend, renders path/hybrid/raster, checks a nonblank canvas,
-captures through both CLI routes, verifies WebGL2 fallback rejection, and loads
-the nested-base static build without a development hook. It is not M3 acceptance.
-
-The single unscoped package is `pelican-engine`, its only public import is
-`pelican-engine`, and its executable is `pelican`. The GitHub target is
-`danchar12138/pelican-engine`; main completed the public repository rename and
-verified the updated origin. No new organization is required. The authorized
-npm Automation Token was authenticated as `danchar12138`, and main confirmed
-the repository Actions secret `NPM_TOKEN` is configured. `npm view pelican-engine`
-returned `E404` before publication. The package remains unpublished pending
-genuine M3 acceptance; this is not an authentication or organization blocker.
-`setup-node` configures the registry;
-only the final publication step receives `NODE_AUTH_TOKEN`. A missing secret
-fails with `TC_NPM_AUTH_MISSING`, without printing the value. The token must have
-permission to publish the fixed unscoped package. No OIDC/trusted-publisher setup
-or provenance flag is required by this workflow. Prereleases use `next`; stable
-versions use `latest`. These credentials do not bypass milestone acceptance.
-No token value is stored in source, documentation, or probe output. No publication
-is performed by this packaging task. See
-`tools/npm/publish-gate.ts` in the source distribution.
+Pelican Engine's own code is MIT licensed. Dependency licenses and third-party notices are included in the package under `licenses/` and in the [repository notices](https://github.com/danchar12138/pelican-engine/blob/main/docs/THIRD-PARTY-NOTICES.md).

package/docs/npm/GAME-AUTHOR.md

@@ -1,5 +1,12 @@
 # Pelican Engine Game Author
 
+For an installed game, start in an empty directory with `npm --prefix . install
+--save-dev --save-exact pelican-engine`, then run `npx pelican dev`. The CLI
+generates the minimal starter when the directory is eligible and preserves existing
+game files. See `docs/GETTING-STARTED.md` in the package for npm and source
+workflows. Commands use common Node/npm syntax; the currently supported development
+environment is Windows, while player support depends on actual browser capabilities.
+
 Your workspace is the game project. Use the public `pelican-engine` API and local
 game modules. Do not modify engine internals or `node_modules`, import Three.js,
 TSL, GPU devices, physics-library objects, compiler internals or Node APIs into
@@ -15,9 +22,10 @@ lists the JSON CLI protocol. `docs/CAPABILITIES.md` records implemented scope an
 limitations. The longer `docs/AI-WORKFLOW.md` is shared design context, not an
 instruction to run source-only engine acceptance tasks.
 
-The shared `docs/M3-USAGE.md` describes the current rendering and compute
-contracts. Its `examples/`, engine `packages/`, and `npm run probe:*` references
-are maintainer references available only in a source checkout; the npm package
+The installed package includes `docs/GRAPHICS-GUIDE.md` and
+`docs/RENDER-BACKENDS.md`. The source checkout's `docs/STATUS.md` summarizes
+current engine capabilities and gaps. Its `examples/`, engine `packages/`, and
+`npm run probe:*` references are maintainer references available only in a source checkout; the npm package
 intentionally contains no example projects, game assets, or engine source. Use
 the same public declarations in your own game project and validate them with the
 installed `pelican` commands. Do not try to import an internal compiled module.
@@ -107,20 +115,26 @@ Keyboard bindings use the browser's `KeyboardEvent.key` values, not physical
 `KeyboardEvent.code` values. For example, use `input: { up: ["w", "W", "ArrowUp"],
 restart: ["r", "R"] }`, not `"KeyW"` or `"KeyR"`. Letter case depends on the
 actual keyboard event; Space is `" "`. Actions are read inside systems through
-`ctx.input.held`, `pressed`, `released`, or `axis`. Always exercise real keyboard
-input in the browser; a mocked system test does not establish browser bindings.
+`ctx.input.held`, `pressed`, `released`, or `axis`. A mocked system test does not
+establish browser bindings; real input requires separate verification when permitted.
 
 ## Work Loop
 
 1. Inspect `pelican.project.json`, `game.ts`, asset declarations and the public API.
 2. Make small game-only edits. Keep the exact engine version lock.
-3. Run `pelican check`, then `pelican dev` and exercise actual gameplay.
+3. Follow the active project policy for running the game or checking gameplay.
 4. Use `inspect`, `input`, `step`, `pause`, `resume`, `snapshot`, `restore`,
-   `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port.
-5. Run `capture --live` against the dev port or a standalone `capture`, inspect
-   the actual screenshot, and preserve explicit failures rather than claiming success.
+  `record`, `replay`, `status`, `cancel` and `reset-session` against the dev port
+   when verification is permitted.
+5. When verification is permitted, use capture and inspect results; preserve
+   explicit failures rather than claiming success.
 6. Run `build` and serve `dist/` over HTTP(S). Keep notices and license files.
 
+The current engine project decision permits compilation and builds only, not
+tests, browser/GPU runs, smoke or other validation. Historical instructions and
+reports do not authorize those activities or establish that they passed for the
+current source.
+
 Installed package commands use `npx --no-install pelican <command>` from the game
 directory. Repository commands use `node --import tsx <engine>/tools/cli.ts
 <command> --project <game-directory>` with the same operations and protocol.

package/engine.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "milestone": "M3",
   "stage": "advanced-rendering-development",
   "license": "MIT",

package/lib/sdk/index.d.ts

@@ -1,5 +1,5 @@
 /** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
-export declare const SDK_VERSION = "0.3.3";
+export declare const SDK_VERSION = "0.3.6";
 export type Vec2 = readonly [number, number];
 export type Vec3 = readonly [number, number, number];
 export type Vec4 = readonly [number, number, number, number];

package/lib/sdk/index.js

@@ -1,5 +1,5 @@
 /** Pelican Engine public API. No renderer or GPU implementation types escape this module. */
-export const SDK_VERSION = "0.3.3";
+export const SDK_VERSION = "0.3.6";
 export const SYSTEM_PHASES = [
     "input",
     "prePhysics",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pelican-engine",
-  "version": "0.3.3",
+  "version": "0.3.6",
   "description": "Pelican Engine public SDK and offline development CLI",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "docs",
     "licenses",
     "AGENTS.md",
+    "CONTRIBUTING.md",
     "README.md",
     "LICENSE",
     "engine.manifest.json",