@world-engines/agent-kit 0.1.0-alpha.0

package/assets/guides/long-form-ladybug-trigger.md

@@ -0,0 +1,98 @@
+# 全文 Ingest、Ladybug Recall 与 Trigger 受控创作
+
+本指南适用于 Codex、Claude Code，以及通过通用 MCP 或 CLI 接入的其他 harness。它不提供新的 harness，也不扩大 ProjectHost 的能力；可调用项以当前 `worldengine` CLI help 与 MCP `tools/list` 为准。DeepSeek Harness 不随套件安装，当前只声明通用 MCP/CLI 接入，不代表已完成 DeepSeek 真机验收。
+
+Codex 从项目级 `.codex/config.toml` 启动 `worldengine` MCP，并且只有从项目根打开且项目被作者标记为 trusted 后才生效；Claude Code 同样从项目根打开并由作者允许 trust。套件不会静默修改 trust、provider、模型、auth 或用户级 override，也不依赖 args 的隐式解析位置。
+
+若当前 Codex CLI 不能自动发现项目 MCP，使用项目根 `.\worldengine-codex.ps1` 启动交互模式，或把 `exec` 及其参数作为独立 argv 传给该脚本。launcher 只在本次进程显式注入 `mcp_servers.worldengine`，不会改写用户配置、provider/auth 或其他 MCP。
+
+配置仅对 `worldengine` 设置 `default_tools_approval_mode = "writes"`。它依赖 Host 的真实 tool annotations：read-only 工具可直接执行，project effect 和未标记只读的交互工具仍提示批准；不得把 effect 误标成 read-only 或把模式扩大到其他 MCP。
+
+项目从根目录打开，harness cwd 已是项目根，因此配置使用 `cwd = "."`，并通过根 `worldengine-mcp.cmd` 使用 portable runtime；不得写成 `".."` 跳出项目。`env_vars` 只转发网络与当前公开 capability 变量，不包含 provider key。Agent Kit 不要求用户配置 DeepSeek/OpenRouter key，也不修改外部 harness 的全局模型。用户确认走 harness 自身对话；预览优先使用 available 的 MCP `preview_inspect/interact` 独立 Chrome adapter，不需要额外环境桥接。
+
+如果作者的网络必须经过环境代理，应在启动 harness 或 CLI **之前**由作者自己的安全启动环境设置 `NODE_USE_ENV_PROXY=1`，并按其网络配置提供适用的 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY`/`NO_PROXY`。仅存在 proxy URL 变量不会自动让 Node fetch 使用环境代理。Agent Kit 只转发已配置变量，不覆盖全局环境、不固定本机端口，也不承诺代理可用。
+
+## 1. Harness、Host 与 embedding 的边界
+
+全文结构化抽取与分段语义由外部 harness 使用它自己当前选择的模型完成。Host 不选择模型、不直连模型 provider；它只准备不改写的原文窗口与输出 schema，校验 harness 返回值，持久化 checkpoint，并把通过校验的最终成书内容 commit。讨论、推理草稿、候选争论和中间对话都不写入作品。
+
+Agent Kit 不分发 provider key，也不要求作者配置 DeepSeek/OpenRouter key。不要把 provider key 写入 `.env`、项目 manifest、prompt、receipt、provenance 或 MCP `env_vars`，也不要替用户修改 Codex、Claude Code 或其他 harness 的全局模型。
+
+embedding 是独立本地准备阶段：作者必须先完成产品登录，再通过 `127.0.0.1:11450` 服务按账户余额结算。harness 不得直连 embedding provider，也不能用自造向量、关键词或伪向量绕过登录/余额门。混合检索与多跳查询消费已经提交的本地向量产物；具体命令、schema 与 receipt 只采用当前已安装 CLI help/MCP `tools/list` 已公开的合同。
+
+## 2. 使用真实全文入口
+
+源文件必须位于项目根内，格式为 `.md`、`.markdown` 或 `.txt`。Windows 优先使用项目根 `.\worldengine.cmd`，它优先 portable Node，不要求全局 Node/npm/npx；系统 Node 已存在时可使用等价的 `npx --no-install worldengine`，且禁止下载。先执行 `.\worldengine.cmd --help`，确认当前 Host 公布以下 positional contract：
+
+```text
+.\worldengine.cmd ingest <path> <scope-id> <source-id> <source-revision>
+.\worldengine.cmd ingest next <operation-id>
+.\worldengine.cmd ingest accept <operation-id> <request-id> <candidate-json-file>
+.\worldengine.cmd ingest commit <operation-id>
+.\worldengine.cmd ingest status <operation-id>
+.\worldengine.cmd ingest resume <operation-id>
+.\worldengine.cmd ask <scope-id> <query>
+.\worldengine.cmd recall prepare [scope-id]
+.\worldengine.cmd dump <document-id> <output-relative-dir>
+.\worldengine.cmd recall <query> [limit]
+.\worldengine.cmd read <entity-id>
+.\worldengine.cmd review prepare <operation-key> [--review-note <text>] [--release-at-ms <timestamp>]
+.\worldengine.cmd review submit <operation-key> [--review-note <text>] [--release-at-ms <timestamp>]
+.\worldengine.cmd review status <operation-key>
+```
+
+然后运行，例如：
+
+```text
+.\worldengine.cmd ingest docs/world-lore.md scenario-main world-lore rev-2026-09-05
+```
+
+初次导入全新文件时，harness 读取当前 manifest 的 `local_scenario_id`，与规范化项目相对文件路径一起稳定生成 CLI 所需的 scope/source/revision identity；不要求作者理解或填写这些内部参数。只有已存在的 source identity 与当前文件冲突、且 source readback 无法消歧时才询问。内容变化不能沿用旧 revision 冒充同一版本。
+
+首个 `ingest` 准备 source 并在 stdout 返回 `{ receipt, next }`。harness 从 `next.request.structuredRequest.messages` 取得模型输入，以同处的 `jsonSchema` 约束候选 JSON；候选文件必须位于项目内且不超过 8 MiB，再以同一 operation/request ID 交给 `accept`。Host 校验候选并落 checkpoint，不重打 raw bytes。重复 `next` 直到 ready 后执行 `commit`；最终持久化仍只经 Host 的 `world_apply`，只提交最终成书内容，不提交讨论、推理草稿或废案。
+
+无损全文细节以启用的 `lossless-document-authoring` Skill 及其 `references/d4f-workflow.md` 为准。ingest/resume 后核对 `operationId`、`rawByteSha256`、`roundtripVerified`、`sourceCoverage`、`graphStatus`、`pendingWindows`、`failedWindows` 和 `embeddingStatus`；新编辑态 `embeddingStatus.status=pending` 是预期结果，不能据此称提审失败或 ready。`staged` 只证明暂存，不证明已经提交 Ladybug。`ingest status` 返回 journal/checkpoint，完成时从其 `commitReceipt` 读取结果；不要凭退出码、完整 source coverage 或已提交 partial 图宣称全书图完成。
+
+恢复使用首个 stdout 回执中的原 operation ID：`ingest resume <operation-id>` 在 journal 已 ready 时直接 commit，否则返回下一条 request。`ingest status` 继续兼容旧 journal；旧 provider 方法没有 adapter 时明确失败，不能清空 checkpoint、伪造 candidate 或静默迁移到新 harness 方法。
+
+当前源码已接入 review CLI，但每次仍以已安装包的 help 为准，不能从源码或文档推断作者环境自动具备。命令要求 `worldengine.project.json` 的 `project_id` 与桌面注入的短期 ProjectAuthBroker capability 匹配；需要 embedding 时还要求已登录的 `127.0.0.1:11450` 服务与足够账户余额。agent 不读取或复述这些能力值。
+
+`review prepare` 捕获并解密 project-bound source-ready revision，核对本地 WESP，运行当前合同声明的 compiler/View build/Rust-WASM、独立本地向量准备和冻结组装；它只写本地随机密文恢复材料，远端写为 0。`review submit` 使用同一 operation key 和同一冻结 wire，成功路径只发一个 attempt POST；重启或结果不确定时先 readback，不重新 prepare。`review status` 查询同一 principal-bound operation，仍需 project auth。prepared 或 `pending_review` 都不是 ready；必须继续读回同源审核、coverage 与质量封分，review 也不等于 publish。
+
+只依据本项目当前 source/WESP receipt、graph status、已安装版本公开的容量门和真实上传/提审 readback 判断状态。局部运输实验不代表 production transport；新的 chunk transport 未经公开入口和回执证明前不得写成已支持。
+
+## 3. 编辑态 readback 与有向量产物验收
+
+新 operation 使用当前 help/schema 公布的 harness request/accept/commit 方法，先核对原始 bytes、完整 source coverage、graph status、来源 revision/provenance 与 reopen readback；`graphStatus=partial` 始终是部分图。聊天式渐进编辑同样只维护中性作者源与 raw graph，不摘要化原文，也不为每次编辑请求 embedding。原文字节完整不证明 fact graph 完整，fact graph 完整也不证明 quality 通过。
+
+用户要求查书时，先说明 semantic 检索要求产品登录，`.\worldengine.cmd recall prepare [scope-id]` 会按账户余额计费；用户登录态是这一产品调用的授权，不再索取 provider key。先为当前 revision 完成 prepare，再运行 `ask <scope-id> <query>`。外部 harness 路径的 `ask` 返回 `candidates`、`graphPaths`、`pathOptions`、`evidence`、完整性与 trace，不返回 `answerable`/成品答案/citations；harness 自己依据 evidence 与有向路径回答，证据不足就明确不可回答。
+
+只有向量准备回执已经证明本机服务 identity、向量 profile/dimension/text identity 与覆盖闭合，才进行 semantic/hybrid 验收。在专用测试文档最后一个自然段放置一个不与前文重复、可独立核验的事实；真实作者原文只选择已有末段事实，不追加或改写。查询命令与 schema 以当前 CLI help/MCP `tools/list` 为准；若已公开独立本地向量与 hybrid 多跳接口，逐项验证：
+
+1. 用不复述原文的同义问题执行 `mode: "semantic"`，命中预期 fact/entity；结果必须包含 `semantic` channel。
+2. 验证不相关查询拒绝：用与文档主题无关的问题执行相同查询，应被距离门拒绝而返回空结果；“总会返回一个最近项”不算通过。
+3. 单独询问末段事实的同义表达，必须命中末段 fact，防止只处理文档前部。
+4. 对命中 ID 执行 `.\worldengine.cmd read <entity-id>`；MCP 等价入口是 `world_get`。核对 fact 与 source provenance；provenance 至少能读回稳定 `sourceId`、项目相对 `sourcePath`、content digest/来源 revision，不得包含 secret 或本机绝对路径。
+5. 关闭并重新启动 Host/MCP，再重复同义、无关和末段查询；reopen 后结果与 provenance 仍正确才算持久化通过。
+
+`semantic` 字样、非空结果、effect receipt 或内存态查询都不是质量证明。缺少登录、余额或闭合的本地向量产物时 semantic/hybrid 必须 fail closed，禁止回退为关键词或伪向量。
+
+当前 schema 若公开 `world_search`，它只读取已准备的检索产物；用 `world_get` 读回命中实体与 provenance。不要把 MCP 工具的存在误解为产品 runtime 或 iframe 依赖 MCP。
+
+全文 ingest 后的小范围明确修订仍使用当前 `tools/list` 已公开的对应 Tool。先读当前 `worldengine.project.json` revision 和目标实体；effect 使用稳定 `operation_id` 与当前 `expected_project_revision`，成功后核对 `readback_verified`。这些编辑保持无向量 raw graph；stale revision 时重读并形成新意图，不要只换 revision 重放旧参数。
+
+## 4. Trigger 的正确顺序
+
+1. 调用 `trigger_schema` 和 `trigger_read` 获取当前结构与已有 Trigger。
+2. 用 `world_get` 确认普通 entity 引用；涉及空间对象时读取现有 Spatial World readback，只使用 stable `spatial_ref`。
+3. 构造完整 candidate document，先调用 `trigger_validate`。有 issue 时不写入。
+4. 以 `trigger_apply` 的当前 contract 写入，并携带稳定 operation ID 与当前 revision。
+5. 核对 effect receipt 后用 `trigger_read` 读回实际已提交投影，再用代表性 event/state 调用 `trigger_simulate`，确认命中的是预期 Trigger。
+
+Trigger 不复制空间树，Ladybug/Trigger 只保存 stable 引用。删除空间对象或引用前先读取 reverse impact；不得用任意 statement 绕过校验。GUI 通知、preview、候选预筛、旧内存数组或 TriggerProgramV1 都不是保存证据；Browser Creator 与 Desktop Tauri 各自需要真实 readback，不能互相替代。
+
+## 5. 交付给作者的证据
+
+需要原文与当前已提交图供人或 LLM 审阅时，使用 `dump` 把已提交的 `documentId` 导出到项目内尚不存在的新目录。它无需模型/凭据，生成原始 bytes 的 `source.txt`、人类可读实体/有向边/断言/证据的 `graph.txt`、组合审阅材料 `review.txt` 与最后发布的 `manifest.json`。原文字节守恒、chunk 覆盖、语义实体/边/断言数量和去重证据覆盖分开报告；`graphStatus=partial` 不因导出成功变完整，图文长度不能换算成理解量，`review.txt` 已生成不代表 D4F 已审核或产物 ready。详细计数与完整性边界见 `lossless-document-authoring` Skill 的工作流。
+
+报告 CLI contract、source/scope/revision identity、ingest receipt、raw graph/source readback、reopen、source provenance、Trigger readback/simulate 和项目 revision 变化。只有存在已闭合向量回执时才报告同义/无关/末段 semantic 查询；不要报告 key 值、内部日志、绝对路径或未经真机验证的 harness 能力。

package/assets/launchers/worldengine-codex.ps1

@@ -0,0 +1,105 @@
+$ErrorActionPreference = "Stop"
+$CodexArguments = [string[]]$args
+
+function ConvertTo-TomlString([string] $Value) {
+  return ($Value | ConvertTo-Json -Compress)
+}
+
+function Find-WorldEngineProjectRoot([string] $StartDirectory) {
+  $candidate = [System.IO.Path]::GetFullPath($StartDirectory)
+  for ($depth = 0; $depth -lt 8; $depth += 1) {
+    if (Test-Path -LiteralPath (Join-Path $candidate "worldengine.project.json") -PathType Leaf) {
+      return (Get-Item -LiteralPath $candidate).FullName
+    }
+    $parent = [System.IO.Directory]::GetParent($candidate)
+    if ($null -eq $parent) { break }
+    $candidate = $parent.FullName
+  }
+  throw "E_PROJECT_ROOT_REQUIRED: launcher is outside a Local Author Project"
+}
+
+function Resolve-WorldEngineNode([string] $ProjectRoot) {
+  $portableNode = Join-Path $ProjectRoot ".worldengine\runtime\node\node.exe"
+  if (Test-Path -LiteralPath $portableNode -PathType Leaf) {
+    return (Resolve-Path -LiteralPath $portableNode).Path
+  }
+  try {
+    $nodeCommands = @(Get-Command node -CommandType Application -ErrorAction Stop)
+  } catch {
+    throw "E_NODE_RUNTIME_UNAVAILABLE: portable Node is missing and system Node was not found"
+  }
+  $nodeCommand = $nodeCommands[0]
+  $major = & $nodeCommand.Source -p "Number(process.versions.node.split('.')[0])"
+  $parsedMajor = 0
+  if ($LASTEXITCODE -ne 0 -or -not [int]::TryParse([string]$major, [ref]$parsedMajor) -or $parsedMajor -lt 24) {
+    throw "E_NODE_RUNTIME_UNAVAILABLE: system Node.js 24 or newer is required"
+  }
+  return $nodeCommand.Source
+}
+
+$launcherPath = (Get-Item -LiteralPath $PSCommandPath).FullName
+$projectRoot = Find-WorldEngineProjectRoot ([System.IO.Path]::GetDirectoryName($launcherPath))
+$nodePath = Resolve-WorldEngineNode $projectRoot
+$manifestPath = Join-Path $projectRoot "worldengine.project.json"
+$projectFormatValidatorPath = Join-Path $projectRoot "node_modules\@world-engines\project-format\dist\index.js"
+if (-not (Test-Path -LiteralPath $projectFormatValidatorPath -PathType Leaf)) {
+  throw "E_PROJECT_MANIFEST_INVALID: installed manifest validator is missing"
+}
+$manifestValidatorSource = @'
+import { readFile } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+const [{ validateLocalAuthorProjectManifest }, source] = await Promise.all([
+  import(pathToFileURL(process.argv[1]).href),
+  readFile(process.argv[2], 'utf8'),
+]);
+validateLocalAuthorProjectManifest(JSON.parse(source));
+'@
+& $nodePath --input-type=module --eval $manifestValidatorSource $projectFormatValidatorPath $manifestPath
+if ($LASTEXITCODE -ne 0) {
+  throw "E_PROJECT_MANIFEST_INVALID: Local Author Project manifest is invalid"
+}
+
+$hostPackageRoot = Join-Path $projectRoot "node_modules\@world-engines\project-host"
+$hostPackageManifestPath = Join-Path $hostPackageRoot "package.json"
+$hostPackageManifest = Get-Content -Raw -LiteralPath $hostPackageManifestPath | ConvertFrom-Json
+if ($hostPackageManifest.name -ne "@world-engines/project-host") {
+  throw "E_PROJECT_HOST_INVALID: installed ProjectHost identity is invalid"
+}
+
+$hostCliLogicalPath = [System.IO.Path]::GetFullPath((Join-Path $hostPackageRoot "dist\cli.js"))
+$rootPrefix = $projectRoot.TrimEnd("\", "/") + [System.IO.Path]::DirectorySeparatorChar
+if (-not $hostCliLogicalPath.StartsWith($rootPrefix, [System.StringComparison]::OrdinalIgnoreCase)) {
+  throw "E_PROJECT_HOST_INVALID: ProjectHost logical path escapes project root"
+}
+$hostCliPath = (Resolve-Path -LiteralPath $hostCliLogicalPath).Path
+if (-not (Test-Path -LiteralPath $hostCliPath -PathType Leaf)) {
+  throw "E_PROJECT_HOST_INVALID: ProjectHost CLI is missing"
+}
+
+$codexCommands = @(Get-Command codex -CommandType Application -ErrorAction Stop)
+$codexCommand = @($codexCommands | Where-Object { [System.IO.Path]::GetExtension($_.Source) -ieq ".exe" })[0]
+if ($null -eq $codexCommand) { $codexCommand = $codexCommands[0] }
+$projectRootToml = ConvertTo-TomlString ($projectRoot -replace "\\", "/")
+$hostCliToml = ConvertTo-TomlString ($hostCliPath -replace "\\", "/")
+$nodeToml = ConvertTo-TomlString ($nodePath -replace "\\", "/")
+$environmentToml = '[__WORLDENGINE_ENV_VARS_TOML__]'
+$mcpOverrides = @(
+  "-c", "mcp_servers.worldengine.command=$nodeToml",
+  "-c", "mcp_servers.worldengine.args=[$hostCliToml,`"mcp`"]",
+  "-c", "mcp_servers.worldengine.cwd=$projectRootToml",
+  "-c", "mcp_servers.worldengine.env_vars=$environmentToml",
+  "-c", "mcp_servers.worldengine.default_tools_approval_mode=`"writes`""
+)
+
+if ($CodexArguments -contains "--") {
+  throw "E_CODEX_ARGUMENTS_INVALID: launcher rejects the -- terminator"
+}
+if ($CodexArguments -contains "-C" -or $CodexArguments -contains "--cd") {
+  throw "E_CODEX_ARGUMENTS_INVALID: Codex working root is launcher-owned"
+}
+if ($CodexArguments | Where-Object { $_ -match "^mcp_servers\.worldengine(?:\.|=)" }) {
+  throw "E_CODEX_ARGUMENTS_INVALID: worldengine MCP override is launcher-owned"
+}
+
+& $codexCommand.Source @mcpOverrides "-C" $projectRoot @CodexArguments
+exit $LASTEXITCODE

package/assets/launchers/worldengine-mcp.cmd

@@ -0,0 +1,5 @@
+@echo off
+setlocal EnableExtensions DisableDelayedExpansion
+cd /d "%~dp0" || exit /b 1
+call "%~dp0worldengine.cmd" mcp
+exit /b %ERRORLEVEL%

package/assets/launchers/worldengine-npm.cjs

@@ -0,0 +1,18 @@
+const { spawnSync } = require("node:child_process");
+
+const [npmCli, dispatch, ...args] = process.argv.slice(2);
+if (npmCli === undefined || dispatch !== "npm") {
+  process.stderr.write("E_NPM_ARGUMENTS_INVALID: worldengine npm dispatcher received invalid argv\n");
+  process.exit(2);
+}
+const result = spawnSync(process.execPath, [npmCli, ...args], {
+  stdio: "inherit",
+  env: process.env,
+  windowsHide: true,
+  shell: false,
+});
+if (result.error !== undefined) {
+  process.stderr.write(`E_NODE_RUNTIME_UNAVAILABLE: ${result.error.message}\n`);
+  process.exit(1);
+}
+process.exit(result.status ?? 1);

package/assets/launchers/worldengine.cmd

@@ -0,0 +1,39 @@
+@echo off
+setlocal EnableExtensions DisableDelayedExpansion
+set "WORLDENGINE_PROJECT_ROOT=%~dp0"
+cd /d "%WORLDENGINE_PROJECT_ROOT%" || exit /b 1
+set "WORLDENGINE_NODE=%WORLDENGINE_PROJECT_ROOT%.worldengine\runtime\node\node.exe"
+if exist "%WORLDENGINE_NODE%" goto run
+
+set "WORLDENGINE_NODE="
+for /f "delims=" %%I in ('where node 2^>nul') do if not defined WORLDENGINE_NODE set "WORLDENGINE_NODE=%%~fI"
+if not defined WORLDENGINE_NODE (
+  >&2 echo E_NODE_RUNTIME_UNAVAILABLE: portable Node is missing and system Node was not found
+  exit /b 1
+)
+for /f "delims=" %%V in ('node --version') do set "WORLDENGINE_NODE_VERSION=%%V"
+for /f "tokens=1 delims=." %%V in ("%WORLDENGINE_NODE_VERSION:v=%") do set "WORLDENGINE_NODE_MAJOR=%%V"
+if not defined WORLDENGINE_NODE_MAJOR (
+  >&2 echo E_NODE_RUNTIME_UNAVAILABLE: system Node version could not be read
+  exit /b 1
+)
+if %WORLDENGINE_NODE_MAJOR% LSS 24 (
+  >&2 echo E_NODE_RUNTIME_UNAVAILABLE: system Node.js 24 or newer is required
+  exit /b 1
+)
+
+:run
+if /i "%~1"=="npm" goto npm
+"%WORLDENGINE_NODE%" "%WORLDENGINE_PROJECT_ROOT%node_modules\@world-engines\project-host\dist\cli.js" %*
+exit /b %ERRORLEVEL%
+
+:npm
+for %%D in ("%WORLDENGINE_NODE%") do set "WORLDENGINE_NODE_DIR=%%~dpD"
+set "WORLDENGINE_NPM_CLI=%WORLDENGINE_NODE_DIR%node_modules\npm\bin\npm-cli.js"
+if not exist "%WORLDENGINE_NPM_CLI%" (
+  >&2 echo E_NODE_RUNTIME_UNAVAILABLE: selected Node runtime does not include npm CLI
+  exit /b 1
+)
+set "PATH=%WORLDENGINE_NODE_DIR%;%PATH%"
+"%WORLDENGINE_NODE%" "%WORLDENGINE_PROJECT_ROOT%worldengine-npm.cjs" "%WORLDENGINE_NPM_CLI%" %*
+exit /b %ERRORLEVEL%

package/assets/prompts/local-author-system.md

@@ -0,0 +1,40 @@
+# WorldEngine Local Author 助手
+
+你在 Local Author Project 根目录中帮助作者制作 Scenario 与 ChatPlay View。你是作者助手，不是 agent supervisor、项目编排器、发布代理或账户管理员。本文件是项目唯一完整 system prompt；根 `AGENTS.md`、`CLAUDE.md` 与 `AGENT.md` 都链接到它。
+
+## 文档与接口
+
+- 开始作者工作先读取 `docs/authoring/development/cli.md` 与 `docs/authoring/development/authoring-workflows.md`；再读取该接口直接相关的其他 development 文档。调用 MCP 前还必须读取本次连接实时返回的 `tools/list`、输入 schema 与 `worldengine/toolAvailability`。文档或实时工具面没有声明的名称、参数、返回值和能力一律未知，不猜测、不按记忆补全。
+- ChatPlay SDK、View fixture、AuthoringBridge、CLI、文件格式与 review protocol 是不同接口。先找到各自文档再使用，不能把一个接口的字段或能力外推给另一个接口。
+- 使用 Codex、Claude Code、Node.js、npm 或其他外部工具时，如项目文档不足，查询该工具维护者的官方文档；不能以博客、旧示例或其他 harness 行为替代当前官方合同。
+- `docs/authoring/guides/` 保存任务指南，`docs/authoring/skills/` 保存可发现 Skill。指南和 Skill 不能覆盖 development 文档或实时 `tools/list` 的接口事实。
+
+## 工作边界
+
+- 本目录同时是项目根与 harness cwd。只修改项目根内的作者文件，不向用户目录、AppData 或临时目录持久化项目数据；保留作者已有改动。
+- View 源码只在 `view/`。先查 ChatPlay SDK 与 fixture 文档，不能读取 top window、cookie、AuthoringBridge 或项目文件系统，也不能把 Scenario 或凭据复制进 View。修改后运行项目已有的最小 typecheck/build 验证。
+- Scenario authority 只在 `scenario/source.wes`，但 Ladybug、Trigger、Layout、Retrieval 与 World Generator 只能经项目 `worldengine` MCP 或文档明确列出的等价 CLI 修改。不得直接编辑二进制、projection、snapshot、operation ledger 或数据库。
+- Scene 作者态读取和写入先看 `docs/authoring/development/scene-authoring.md`：`world_schema.scene` 给出当前 operation，`trigger_schema.local_effect_capabilities` 给出 registered arguments schema，`world_get.metadata.initial_scene` 是作者态 readback。不要猜单独 Scene tool。
+- creator-view 运行在不含 `allow-same-origin` 的 sandboxed iframe；iframe 只使用文档明确提供的 ChatPlay SDK 能力。
+- MCP 只是外部 harness 的开发脚手架。产品 runtime 和 creator-view iframe 不依赖 MCP，也不得从 iframe 暴露 MCP；运行时交互只使用 ChatPlay SDK。
+- `.worldengine/` 仅保存本项目运行态。不得提交、读取、打印、记录或复制 token、cookie、验证码、密钥、`.env` 或其他凭据，也不得改写全局 provider、模型、认证、代理或用户配置。
+
+## 有副作用的操作
+
+- 每次开始先读取 `worldengine.project.json` 的当前 `project_revision`。持久化 effect 使用稳定 `operation_id` 与刚读到的 `expected_project_revision`，成功后核对 receipt、revision、snapshot digest 与 readback。stale 时重读并重新表达作者意图，不盲目替换 revision 或重复提交。
+- 全文入口、恢复、问答与 review 命令以当前 development 文档和 CLI help 为准；Windows 优先运行项目根 `.\worldengine.cmd`，它使用 portable Node；只有系统 Node 已存在时才使用等价的 `npx --no-install worldengine`，且不允许隐式下载。结构化抽取与分段语义使用当前外部 harness 自己的模型；模型输入取自 `next.request.structuredRequest.messages`，输出必须符合其 `jsonSchema`。Host 只准备原文窗口、校验返回值、持久化 checkpoint 并 commit。只写最终成书内容，不把讨论、推理草稿、中间对话或废案写进作品。原文 bytes、BOM、换行与 Unicode 不改写；source coverage、graph completeness、embedding identity 与 quality review 是独立结论，没有对应 readback 就不能声称完成。
+- 初次导入全新来源时，不要求作者理解或填写 scope/source/revision：根据当前 manifest 的 `local_scenario_id` 与规范化的项目相对文件路径稳定推导身份。只有已有 source identity 与当前文件发生冲突、且 readback 无法消歧时才询问作者。
+- 作者可把绝对外部 `.txt/.md/.markdown` 原文路径直接交给 `ingest`。Host 在单一入口校验 regular file/扩展名/边界并逐字节复制到 `.worldengine/imported-sources/<content-hash>.<ext>`；回执的稳定逻辑 `sourcePath` 为 `external-source/<path-hash>.<ext>`，`sourceStoragePath` 指向物理副本。初始 source identity 仍由 `local_scenario_id` 与逻辑路径推导，不从 content hash 推导。外部原件不移动、不改写、不执行。代码工程与其他资源转换仍由 harness 静态安全复制进项目，禁止执行来源脚本或宏。用户初始请求已明确“转换并写入/生成”时直接执行；只有用户要求先讨论、比较或逐项确认时才等待成稿意图。
+- embedding 只能在作者已登录后调用本机 `127.0.0.1:11450`，并按账户余额结算。不得索取、配置或分发 DeepSeek/OpenRouter provider key，也不得直连 provider。独立本地向量准备、混合检索和多跳查询的命令/字段只从当前 CLI help 或 MCP schema 获取。
+- 用户要求查书时，先说明 semantic 检索需要产品登录，`recall prepare [scope-id]` 会按账户余额计费；登录态本身是产品授权，不另索取 provider key。准备当前 revision 后再调用 `ask`。npm 作者路径的 `ask` 只返回 `candidates`、`graphPaths`、`pathOptions`、`evidence` 等证据 bundle，不返回成品答案；由当前 harness 依据 bundle 回答并保留不确定性。
+- Trigger 写入前读取当前 schema/document，先 validate；写入后 readback 并 simulate。只引用已读回的 entity 或 stable `spatial_ref`，GUI 通知、preview 或内存对象不算保存证据。
+- Scene 在场对象可引用任意现存 logical graph node；`spatialRef.sourceRevision` 是地图自身 revision，不是 project revision。manuscript note 的 text 必须逐字保留，只是 writer-facing data，lifetime 为 `once|scene_end`；不能写成 system prompt、永久 fact 或 entity attribute。旧 `next-system-prompt` 转换为 typed `scene.note.add`，不要注入系统提示词。
+- 需要用户选择时直接在当前 harness 对话中询问，不调用内部 `ask_user`。预览优先使用实时 `tools/list` 标记 available 的 MCP `preview_inspect/interact`；它们由独立 Chrome adapter 提供，不需要额外环境桥接，必须消费 `preview_inspect` 返回的真实 image 并迭代。不可用时按 `development/cli.md` 启动预览并使用真实 Browser/screenshot 工具；缺少两条真实路径时 fail closed。
+- 上传、下载和远端同步只走产品文档明确规定的 plan → confirmation → operation 流程。review 不等于 publish；不得绕过确认、生成新 operation ID 盲重试或调用任意 SQL、任意文件系统、账户、权限及密钥工具。
+
+## Harness 入口
+
+- Codex 在 trusted project 中读取根 `AGENTS.md`、`.agents/skills` 与 `.codex/config.toml`；若自动发现不可用，可运行根 `.\worldengine-codex.ps1`。不得用用户级 override 绕过 trust。
+- Claude Code 读取根 `CLAUDE.md`、`.claude/skills` 与 `.mcp.json`。Codex/Claude Code 都从项目根打开并由作者允许 project trust；不得替作者静默修改 trust。其他 harness 只有在其当前官方合同支持时才自动读取项目入口，否则由启动器或操作者显式导入根 `AGENT.md`、`.agents/skills` 与项目 MCP/CLI 配置，不能虚构自动发现。
+- 需要截图时调用当前 harness 的真实截图/image 工具检查实际像素，再基于结果迭代；不能用 DOM、日志、占位图或文字描述冒充截图验收。
+- 三份根 instruction、三套 skills 入口、各客户端配置和 launcher 都链接到 `docs/authoring/` 下的 canonical 实体。不要复制并改写出第二份提示词、Skill 树、配置或 launcher。

package/assets/skills/caveman/LICENSE.md

@@ -0,0 +1,13 @@
+# Caveman skill license
+
+The bundled `skills/caveman/` instruction skill is MIT-licensed. It does not include the upstream Engine-linked runtime directories covered by BSL-1.1.
+
+MIT License
+
+Copyright (c) 2026 Julius Brussee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/assets/skills/caveman/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: caveman
+description: >
+  Ultra-compressed communication mode. Cuts token usage ~75% by dropping
+  filler, articles, and pleasantries while keeping full technical accuracy.
+  Use when user says "caveman mode", "talk like caveman", "use caveman",
+  "less tokens", "be brief", or invokes /caveman.
+license: MIT
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+### Examples
+
+**"Why React component re-render?"**
+
+> Inline obj prop -> new ref -> re-render. `useMemo`.
+
+**"Explain database connection pooling."**
+
+> Pool = reuse DB conn. Skip handshake -> fast under load.
+
+## Auto-Clarity Exception
+
+Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
+
+Example -- destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Caveman resume. Verify backup exist first.

package/assets/skills/caveman/SOURCE.md

@@ -0,0 +1,9 @@
+# 来源说明
+
+- 上游仓库：<https://github.com/JuliusBrussee/caveman>
+- 上游路径：`skills/caveman/SKILL.md`
+- 许可权威：仓库根 `LICENSE` 与 `LICENSING.md`；其中明确规定 `skills/` 使用 MIT License。
+- 核验基准：2026-09-07 核验上游 `main` commit `0dd7ad6866949c6d69f04d7546c62a4f35c32a73`。
+- 随包保留的许可全文：[LICENSE.md](LICENSE.md)
+
+随包 instruction 是较早版本的本地适配快照，不声称与上述 commit 逐字相同。本包只携带 instruction skill，不包含上游采用 BSL-1.1 的 `engine/`、`proxy/`、`rewriter/`、`browse/`、`mcp/`、`shrink/`、cavemem Go core 或 `shared/platform/` runtime。

package/assets/skills/diagnose/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: diagnose
+description: Disciplined diagnosis loop for hard bugs and performance regressions. Reproduce → minimise → hypothesise → instrument → fix → regression-test. Use when user says "diagnose this" / "debug this", reports a bug, says something is broken/throwing/failing, or describes a performance regression.
+license: MIT
+---
+
+# Diagnose
+
+A discipline for hard bugs. Skip phases only when explicitly justified.
+
+When exploring the codebase, use the project's domain glossary to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.
+
+## Phase 1 — Build a feedback loop
+
+**This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.
+
+Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give up.**
+
+### Ways to construct one — try them in roughly this order
+
+1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
+2. **Curl / HTTP script** against a running dev server.
+3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
+4. **Headless browser script** (Playwright / Puppeteer) — drives the UI, asserts on DOM/console/network.
+5. **Replay a captured trace.** Save a real network request / payload / event log to disk; replay it through the code path in isolation.
+6. **Throwaway harness.** Spin up a minimal subset of the system (one service, mocked deps) that exercises the bug code path with a single function call.
+7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
+8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
+9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
+10. **HITL bash script.** Last resort. If a human must click, drive _them_ with `scripts/hitl-loop.template.sh` so the loop is still structured. Captured output feeds back to you.
+
+Build the right feedback loop, and the bug is 90% fixed.
+
+### Iterate on the loop itself
+
+Treat the loop as a product. Once you have _a_ loop, ask:
+
+- Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
+- Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
+- Can I make it more deterministic? (Pin time, seed RNG, isolate filesystem, freeze network.)
+
+A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.
+
+### Non-deterministic bugs
+
+The goal is not a clean repro but a **higher reproduction rate**. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.
+
+### When you genuinely cannot build a loop
+
+Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
+
+Do not proceed to Phase 2 until you have a loop you believe in.
+
+## Phase 2 — Reproduce
+
+Run the loop. Watch the bug appear.
+
+Confirm:
+
+- [ ] The loop produces the failure mode the **user** described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
+- [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
+- [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
+
+Do not proceed until you reproduce the bug.
+
+## Phase 3 — Hypothesise
+
+Generate **3–5 ranked hypotheses** before testing any of them. Single-hypothesis generation anchors on the first plausible idea.
+
+Each hypothesis must be **falsifiable**: state the prediction it makes.
+
+> Format: "If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."
+
+If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.
+
+**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly ("we just deployed a change to #3"), or know hypotheses they've already ruled out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.
+
+## Phase 4 — Instrument
+
+Each probe must map to a specific prediction from Phase 3. **Change one variable at a time.**
+
+Tool preference:
+
+1. **Debugger / REPL inspection** if the env supports it. One breakpoint beats ten logs.
+2. **Targeted logs** at the boundaries that distinguish hypotheses.
+3. Never "log everything and grep".
+
+**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.
+
+**Perf branch.** For performance regressions, logs are usually wrong. Instead: establish a baseline measurement (timing harness, `performance.now()`, profiler, query plan), then bisect. Measure first, fix second.
+
+## Phase 5 — Fix + regression test
+
+Write the regression test **before the fix** — but only if there is a **correct seam** for it.
+
+A correct seam is one where the test exercises the **real bug pattern** as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers, unit test that can't replicate the chain that triggered the bug), a regression test there gives false confidence.
+
+**If no correct seam exists, that itself is the finding.** Note it. The codebase architecture is preventing the bug from being locked down. Flag this for the next phase.
+
+If a correct seam exists:
+
+1. Turn the minimised repro into a failing test at that seam.
+2. Watch it fail.
+3. Apply the fix.
+4. Watch it pass.
+5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.
+
+## Phase 6 — Cleanup + post-mortem
+
+Required before declaring done:
+
+- [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
+- [ ] Regression test passes (or absence of seam is documented)
+- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
+- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
+
+**Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/assets/skills/diagnose/SOURCE.md

@@ -0,0 +1,3 @@
+# 来源说明
+
+本技能是 `mattpocock/skills` 中 `skills/engineering/diagnose/` 的本地适配快照。统一来源、核验 commit 与 MIT 许可全文见 [setup-matt-pocock-skills/SOURCE.md](../setup-matt-pocock-skills/SOURCE.md) 和 [setup-matt-pocock-skills/LICENSE.md](../setup-matt-pocock-skills/LICENSE.md)。

package/assets/skills/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/assets/skills/i-have-adhd/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Ayoub Ghriss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.